test/docs(apply): §6 M2 structural-divergence journey + design note

`tests/structural_divergence.rs`: a repo that nests a group under a different
parent than the server → `pic plan` shows it `diverged`; a bare apply is
refused (422); `--force-local-structure` reparents to the manifest shape;
`--adopt-server-structure` keeps the server placement. Design doc §6 records M2
shipped, leaving only per-env approval gating deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/design/groups-and-project-tool.md

@@ -810,8 +810,22 @@ caller-supplied `resolved_ids` map (existing + just-created) and returns a `to_c
 previews (empty current → a full-create plan; ownership → `claim`) — a to-create group's token part is identical
 to its post-create part, so plan/apply tokens match across a create. `authz_tree` skips a to-create group (its
 authorization is the service-side create gate). Reparent of an EXISTING diverged group + the detect-and-refuse
-flags are M2. Pinned by `tests/group_create.rs`. **Still deferred:** §6 structural-divergence detection + M2
-reparent; per-env approval gating.
+flags are M2. Pinned by `tests/group_create.rs`.
+
+**§6 group-tree M2 shipped — structural-divergence detection + declarative reparent.** With the declared parent now
+on the wire, `apply_tree` compares each EXISTING group node's server parent against the manifest's (directory-
+nesting) parent. A divergence is resolved by a request `StructureMode` (default `Refuse`, so a pre-M2 CLI never
+reshapes the tree): `Refuse` → `ApplyError::StructuralDivergence` (422, naming the resolution flags); `ForceLocal`
+→ reparent to the declared parent IN the apply tx via the extracted `group_repo::reparent_group_tx` (cycle guard +
+`structure_version` bump), §5.6-gated (`GroupAdmin` on the node + source + destination) and attach-ceilinged;
+`AdoptServer` → keep the server shape, reconcile content in place. M1's `create_missing_groups_tx` generalized to
+`reconcile_group_structure_tx` (create + reparent share the coarse-lock / attach / RBAC path; both are recorded as
+`structurally_changed` so the pool-based attach re-check skips their uncommitted rows). `pic plan` previews the
+divergence (`divergence_preview` → a `structure` row: `diverged`, server + manifest parents). CLI:
+`--force-local-structure` / `--adopt-server-structure` (mutually exclusive) → the `structure_mode` wire field; the
+422 surfaces verbatim. A concurrent `pic groups reparent` between plan and apply still trips `StateMoved` (the tree
+token folds `structure_version`). Pinned by `tests/structural_divergence.rs`. **Still deferred:** per-env approval
+gating (`[project.environments]`).
 
 ---