mandrel 2.7.0 → 2.8.0

package/.agents/docs/configuration.md

@@ -286,429 +286,128 @@ top-level keys are validation errors.
 
 <!-- END GENERATED:agentrc -->
 
-## `project` (required)
-
-Project-local execution behaviour. Only `paths` is required; everything else
-falls back to documented defaults.
-
-### `project.paths` (required)
-
-Filesystem roots the framework reads from. All three keys are required —
-the resolver no longer applies code-level fallbacks; a missing value is a
-validation error with a clear `instancePath`.
-
-| Field       | Required | Purpose                                          |
-| ----------- | -------- | ------------------------------------------------ |
-| `agentRoot` | Yes      | Path to the materialized framework payload (e.g. `.agents`). |
-| `docsRoot`  | Yes      | Path to project documentation (e.g. `docs`).      |
-| `tempRoot`  | Yes      | Path for ephemeral artefacts (e.g. `temp`).       |
-
-`auditOutputDir` is derived (not configurable) — it resolves to
-`${tempRoot}/audits` and is the canonical destination for every
-`audit-*` workflow's result reports **and** the audit-suite's prompt
-artifacts. Override `tempRoot` to relocate audit output.
-
-### `project.baseBranch`
-
-| Field        | Required | Default | Purpose                                                                   |
-| ------------ | -------- | ------- | ------------------------------------------------------------------------- |
-| `baseBranch` | No       | (none)  | Default branch name (e.g. `main`). Read by close, push, and rebase paths. |
-
-### `project.commands`
-
-Executable strings the framework spawns for validation, testing, and baseline
-ratchets. Strings must be non-empty and pass the shell-injection guard
-(`safeString` — disallows `;`, `&`, `|`, backtick, `$`, `<`, `>`).
-
-`typecheck` is nullable to indicate "not applicable for this repo"; `null`
-is the canonical disabled value.
-
-| Field          | Required | Default                       | Type            | Purpose                                                |
-| -------------- | -------- | ----------------------------- | --------------- | ------------------------------------------------------ |
-| `lintBaseline` | No       | (none)                        | `string`        | Structured-output linter for the lint ratchet.         |
-| `test`         | No       | (none)                        | `string`        | Project test runner.                                   |
-| `typecheck`    | No       | `null`                        | `string \| null` | Strict type-checking. `null` = disabled.               |
-| `formatCheck`  | No       | `npx biome format .`          | `string`        | Read-only format check used by close-validation.       |
-| `formatWrite`  | No       | `npx biome format --write .`  | `string`        | Auto-format invocation used by `runFormatAutofix`.     |
-
-Read with `getCommands(config)` — see
-[`config-resolver.js`](../scripts/lib/config-resolver.js).
-
-### `project.docsContextFiles`
-
-| Field              | Required | Default | Purpose                                                                                            |
-| ------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
-| `docsContextFiles` | No       | `[]`    | Files the context-hydration engine includes when assembling agent prompts. Resolved against `paths.docsRoot`. |
-
-> **Entries are plain filenames, not globs.** Each entry is resolved as a
-> single file under `paths.docsRoot`; the loader does **not** expand glob
-> patterns. This matters for the decisions log: when a project adopts the
-> index + `decisions/` ADR-directory layout (see
-> [`documentation-and-adrs`](../skills/core/documentation-and-adrs/SKILL.md)),
-> the **index** `decisions.md` stays the mandatory-read and the per-ADR bodies
-> under `decisions/` are link-followed on demand — **index-only by default**.
-> Auto-loading every ADR body into each task's context would reintroduce the
-> bloat the directory split exists to remove. A project that genuinely wants
-> the full ADR set in mandatory context must opt in by listing the individual
-> ADR files explicitly (one filename per entry); there is no built-in
-> `decisions/*.md` glob.
-
----
-
-## `github`
-
-Ticketing provider configuration. Required when any GitHub-aware workflow
-runs (which is the common case).
-
-### `github` — top-level
-
-| Field            | Required | Purpose                                                            |
-| ---------------- | -------- | ------------------------------------------------------------------ |
-| `owner`          | Yes      | GitHub repository owner (user or org).                              |
-| `repo`           | Yes      | GitHub repository name.                                             |
-| `projectNumber`  | No       | GitHub Projects V2 number for custom field writes.                  |
-| `projectOwner`   | No       | Project board owner (defaults to `owner`).                          |
-| `operatorHandle` | No       | `@`-prefixed handle used in operator @mentions.                     |
-
-### `github.branchProtection`
-
-Drives the `node .agents/scripts/bootstrap.js` flow that creates or merges
-branch protection on the base branch.
-
-| Field            | Required | Default | Purpose                                                                 |
-| ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
-| `enforce`        | No       | `true`  | When `true`, `node .agents/scripts/bootstrap.js` calls `applyBranchProtection(...)`. |
-| `requiredChecks` | No       | `[]`    | Array of `{ name, cmd[] }` entries used both as required-status-check expectations on the PR and as local close-validation gate invocations. |
-
-Each `requiredChecks` entry takes the shape:
-
-```jsonc
-{ "name": "lint", "cmd": ["npm", "run", "lint"] }
-```
-
-### `github.mergeMethods`
-
-Repository-level merge-method allowlist applied by bootstrap.
-
-| Field                    | Required | Default | Purpose                                          |
-| ------------------------ | -------- | ------- | ------------------------------------------------ |
-| `allow_squash_merge`     | No       | `true`  | Permit squash merges through the UI / `gh`.      |
-| `allow_rebase_merge`     | No       | `false` | Permit rebase merges.                            |
-| `allow_merge_commit`     | No       | `false` | Permit merge commits.                            |
-| `allow_auto_merge`       | No       | `true`  | Enable auto-merge for the repository.            |
-| `delete_branch_on_merge` | No       | `true`  | Delete the source branch after merge.            |
-
-### `github.notifications`
-
-| Field             | Required | Default                                                                                | Purpose                                                                                                                                       |
-| ----------------- | -------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mentionOperator` | No       | `false`                                                                                | When `true`, friction comments @-mention `operatorHandle` for `medium`-severity dispatches (high always @mentions).                          |
-| `commentEvents`   | No       | `["state-transition", "story-merged", "operator-message"]`                             | Allowlist of event names that reach the GitHub ticket comment channel.                                                                       |
-| `webhookEvents`   | No       | `["state-transition", "story-merged", "story-closing", "operator-message", "merge.unlanded", "merge.flip-failed", "loop.tick"]` | Allowlist of event names that reach `NOTIFICATION_WEBHOOK_URL`. The vocabulary mirrors the events the v2 runtime actually emits through `notify()`. |
-
-Both fields' enums are pinned in the schema and rejected if extended. To
-suppress a channel entirely, set its array to `[]`.
-
-> **Severity assignment.** Story state transitions fire `medium`. Blockers
-> and HITL gates fire `high` (webhook prefix `[Action Required]` when an
-> allowlisted blocker event reaches the webhook).
-
----
-
-## `planning`
-
-`/plan` tuning. All fields optional. **Defaults are advisory**, not Story-width
-ceilings: the retired `taskSizing.softFiles` / `hardFiles` file-count gates,
-`planning.modelCapacity` operator knobs, and `maxTokenBudget` envelope are
-gone. Session-mass ceilings live as absolute authored-token constants on
-`DEFAULT_MODEL_CAPACITY` in `ticket-validator-sizing.js` (soft 30k / hard 75k).
-Soft findings are advisory; the hard ceiling rejects only Spec novels, and
-`wide` lifts that rejection. Cohesion / split policy / conflict advisories
-remain the primary sizing signal.
-
-| Field | Required | Default | Purpose |
+## Field semantics
+
+The generated table above — together with the exhaustive
+[`agentrc-reference.json`](agentrc-reference.json) — is the SSOT for every
+key's name, type, and default. This section adds only the semantics those
+sources cannot capture: accessor gotchas, derived values, extender forms, and
+the operational behaviour behind a handful of keys. It does **not** restate
+names or defaults.
+
+### `project`
+
+- **`paths` (required).** All three roots are required — the resolver applies
+  no code-level fallback, so a missing value is a validation error with a clear
+  `instancePath`. `auditOutputDir` is **derived, not configurable**: it
+  resolves to `${tempRoot}/audits` (the destination for every `audit-*` report
+  and the audit-suite prompt artifacts). Override `tempRoot` to relocate it.
+- **`commands`.** Each string must be non-empty and pass the shell-injection
+  guard (`safeString` — disallows `;`, `&`, `|`, backtick, `$`, `<`, `>`).
+  `typecheck` is nullable; `null` is the canonical "not applicable for this
+  repo" value. Read the block via `getCommands(config)`
+  ([`config-resolver.js`](../scripts/lib/config-resolver.js)).
+- **`docsContextFiles`.** Entries are **plain filenames, not globs** — each
+  resolves to a single file under `paths.docsRoot`. For the decisions log this
+  means the **index** `decisions.md` stays the mandatory-read while per-ADR
+  bodies under a `decisions/` directory are link-followed on demand (index-only
+  by default; there is no `decisions/*.md` glob). See
+  [`documentation-and-adrs`](../skills/core/documentation-and-adrs/SKILL.md).
+
+### `github`
+
+- **`operatorHandle`.** Schema-required but per-contributor: the committed
+  `.agentrc.json` carries only the `@[USERNAME]` placeholder, which
+  [`normalizeOperatorHandle`](../scripts/lib/orchestration/ticket-lease.js)
+  resolves to `null`, making the lease guards fail closed until you set your own
+  handle locally (see [Per-machine local overrides](#per-machine-local-overrides)).
+  `github.owner` / `repo` are shared and stay committed with real values.
+- **`branchProtection.requiredChecks`.** Each `{ name, cmd[] }` entry is used
+  **both** as a required-status-check expectation on the PR and as a local
+  close-validation gate invocation.
+- **`notifications`.** Both event allowlists filter their channel
+  independently; their enums are pinned in the schema. Set an array to `[]` to
+  suppress a channel. The severity vocabulary and shipped default allowlists
+  are documented under [`SDLC.md` § Notification system](SDLC.md#notification-system).
+
+### `planning`
+
+Defaults are **advisory, not Story-width ceilings**. Session-mass ceilings live
+as absolute authored-token constants on `DEFAULT_MODEL_CAPACITY` in
+`ticket-validator-sizing.js` (soft 30k / hard 75k); there is no `maxTokenBudget`
+envelope, and cohesion / split policy / conflict advisories are the primary
+sizing signal. The `codebaseSnapshot` `skinny` tier caps at 250 paths using
+**per-top-level-directory proportional budgeting** (round-robin across matched
+trees) so a large dot-prefixed tree like `.agents/scripts/**` cannot monopolise
+the budget and truncate away the consumer's own source; the shipped `include`
+scans `.agents/scripts/**`, `src/**`, `lib/**`, `app/**`, `packages/**` and
+`exclude` drops `node_modules`, build dirs, and test files. Override `include`
+only when the project's source layout differs.
+
+### `delivery`
+
+- **`docsFreshness.paths`.** Files refreshed during the post-PR-merge release
+  tagging step.
+- **`quality` accessor gotcha.** Internal callers MUST read the quality block
+  via `getQuality(config)` where `config` is the full `resolveConfig()` envelope
+  (or any object exposing `delivery.quality.*`). Passing a sub-pick like
+  `getQuality({ agentSettings })` silently resolves to framework defaults —
+  `agentSettings` is not part of the post-Epic-#2880 resolver output. The same
+  applies to `getBaselines(config)`.
+- **`quality.gates.<tier>` common shape.** Every gate shares
+  `enabled` / `baselinePath` / `tolerance` (`{ kind, value }`) /
+  `floors` (`{ <workspace>: { <metric>: <number> } }`) /
+  `components` (`{ <component>: [<glob>] }`). The `crap` / `maintainability` /
+  `duplication` `targetDirs` default `["src"]`. The `bundle-size` gate has
+  **no** `refreshTag` — there is no scorer to regenerate its baseline, so its
+  one-shot refresh is the `BUNDLE_SIZE_REFRESH=1` env var, not a config knob
+  (see [`quality-gates.md` § Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)).
+  Extend the list-valued gate keys with the deep-merge extender form (see
+  [How to extend](#how-to-extend)).
+
+#### `delivery.worktreeIsolation` — node_modules strategies
+
+When `enabled: true`, each Story runs in its own worktree under
+`.worktrees/story-<id>/`, and `nodeModulesStrategy` picks how `node_modules` is
+populated. This is the single home for the strategy trade-offs (README's
+worktree section points here):
+
+| Strategy | When to use | Cold-start cost | Notes |
 | --- | --- | --- | --- |
-| `riskHeuristics` | No | (framework list) | Free-form rubric for `risk::high` decisions (informational — does not gate runtime). Accepts a plain array or `{ append/prepend }`. |
-| `failOnSharedEditors` | No | `false` | When `true`, upgrade shared-editor findings to hard errors. Soft advisory otherwise. |
-| `requireExplicitCrossStoryDeps` | No | `false` | When `true`, upgrade implicit cross-Story dep findings to hard errors. Soft advisory otherwise. |
-| `failOnRegistryConflicts` | No | `false` | When `true`, upgrade concurrent registry-edit findings to hard errors. Soft advisory otherwise. |
-| `failOnLargeFanOut` | No | `false` | When `true`, upgrade delete blast-radius (`fan-out-warning`) findings to hard errors. Soft advisory otherwise. |
-| `largeFanOutThreshold` | No | `10` | Call-site count above which a Story that **deletes** a module warns. Not a Story-size limit — it only scores base-branch references to a path marked `assumption: "deletes"`. |
-| `crossCuttingRegistries` | No | listener/handler index patterns | Registry path patterns flagged when two Stories edit them concurrently. |
-| `navigation` | No | (empty → no-op) | Opt-in reachability gate for route-adding Stories. |
-
-### Conflict advisories (`failOn*` / `largeFanOutThreshold`)
-
-These knobs do **not** force thin Stories. By default every conflict finding
-is `soft` (visible to the planner, does not trip re-decompose). Set a
-`failOn*` flag only when you want that finding class to become a hard
-`errors[]` refusal.
-
-`largeFanOutThreshold` specifically:
-
-1. Looks only at `body.changes[]` entries with `assumption: "deletes"`.
-2. Counts distinct base-branch files that reference the deleted module basename.
-3. Emits `fan-out-warning` when `callSiteCount > largeFanOutThreshold` (default 10).
-4. Stays soft unless `failOnLargeFanOut: true`. Persist can still require an
-   explicit `--allow-large-fan-out` operator flag for very large delete blasts;
-   that is separate from Story sizing.
-
-### `planning.codebaseSnapshot`
-
-Controls the codebase-snapshot fetcher that grounds Tech Spec / Story authoring.
-
-| Field                | Required | Default     | Purpose                                                                  |
-| -------------------- | -------- | ----------- | ------------------------------------------------------------------------ |
-| `tier`               | No       | `'skinny'`  | One of `'skinny'` or `'medium'`. `medium` opts into a richer snapshot.    |
-| `include`            | No       | (see below) | Glob patterns whose matches are included in the snapshot.                |
-| `exclude`            | No       | (see below) | Glob patterns whose matches are excluded from the snapshot.              |
-| `recentCommitWindow` | No       | `30`        | Number of recent commits to summarise in the snapshot header.            |
-
-The shipped `include` default scans `.agents/scripts/**`, `src/**`,
-`lib/**`, `app/**`, and `packages/**`; the shipped `exclude` default drops
-`node_modules`, `dist`, `build`, `.next`, `.turbo`, `coverage`, and
-`*.test.*` / `*.spec.*`. Override only when the project's source layout
-differs.
-
-The `skinny` tier caps its file list at 250 paths. When the include set
-matches more than that, the cap is applied with **per-top-level-directory
-proportional budgeting** (round-robin across the matched top-level trees)
-rather than a flat lexicographic slice — so a large, dot-prefixed tree like
-`.agents/scripts/**` can no longer monopolise the budget and truncate away
-the consumer's own `src/` / `lib/` source. When `.agents/scripts/**` is the
-only matching tree (the Mandrel-repo dogfood case), the round-robin
-degenerates to taking the first 250 sorted paths, so that snapshot stays
-useful. When truncation occurs, `/plan` emits an operator-visible warning
-naming the dropped file count and suggesting `tier: "medium"` and/or a
-narrowed `include`. Opt into the richer `medium` tier or narrow `include`
-if the partial skinny view is insufficient.
-
-### `planning.navigation`
-
-Opt-in. When `routeGlobs` is absent or empty the reachability gate is a
-silent no-op. When configured, a Story that adds a matching route path is
-expected to also touch a `navRegistry` token.
-
-| Field         | Required | Default | Purpose |
-| ------------- | -------- | ------- | ------- |
-| `routeGlobs`  | No       | `[]`    | Globs marking user-facing route paths. |
-| `navRegistry` | No       | `[]`    | Tokens identifying the nav-registry SSOT. |
-
----
-
-## `delivery`
-
-`/deliver` and `/deliver` tuning. All sub-blocks are optional and
-fall back to documented defaults (or are no-ops when omitted).
-
-### `delivery.execution`
-
-| Field       | Required | Default    | Purpose                                                            |
-| ----------- | -------- | ---------- | ------------------------------------------------------------------ |
-| `timeoutMs` | No       | `600000`   | Per-spawn timeout (ms) for child processes the framework launches. |
-
-> Session-mass ceilings live as absolute authored-token constants on
-> `DEFAULT_MODEL_CAPACITY` in `ticket-validator-sizing.js` (soft 30k / hard
-> 75k). There is no `maxTokenBudget` envelope — cohesion is the primary
-> sizing signal; the numeric backstop only catches Spec novels.
-
-### `delivery.docsFreshness`
-
-| Field   | Required | Default | Purpose                                                       |
-| ------- | -------- | ------- | ------------------------------------------------------------- |
-| `paths` | No       | `[]`    | Files refreshed during the post-PR-merge release tagging step. |
-
-### `delivery.deliverRunner`
-
-| Field                       | Required | Default | Purpose                                          |
-| --------------------------- | -------- | ------- | ------------------------------------------------ |
-| `concurrencyCap`            | No       | `3`     | Max ready Stories dispatched by `/deliver` at once. |
-
-### `delivery.worktreeIsolation`
-
-Story-level worktree isolation. When `enabled: true`, `/deliver` runs
-each Story inside `.worktrees/story-<id>/` instead of moving the main
-checkout's HEAD.
-
-| Field                   | Required        | Default          | Purpose                                                     |
-| ----------------------- | --------------- | ---------------- | ----------------------------------------------------------- |
-| `enabled`               | No              | `true`           | Master switch.                                              |
-| `root`                  | Conditional     | `.worktrees`     | Required when `enabled: true`. Worktree parent directory.    |
-| `nodeModulesStrategy`   | No              | `clone` (darwin/linux); `per-worktree` (Windows) | One of `per-worktree`, `clone`, `symlink`, `pnpm-store`. `clone` copy-on-write (reflink/clonefile) clones the donor's `node_modules` and skips the per-tree install on a byte-exact lockfile match, falling back to `per-worktree` on any failure. |
-| `primeFromPath`         | No              | `null`           | Optional source path used to prime `node_modules`.            |
-| `allowSymlinkOnWindows` | No              | `false`          | Permit symlink strategy on Windows (requires admin/dev mode). |
-| `reapOnSuccess`         | No              | `true`           | Reap the worktree after a successful Story close.            |
-| `bootstrapFiles`        | No              | `[".env", ".mcp.json", ".agentrc.local.json", ".agents/instructions.local.md"]` | Untracked files copied into each new worktree (local overrides included). |
-
-### `delivery.signals`
-
-Friction-detector thresholds consumed by progress-signal listeners.
-
-| Field                  | Required | Default | Purpose                                                                  |
-| ---------------------- | -------- | ------- | ------------------------------------------------------------------------ |
-| `rework.editsPerFile`  | No       | (none)  | Edits to the same file before a rework signal fires.                      |
-| `retry.repeatCount`    | No       | (none)  | Identical retried commands before a retry signal fires.                   |
-
-### `delivery.quality`
-
-Quality-gate configuration. Lives under `delivery.quality` and uses the
-uniform `gates.<tier>` shape (seven gates: `lint`, `coverage`, `crap`,
-`maintainability`, `mutation`, `lighthouse`, `bundle-size`) introduced by
-Epic #1720 Story #1737.
-
-#### `delivery.quality.gateScoping`
-
-| Field     | Required | Default  | Purpose                                                                        |
-| --------- | -------- | -------- | ------------------------------------------------------------------------------ |
-| `scope`   | No       | `'full'` | One of `'diff'` (only files changed vs `diffRef`) or `'full'` (all targetDirs). |
-| `diffRef` | No       | (none)   | Ref used to compute the diff when `scope: 'diff'` (e.g. `main`).               |
-
-#### `delivery.quality.gates.<tier>` — common shape
-
-Every gate shares the same envelope:
-
-| Field          | Required | Purpose                                                                                                        |
-| -------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `enabled`      | No       | Master switch. `false` makes all three gate sites self-skip for this tier.                                     |
-| `baselinePath` | No       | Path to the per-tier ratchet baseline file (e.g. `baselines/crap.json`).                                       |
-| `tolerance`    | No       | `{ kind: 'absolute' \| 'percent', value: <number> }` — slack permitted when comparing scores against baseline. |
-| `floors`       | No       | `{ <workspace>: { <metric>: <number> } }` — absolute floors below which the gate fails regardless of baseline. |
-| `components`   | No       | `{ <component>: [<glob>, ...] }` — optional component-level grouping for breakdown reporting.                  |
-
-Tier-specific knobs:
-
-##### `gates.lint`
-
-No tier-specific knobs beyond the common shape.
-
-##### `gates.coverage`
-
-| Field          | Required | Default                          | Purpose                                                  |
-| -------------- | -------- | -------------------------------- | -------------------------------------------------------- |
-| `coveragePath` | No       | `coverage/coverage-final.json`   | Per-method coverage artifact consumed by the gate.       |
-| `timeoutMs`    | No       | `600000`                         | Wall clock (ms) for `npm run test:coverage` spawned by `coverage-capture.js`. SIGKILL → exit 124 (GNU `timeout` convention) so close-validation can branch on hang-vs-failure. |
-
-> **Canonical accessor.** Internal callers MUST read this block via
-> `getQuality(config)` where `config` is the full envelope returned by
-> `resolveConfig()` (or any object that exposes `delivery.quality.*`).
-> Passing a sub-pick such as `getQuality({ agentSettings })` silently
-> resolves to framework defaults — `agentSettings` is not part of the
-> post-Epic-#2880 resolver output and `getQuality` reads only
-> `config?.delivery?.quality`. The same applies to `getBaselines(config)`.
-
-##### `gates.crap`
-
-| Field               | Required    | Default                     | Purpose                                                          |
-| ------------------- | ----------- | --------------------------- | ---------------------------------------------------------------- |
-| `targetDirs`        | No          | `["src"]`                   | Source dirs to score. Accepts list or `{ append/prepend }` form. |
-| `newMethodCeiling`  | No          | `30`                        | Max CRAP score allowed for methods absent from the baseline.     |
-| `requireCoverage`   | No          | `true`                      | When `true`, methods without coverage are skipped (not failed).  |
-| `friction.markerKey`| No          | `crap-baseline-regression`  | Friction-log marker for regressions.                             |
-| `refreshTag`        | No          | `baseline-refresh:`         | Subject prefix the refresh-guardrail expects on baseline-only commits. |
-| `refreshTimeoutMs`  | No          | `60000`                     | Bounded timeout (ms) for `npm run crap:update` in the baseline-attribution refresh path. SIGKILL → exit 124 → Story `agent::blocked`. |
-
-##### `gates.maintainability`
-
-| Field              | Required | Default     | Purpose                                                          |
-| ------------------ | -------- | ----------- | ---------------------------------------------------------------- |
-| `targetDirs`       | No       | `["src"]`   | Source dirs to score. Accepts list or `{ append/prepend }` form. |
-| `refreshTimeoutMs` | No       | `60000`     | Bounded timeout (ms) for `npm run maintainability:update` in the baseline-attribution refresh path. |
-
-##### `gates.mutation`
-
-| Field                | Required | Default | Purpose                                                  |
-| -------------------- | -------- | ------- | -------------------------------------------------------- |
-| `strykerConfigPath`  | No       | `null`  | Path to the Stryker config the mutation gate consumes.   |
-
-##### `gates.lighthouse`
-
-| Field     | Required | Default | Purpose                                                                                  |
-| --------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
-| `baseUrl` | No       | `null`  | Base URL Lighthouse audits.                                                              |
-| `routes`  | No       | `[]`    | Array of `{ path, formFactor? }` entries, where `formFactor` is `'mobile'` or `'desktop'`. |
-
-##### `gates.bundle-size`
-
-| Field     | Required | Default | Purpose                                                                                  |
-| --------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
-| `bundles` | No       | `[]`    | Array of `{ name, path, limit }` entries (e.g. `{ "name": "app", "path": "dist/app.js", "limit": "100kB" }`). |
-
-Unlike `crap` / `maintainability`, this gate has no `refreshTag` config
-field — there is no scorer to regenerate the baseline from source, so the
-one-shot refresh/acknowledge mechanism is an env var, not a config knob.
-See [`.agents/docs/quality-gates.md` § Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)
-for `BUNDLE_SIZE_REFRESH=1` usage.
-
-#### `delivery.quality.formatAutofix`
-
-| Field       | Required | Default | Purpose                                                                                                                  |
-| ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `timeoutMs` | No       | (none)  | Bounded timeout (ms) for the close-time `npx biome format --write` spawn. SIGKILL maps to exit 124 → Story `agent::blocked`. |
-
-#### `delivery.quality.codingGuardrails`
-
-| Field                  | Required | Default | Purpose                                                            |
-| ---------------------- | -------- | ------- | ------------------------------------------------------------------ |
-| `cyclomaticFlag`       | No       | (none)  | Cyclomatic-complexity value at which the engineer should refactor.  |
-| `cyclomaticMustFix`    | No       | (none)  | Cyclomatic-complexity value that hard-fails the gate.               |
-| `requireSiblingTest`   | No       | (none)  | When `true`, a new function requires a sibling test file.           |
-
-#### `delivery.quality.autoRefresh`
-
-Controls Story-close auto-baseline-refresh for gated metrics.
-
-| Field         | Required | Default | Purpose                                                  |
-| ------------- | -------- | ------- | -------------------------------------------------------- |
-| `enabled`     | No       | (none)  | Master switch.                                           |
-| `crapJumpCap` | No       | (none)  | Max CRAP jump the auto-refresher will absorb before failing. |
-| `scope`       | No       | (none)  | One of `'diff'` or `'full'`.                              |
-
-#### `delivery.quality.baselineEpsilon`
-
-Per-kind epsilon (introduced by Story #1964). Sub-epsilon row deltas resolve
-to prior bytes so cross-environment variance does not rewrite the on-disk
-baseline.
-
-| Field             | Required | Default | Purpose                                |
-| ----------------- | -------- | ------- | -------------------------------------- |
-| `maintainability` | No       | (none)  | Epsilon for maintainability rows.      |
-| `crap`            | No       | (none)  | Epsilon for CRAP rows.                 |
-| `coverage`        | No       | (none)  | Epsilon for coverage rows.             |
-| `mutation`        | No       | (none)  | Epsilon for mutation rows.             |
-| `lint`            | No       | (none)  | Epsilon for lint rows.                 |
-| `lighthouse`      | No       | (none)  | Epsilon for Lighthouse rows.           |
-| `bundle-size`     | No       | (none)  | Epsilon for bundle-size rows.          |
-
-### `delivery.codeReview`
-
-Configuration block for the code-review pipeline that runs during Story
-delivery (`helpers/deliver-story` / `runCodeReview()`). Select providers
-via the `providers[]` chain (generated table above); when unset or empty,
-the factory defaults to `[{ name: "native" }]`. See
-[`.agents/README.md` § Code review providers](../README.md#code-review-providers-pluggable-chain)
-for chain-entry fields (`name`, `scopes`, `optional`, `manualPrompt`, `when`).
-
-| Field              | Required | Default | Purpose                                                              |
-| ------------------ | -------- | ------- | -------------------------------------------------------------------- |
-| `providers`        | No       | `[{ name: "native" }]` | Review-provider chain. Inline adapters merge `Finding[]`; manual-prompt entries append suggestions. |
-| `providerConfig`   | No       | `{}`    | Optional escape hatch for adapter-specific configuration. Reserved; no documented keys yet. |
-| `maxFixAttempts`   | No       | `3`     | Max auto-fix retry attempts per finding. `0` disables auto-fix. |
-| `maxFixScopeFiles` | No       | `5`     | Max file count a single auto-fix may modify before escalating to `agent::blocked`. |
-| `autoFixSeverity`  | No       | `"medium"` | Severity threshold for on-branch remediation (`medium` or `high`). |
-
-#### Dual-scope fix budget
-
-`maxFixAttempts` and `maxFixScopeFiles` are enforced during the risk-routed
-Story review ceremony using the same configured values for every Story in
-a `/deliver` run. Setting `maxFixAttempts: 0` disables auto-fix; there is
-no per-Story override.
-
-### `delivery.feedbackLoop`
-
-| Field                   | Required | Default | Purpose                                                                                                                                  |
-| ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `auditResultsAutoFile`  | No       | `true`  | When `true`, the deliver finalize path auto-files non-blocking findings from the unified `verification-results` comment as follow-up issues routed by source classification. (The former `codeReviewAutoFile` key was retired with its graduator when Story #4411 unified the pass; a config carrying it fails validation.) |
-| `retroProposals`        | No       | `true`  | When `true`, auto-file the retro's actionable routed proposals as GitHub follow-up issues (Story #4418). |
+| `clone` | **Default on darwin/linux** — copy-on-write clone of donor `node_modules`. | Near-zero on reflink FS. | Falls back to `per-worktree` on unsupported/cross-volume FS. |
+| `per-worktree` | Default on Windows; safe fallback everywhere. | Full `npm ci` per Story. | Independent `node_modules` per worktree. |
+| `symlink` | npm/yarn repos wanting the fast path. **Opt-in.** | Near-zero. | Junctions a donor `node_modules`; refuses on Windows unless `allowSymlinkOnWindows`. |
+| `pnpm-store` | pnpm repos. **Opt-in.** | Fast (store-backed). | `pnpm install --frozen-lockfile` against the shared store. |
+
+For `symlink`, also set `primeFromPath` (relative path to the donor worktree
+whose `node_modules/` is reused — `"."` = the root checkout, which must already
+have `node_modules/`; `single-story-init.js` pre-checks this) and, on Windows,
+`allowSymlinkOnWindows: true` (junctions, no admin rights). `single-story-init.js`
+then skips `npm ci` and junctions/symlinks the donor's `node_modules`.
+
+#### `delivery.codeReview` — provider chain
+
+`providers[]` is iterated in declaration order (unset/empty →
+`[{ name: "native" }]`). Beyond the field list in the generated table: `scopes`
+defaults to both `story` and `epic`; `when` is a label predicate (`when.label`
+/ `when.labelAny`) that silently skips the entry when false; `manualPrompt`
+entries contribute a one-line suggestion and do **not** affect severity counts
+or the `halted` gate. **Cross-runtime contract:** manual-prompt providers emit
+Markdown only and MUST NEVER throw under any host; inline providers that shell
+out to a host-specific binary (e.g. `security-review` →
+`claude --print /security-review`) SHOULD be declared `optional: true` so
+non-Claude consumers can pin the same `.agents/` version unmodified. The fix
+budget (`maxFixAttempts` / `maxFixScopeFiles`) uses the same values for every
+Story in a run — there is no per-Story override.
+
+#### `delivery.feedbackLoop` — verification-results auto-graduation
+
+`auditResultsAutoFile` auto-graduates surviving non-blocking findings from the
+unified `verification-results` comment into follow-up issues; the graduator
+embeds a content-derived idempotency marker so re-runs skip findings that
+already have an issue (re-enabling after a manual-triage window is safe). The
+former `codeReviewAutoFile` key was retired when Story #4411 unified the pass —
+a config carrying it fails validation; delete it.
 
 ---
 
@@ -765,18 +464,12 @@ the lint ratchet, and the CRAP/MI gates.
 | `baselines/maintainability.json`  | `update-maintainability-baseline.js` | `npm run maintainability:update`                                        |
 | `baselines/bundle-size.json`      | consumer's own build/measure step    | Commit the build's measured sizes; for an intentional growth, run the check with `BUNDLE_SIZE_REFRESH=1` (see [Bundle-size ratchet](quality-gates.md#bundle-size-ratchet--one-shot-refreshacknowledge-story-151)) |
 
-These files are the contract. They are read by every gate (Story close, push
-hook, CI) and are regenerated only via tagged `baseline-refresh:` commits
-with a non-empty body. The convention is operator-enforced; see the CRAP
-section of [`quality-gates.md`](quality-gates.md) for the policy.
-
-Paths are configured in `delivery.quality.gates.<tier>.baselinePath`. The
-default values match the canonical layout above; override only when a
-project genuinely stores baselines elsewhere.
-
-The `.agents/state/` directory itself is created on demand by the progress
-reporter; the framework does not require it to exist ahead of time and does
-not commit its contents.
+These files are the contract — read by every gate (Story close, push hook, CI)
+and regenerated only via tagged `baseline-refresh:` commits with a non-empty
+body (see [`quality-gates.md`](quality-gates.md) for the policy). Paths are
+configured in `delivery.quality.gates.<tier>.baselinePath`, defaulting to the
+layout above. The `.agents/state/` directory is created on demand by the
+progress reporter and is not committed.
 
 ---
 
@@ -999,72 +692,13 @@ move and the allowlist response in the same diff.
 
 ---
 
-## CLI subcommand quick-reference
-
-`mandrel --help` prints the full subcommand list. Each subcommand that
-mutates state supports `--dry-run` to preview without writing. The table
-below covers every dispatch-visible subcommand:
-
-| Subcommand | What it does | Key flags |
-| ---------- | ------------ | --------- |
-| `init` | Install and configure mandrel in the current project. | `--assume-yes`, `--skip-github`, `--dry-run` |
-| `sync` | Re-materialize `.agents/` from the installed package payload. | `--dry-run`, `--force` |
-| `sync-commands` | Rebuild `.claude/commands/` from `.agents/workflows/`. | — |
-| `doctor` | Run readiness checks and report remedies. | — |
-| `update` | Upgrade mandrel to the newest published version. | `--dry-run`, `--install-cmd` |
-| `migrate` | Apply version-keyed migrations for a version range. | `--from`, `--to`, `--dry-run` |
-| `explain` | Print resolved config values with sources. | `--json` |
-| `uninstall` | Reverse a recorded install using the install ledger. | `--include-github`, `--dry-run` |
-
-### `mandrel explain`
-
-Prints every resolved config key — its effective value, its source layer
-(`[agentrc]` or `[default]`), and a one-line description. Secret-shaped
-values are shown as `<redacted>`. Useful when debugging unexpected behavior
-caused by config layering.
-
-```bash
-mandrel explain          # human-readable report
-mandrel explain --json   # JSON report for scripting
-```
-
-### `mandrel sync-commands`
-
-Regenerates the flat `.claude/commands/` tree from `.agents/workflows/`. Runs
-automatically at install time (via `prepare`) and as part of `mandrel
-sync`/`update`; manual invocations are only needed when the commands/ tree is
-manually deleted or edited by hand. Refuses to project when the materialized
-`.agents/` tree doesn't match the running CLI's own version.
-
-```bash
-mandrel sync-commands
-```
-
-### `mandrel sync-agents`
-
-Regenerates the flat `.claude/agents/` tree from `.agents/agents/` — the
-role-scoped boot contexts `delivery.routing.roleScopedAgents` (default
-`true`) dispatches spawns against. Same wiring and version-match refusal as
-`mandrel sync-commands` above.
-
-```bash
-mandrel sync-agents
-```
+## CLI subcommand reference
 
-### `mandrel uninstall`
-
-Reverses a recorded install using the install ledger
-(`.agents/.install-manifest.json`). Restoration is marker-based and
-non-destructive: operator-authored content that pre-existed the install
-is preserved; only install-created files and framework additions are removed.
-GitHub-side state is never acted on automatically; it is surfaced as a
-manual checklist.
-
-```bash
-mandrel uninstall                  # reverse all local mutations
-mandrel uninstall --dry-run        # preview without writing
-mandrel uninstall --include-github # acknowledge GitHub-side follow-ups
-```
+The `mandrel` CLI subcommands (`init`, `sync`, `sync-commands`, `sync-agents`,
+`doctor`, `update`, `migrate`, `explain`, `uninstall`) — what each does, its
+key flags, and the per-subcommand notes — are documented once in
+[`.agents/README.md` § CLI subcommand reference](../README.md#cli-subcommand-reference).
+Run `mandrel --help` for the live list.
 
 ---