@event4u/agent-config 8.10.0 → 8.12.0

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **639 public artefacts** shipped by
+Consumer-facing catalog of all **642 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `./scripts-run src/scripts/generate_index`
 > Auto-generated — do not edit manually.
 
-## Skills (270)
+## Skills (271)
 
 > **Behavioural-eval coverage is measured, not implied.** A skill is
 > behaviourally evaluated only if it ships `evals/evals.json`; most do
@@ -129,6 +129,7 @@ are excluded.
 | skill | [`guideline-writing`](../dist/agent-src/skills/guideline-writing/SKILL.md) |  | Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'. |
 | skill | [`hiring-loop-design`](../dist/agent-src/skills/hiring-loop-design/SKILL.md) |  | Use when shaping an engineering hiring loop — stages, take-home vs live, calibration, bar-raiser, signal-vs-noise audit. Triggers on 'design our interview loop', 'audit our hiring bar'. |
 | skill | [`html-deck`](../dist/agent-src/skills/html-deck/SKILL.md) |  | Build a slide presentation as one HTML file — fixed 1920×1080 canvas letterboxed to any viewport, layout-system-first, type floors. Use for deck, slides, presentation, or pitch requests. |
+| skill | [`humanizer`](../dist/agent-src/skills/humanizer/SKILL.md) |  | Use when removing AI-writing tells from deliverable prose — posts, articles, drafts. Triggers on 'make this sound less like AI', 'humanize this draft', 'this reads like ChatGPT wrote it'. |
 | skill | [`iconography`](../dist/agent-src/skills/iconography/SKILL.md) |  | Resolve an icon request to a concrete Iconify name and emit the embedding for the project's stack. Use when adding icons, picking an icon set, or wiring Lucide/Heroicons/Phosphor/Tabler. |
 | skill | [`image-analyser`](../dist/agent-src/skills/image-analyser/SKILL.md) |  | Use to analyse a character image down to the smallest mole and diff against a canon — per-feature spec, OCR-reads tattoo text, flags drift. Triggers 'analyse this image', 'match the canon'. |
 | skill | [`image-creator`](../dist/agent-src/skills/image-creator/SKILL.md) |  | Use to generate a character image to spec — max-fidelity reproducible prompt from a Canon Spec, anchors-first, provider/governance-gated. Triggers 'generate this character', 'render to spec'. |
@@ -265,7 +266,7 @@ are excluded.
 | skill | [`sql-writing`](../dist/agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement`; fires even on a pasted query asking 'why is this slow'. |
 | skill | [`stakeholder-tradeoff`](../dist/agent-src/skills/stakeholder-tradeoff/SKILL.md) |  | Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'. |
 | skill | [`standards-from-config`](../dist/agent-src/skills/standards-from-config/SKILL.md) |  | Use when you need this project's coding standards (line length, quotes, import order, naming, commit format) — derive them from the REAL tooling config as a pointer + digest, never a guessed claim. |
-| skill | [`subagent-orchestration`](../dist/agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
+| skill | [`subagent-orchestration`](../dist/agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — form gate + eight modes (do-and-judge ±two-stage, steps/parallel/worktrees, competitively, debate, live-app-judge). |
 | skill | [`supply-chain-intake`](../dist/agent-src/skills/supply-chain-intake/SKILL.md) |  | Before adding/installing any dependency the agent named — verify the package exists (slopsquatting: ~1 in 5 AI suggestions are hallucinated), isn't typo-adjacent, is pinned + locked, and CVE-scanned |
 | skill | [`symfony-workflow`](../dist/agent-src/skills/symfony-workflow/SKILL.md) |  | Writes Symfony PHP — DI container, bundles, Doctrine, Messenger, Security voters, console commands. For Laravel / Eloquent / Artisan use `laravel`. For framework-free PHP use `php-coder`. |
 | skill | [`systematic-debugging`](../dist/agent-src/skills/systematic-debugging/SKILL.md) |  | Use on a bug, test failure, crash, or unexpected behavior — enforce reproduce → isolate → hypothesize → verify before any fix; fires even on 'this is broken' / 'quick fix'. |
@@ -298,7 +299,7 @@ are excluded.
 | skill | [`wireframe`](../dist/agent-src/skills/wireframe/SKILL.md) |  | Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis, before any hi-fi work. Use when the user wants to sketch directions or explore structure. |
 | skill | [`worktree-lifecycle`](../dist/agent-src/skills/worktree-lifecycle/SKILL.md) |  | Use when governing a worktree across its whole life — scope-lock declaration, merge-readiness status, scoped verification, and safe cleanup that refuses while unique unmerged commits exist. |
 
-## Rules (102)
+## Rules (103)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -315,6 +316,7 @@ are excluded.
 | rule | [`brand-source-of-truth`](../dist/agent-src/rules/brand-source-of-truth.md) | auto | Consumer brand tokens + voice profile are the run's source of truth — the corpus fills gaps, never overrides |
 | rule | [`broken-access-control`](../dist/agent-src/rules/broken-access-control.md) | auto | Endpoint/query returning user or tenant data — authenticated ≠ authorized; enforce a server-derived ownership/tenant/role check + the three negative tests (401/non-owner/cross-tenant) |
 | rule | [`cli-output-handling`](../dist/agent-src/rules/cli-output-handling.md) | auto | Verbose CLI output (git, tests, linters, docker, npm, composer) — wrap with rtk; tail/grep fallback |
+| rule | [`code-comment-discipline`](../dist/agent-src/rules/code-comment-discipline.md) | auto | Writing/editing code in any language — a comment states a WHY or a constraint the code cannot show; never restate what names/types already say; no signature-mirroring docblocks |
 | rule | [`command-suggestion-policy`](../dist/agent-src/rules/command-suggestion-policy.md) | auto | Prompt matches an eligible slash command — surface as numbered options with as-is escape; never auto-execute |
 | rule | [`commit-conventions`](../dist/agent-src/rules/commit-conventions.md) | auto | Git commit format, branch naming, conventional commits, committing, pushing, creating PRs |
 | rule | [`commit-policy`](../dist/agent-src/rules/commit-policy.md) | always | Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked |
@@ -405,7 +407,7 @@ are excluded.
 | rule | [`user-interrupt-priority`](../dist/agent-src/rules/user-interrupt-priority.md) | auto | New user instruction mid-flight — STOP the current task, run the new one in full, ASK before resuming |
 | rule | [`verify-before-complete`](../dist/agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (177)
+## Commands (178)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -484,6 +486,7 @@ are excluded.
 | command | [`ghostwriter-show`](../dist/agent-src/commands/ghostwriter/show.md) | cluster: ghostwriter | Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source URLs. Read-only. |
 | command | [`ghostwriter-write`](../dist/agent-src/commands/ghostwriter/write.md) | cluster: ghostwriter | Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory non-removable disclosure footer. |
 | command | [`grill-me`](../dist/agent-src/commands/grill-me.md) | cluster: challenge-me | Alias for /challenge-me — interactive grill-style interview that sharpens a fuzzy plan/idea into a copyable Markdown pitch |
+| command | [`humanize`](../dist/agent-src/commands/humanize.md) | cluster: humanize | Remove AI-writing tells from pasted text or a file — runs the humanizer skill's draft→audit→final loop and prints the rewrite plus a detector summary. |
 | command | [`image`](../dist/agent-src/commands/image.md) | cluster: image | Character-image fidelity orchestrator — analyse, create, and verify a character image against its canon. Routes to analyse, create, verify. |
 | command | [`image-analyse`](../dist/agent-src/commands/image/analyse.md) | cluster: image | Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tattoo text, severity-ranked drift report. |
 | command | [`image-create`](../dist/agent-src/commands/image/create.md) | cluster: image | Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; governance- and provider-gated, dry-run by default. |

package/docs/command-flows.md

@@ -7,7 +7,7 @@
 
 > Every command is classified in `src/flows/surface-map.yaml` (coverage enforced by `scripts/lint_command_flow_coverage.py`). The four user-work flows carry rich definitions in `src/flows/<flow>.yaml`.
 
-**177 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
+**178 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
 
 ## User-work flows
 
@@ -240,6 +240,7 @@ _Ghostwriter + post-as voice pipeline._
 - `ghostwriter-list` — List captured ghostwriter profiles under agents/reference/ghostwriter/ as a numbered table with confidence,…
 - `ghostwriter-show` — Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source UR…
 - `ghostwriter-write` — Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory n…
+- `humanize` — Remove AI-writing tells from pasted text or a file — runs the humanizer skill's draft→audit→final loop and…
 - `post-as` — Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no discl…
 - `post-as-ghostwriter` — Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with…
 - `post-as-me` — Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample).…

package/docs/contracts/ai-council-config.md

@@ -159,6 +159,15 @@ Implications:
   user opt into a per-day cap; counter state persists at
   `~/.event4u/agent-config/cli-calls.json` with daily UTC reset (wired in
   Phase 1 of the CLI-transport roadmap).
+- **Omitting `model:` for a vendor `cli` member is a PIN, not "latest".**
+  Each vendor CLI client (`anthropic` / `openai` / `gemini`) falls back to a
+  dedicated `DEFAULT_*_CLI_MODEL` constant when `model` is unset
+  (`clients.ts`); `xai` / `perplexity` CLIs are community API wrappers and
+  reuse their `DEFAULT_*_MODEL` API constant. The value is a deliberate pin;
+  the vendor CLI's own default may be newer. Bump the constant intentionally —
+  never assume the omitted default tracks the provider's latest release. The
+  CLI constants are separate from the API ones because the two can legitimately
+  diverge — `openai` API `gpt-4o` vs CLI `gpt-5` is the proof.
 - **Quota observability (step-8 D1, D4):** every `council run` /
   `council debate` prints a one-line `council:quota · <provider>
   used/limit · …` summary before the first member fires. Only
@@ -366,6 +375,94 @@ _artefact mode: full|redacted (counts only)_
 
 Findings are ranked by `consensus_strength` descending. Empty sessions
 emit the heading plus `*No findings were extracted for this session.*`.
+The trailer additionally carries two aggregate lines — **Evidence spread**
+(high/medium/low counts across findings) and **Provider spread** (distinct
+providers that deliberated) — folded in beside `_artefact mode:_`.
+
+### Stance tally (Phase 1 — option-level verdict)
+
+`consensus_scoring` scores *findings*; `stance_tally` produces an
+*option-level* verdict for "A or B?" questions. **Default-off**; with the
+block absent the council path is byte-identical to today.
+
+**Configuration.**
+
+- `stance_tally.enabled` (bool, default `false`) — master switch. A
+  non-bool value is rejected at config load (`CouncilConfigError`); unknown
+  values are not silently coerced.
+
+**Behaviour when enabled.** The final round appends a mandatory closing-line
+contract — `STANCE: <label> | CONFIDENCE: high|med|low | DEALBREAKER: yes|no`
+— parsed deterministically (`stance_tally.ts`), never inferred from prose.
+Weights are confidence factors (`high 1.0 / med 0.75 / low 0.5`); `W_total`
+sums base weights over every member with a parseable stance (abstentions
+included, so they raise the bar). Consensus requires an option to clear
+`⅔ × W_total`; below threshold a structured **split** is returned to the
+user — never a forced winner, never an auto-added round. The synthesis gains
+a **Vote Tally** section (one line per option, the threshold, and a
+cleared-or-escalated line). The final-round wiring is LIVE (2026-07-12): `consult` appends the contract to
+the final round and `render` emits the Vote Tally block, threaded via
+`payload.stance_tally`. A member whose stance line is missing or unparseable is
+a repair-marker; the bounded stance-line-only repair CALL (policy: `repair_action`
+— confirm-interactive / auto-fire under `--auto-continue`) and its estimate row
+are the remaining dispatch wiring.
+
+### Chairman synthesis (Phase 2 — opt-in)
+
+The skill's own Iron Law argues the host, having framed the artefact, cannot
+independently judge it. `chairman` lets a **non-deliberating member** author the
+synthesis instead. **Default `host`** = today's behaviour, byte-identical.
+
+**Configuration.**
+
+- `chairman.mode` (enum `host` | `member` | `auto`, default `host`) — an unknown
+  value is rejected at config load.
+- `chairman.member` (string, required when `mode: member`) — must name a member
+  that exists AND is enabled; **fails closed** at load otherwise.
+- `members.<name>.tier` (int ≥ 1, optional) — capability rank used only as the
+  `auto` tie-break (higher = stronger); non-integer / < 1 rejected at load.
+
+**Selection** (`chairman.ts` `select_chairman`, pure): `host` → host synthesis;
+`member` → the named member, but only if it did **not** deliberate this session
+(a member that argued cannot self-judge — else host fallback with a visible
+annotation); `auto` → **provider-family difference primary, tier tie-break,
+config-order final** — decided by the contested-design council pass
+(claude-sonnet-4-5 + gpt-4o, 2-round debate, 2026-07-12): independence from the
+deliberators' priors is the binding constraint for a judge, so `auto` picks a
+non-deliberating member (provider-different by construction under the
+one-member-per-provider invariant); among candidates the optional
+`members.<name>.tier` wins, else the deterministic config order; no
+non-deliberating member → annotated host fallback. The billable chairman
+dispatch (rendering the synthesis as one member call in `cmd_run`) is the
+remaining wiring step.
+
+### Debate enforcement gates (Phase 3 — opt-in)
+
+- `debate_gates.enabled` (bool, default `false`) — when on, round-2+ debate
+  prompts carry the **anti-conformity directive** (`prompts.ANTI_CONFORMITY_DIRECTIVE`:
+  defend a position; change only on a specific named flaw; agreement without a
+  named reason is conformity). Byte-identical across api/cli/manual (it is part of
+  the shared `user_prompt`). Default-off keeps the debate path byte-identical.
+- `restate.enabled` (bool, default `false`) — or the `--restate` debate flag:
+  a pre-round-1 pass collecting a ≤ 50-word restatement + one alternative
+  framing per member (billable, through the same spend gate), rendered above
+  the round-1 responses; a restatement with little token overlap vs the stated
+  ask is flagged before further spend.
+
+The deterministic post-round detectors — dissent-quota (`debate_gates.dissent_quota_met`)
+and the novelty gate (`debate_gates.is_near_duplicate`, reusing the shared
+Jaccard util) — are implemented and tested as pure functions.
+
+**Repair-call policy** (`debate_gates.repair_action`) — decided by the
+contested-design council pass (claude-sonnet-4-5 + gpt-4o, 2026-07-12): a cost
+estimate is an upper bound, not a spend commitment, and repairs are failure-mode
+responses — so **interactive runs get a one-line confirm** before each repair
+call; **unattended runs (`--auto-continue`) auto-fire** under the hard cap
+(≤ 1 repair per member per round, absolute — an already-repaired member is
+skipped in every mode); manual-transport members follow the same policy. The repair dispatch is LIVE in `run_debate` (2026-07-12): post-round checks on
+round 2+, ≤ 1 repair per member per round, dispatched via the CLI's
+`_make_repair_confirm` transport (auto-fire under `--auto-continue`, one-line
+confirm interactive); a successful repair replaces the member's round entry.
 
 ### Decision resolution by impact (Phase 10, ask-user routing)
 

package/docs/contracts/command-clusters.md

@@ -48,6 +48,7 @@ column 1 of this table.
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
 | `sync` | 4 | `agent-settings` · `gitignore` · `gitignore-fix` | new cluster 2026-07-08 — absorbs the former single-sub `sync-gitignore` cluster (slug-neutral nests: `sync-agent-settings`, `sync-gitignore`, `sync-gitignore-fix` keep their slugs; the gitignore node keeps its own `fix` sub-dir, mirroring the `agents/user` deep-nest precedent). Bare `/sync` shows the menu. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
+| `humanize` | — | _(none yet — cluster head only)_ | new cluster 2026-07-11 (`road-to-humanized-writing` Phase 3) — on-demand AI-tell removal for deliverable prose (pasted text or file path) via the [`humanizer`](../../src/skills/humanizer/SKILL.md) skill's draft→audit→final loop + the `detect_ai_tells.ts` detector; `--voice=<slug\|me>` reuses the write-engine style-source resolution (no second voice mechanism). Counterpart to the engine-internal step 4b in [`write-engine`](write-engine.md). Single cluster head; sub-commands deferred until a second verb is needed. |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
 | `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/media/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
 | `knowledge` | — | `ingest` · `list` · `forget` · `cross-repo` | local-knowledge namespace (employee-product Phase 7); `:cross-repo` added 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 4) — read-only targeted retrieval over opted-in `linked_projects` siblings (ADR-032 Option A), per [`cross-repo-retrieval`](cross-repo-retrieval.md). The pre-existing `ingest`/`list`/`forget` sub-commands are recorded in the registry here for the first time. |

package/docs/contracts/evidence-based-pruning.md

@@ -94,6 +94,7 @@ candidate; the human, seeing the evidence, makes the call.
 
 ## See also
 
+- [`ADR-118`](../decisions/ADR-118-loop-engineering-boundaries.md) — engagement counts stay ONE input; the pruning decision is never automated (disposition #2).
 - [`local-analytics.md`](local-analytics.md) — the measurement events + privacy floor.
 - [`capability-packs.md`](capability-packs.md) — sibling per-pack budget governance.
 - [`ADR-041`](../decisions/ADR-041-controlled-command-verbs.md) — sibling command-surface governance.

package/docs/contracts/hook-architecture-v1.md

@@ -192,6 +192,31 @@ Phase 7.4 ships a regression test that spawns two concurrent
 dispatcher invocations against the same event and asserts no torn
 writes (file ends with valid JSON, last-writer-wins).
 
+## Hook-resilience shim — every registered command degrades silently
+
+Every hook command the installer registers (Claude managed block + plugin
+`hooks/hooks.json`, Cursor, Windsurf, Gemini, the Augment trampoline) follows
+one shape (road-to-opt-subagent-harvest P1.4):
+
+1. **Resolve the dispatcher** — project-local binary first, PATH fallback
+   where the platform supports it (Claude: `$CLAUDE_PROJECT_DIR/agent-config`
+   → `agent-config`).
+2. **Missing dispatcher → silent `exit 0`.** A hook must never error-spam or
+   block the agent loop on a repo where the suite is not (yet) installed.
+   This is the honest degrade even for `fail_closed` concerns: an absent
+   dispatcher cannot evaluate anything, so there is nothing to fail closed
+   ON — the deny power exists only where the suite exists.
+3. **Present dispatcher → exit code PROPAGATES.** No `|| true` around the
+   dispatch call itself: a `fail_closed: true` concern (e.g.
+   `block-no-verify`) keeps its deny. Fail-open of crashed concerns is
+   handled INSIDE `dispatch_hook.ts` per the manifest's `fail_closed` flag,
+   never by the outer shim.
+
+The Augment trampoline (`src/scripts/hooks/augment-dispatcher.sh`) is the
+reference implementation of the same contract in shell form (`set -u`,
+silent bails, unconditional `exit 0` — Augment concerns are all
+observe-only, so blanket exit 0 is correct there).
+
 ## Copilot fallback pattern
 
 Copilot has no hook surface. Concerns whose source rule cites

package/docs/contracts/kernel-membership.md

@@ -302,3 +302,38 @@ with the trigger-relaxed parameter, lock new value, re-attempt.
 | 2026-05-06 | `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json` | Council R2 (3500 tokens) — locks median r, splits criterion #3, adds criterion #5, raises per-rule cap to 2.5k, defines abort criteria | <!-- council-ref-allowed: contract decision trace -->
 | 2026-05-06 | this file | kernel set locked: 9 rules, projected 23 071 chars (median r = 0.712) |
 | 2026-05-06 | P2.2 condensation + `scripts/iron_law_sha.py --all-kernel` | empirical: 25 590 chars (r_actual = 0.795 across kernel; longer rules condense less than the pilot median) — see `docs/decisions/ADR-002-kernel-bucket-overrides.md` (KERNEL_HARD raised 25k → 26k, 6 per-rule overrides ≤ 4k ceiling, all Iron-Law SHAs preserved) |
+
+## § 10 — Changing a protected invariant
+
+The semantic-invariants gate (`src/scripts/check_rule_invariants.ts` over
+`tests/golden/invariants.json`, 19 protected strings across the 9 kernel
+rules) enforces string presence in BOTH `src/rules/` and the
+`dist/agent-src/rules/` projection. String matching is deliberately the
+current enforcement: it is zero-cost and trips on casual edits. Its known
+brittleness — a semantically equivalent rewording breaks the gate — is
+handled by process, not by weakening the gate.
+
+**Rewording a protected string is allowed, but never "update the gate
+green".** A PR that changes an entry in `tests/golden/invariants.json`
+MUST:
+
+1. Name WHICH invariant changes and WHY the wording changes (PR body).
+2. State old/new side-by-side with an explicit assertion-equivalence
+   sentence ("the new wording still guarantees X").
+3. Re-run and quote `check_rule_invariants.ts --mutation-selftest` in the
+   PR (the selftest guards the checker against silently-green
+   normalisation bugs after the edit).
+4. Cite the behavioral eval covering the invariant where one exists; where
+   none exists, say so explicitly — an uncovered invariant rewording gets
+   extra review scrutiny, not less.
+
+Kernel-edit slow-rollout rules (own PR, ≥ 24 h soak between kernel merges,
+per `scope-control § kernel-rule-edits`) apply on top — the invariants file
+is part of the kernel surface.
+
+**ID migration is gated, not planned.** Migrating string fragments to
+frontmatter invariant IDs happens only after behavioral evals cover ≥ 10
+of the 19 invariants. Until then, IDs would claim guarantees nothing
+verifies — an ID whose text drifted validates nothing, and that failure is
+silent, unlike a string miss (council convergence, anthropic/
+claude-sonnet-4-5 + openai/gpt-4o, 2026-07-10).

package/docs/contracts/measurement-baseline.md

@@ -96,6 +96,7 @@ P2 roadmap reads — not the live `internal/bench/reports/` directory.
 
 ## Cross-references
 
+- [`ADR-118`](../decisions/ADR-118-loop-engineering-boundaries.md) · bench-drift stays advisory by decision — never a blocking gate (disposition #4)
 - [`benchmark-report-schema.md`](benchmark-report-schema.md) · per-report JSON schema
 - [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md) · corpus YAML schema
 - [`condensation-default-kill-criterion.md`](condensation-default-kill-criterion.md) · decision table read by step-4 closeout

package/docs/contracts/persona-schema.md

@@ -144,6 +144,55 @@ major version bump in the package release notes. Size-cap tightening
 is breaking when it forces existing personas to lose content; size-cap
 loosening is non-breaking.
 
+## § 8 — Governance discipline (the four checks)
+
+_Origin: migrated from `src/rules/persona-governance.md` per the P4 pattern of `road-to-kernel-and-router.md`. The rule keeps the Iron Law and the check names; the detail lives here._
+
+Personas are review lenses, not free real estate. Every specialist persona has a maintenance cost: it must stay aligned with this schema, the cited skills must still want it, and the per-domain reasoning surface must not bloat to the point that no single persona is load-bearing.
+
+### 8.1 Per-domain cap — ≤ 2 specialised personas per content domain
+
+A **content domain** is a self-contained creative or technical surface that one or two specialist personas can fully cover. Current domains:
+
+| Domain | Specialists allowed | Examples |
+|---|---|---|
+| ai-video / ai-image / ai-audio | ≤ 2 | one director-shaped lens + one technical-tuning lens |
+| backend engineering | ≤ 2 | architect + ORM-tamer |
+| frontend engineering | ≤ 2 | component / lifecycle + design / a11y |
+| security | ≤ 2 | abuse-case + secrets-and-trust |
+| gtm / growth | ≤ 2 | CMO + RevOps |
+| money / strategy | ≤ 2 | finance-partner + strategist |
+| people / org | ≤ 2 | engineering-manager + people-strategist |
+| customer / discovery | ≤ 2 | discovery-lead + customer-success-lead |
+
+**Core personas** (`developer`, `senior-engineer`, `product-owner`, `stakeholder`, `critical-challenger`, `ai-agent`) are exempt — they are always-loaded cross-cutting lenses, not domain specialists.
+
+A new specialist into a full domain MUST come with a deprecation candidate from the same domain. The agent surfaces both, then runs an ai-council debate (per [`ai-council`](../../src/skills/ai-council/SKILL.md)) before any rename / merge / delete.
+
+### 8.2 Skill citation floor — ≥ 1 cite before merge
+
+A specialist persona without a `personas: [<id>]` citation in at least one skill's frontmatter is dead weight. The PR adding the persona MUST also add the citation, OR the PR is rejected. Citation map lives in [`docs/personas.md § Skill citations`](../personas.md#skill-citations).
+
+### 8.3 Deprecation path — delete immediately, record in commit
+
+A persona being removed is **deleted in the same commit** that lands its replacement. The commit message names the successor (or "merged into X") and cites the council decision (or maintainer rationale) that authorised it. No soak window — internal personas have no external consumers; a persona file kept around as a tombstone is dead weight the linter still loads. No silent deletes either: the audit trail is the commit, not a docs table.
+
+### 8.4 Schema conformance — the skill linter is the gate
+
+Every persona file is linted against this contract (§ 1–§ 5) by the skill linter: frontmatter shape, tier enum, wing enum, required sections per tier, line budget per tier (with wing override), `Unique Questions` ≥ 3, filename / id match, description ≤ 160 chars. The agent runs `./scripts-run src/scripts/skill_linter` before any persona PR is marked ready.
+
+### Failure modes — what counts as a violation
+
+- Adding a third specialist to a full domain without naming the deprecation candidate.
+- Landing a specialist with no `personas: [<id>]` cite in any skill.
+- Renaming or deleting a persona file without naming the successor (or sunset reason) in the commit message.
+- Editing core-tier personas in-place with breaking changes (rename, section removal) without bumping to a new id.
+- Skipping the skill linter (`./scripts-run src/scripts/skill_linter`) on a persona PR.
+
+### Governance day-one state
+
+Resolved 2026-05-17 via two-round ai-council debate (members: anthropic/claude-sonnet-4-5, openai/gpt-4o — converged on delete-and-fold): `pixar-storyboard-artist` deleted; its acting / beat-decomposition lens folded into the [`pixar-storyteller`](../../src/skills/pixar-storyteller/SKILL.md) skill body. Active per-domain count for `ai-video` is now 2 (`ai-video-technical-director`, `hollywood-director`), within cap. Total active personas in the root cluster: 24 (plus 5 advisors in `personas/advisors/`). Full inventory + ownership in [`docs/personas.md`](../personas.md).
+
 ## See also
 
 - [`skill-domains`](skill-domains.md) — sister taxonomy for skills

package/docs/contracts/provider-lifecycle.md

@@ -68,19 +68,44 @@ When the agent picks a provider for a `/video:*` / `/image:*` /
 1. **Read** the `provider_lifecycle` tag from the adapter's header
    comment **and** the matching `<provider id="…">` block in
    `agents/templates/.ai-video.xml.example` (or the operator's
-   `agents/.ai-video.xml`).
+   `agents/.ai-video.xml`). This applies to every resolution path —
+   `--provider <id>`, `<default-video-provider>` /
+   `<default-image-provider>`, or a skill's default. A **mismatch
+   between the two sources is a contract violation** and MUST be
+   surfaced before running.
 2. **Refuse-and-surface** if the operator's resolved default is a
    non-`stable` tier — name the tier and the path to this contract
    document, then emit one clarifying question (per
    [`ask-when-uncertain`](../../.augment/rules/ask-when-uncertain.md)):
    either pick a `stable` provider, or confirm the non-stable run.
+   No silent default. No "I'll just try it".
 3. **Record** in the run summary which tier the chosen adapter
-   carries — this is the audit log entry the agent-in-the-loop
-   model rests on.
+   carries — the summary line after every `/video:*` / `/image:*` /
+   `/audio:*` run names the chosen provider AND its tier. This is the
+   audit log entry the agent-in-the-loop model rests on.
+4. **Never auto-promote.** Promotion is the maintainer's call. The
+   agent MAY draft a promotion checklist (per
+   [§ 2 — Promotion path](#-2--promotion-path)) for maintainer
+   review, but the tier-flip commit is human-authored.
 
 The agent never picks `deprecated` silently. If a successor is
 declared, the agent surfaces "X is deprecated; successor: Y" before
-running.
+running — even with confirmation.
+
+### § 4a — Failure modes (agent-side violations)
+
+_Origin: migrated from `src/rules/provider-lifecycle-discipline.md` per the P4 pattern of `road-to-kernel-and-router.md`. The rule keeps the Iron Law and the read-tier / refuse-and-surface one-liners; the detail lives here._
+
+- Running `/video:scene` against the `<default-video-provider>` without reading the lifecycle tag first → violation.
+- Picking a `community` provider because it was named in the prompt, without surfacing the tier → violation.
+- Editing an adapter and leaving its header `Lifecycle:` comment out of sync with `agents/templates/.ai-video.xml.example` → violation (CI does not catch this; the agent must).
+- Auto-promoting an adapter from `experimental` to `stable` because "dry-run worked" → violation. Promotion requires a maintainer-captured real-API smoke trace under `agents/reference/ai-video/smoke-traces/`.
+
+### § 4b — Why agent-in-the-loop, not a Python gate
+
+A Python pre-run gate enumerating tier-by-command rules would either be too coarse (`experimental → block`, breaking day-to-day dev iteration) or too detailed (per-command tier matrix, drifting from reality on every new provider). The agent reading the tag at run time, surfacing the tier, and asking is the correct enforcement surface: the model that picked the provider is the model that surfaces the obligation, and the human is the policy decision point.
+
+The CI guarantee is structural reachability — the linter would fail if a provider was declared in `agents/templates/.ai-video.xml.example` without a lifecycle tag (extension planned). It does not enforce the runtime obligation; the agent does.
 
 ## § 5 — Day-one assignment
 

package/docs/contracts/release-sizing.md

@@ -21,6 +21,28 @@ Scope discipline, not a ratio: what qualifies is a judgment call the
 maintainer makes when labeling the release PR
 ([`release-pr-gating.md`](release-pr-gating.md)).
 
+### Primary goal declaration
+
+Every release PR body carries one literal line:
+
+```
+Primary-Goal: <one sentence>
+```
+
+A release bundling multiple major themes anyway annotates the
+**exception + reason** in the release notes ("this release bundles N
+themes because <reason>; future releases return to one primary goal").
+The declaration keeps the norm visible and the exception deliberate.
+
+Explicitly REJECTED (council, anthropic/claude-sonnet-4-5 +
+openai/gpt-4o, 2026-07-10): a mechanical subsystem-count lint on the
+release PR. A file→subsystem map is its own maintenance burden, and
+changed-file counts are a bad proxy for scope (a one-line kernel change
+has a larger blast radius than 50 lines in a niche skill). Sizing stays
+a norm enforced by declaration + human judgment; if the maintainer
+wrote a nine-theme release, the maintainer already judged it — the
+header makes that judgment explicit, not automatic.
+
 ## Major subsystems are independently disableable where feasible
 
 A major subsystem shipped or substantially reworked in a release is

package/docs/contracts/write-engine.md

@@ -65,7 +65,8 @@ One question per turn, in this order:
 Modifiers may be supplied via flags (`--tone=casual --length=200
 --channel=linkedin-post --audience="early-stage founders"`) to skip
 the interactive interview. `--as=<slug>` selects the ghostwriter
-non-interactively for `/ghostwriter:write` and the alias.
+non-interactively for `/ghostwriter:write` and the alias. `--raw`
+skips the step-4b humanize audit for this run (see § 4b).
 
 #### Per-channel defaults
 
@@ -102,6 +103,42 @@ Emit the body as a single fenced markdown block. The body MUST:
 - Respect `style.fingerprint.hashtag_rules` and `emoji_rules`.
 - Stay within ±15% of the requested length.
 
+### 4b. Humanize audit (default-on, `--raw` opts out)
+
+After drafting and before the footer, run the AI-tell audit from the
+[`humanizer`](../../src/skills/humanizer/SKILL.md) skill against the
+draft body:
+
+1. Ask: "What makes this draft read AI-generated?" — audit against the
+   pattern catalog (`src/skills/humanizer/data/patterns.md`), counting
+   clusters, never isolated hits.
+2. Revise the draft to clear the audit findings while preserving the
+   step-4 fingerprint constraints and full coverage.
+3. Where a runtime is available, verify the final body with
+   `npx tsx src/scripts/detect_ai_tells.ts --stdin --fail` under the
+   thresholds from the consumer's `humanizer:` block in
+   `.agent-project-settings.yml` (defaults: hard 0, cluster score 3 per
+   500 words, dash density 2 per 500 words). No runtime → the prose
+   audit in (1) is the pass; do not skip it.
+
+Precedence and scope rules (binding, not judgment calls):
+
+- **Fingerprint wins.** When the profile's captured voice legitimately
+  uses a watched pattern (a figure who genuinely writes in em dashes,
+  `emoji_rules: allowed`, hashtag rules), the step-4 fingerprint
+  constraint is authoritative and the corresponding tell is suppressed
+  for that run.
+- **The disclosure footer (§ 5) is exempt.** It is a literal template
+  string appended after this step — the audit never inspects, rewords,
+  or removes it.
+- **Technical/reference output is excluded.** When the requested
+  artifact is reference or technical documentation, skip step 4b and
+  say so — neutral, plain prose is the correct register there.
+- **`--raw` opts out per run.** The flag skips step 4b entirely (for
+  deliberate neutral-register output); it never touches the footer
+  rules. Default is on for every engine consumer
+  (`humanizer.write_engine: on`).
+
 ### 5. Append the disclosure footer (ghostwriter only)
 
 For ghostwriter consumers, append on its own line, separated by a

package/docs/customization.md

@@ -406,6 +406,18 @@ agents/
 Full classification (git policy, retention, owner) for every allowed entry:
 [`docs/contracts/agents-layout.md`](contracts/agents-layout.md).
 
+#### Environment bootstrap (optional)
+
+If standing up your project takes more than a package install — starting
+services, seeding fixtures, generating config — declare a single **`env-bootstrap`**
+entry in your runner file (a `Taskfile.yml` / `Makefile` target or a
+`package.json` script named `env-bootstrap`). When present, the agent surfaces
+it as the suggested first action at worktree/session stand-up (see the
+`using-git-worktrees` skill § 5) — **suggest-only, never auto-run**. This gives
+long-running work one deterministic stand-up entry instead of re-deriving it
+each session. Purely optional: with no entry, dependency install + a green
+baseline is the whole stand-up.
+
 #### User inbox workflow (`agents/tmp/` → `agents/tmp.old/`)
 
 Drop a note or draft into `agents/tmp/` and point a command at it

package/docs/decisions/ADR-002-kernel-bucket-overrides.md

@@ -1,3 +1,14 @@
+---
+adr: 002
+status: accepted
+date: 2026-05-06
+decision: kernel-bucket-overrides
+supersedes: —
+superseded_by: —
+phase: road-to-kernel-and-router · P2.2
+type: structural
+---
+
 # ADR-002 — Kernel-Bucket Cap Raise (25k → 26k) and Per-Rule Iron-Law Overrides
 
 - **Status:** Accepted (2026-05-06)

package/docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md

@@ -1,3 +1,14 @@
+---
+adr: 003
+status: accepted
+date: 2026-05-07
+decision: flat-cluster-subs-and-colon-syntax
+supersedes: —
+superseded_by: —
+phase: command-cluster contract (Phase 2 follow-up)
+type: structural
+---
+
 # ADR-003 — Flat Cluster Sub-Commands and Colon-Canonical Invocation
 
 - **Status:** Accepted (2026-05-07)

package/docs/decisions/ADR-006-skill-tools-python-pilot.md

@@ -5,7 +5,7 @@ date: 2026-05-09
 decision: skill-tools-python-pilot-pass
 supersedes: —
 superseded_by: —
-phase: road-to-better-skills-and-profiles · Block D (D1–D5)
+phase: road-to-better-skills-and-profiles · Block D (D1–D5) — historical: Python pilot; zero .py remains post-ADR-200
 ---
 
 # ADR-006 — Skill-Tools Python Pilot: Outcome and Decision

package/docs/decisions/ADR-028-root-layout.md

@@ -1,6 +1,6 @@
 ---
 adr: 028
-status: accepted
+status: superseded
 date: 2026-05-25
 decision: root-layout
 supersedes: —

package/docs/decisions/ADR-038-canonical-settings-path.md

@@ -1,3 +1,13 @@
+---
+adr: 038
+status: accepted
+date: 2026-06-01
+decision: canonical-settings-path
+supersedes: —
+superseded_by: —
+type: structural
+---
+
 # ADR-038: Canonical settings path is `agents/settings/.agent-settings.yml`
 
 - **Status:** Accepted