session-orchestrator 3.16.0 → 3.19.0

package/docs/session-config-reference.md

@@ -32,6 +32,35 @@ Validation runs automatically via `scripts/parse-config.mjs` → `scripts/valida
 
 Bypass via `SO_SKIP_CONFIG_VALIDATION=1`. Missing fields can be patched into an existing config file via `/bootstrap --retroactive`.
 
+## Parser Gotcha: No-Inline-Comment Block Headers
+
+**General contract, applies to every nested (block-shaped) Session Config key, not just the handful annotated below.** A top-level block key like `eval:`, `custom-phases:`, `moc-staleness:`, `context-coverage:`, or `worktree-orphans:` is opened by the shared bold-tolerant matcher `matchBlockHeader(line, key)` (`scripts/lib/config/block-header.mjs`) rather than by a per-key regex. As of the #830 generalisation, **38 files** under `scripts/lib/config/` import it — 37 block-shaped parsers (`auto-dream`, `broken-window`, `cold-start`, `config-protection`, `context-coverage`, `cross-repo`, `custom-phases`, `dialectic`, `discovery-validator`, `dispatcher-autonomy`, `dispatcher-autonomy-capture`, `docs-orchestrator`, `docs-staleness`, `drift-check`, `eval`, `events-rotation`, `evolve`, `frontend-slop-hook`, `gitlab-portfolio`, `handover-gate`, `loop-guard`, `memory`, `moc-staleness`, `persona-gate-wave`, `reconcile`, `skill-evolution`, `slopcheck`, `state-md-lock`, `templates-first`, `test`, `vault-integration`, `vault-mirror-quality`, `vault-staleness`, `vault-sync`, `verification-auto-fix`, `wave-reviewers`, `worktree-orphans`) plus `block-header.mjs` itself — confirmed via `grep -rln "matchBlockHeader" scripts/lib/config/ | wc -l` → `38`.
+
+**The matcher's accept/reject contract** (`matchBlockHeader(line, key)`, equivalent to the regex `^(?:-\s+)?(?:\*\*)?<key>:(?:\*\*)?\s*$`):
+
+| Form | Matches? |
+|---|---|
+| `key:` | ✅ plain header |
+| `- key:` | ✅ dash-bullet header |
+| `**key:**` | ✅ bold header |
+| `- **key:**` | ✅ dash-bullet + bold header |
+| `key: value` | ❌ a header carrying a value is not a block-opener |
+| `key:  # comment` | ❌ **the load-bearing gotcha** — a trailing inline comment on the header line itself |
+| `  key:` (indented) | ❌ this is a sub-key of some other block, not a top-level header |
+| `other-key:` | ❌ different key |
+
+**Why the inline-comment case matters more than it looks.** When a block-header line carries a trailing `# comment`, the matcher returns `false` for that line — the block-open scan never flips into "in-block" mode, so **every field under that key silently falls back to its default**. There is no error, no warning, no stderr output anywhere in the pipeline. The only symptom is a repo's opt-in feature quietly behaving as if it were never configured — exactly the class of bug this gotcha exists to prevent. Sub-key lines (`enabled:`, `mode:`, …) are unaffected — inline comments on THOSE lines parse fine; only the block-opener line itself is fragile.
+
+**The five keys carrying an explicit source-level warning comment today** (a strict subset of the 37 — every other block-shaped key has the identical failure mode, just without an inline reminder):
+
+- `eval:` — see § Eval (#803) below for the full parser-gotcha paragraph (learning confidence 0.9).
+- `custom-phases:` — see § Custom Phases (#637) below.
+- `moc-staleness:` — see § MOC Staleness (#831/B2) below.
+- `context-coverage:` — see § Context Coverage (#831/B4) below.
+- `worktree-orphans:` — see § Worktree Orphans (#831/B5) below.
+
+**Stale-citation note:** an older code comment on the `custom-phases:` key in this repo's own `CLAUDE.md` cites a per-key regex (`/^custom-phases:\s*$/`) as the mechanism. That citation predates the #830 generalisation — `custom-phases.mjs` (like all 37 consumers) now delegates to the shared `matchBlockHeader(line, 'custom-phases')`, which is strictly MORE tolerant than the old per-key regex (it additionally accepts the dash-bullet and bold-bullet renderings). The no-inline-comment failure mode is unchanged; only the underlying mechanism moved from a bespoke regex to the shared helper. Treat any remaining per-key regex citation in prose (including in this file, prior to this section's introduction) as documentation of the OLD mechanism — the general contract above is current.
+
 ## Policy Files
 
 Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
@@ -67,6 +96,24 @@ Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
 | `stale-branch-days` | integer | `7` | Days of inactivity before a branch is flagged as stale. |
 | `stale-issue-days` | integer | `30` | Days without progress before an issue is flagged for triage. |
 
+## Auto-Skill Dispatch (#337)
+
+Opt-in phrase-match meta-skill (`skills/using-orchestrator/SKILL.md`) that inspects the user's first message for implicit slash-command intent (e.g. "plane neues Projekt", "run discovery on the backlog") and dispatches to the highest-confidence matching entry-point skill via the `Skill` tool — before that skill's own Phase 1 — once the bootstrap gate is open. Off by default; when `false` (or absent) the meta-skill returns immediately with zero reads, zero logging, zero side effects, and every calling skill behaves exactly as if it was never invoked.
+
+This is a top-level SCALAR field — not a nested object — matching `vcs`, unlike most of the other opt-in features in this reference which live under a nested block.
+
+```yaml
+auto-skill-dispatch: false               # opt-in; default false preserves existing behavior
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `auto-skill-dispatch` | boolean | `false` | Master toggle. When `false`, `skills/using-orchestrator/SKILL.md` is a no-op — no message inspection, no phrase-map scoring, no dispatch. When `true`, every entry-point skill (per `skills/_shared/bootstrap-gate.md`) invokes the meta-skill once before its own Phase 1. |
+
+**Dispatch algorithm summary:** the meta-skill scores the user's first message against a bilingual (EN/DE) phrase map covering `/plan {new,feature,retro}`, `/session {housekeeping,feature,deep}`, `/discovery`, `/evolve`, `/close`, `/bootstrap`. Confidence tiers: exact slash-command match `0.95`, exact natural-language match `0.90`, substring match `0.60`, semantic near-miss `0.40`. Only scores ≥ `0.85` trigger a dispatch. When the top two candidates both score ≥ `0.85` with a delta < `0.15`, the meta-skill disambiguates via `AskUserQuestion` (per `.claude/rules/ask-via-tool.md` AUQ-003) rather than silently picking one. Below `0.85`, or with no candidates, the meta-skill returns silently and the calling skill's own routing logic takes over — the original user message is never rewritten before being passed to the dispatch target.
+
+**Used by:** `skills/using-orchestrator/SKILL.md` (the dispatch algorithm, full phrase map, and confidence-scoring table), `skills/_shared/bootstrap-gate.md` (the opt-in call site — invoked once per entry-point skill when the gate is open). Note: unlike most Session Config booleans documented in this file, `auto-skill-dispatch` has no dedicated parser module under `scripts/lib/config/` — it is read directly from the raw Session Config text by the calling skill's own Phase logic, the same pattern used for prose-level opt-in flags that never reach `scripts/parse-config.mjs`'s structured JSON output.
+
 ## Templates-First Hook (#519)
 
 Opt-out configuration for the PreToolUse `Bash` hook that blocks `gh|glab pr|mr|issue create` calls unless the matching repo template (`.github/PULL_REQUEST_TEMPLATE*`, `.github/ISSUE_TEMPLATE*`, `.gitlab/merge_request_templates/*`, `.gitlab/issue_templates/*`) was Read in the current session. Per-session acknowledgement is tracked in `.orchestrator/runtime/templates-acknowledged.json` — once a template is Read (or `/templates-ack` is invoked), the hook stops blocking for the remainder of the session. Mechanical replacement for gitlab-ops template advice. PRD gsd Pattern 3 / issue #519.
@@ -120,13 +167,36 @@ verification-auto-fix:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `discovery-on-close` | boolean | session-type aware: `false` for `housekeeping`, `true` for `feature`/`deep` (#264) | Run discovery probes automatically during `/close`. Default is `false` for housekeeping sessions and `true` for feature and deep sessions when not explicitly configured. An explicit value always overrides the session-type default. |
+| `discovery-on-close` | boolean | `true` for every session type | Run discovery probes automatically during `/close`. An explicit value always wins. Was session-type aware until 2026-07-29 (`false` for `housekeeping`, #264); measurement showed the probes are the system's main project-hygiene surface, so defaulting them off for the cleanup session type left it as the only one closing without hygiene diagnostics. Set `false` explicitly for a faster close. |
 | `discovery-probes` | list | `[all]` | Probe categories to run: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature`. |
 | `discovery-exclude-paths` | list | `[]` | Glob patterns to exclude from discovery scanning (e.g., `vendor/**`, `dist/**`). |
 | `discovery-severity-threshold` | string | `low` | Minimum severity for reported findings: `critical`, `high`, `medium`, `low`. |
 | `discovery-confidence-threshold` | integer | `60` | Minimum confidence score (0-100) for discovery findings to be reported. Findings below this threshold are auto-deferred. |
 | `discovery-parallelism` | integer | `5` | Maximum probe agents dispatched in parallel per category during Phase 3. Bounds: `1..16`; out-of-range values silently fall back to the default. Raise for large stacks to reduce wall-clock, lower to relieve a busy host. |
 
+## Issue Budget (per-session creation cap)
+
+Bounds how many issues ONE session may create. This is a **quantity** gate and is deliberately separate from `discovery-severity-threshold` / `discovery-confidence-threshold` above, which are per-finding **quality** filters: those two cannot bound volume (their `low` / `60` defaults filter almost nothing), they are only consulted in skill prose, and the largest producers — session-end carryover filing, `/plan` issue creation, `scripts/lib/spiral-carryover.mjs` — never read them at all.
+
+```yaml
+issue-budget:
+  max-per-session: 12          # integer >= 0; 0 blocks every non-exempt creation
+  mode: strict                 # strict | warn | off
+  overflow: collect-issue      # collect-issue | vault-note
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `issue-budget.max-per-session` | integer | `12` | Non-exempt issues one session may create before the cap bites. `0` is valid (blocks everything non-exempt). Malformed or negative values fall back to `12`. |
+| `issue-budget.mode` | string | `strict` | `strict` blocks over-cap creations (exit 2 from the hook) and parks them as overflow; `warn` allows them with a stderr notice; `off` disables the gate entirely (no counter is written). |
+| `issue-budget.overflow` | string | `collect-issue` | Where session-end drains parked creations. `collect-issue` files exactly ONE `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte` issue (`type::backlog`, `priority::low`) whose body is a checklist of the parked items; `vault-note` writes a single Markdown file under `vault/00-inbox/` instead. |
+
+**Exemptions (load-bearing).** `priority::critical`, the carryover class (`[Carryover]`, `[SPIRAL]`/`[FAILED]`, `type::carryover`, a bare `carryover` label) and `broken-window` closure issues bypass the cap unconditionally. Without those exemptions the cap would break the standing session-end promises in `skills/session-end/SKILL.md` (Phase 1.8 "non-deselectable" SPIRAL/FAILED carryover, and the Critical Rule "ALWAYS create issues for unfinished PLANNED work"). Exempt creations are counted in the state file's `exempt` field for observability but never blocked.
+
+**Counter file:** `.orchestrator/runtime/issue-budget.json` — `{ sessionId, count, exempt, overflow: [...] }`. It resets automatically when a new `sessionId` is seen.
+
+**Used by:** `hooks/pre-bash-issue-budget.mjs` (shell path, PreToolUse/Bash), `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), `scripts/lib/issue-budget.mjs` (shared decision core), `skills/session-end/SKILL.md` Phase 5 Step 3b (overflow drain). Parser: `scripts/lib/config/issue-budget.mjs`.
+
 ## Slopcheck (Package Legitimacy Gate) (#520)
 
 Opt-in defense against LLM-hallucinated package names ("slopsquatting"). When enabled, `classifyPackages(pkgs)` consults the registry and classifies each package as `LEGITIMATE` (exists, download count above threshold), `ASSUMED` (exists but very new / low downloads — warning, not block), `SUS` (audit warning hit — operator confirmation required), or `SLOP` (package not found in the registry — a possible LLM hallucination; hard block in plan-flow). Hooked into `/plan` PRD generation (Phase 3.5 Package-Audit) and `/discovery` supply-chain probes. Complementary to the always-on SEC-020 supply-chain baseline (`ignore-scripts=true`, `block-exotic-subdeps=true`, `minimum-release-age=1440`): SEC-020 prevents post-install execution of malicious packages; Slopcheck prevents adopting non-existent (typosquat-target) packages in the first place. PRD gsd Pattern 2 / issue #520.
@@ -157,7 +227,7 @@ slopcheck:
 | `learnings-surface-top-n` | integer | `15` | Cap on how many learnings the session-start Phase 5.6 and session-plan Step 0.5 sections surface, ranked by confidence descending. `0` = do not surface any learnings. Applies to Project Intelligence output. |
 | `learning-decay-rate` | float (0.0 ≤ x < 1.0) | `0.05` | Confidence decay applied to every untouched learning at session-end (after touched-set update, before prune). `0.0` = disable decay. A learning starting at `0.5` confidence survives ~10 untouched sessions with default decay. |
 | `enforcement` | string | `warn` | Hook enforcement level for scope and command restrictions: `strict`, `warn`, or `off`. |
-| `enforcement-gates` | object | null | Per-gate toggles for enforcement hooks. Keys: `path-guard`, `command-guard`, `post-edit-validate`. Values are booleans. Missing keys default to enabled. Example: `{ path-guard: true, command-guard: true, post-edit-validate: false }`. Combined with `enforcement` (which controls strict/warn/off globally). |
+| `enforcement-gates` | object | null | Per-gate toggles for enforcement hooks. Keys: `path-guard`, `command-guard`, `post-edit-validate`, `bash-write-guard`, `bash-write-verify`. Values are booleans. **Missing keys default to enabled — with one deliberate exception: `bash-write-guard` defaults to DISABLED** (see below). Example: `{ path-guard: true, command-guard: true, post-edit-validate: false }`. Combined with `enforcement` (which controls strict/warn/off globally). |
 | `allow-destructive-ops` | boolean | `false` | When `true`, disables the main-session destructive-command guard (`hooks/pre-bash-destructive-guard.mjs`). Set to `true` for intentional maintenance sessions that need `git reset --hard`, `rm -rf`, etc. Defaults to `false` (safe). See issue #155 and `.claude/rules/parallel-sessions.md` (PSA-003). Example: `allow-destructive-ops: true` |
 | `reasoning-output` | boolean | `false` | Enable STATE:/PLAN: structured reasoning markers in agent prompts. When true, agents emit short transparency lines before tool calls. Opt-in — adds prompt overhead. |
 | `grounding-check` | boolean | `true` | Enable file-level grounding verification in session-end Phase 1.1a (planned vs touched files). When true, session-end compares each agent's declared file scope against `git diff --name-only $SESSION_START_REF..HEAD` and reports scope creep + incomplete coverage. Informational — does not block session close. |
@@ -166,6 +236,113 @@ slopcheck:
 | `max-turns` | integer or string | `auto` | Maximum agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
 | `auto-commit-per-wave` | boolean | `false` | Automatically commit each wave's work after the Quality-Lite gate passes. Checkpoint commits per wave reduce the risk of data loss from `git stash` collisions in parallel sessions (V3.3 RESCUE incident — see GitLab #214). When `false`, all work is committed at session-end via `/close`. Requires `persistence: true`; the flag is silently ignored when `persistence: false`. Trade-off: each wave produces an additional commit; git log shows N+1 commits instead of 1. Use `/simplify` or `git rebase -i --autosquash` before final close to squash if a clean history is desired. **Implementation note:** the procedural commit sequence (`scripts/lib/auto-commit.mjs`) is deferred to V3.6. Until then, setting this flag to `true` triggers a session-start warning that auto-commits are not yet active — the flag is a no-op but is validated so projects can opt in early. |
 
+### enforcement-gates: the five gate keys (#800/#915)
+
+`enforcement-gates` is surfaced to the hook layer as `gates` inside the wave's
+`wave-scope.json`. Five keys are read today:
+
+| Gate key | Hook | Event | Default when the key is ABSENT | Effect |
+|----------|------|-------|-------------------------------|--------|
+| `path-guard` | `hooks/enforce-scope.mjs` | PreToolUse `Edit\|Write\|MultiEdit` | **enabled** | Denies (strict) / warns (warn) on a file path outside `allowedPaths`. |
+| `command-guard` | `hooks/enforce-commands.mjs` | PreToolUse `Bash` | **enabled** | Denies (strict) / warns (warn) on a blocked command pattern. |
+| `post-edit-validate` | `hooks/post-edit-validate.mjs` | PostToolUse `Edit\|Write` | **enabled** | Per-file validation after a successful edit. |
+| `bash-write-guard` | `hooks/enforce-commands.mjs` | PreToolUse `Bash` | **DISABLED — inverted default** | Warn-only; parses likely shell write targets out of the command and warns for each one outside `allowedPaths`. |
+| `bash-write-verify` | `hooks/post-bash-write-verify.mjs` | PostToolUse `Bash` | **enabled** | Warn-only; observes the actual working-tree delta after a Bash call and reports files changed outside `allowedPaths`. |
+
+**`bash-write-guard` is the one gate whose missing key means OFF.** Every other
+key follows "absent → enabled", so a reader who has internalised that convention
+will assume a repo without an explicit entry is covered. It is not. The hook
+requires `gates['bash-write-guard'] === true` **literally** —
+`enforce-commands.mjs` tests for the boolean `true`, not for "not false".
+
+That silent assumption is why this row exists at all (#915): the gate shipped in
+#800, was documented nowhere for two releases, and consequently ran in zero
+sessions while the enforcement layer was believed to cover Bash writes. It does
+not by default — and `enforce-scope.mjs` gates only `Edit`/`Write`/`MultiEdit`,
+so a plain `echo x > out-of-scope.mjs` passes every PreToolUse path check.
+
+The inverted default is deliberate, not an oversight: parsing write targets out
+of an arbitrary shell command is heuristic (quoting, `>$VAR`, process
+substitution, heredocs), so a false positive is cheap to produce. Measured over
+2 528 real Bash calls from 41 archived sessions of this repo, the parser flagged
+56 calls (2.22 %) — of which the majority were parse artefacts (`EOF`, `{`,
+`0.3`) that never touched the filesystem. Keeping it opt-in until that rate is
+driven down is correct; leaving it undocumented was not.
+
+`bash-write-verify` (#915) is the complementary, non-heuristic half: it reports
+what the filesystem actually shows rather than what the command appeared to say,
+which is why it can default to enabled. It is warn-only and cannot block — a
+PostToolUse hook fires after the command already ran. Its purpose is to produce
+the evidence needed to flip `bash-write-guard` to `true` with confidence. See
+§ Bash-Write Verify below.
+
+## Bash-Write Verify (PostToolUse Bash diff, #915)
+
+`hooks/post-bash-write-verify.mjs` closes the observability half of the Bash
+bypass class. After every `Bash` tool call it runs
+`git --no-optional-locks status --porcelain -z`, subtracts a baseline snapshot
+taken on the previous invocation, and reports paths that appeared or changed
+**outside** the wave's `allowedPaths`.
+
+Properties that matter:
+
+- **Warn-only, always.** stderr line plus a PostToolUse `additionalContext`
+  string. Never a deny; PostToolUse cannot block a command that already ran.
+- **Delta, not absolute.** Reporting the whole dirty tree on every call would
+  fire on every Bash call for the rest of the session once a single file is
+  edited. Only paths that are new *relative to the previous Bash call* are
+  reported, and each path is reported **once**.
+- **Silent re-baseline.** First call of a session, and any call after the wave's
+  `allowedPaths` change, records the current dirty set without warning — that
+  dirt was not caused by the call being observed.
+- **Snapshot lives outside the repo** (`$TMPDIR/so-bash-write-verify/<hash>.json`),
+  so the guard can never report its own bookkeeping.
+- **Ignore list is part of the contract**, not an implementation detail — see
+  the table in the hook's header comment. It covers sibling-hook writes under
+  `.orchestrator/`, coordinator status files under `.claude/`/`.codex/`/`.cursor/`/`.pi/`,
+  package-manager artefacts (`node_modules/`, lockfiles), build/coverage output,
+  and `tmp+rename` residue (`*.tmp*`). These are mostly `.gitignore`d in this
+  repo, but the guard must not depend on a consumer repo's `.gitignore` being
+  complete.
+
+**Measured cost and noise.** All figures below were measured on 2026-07-30
+against this repo at 1 507 tracked files (`git ls-files | wc -l`); the corpus is
+this repo's 51 archived Claude Code transcripts (the per-project `*.jsonl`
+files under the host-local Claude Code projects directory), of which 41 contain
+at least one `Bash` tool call.
+
+| Metric | Value |
+|--------|-------|
+| Hook end-to-end, per Bash call | **94.8 ms** (10 runs, wall clock) |
+| …of which node cold start (paid by every hook process anyway) | ~67 ms — an existing PreToolUse Bash hook, `enforce-commands.mjs`, measures 66.9 ms on the same loop |
+| …marginal cost of the `git status` this hook adds | **~28 ms** |
+| `git … status --porcelain -z --untracked-files=all` | 25.0 ms/call (`--untracked-files=normal` measured 28.7 ms — `all` is not the slower option here, because the expensive subtrees are `.gitignore`d) |
+| Bash calls in the corpus | 2 528 |
+| Calls containing any write construct at all | 732 (29.0 %) |
+| Calls writing a real in-repo, non-ignored path | **23 (0.91 %)** |
+| Distinct such paths per session | **median 1, max 5** |
+
+So a typical session sees ~1 warning and a worst-case session sees 5. Two
+design choices produce that number rather than the naive one: the ignore list,
+and — more importantly — report-once. Without report-once the guard emits a
+line on *every* Bash call from the first out-of-scope write to the end of the
+session, because `git status` reports the cumulative dirty tree, not a delta.
+
+Live cross-check on the session that added this hook: with a 29-entry
+`allowedPaths` union, the snapshot recorded **0** out-of-scope paths — i.e. zero
+warnings across the session's Bash calls.
+
+**Turning it off:** `enforcement-gates: { bash-write-verify: false }`, or
+`enforcement: off`, or the standard `SO_DISABLED_HOOKS=post-bash-write-verify`
+profile-gate env var.
+
+**Making it bite.** This hook can never become blocking — the escalation path is
+to flip `bash-write-guard` (PreToolUse, *can* deny) to `true` once its
+false-positive rate has been measured down. Prerequisite before that flip: a
+session's worth of `bash-write-verify` warnings compared against the same
+session's `bash-write-guard` warnings, showing the parser produces no warning
+that the filesystem diff does not confirm.
+
 ## STATE.md Lock (#518)
 
 Mechanical write-lock around STATE.md that prevents race conditions between parallel worker sessions (or parallel wave-executor checkpoints within one session) writing the same file. When enabled, `withStateMdLock(repoRoot, fn)` acquires `.orchestrator/state.lock` via atomic tmp-file + rename before invoking `fn`, and releases on completion or throw. A stale lock (holder PID no longer alive, or heartbeat expired) is overridden atomically with a WARN on stderr; genuine contention past `timeout-ms` returns `{ ok: false, reason: 'timeout' }` to the caller. This mechanically enforces PSA-003/PSA-004 (Destructive Action Safeguards / Commit Discipline) for STATE.md specifically — the race condition becomes structurally impossible rather than merely discouraged. PRD gsd Pattern 1 / issue #518.
@@ -303,6 +480,19 @@ Independent of isolation choice, wave-executor now persists a per-worktree meta
 
 This guard converts the manual post-copy `git diff` check (used to rescue the 07:30 and 09:00 regressions) into a coded pre-copy gate. The check is non-blocking on `pass` / `warn` / `no-meta`; only `block` interrupts the wave.
 
+### Heavy-Repo Preflight (HR-003/HR-004, baseline #60)
+
+`templates/shared/.claude/rules/heavy-repo.md` documents two Session Config fields for repos large enough that default parallelism risks resource pressure (HR-001 indicators: checkout > 50 MB, DB surface > 100 tables, prior parallel agent count > 15, build time > 90s, generated artifacts > 200 MB). Both fields are now wired end-to-end (previously documented but silently dropped by the parser):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `heavy-repo` | boolean | `false` | Marks the repo as heavy per HR-001. When `true`, `scripts/lib/resource-probe/evaluate.mjs` and `scripts/lib/wave-resource-gate.mjs` apply a STATIC preflight ceiling: `recommended_agents_per_wave_cap` / dispatched `agents` are clamped to at most `agents-per-wave`, REGARDLESS of the live resource-probe verdict. When `agents-per-wave` uses the parenthetical override syntax (e.g. `4 (deep: 18)`), the parsed value is an object `{default, <mode>: N}`, not a plain number — both modules resolve that shape to `.default` (no session-mode input is in scope at the gate), so the cap is never silently skipped for overridden repos. More-restrictive-wins: a resource-driven `reduce`/`coordinator-direct` that already computed a tighter number is never loosened by this cap — it only ever lowers, never raises, the dispatched agent count. `validateSessionConfig()` (`scripts/lib/config-schema.mjs`) also emits a warn-level cross-field finding when `heavy-repo: true` and `isolation` is `auto` or `none` — heavy repos should pin `isolation: worktree` (HR-003 anti-pattern). |
+| `worktree-cleanup` | string | `default` | One of `default` \| `aggressive`. HR-003 recommends `aggressive` for heavy repos (clean up worktrees immediately after each wave, no cross-wave retention). **Honesty note:** `aggressive` currently behaves identically to `default` at runtime — the parser accepts and returns the value, but the per-wave aggressive sweep into `worktree-cleanup.mjs`/`worktree-sweep.mjs` is a tracked follow-up, not yet implemented. Setting this field today documents intent; it does not yet change wave-executor's cleanup cadence. |
+
+Session-start Phase 4.5 (`skills/session-start/phase-4-5-resource-health.md`) passes `heavy-repo` and `agents-per-wave` through to `evaluate()` and renders `⚠ Heavy-repo mode active — agents-per-wave capped to N (Session Config heavy-repo: true)` when the ceiling actually reduces the recommendation, per HR-004.
+
+The heavy-repo cap applies only on the resource-aware path: it runs inside `applyDecisionRules()`/`evaluate()`, both gated behind `resource-awareness` being enabled (the default). Setting `resource-awareness: false` is a FULL opt-out — it skips the live probe AND bypasses the HR-004 static cap, even when `heavy-repo: true` is also set.
+
 ## Planning
 
 | Field | Type | Default | Description |
@@ -451,7 +641,7 @@ vault-integration:
 | `vault-integration.enabled` | boolean | `false` | If true, session-end and evolve skills invoke `vault-mirror.mjs` to sync learnings and sessions into the vault. When false (or missing), mirroring is skipped silently. |
 | `vault-integration.vault-dir` | string or null | `null` | Absolute path to the vault repository. Falls back to `$VAULT_DIR` env variable if not set. Required when `enabled` is true. |
 | `vault-integration.mode` | string | `warn` | Mirror error handling. `strict` blocks session close if the mirror exits non-zero. `warn` reports errors but does not block. `off` bypasses mirror invocation entirely (useful when transitioning). |
-| `vault-integration.vault-name` | string or null | `null` | Optional override for the per-project vault namespace segment (#660). When set (or via CLI `--vault-name`), vault writes go to `40-learnings/<vault-name>/` and `50-sessions/<vault-name>/`, sanitised to a kebab slug. When null/absent, the namespace is derived from the git origin via `deriveRepo()`. Owner-privacy leaks (personal home path / private slug / personal name) are redacted to `redacted-repo`. NOT a filesystem path → NOT host-path-resolved. Resolver: `scripts/lib/vault-mirror/namespace.mjs` (`resolveRepoNamespace`). |
+| `vault-integration.vault-name` | string or null | `null` | Optional override for the per-project vault namespace segment (#660). When set (or via CLI `--vault-name`), vault writes go to `40-learnings/<vault-name>/` and `50-sessions/<vault-name>/`, sanitised to a kebab slug. When null/absent, the namespace is derived from the git origin via `deriveRepo()`. Owner-privacy leaks (personal home path / private slug / personal name) are redacted to `redacted-repo`. NOT a filesystem path → NOT host-path-resolved. **Coverage gap:** portfolio board rows are NOT yet namespace-aware — the override only reaches `40-learnings/`, `50-sessions/`, and the per-repo narrative mirror (`narrative-mirror.mjs`, #832 item 2); tracked separately in #832. Resolver: `scripts/lib/vault-mirror/namespace.mjs` (`resolveRepoNamespace`). |
 | `vault-integration.gitlab-groups` | string[] or null | `null` | List of GitLab group paths to scan for repos missing `.vault.yaml`. Consumed by `scripts/vault-backfill.mjs` (via `readVaultIntegrationConfig()`) and the `/plan retro` vault-backfill sub-mode (`skills/plan/mode-retro.md` Phase 1.6 Step 1). When null/unset, the backfill CLI exits with a "no groups configured" notice. |
 
 ### Environment override: `VAULT_MIRROR_CANONICAL_SUFFIX`
@@ -651,7 +841,7 @@ handover-gate:
 
 ## Broken-Window Budget (#730/H5)
 
-Opt-in configuration for the Broken-Window Budget in `/close`. When enabled, session-end Phase 2.6 aggregates THIS session's "knowingly-broken shipments" — echo-stub findings that shipped under `enforcement: warn`, "Override and close" choices in Phase 2.3 / 2.5, MED/LOW review findings routed to "Unresolved Review Findings" (#617), and wave-level reviewer findings overridden without a fix task — and files ONE hard-terminated closure issue per item (labels `broken-window` + `priority:high`, with a hard due-date). It also emits `orchestrator.finding.overridden` events feeding the `effectiveness.override_ratio` metric. Non-blocking and idempotent: a filing failure is a WARN and re-running a close never duplicates issues.
+Opt-in configuration for the Broken-Window Budget in `/close`. When enabled, session-end Phase 2.6 aggregates THIS session's "knowingly-broken shipments" — echo-stub findings that shipped under `enforcement: warn`, "Override and close" choices in Phase 2.3 / 2.5, MED/LOW review findings routed to "Unresolved Review Findings" (#617), and wave-level reviewer findings overridden without a fix task — and files ONE hard-terminated closure issue per item (labels `broken-window` + `priority::high`, with a hard due-date). It also emits `orchestrator.finding.overridden` events feeding the `effectiveness.override_ratio` metric. Non-blocking and idempotent: a filing failure is a WARN and re-running a close never duplicates issues.
 
 All fields live under a top-level `broken-window-budget` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
@@ -695,6 +885,8 @@ dialectic:
 
 **Token cost:** With defaults (cadence: 5, budget-tokens: 8000, output 4000, model haiku), ~12k tokens every 5 sessions. At haiku pricing this is ~$0.02/run. Surfaced in Final Report.
 
+**Empirical note (2026-07-04 session-3) — the parser default of `8000` proved structurally unreachable for this repo's own peer-card/steering corpus.** Fixed overhead (Peer-Cards + Steering + scaffold) alone runs ≈13k tokens, and a full input set (top-50 learnings + last-10 sessions) runs ≈28.4k tokens — both already exceed the `8000` default before any call is made. This repo's own committed Session Config therefore sets `budget-tokens: 32000`, not the documented default. If your repo accumulates a similarly large peer-card/steering corpus over time, raise `budget-tokens` accordingly rather than leaving the low default in place — a too-low budget silently truncates the dialectic critique input rather than erroring.
+
 ## Eval (#803)
 
 Opt-in configuration for the Standard v1 evaluation harness (aiat-llm-eval PRD, `docs/prd/2026-07-16-aiat-llm-eval.md` §S6) and the forthcoming `/eval` skill (Session-Prozess-Eval — lands in a later wave of Epic #803). This section documents the config surface only; the skill that reads it is not yet shipped as of this parser's introduction.
@@ -718,7 +910,7 @@ eval:
 | `eval.report` | string | `html` | Report artifact format. Must be one of `html`, `none`. **Fail-fast** on an unknown value, same as `eval.mode`. |
 | `eval.handle` | string \| `null` | `null` | Optional free-text handle/label for the eval run. Absent, empty, or whitespace-only values all collapse to `null` (never an empty string). |
 
-**Parser gotcha (learning confidence 0.9 — mirrors `custom-phases:` and `dialectic:`):** the `eval:` key-line itself MUST NOT carry an inline comment. The block-open scan uses the strict regex `/^eval:\s*$/`; a trailing `# comment` on that exact line fails the match, so the parser never enters the block and ALL fields silently fall back to their defaults — no error, no warning surfaces anywhere. Sub-key lines (`enabled:`, `mode:`, …) tolerate inline comments without issue.
+**Parser gotcha (learning confidence 0.9 — mirrors `custom-phases:` and every other block-shaped key):** the `eval:` key-line itself MUST NOT carry an inline comment. The block-open scan uses the shared `matchBlockHeader(line, 'eval')` (`scripts/lib/config/block-header.mjs`) — it tolerates the bold-bullet `- **eval:**` rendering (#830) but a trailing `# comment` on the header line still fails the match, so the parser never enters the block and ALL fields silently fall back to their defaults — no error, no warning surfaces anywhere. Sub-key lines (`enabled:`, `mode:`, …) tolerate inline comments without issue. See § Parser Gotcha: No-Inline-Comment Block Headers (top of this file) for the general contract this key shares with 36 other block-shaped keys.
 
 **Used by:** `scripts/lib/config/eval.mjs` (`_parseEval`), `scripts/lib/config.mjs`. Skill consumer (`skills/eval/SKILL.md`) is a follow-up wave of Epic #803 — not yet implemented as of this parser.
 
@@ -785,6 +977,71 @@ docs-staleness:
 
 **Used by:** `skills/discovery/probes/docs-staleness.mjs` (`runProbe`), `scripts/lib/config/docs-staleness.mjs` (`_parseDocsStaleness`). Writes one JSONL summary record per run to `.orchestrator/metrics/docs-staleness.jsonl`. See `docs/README.md` for the living-vs-archived docs classification this probe enforces.
 
+## MOC Staleness (#831/B2)
+
+Opt-in session-start banner probe for Obsidian "map of content" index notes — `<vault>/08-topics/*-moc.md` whose frontmatter `updated:` is older than the threshold. Complements `vault-staleness` (which covers project narratives) by covering the topic index layer. Rendered at session-start Phase 4 alongside the other banners; never blocks a session.
+
+```yaml
+moc-staleness:
+  # Parser gotcha: this key line must carry NO inline comment (§ Parser Gotcha: No-Inline-Comment Block Headers, top of this file).
+  enabled: false                       # opt-in
+  thresholds:
+    moc: 90                            # days — frontmatter `updated:` staleness threshold
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `moc-staleness.enabled` | boolean | `false` | Must be explicitly `true` to activate. The gate fails CLOSED — a missing block, a missing `enabled` key, or an omitted `config` argument all return `null` before any filesystem I/O. |
+| `moc-staleness.thresholds.moc` | integer (days) | `90` | Age threshold measured against frontmatter `updated:`. Non-numeric or non-positive values fall back to the default. |
+| `moc-staleness.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+A MOC whose `updated:` is **missing or unparseable is deliberately EXCLUDED**, not reported as stale — the corrective action there is "fix the frontmatter", not the banner's own hint. Same rule as `scripts/lib/peer-cards/staleness-banner.mjs`.
+
+**Used by:** `scripts/lib/moc-staleness-banner.mjs` (`checkMocStaleness`), `scripts/lib/config/moc-staleness.mjs` (`_parseMocStaleness`). Wired at `skills/session-start/SKILL.md` Phase 4.
+
+## Context Coverage (#831/B4)
+
+Opt-in session-start coverage banner: registered `<vault>/01-projects/<slug>/` folders that carry **neither** `context.md` nor `_passive.md`. A project counts as *registered* iff its folder contains `_overview.md` — the same convention `discoverVaultRepos()` uses (`scripts/lib/gitlab-portfolio/vcs-detect.mjs`). Folders lacking `_overview.md` are never counted and never reported as gaps.
+
+```yaml
+context-coverage:
+  # Parser gotcha: this key line must carry NO inline comment (§ Parser Gotcha: No-Inline-Comment Block Headers, top of this file).
+  enabled: false                       # opt-in
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `context-coverage.enabled` | boolean | `false` | Must be explicitly `true` to activate. Fails CLOSED, as above. |
+| `context-coverage.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+**Used by:** `scripts/lib/context-coverage-banner.mjs` (`checkContextCoverage`), `scripts/lib/config/context-coverage.mjs` (`_parseContextCoverage`). Wired at `skills/session-start/SKILL.md` Phase 4.
+
+## Worktree Orphans (#831/B5)
+
+Opt-in session-end sweep (Phase 4b) identifying git worktree branches with **0 commits ahead of the base branch** — leftovers from finished sessions. The module **proposes; it never disposes**: it returns `candidates` and the coordinator renders the removal AUQ. Nothing is removed without explicit operator confirmation (PSA-003).
+
+```yaml
+worktree-orphans:
+  # Parser gotcha: this key line must carry NO inline comment (§ Parser Gotcha: No-Inline-Comment Block Headers, top of this file).
+  enabled: false                       # opt-in
+  base-branch: main                    # ref the ahead-count is measured against
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `worktree-orphans.enabled` | boolean | `false` | Must be explicitly `true` to activate. Fails CLOSED — a repo that never opted in pays no git invocation. |
+| `worktree-orphans.base-branch` | string | `main` | Ref the ahead-count is measured against. **Validated:** a value beginning with `-`, or containing whitespace or shell metacharacters, is rejected and falls back to `main`. |
+| `worktree-orphans.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+**Why `base-branch` is validated rather than passed through.** It reaches an argv position in `git rev-list --count <base>..<branch>`. A value shaped like a git flag (e.g. `--glob=refs/heads/*`) is parsed as an OPTION rather than a revision range, exits 0, and prints `0` — silently marking **every** worktree as a 0-ahead orphan and offering the operator a deletion prompt for worktrees full of live work. The conservative default does not catch it, because `0` parses fine. Defence is two-layer: the parser rejects leading-dash values, and the sink passes `--end-of-options` so any surviving payload becomes a hard git error. This makes `base-branch` a **fifth command-influencing Session Config surface** beyond the four listed in `.claude/rules/security.md` § "Session Config Command Trust" — and unlike those, no attacker is required: a typo reaches the same outcome.
+
+A worktree holding uncommitted, staged or untracked work is **never** a candidate — `isWorktreeClean()` (the Phase 4a helper) is consulted first, and any git error while checking excludes the worktree conservatively.
+
+**Used by:** `scripts/lib/session-end/worktree-orphan-sweep.mjs` (`checkWorktreeOrphans`), `scripts/lib/config/worktree-orphans.mjs` (`_parseWorktreeOrphans`, `_isSafeBaseBranch`). Wired at `skills/session-end/SKILL.md` Phase 4b.
+
 ## Docs Orchestrator
 
 Opt-in configuration for the `docs-orchestrator` skill, which generates audience-split documentation (User / Dev / Vault) within sessions (see `skills/docs-orchestrator/SKILL.md`). When enabled, session-start runs a Phase 2.5 docs-context step, session-plan assigns a Docs role, and session-end runs a Phase 3.2 gap-reporting step. The `docs-writer` agent is made available automatically when `enabled: true`.
@@ -859,6 +1116,8 @@ test:
 
 Opt-in, repo-declared deterministic phases that run as their own phase during session close (and/or housekeeping). Where the freeform `special:` key gives no execution guarantee, `custom-phases` is a **contract**: each phase runs a deterministic `command` via Bash with exit-code gating and summary reporting, so a repo can run a domain command (e.g. an eval-learn aggregate) as a first-class close step. Absent/empty ⇒ `[]` ⇒ no custom phases run; existing sessions are unaffected.
 
+**Parser gotcha:** like every other block-shaped Session Config key, the `custom-phases:` key-line itself MUST NOT carry an inline comment — see § Parser Gotcha: No-Inline-Comment Block Headers (top of this file) for the general `matchBlockHeader` contract. A trailing `# comment` on that exact line means the parser never enters the block and `custom-phases` silently resolves to `[]` — no error, no warning.
+
 The block is a YAML list under a top-level `custom-phases` key:
 
 ```yaml
@@ -926,6 +1185,7 @@ reconcile:
   confidence-floor: 0.5    # min learning confidence before a learning is eligible
   min-rule-days: 7         # floor on emitted expires-at so a rule is never born-dead
   min-insight-chars: 24    # reject placeholder/minimal insights before rule conversion
+  max-proposals-per-run: 10 # volume brake — cap on proposals minted per engine run
 ```
 
 | Field | Type | Default | Description |
@@ -937,6 +1197,7 @@ reconcile:
 | `reconcile.confidence-floor` | float | `0.5` | Minimum learning confidence (0.0..1.0) required before a learning is eligible for a rule proposal. Learnings with `confidence < confidence-floor` are skipped by the engine. Bounds: `0.0 ≤ value ≤ 1.0`; out-of-range values silently fall back to `0.5`. Set to `0.0` to surface proposals for all learnings regardless of confidence. |
 | `reconcile.min-rule-days` | integer | `7` | Floor (in days) applied to the emitted rule's `expires-at` — issue #741.1. A learning close to its natural per-type TTL expiry could otherwise generate a rule that expires almost immediately ("born-dead"); `computeExpiresAt()` (`scripts/lib/reconcile/emitter.mjs`) floors the result at `now + min-rule-days` so an approved rule always has at least this many days of active life. Mirrors the hardcoded `MIN_RULE_DAYS_DEFAULT` constant in the emitter. Bounds: positive integer; non-finite or ≤0 values fall back to the default. |
 | `reconcile.min-insight-chars` | integer | `24` | Minimum `insight` length (characters) required before a learning is eligible for rule conversion — issue #741.2. Opt-in and additive to the always-on placeholder/empty-insight rejection in `classifyLearning()` (`scripts/lib/reconcile/eligibility.mjs`): a non-empty but too-short insight (e.g. a stub or a recovery placeholder) is rejected with reason `placeholder-insight` before it reaches proposal generation. Set to `0` to disable the length check (only the always-on empty/placeholder-regex check applies). |
+| `reconcile.max-proposals-per-run` | integer | `10` | Volume brake — issue #900 D. After the eligibility filter runs, `runReconcile()` (`scripts/lib/reconcile/engine.mjs`) sorts eligible learnings by confidence DESC and proposes at most this many per run; the rest are recorded as `capped` rejections (visible in `summary.capped` and each carrying a `capped — ...` reason) rather than silently dropped. Both production call sites — the session-end Phase 3.6.8 dispatcher (`decideReconcile()` in `scripts/lib/session-end/phase-skip.mjs`) and the on-demand `/reconcile` command (`skills/reconcile/SKILL.md`) — forward this Session Config value to `runReconcile()` as `maxProposalsPerRun`. The brake is **always active** even beyond that: a caller that omits the parameter entirely (e.g. a direct programmatic `runReconcile()` call) still gets the engine's own internal default, which mirrors the Session Config parser's default of `10`. Bounds: positive integer (≥ 1); malformed, absent, or non-positive values fall back to `10`. |
 
 ### Never-always-on invariant
 
@@ -966,7 +1227,7 @@ Session-end Phase 3.7a is the **only writer** of these fields. Session-start Pha
 | Field | Type | Value range | Description |
 |-------|------|-------------|-------------|
 | `recommended-mode` | string | `housekeeping` \| `feature` \| `deep` \| `discovery` \| `evolve` \| `plan-retro` | v0 heuristic output: suggested mode for the next session. |
-| `top-priorities` | integer[] | 0–5 entries | Carried-over issue IIDs, pre-sorted (priority:critical/high first, FIFO tiebreak). |
+| `top-priorities` | integer[] | 0–5 entries | Carried-over issue IIDs, pre-sorted (priority::critical/high first, FIFO tiebreak). |
 | `carryover-ratio` | float | `0.00`–`1.00` | `carryover_count / planned_issues` (0 when planned=0). Rounded to 2 decimals. |
 | `completion-rate` | float | `0.00`–`1.00` | `completed_issues / planned_issues`. Rounded to 2 decimals. |
 | `rationale` | string | ≤ 120 chars, single line | Which v0 rule branch fired (e.g. `"v0: completion <50% → retro"`). |
@@ -1094,6 +1355,15 @@ allow-config-weakening: false          # per-session bypass (mirrors allow-destr
 
 Always-on directive-budget banner. At session-start Phase 4 the probe (`scripts/lib/instruction-budget-guard.mjs`, `checkInstructionBudget`) sums the structural directives (bullets, ordered items, headings ≥ depth 2 — fenced code and YAML frontmatter excluded) across the always-on `.claude/rules/*.md` files (membership delegated to `rule-loader.mjs`; glob-scoped rules excluded) and renders a **warn-only / non-blocking** banner when the total **exceeds** `ceiling`. It is a *growth-ratchet*: the current baseline (~457 structural directives across 11 always-on rules) sits under the default ceiling of `480`, so the banner is silent today and only fires when NEW always-on directives push the count over the ceiling — "mechanism over discipline". Default ON (this is a guard, not an opt-in feature) — set `enabled: false` or `mode: off` to silence it.
 
+**Two axes, not one (#931a).** Since the byte dimension shipped in #877 it was measured but never judged: `overBudget` followed from the directive count alone, and the banner text never named a byte. It now reads `overDirectiveBudget || overByteBudget`, and the banner names only the axis that actually broke (re-sorting the top-files list by bytes when bytes were the trigger, because the count ordering points at the wrong file).
+
+| Key | Default | Meaning |
+|---|---|---|
+| `instruction-budget.ceiling` | `480` | Structural-directive ceiling. Baseline ~457, i.e. +5% headroom. |
+| `instruction-budget.byte-ceiling` | `114000` | Byte ceiling over the same always-on corpus. Baseline 108,589 measured 2026-07-30, i.e. the same +5% headroom — the two axes are calibrated alike so neither is accidentally the stricter one. |
+
+Why both: a 9 KB prose rule carrying three bullets is nearly invisible to the directive count while consuming real prompt payload. Why the headroom rather than the measured value: a ceiling that reddens the current state is switched off within a session and then measures nothing.
+
 All fields live under a top-level `instruction-budget` object inside the `## Session Config` block of your host file (`CLAUDE.md` or `AGENTS.md`):
 
 ```yaml
@@ -1163,6 +1433,7 @@ SO_DISABLED_HOOKS=enforce-scope,enforce-commands claude ...
 | `enforce-commands` | PreToolUse/Bash |
 | `enforce-scope` | PreToolUse/Edit\|Write |
 | `post-edit-validate` | PostToolUse/Edit\|Write |
+| `post-bash-write-verify` | PostToolUse/Bash |
 | `on-stop` | Stop + SubagentStop |
 
 ### Implementation
@@ -1292,6 +1563,31 @@ autopilot:
 
 **Feature introduced by:** GitLab issue #431 (CC 2.1.143 `worktree.bgIsolation` changelog adoption). Implementation: `scripts/autopilot-multi.mjs` reads `config?.autopilot?.['bg-isolation']` via `scripts/parse-config.mjs`. Documentation: `skills/autopilot/SKILL.md` § Configuration.
 
+## Wave Reviewers
+
+Opt-in inter-wave architecture/QA/PRD audit dispatch. When configured, wave-executor's `### 5a. Persona-reviewer dispatch` step (Impl-Core and Impl-Polish waves only — Discovery, Quality, and Finalization are skipped) fans out the named code-oriented reviewer agents in parallel with read-only scope after the wave's own work completes. Findings are **advisory only** — a `WARN` or `FAIL` never blocks the wave; it is surfaced in the wave progress summary and fed into the next wave's agent assignments, or logged as an overridden Deviation (#730/H5) when not actioned.
+
+All fields live under a top-level `wave-reviewers` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
+
+```yaml
+wave-reviewers:
+  enabled: false            # opt-in inter-wave architecture/QA/PRD audits
+  reviewers: []             # ["architect-reviewer", "qa-strategist", "analyst"]
+  mode: warn                # warn | strict | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `wave-reviewers.enabled` | boolean | `false` | Master toggle. Absent, `false`, or an empty `reviewers` array all resolve to the same no-op — the dispatch step is skipped entirely and the wave loop proceeds exactly as before. |
+| `wave-reviewers.reviewers` | string[] | `[]` | Reviewer agent names to dispatch in parallel. Plugin-provided values: `architect-reviewer`, `qa-strategist`, `analyst`. Custom reviewer agents under `agents/` are also valid if their `name` frontmatter matches. Each name is dispatched via `Agent({ subagent_type: "session-orchestrator:<reviewer-name>", ... })` with read-only scope. |
+| `wave-reviewers.mode` | string (`warn` \| `strict` \| `off`) | `warn` | Parsed but currently only `enabled` + a non-empty `reviewers` array gate the dispatch step in `skills/wave-executor/wave-loop.md`; `mode` is reserved for future escalation behaviour (e.g. blocking on `FAIL`). |
+
+**Deprecated alias:** `persona-reviewers` is accepted as a backward-compatible alias. When only `persona-reviewers` is present, its values are used and a deprecation WARN is emitted to stderr; when both keys are present, `wave-reviewers` wins and the WARN still fires. Issue #461/#478.
+
+**Distinct from `persona-gate-wave`** (below): `wave-reviewers` dispatches code-oriented reviewer agents (`architect-reviewer`, `qa-strategist`, `analyst`) that judge implementation correctness; `persona-gate-wave` dispatches catalog domain/buyer/audit personas from `.claude/personas/` that judge audience fit. The two keys are independent and may both be configured on the same project without conflict.
+
+**Used by:** `scripts/lib/config/wave-reviewers.mjs` (`_parseWaveReviewers`), `scripts/lib/config.mjs`, `skills/wave-executor/wave-loop.md` § 5a.
+
 ## Persona-Gate Wave (#458)
 
 Opt-in mid-wave hook that dispatches a `/persona-panel`-style review after a configured wave completes (Quality or Impl-Polish). Distinct from `wave-reviewers` (which targets code-oriented reviewer agents like `architect-reviewer` and `qa-strategist`): `persona-gate-wave` dispatches catalog personas from `.claude/personas/` — domain-experts, buyer-personas, and auditors. The two keys are independent; a project may configure both on the same wave without conflict.
@@ -1409,6 +1705,8 @@ skill-evolution:
 
 **Parity note.** The `skill-evolution:` key is documented in `docs/session-config-template.md` as a **standalone `## Skill Evolution` section** outside the `## Session Config` block — intentionally parity-exempt from `claude-md-drift-check` Check-6. Adding it as a column-0 key inside `## Session Config` would hard-fail every repo with `drift-check.mode: hard` that has not yet adopted the feature.
 
+**Root instruction-file activation capture (#652).** This repo's own `## Skill Evolution` block records why the feature was armed (`autonomy: autonomous-gated`) here specifically: the engine was activated for this repo (#652) after the C2 engine (#647/#651) plus the H1 `evidence_kind` guard (session-3) made autonomous-apply safe. Under that gate, the engine may auto-apply ONLY the `command-count` drift shape on the root instruction file, behind the quadruple condition (autonomy ∧ safe-posture ∧ gate-green ∧ evidence ≥ evidence-floor) AND only for `filesystem-fact`-sourced candidates. Plugin-level, local-skill, and remote-skill repair targets are ALWAYS MR-only regardless of this setting.
+
 ## Dispatcher Autonomy (#679)
 
 Opt-in configuration for the cross-repo free-repo dispatcher autonomy gate (Epic #673, Sub-issue #679). Controls whether the `/dispatcher` flow runs in advisory mode (surfaces ranked candidates for operator review only) or applies dispatch decisions behind a confidence gate. The default is `off` — fail-closed, no behavior change for repos that omit this block.
@@ -1434,6 +1732,8 @@ dispatcher-autonomy:
 
 **Parity note.** The `dispatcher-autonomy:` key is documented in `docs/session-config-template.md` as a **standalone `## Dispatcher Autonomy` section** outside the `## Session Config` block — intentionally parity-exempt from `claude-md-drift-check` Check-6 (session-config-parity). Adding it as a column-0 key inside `## Session Config` would hard-fail every repo with `drift-check.mode: hard` that has not yet adopted the feature.
 
+**Root instruction-file adoption capture (#681).** This repo's own `## Dispatcher Autonomy` block is the one-time capture of #681 (dogfooded here), committed with `autonomy: off` — fail-closed, identical to this repo's de-facto state before adoption. Its committed PRESENCE is itself the never-re-ask marker: session-start Phase 1.1's migration trigger checks for the block's existence and will not re-prompt, regardless of the value inside. See the Host-local override paragraph above (#653 pattern) for the full env > `owner.yaml` > committed > `off` precedence chain that lets a machine opt this repo into `advisory`/`autonomous-gated` without editing the committed block.
+
 ## Defaults
 
 If no `## Session Config` section exists in the platform config host file (`CLAUDE.md` or `AGENTS.md`), skills use: `feature` type, 6 agents, 5 waves, and field-specific defaults listed above.