Phase 5 — auto-groups (#14) + permissions (#13) + blueprints (#7)

[2000game]

Phase 5 — Auto-groups (#14) + Permissions (#13) + Blueprints (#7)

Declarative, idempotent management of ChurchTools' rights-bearing structure, built on a shared synthetic-field engine seam. One branch, sequenced #14 → #13 → #7. All three features complete.

✅ #14 — Auto-groups (dynamic groups) as code

• Opt-in dynamic: { status, ruleset } block on a group. status ∈ active | manual | inactive | none (none demotes back to a normal group).
• Generalized the one-off parents hierarchy fold into a reusable synthetic-field registry (src/engine/synthetic.ts); parents and dynamic are its first two entries — build.ts/execute.ts gained no per-feature branches.
• Normalizer (src/engine/dynamic.ts) makes drift real, not spurious: unwraps the [RuleSet] GET array + dynamicGroupRuleSet PUT envelope, drops read-only timestamps, and (scoped to the query subtree) strips cosmetic dterm labels + coerces int/string ids. Validated against 3 real production rulesets.
• Typed query DSL (src/config/query.ts): q.and/or/not/eq/oneof/isnull/var + churchQuery(), matched to the real ChurchQuery envelope shape.
• ct apply --refresh (opt-in, per-group only — never the all-groups endpoint).

✅ #13 — Permissions as code

• ct.groupRole({ id, grants }) / ct.groupTypeRole({ id, grants }) — grants are human-readable module:right names or { right, scope: [groupKeys] }.
• Ships a static name→authId catalog (src/permissions/catalog.json, 187 rights) — not in the REST API, so captured reference data (with scopeField + revocable). ct get permissions-catalog lists it.
• Set reconciliation keyed by (domainType, domainId, authId, dataId), tolerant of the self-re-adding system baseline (modifiedPid: -1) and inherited grants. Scoped grants fan out to one tuple per dataId to match the API's scalar read shape (idempotent, incl. multi-scope). Managed-guard: undeclared domain objects stay invisible.
• Domain-rule validation (authId < 10000 for group_type_role; scoped rights require a scopeField); duplicate (domainType, domainId) declarations rejected.

✅ #7 — Blueprints

• Proves the config DSL supports parametrized campus blueprints with no new machinery — a blueprint is a plain function over the injected context, called in a loop. Example: examples/campus-blueprint.config.ts (a Kids area instantiated across 2 campuses, composing parents hierarchy + a dynamic auto-group + a groupTypeRole grant).
• tests/blueprint.test.ts locks the guarantee: one blueprint across ≥2 campuses yields a correctly dependency-ordered plan (campuses → groups → hierarchy), with the managed-parent typo guard.

Architecture

Both auto-groups and hierarchy attach to a domain object as an opt-in pseudo-field, folded into the diff on both sides and routed at apply to dedicated endpoints — never the resource body. Permissions run as a cohesive src/permissions/ subsystem (its own plan/apply) reusing the state file, assertNotPeople, and the plan/apply commands.

Testing

• 202 passing / 4 skipped (the 4 are opt-in CT_LIVE-gated round-trip tests), typecheck + lint clean, built binary reads the catalog.
• Live integration tests are gated and default-skipped; write-based ones are doubly gated with a host-match guard and must target a dev instance (never production).
• Built via multi-agent subagent-driven development: fresh implementer + independent spec/quality review per task, plus a whole-branch review per feature (which caught, e.g., the multi-scope idempotency bug — fixed and test-locked).

Design docs

• Spec: docs/superpowers/specs/2026-07-08-phase-5-permissions-autogroups-blueprints-design.md
• Plans: docs/superpowers/plans/2026-07-08-{auto-groups,permissions,blueprints}.md
• Feature guides: docs/{dynamic-groups,permissions,blueprints}.md

Closes #14. Closes #13. Closes #7.

https://claude.ai/code/session_017tFJu7SrS5uLdit5FtXiwS

[2000game]

Review — three-agent review (engine/dynamic · permissions · blueprints/docs)

Verdict: approve after fixes — all blocking findings fixed in 4d4348a on this branch. Verified: 215 tests passing (up from 202), typecheck + lint clean.

What this PR does well

• The synthetic-field registry is a clean seam: parents and dynamic route through one SyntheticField abstraction and build.ts/execute.ts stayed genuinely feature-agnostic.
• Permissions set-reconciliation core (keying by type:authId:sorted-dataId, scalar fan-out, baseline/inherited tolerance, managed-guard) is sound and well-tested on the happy path.
• tests/blueprint.test.ts genuinely locks the ordered-plan guarantee (campus → own groups → hierarchy, per campus, from one blueprint function).
• Normalizer envelope handling ([RuleSet] GET unwrap, dynamicGroupRuleSet PUT envelope, status shape) matches the documented API shapes.

Blocking findings — fixed in 4d4348a

1. (security) Bare-string declaration of a scoped right silently granted globally — desiredTuples emitted dataId: [] with no scopeField check; validation was asymmetric (scope on an unscoped right threw, the reverse didn't). Now throws with a message directing to { right, scope: [...] }. 63 catalog rights were reachable this way.
2. (security) Reconciliation deleted pre-existing revoke (deny) rows — desired tuples are always type:"grant", so an admin's explicit deny on a managed domain always landed in toDelete. Non-grant rows are now unmanaged: never deleted, surfaced as a preserved note in the plan.
3. Invalid grant name in example + docs — churchgroup:edit group members doesn't exist (correct: churchgroup:edit group memberships of group, authId 1112); nothing caught it because examples/ was outside the typecheck/test surface. Fixed + new tests/examples.test.ts loads every example and resolves every grant against the catalog.
4. { ref } rulesets resolved against cwd, not the config file's directory, and a missing file crashed with a raw ENOENT out of foldSynthetic. configDir now threads loadConfig → buildPlan → foldSynthetic; errors name the group and resolved path. Was fully untested; now covered.
5. Ruleset/status GETs shared one try/catch — a status-GET failure after a successful ruleset GET fabricated the "not dynamic" sentinel, discarding the real ruleset and proposing a spurious re-PUT. Now only a ruleset-404 produces the sentinel; other failures degrade the plan via fetchErrors.
6. Docs: permissions.md claimed unknown right names throw "at config evaluation time" (actually plan/apply time in desiredTuples); dynamic-group example comment described a nonexistent "tier 5" write (dynamic applies inline in the group's tier-1 apply).

Tracked as issues instead of blocking

• Un-declaring a permission block never revokes its grants (no state tracking; ct destroy ignores permissions) — noted on chore: codebase-review cleanups — serial I/O, keychain triple-read, type-registration drift, dead code #35 (item 13), promote when picked up.
• Ruleset round-trip assumption unverified — convergence relies on CT echoing description/shorty/importance/personIdFieldName/process byte-for-byte; needs a live-gated user-authored-ruleset test → bug: dynamic ruleset round-trip assumption unverified — CT-recomputed fields would cause perpetual diffs #36.
• Minors on chore: codebase-review cleanups — serial I/O, keychain triple-read, type-registration drift, dead code #35: permission-apply progress messaging, status-only re-PUT of the ruleset, ct plan --json shape change.
• Already-filed and confirmed during review: bug: apply reverts drifted fields — update body built from stale state snapshot, not actuals #27, bug: first apply on a fresh state silently drops all group hierarchy edges #28 (parents only — dynamic is unaffected), bug: group + grant scoped to it in one config can never be applied (scope-resolution deadlock) #29, bug: dynamic groups — normalizer corrupts leading-zero strings; status:none demote never converges #34.