mandrel 1.93.0 → 2.0.0

package/.agents/docs/configuration.md

@@ -26,7 +26,7 @@ with the runtime validators.
   "$schema": "./.agents/schemas/agentrc.schema.json",
   "project":  { /* paths, commands, baseBranch, docsContextFiles */ },
   "github":   { /* owner, repo, branchProtection, mergeMethods, notifications */ },
-  "planning": { /* riskHeuristics, codebaseSnapshot, context */ },
+  "planning": { /* riskHeuristics, conflict gates, codebaseSnapshot, context */ },
   "delivery": { /* execution, quality, worktreeIsolation, deliverRunner, ... */ }
 }
 ```
@@ -38,8 +38,8 @@ top-level keys are validation errors.
 | ------------- | -------- | ---------------------------------------------------------------------------------- |
 | `project`     | **Yes**  | Project-local paths, base branch, validation commands, and context-hydration files. |
 | `github`      | No       | Ticketing provider config: owner/repo, branch protection, merge methods, notifications. |
-| `planning`    | No       | `/plan` tuning: ticket budget, risk heuristics, codebase snapshot, context cap. |
-| `delivery`    | No       | `/deliver` and `/deliver` tuning: quality gates, worktree isolation, runners, lifecycle. |
+| `planning`    | No       | `/plan` tuning: conflict advisories, codebase snapshot, context cap. (Story sizing ceilings are code-absolute — not agentrc.) |
+| `delivery`    | No       | `/deliver` tuning: quality gates, worktree isolation, runners, CI watch, code-review providers. |
 | `$schema`     | No       | JSON Schema pointer for editor tooling.                                            |
 
 ---
@@ -105,20 +105,14 @@ top-level keys are validation errors.
 | `codebaseSnapshot.include` | No | `array<string>` | — | — |
 | `codebaseSnapshot.exclude` | No | `array<string>` | — | — |
 | `codebaseSnapshot.recentCommitWindow` | No | `integer` | — | — |
-| `taskSizing` | No | `object` | — | Story-sizing thresholds consumed by ticket-validator-sizing.js. Operator overrides shallow-merge with DEFAULT_TASK_SIZING defaults. Story #3760 collapsed the per-profile matrix and the parallel testSurface axis into a flat set of knobs; the sizingProfile enum was replaced by an optional body-level `wide` declaration that lifts the hardFiles rejection. Story #3874 cut over to one uniform relaxed profile sized for capability slices a frontier model delivers and self-verifies in one pass. |
-| `taskSizing.softFiles` | No | `integer` | — | File-count soft-warn threshold above which a typical-Story width finding fires (default 15). |
-| `taskSizing.hardFiles` | No | `integer` | — | File-count hard ceiling: a Story exceeding it is rejected unless it declares `wide` with a reason (default 30). |
-| `taskSizing.softAcceptanceCount` | No | `integer` | — | Soft-warn threshold on acceptance[] item count (default 10). Acceptance mass is advisory-only — there is no hard acceptance ceiling. |
-| `taskSizing.mergeCandidateMaxFiles` | No | `integer` | — | Under-size threshold (Story #4312): a Story with at most this many declared changes[] files, at most mergeCandidateMaxAcceptance acceptance items, and at least one depends_on edge to a sibling trips the advisory `merge-candidate` soft finding (default 3). |
-| `taskSizing.mergeCandidateMaxAcceptance` | No | `integer` | — | Under-size threshold (Story #4312): the acceptance[] item ceiling of the `merge-candidate` soft finding heuristic (default 4). |
-| `failOnSharedEditors` | No | `boolean` | — | — |
-| `requireExplicitCrossStoryDeps` | No | `boolean` | — | — |
-| `failOnRegistryConflicts` | No | `boolean` | — | — |
-| `failOnLargeFanOut` | No | `boolean` | — | — |
-| `largeFanOutThreshold` | No | `integer` | — | — |
-| `crossCuttingRegistries` | No | `string[]` or `{ append?, prepend? }` | — | — |
-| `navigation` | No | `object` | — | Navigability-reachability config consumed by the plan-persist draft reachability gate (Epic #4474 PR6; also the manual epic-plan-healthcheck --paranoid re-check). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
-| `navigation.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route. |
+| `failOnSharedEditors` | No | `boolean` | — | When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only). |
+| `requireExplicitCrossStoryDeps` | No | `boolean` | — | When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only). |
+| `failOnRegistryConflicts` | No | `boolean` | — | When true, upgrade cross-cutting registry conflict findings to hard errors (default false). |
+| `failOnLargeFanOut` | No | `boolean` | — | When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory). |
+| `largeFanOutThreshold` | No | `integer` | — | Call-site count above which a Story that deletes a module emits a fan-out-warning. Counts base-branch references to the deleted path basename. Soft by default; does not size or reject Stories. Default 10. |
+| `crossCuttingRegistries` | No | `string[]` or `{ append?, prepend? }` | — | Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted. |
+| `navigation` | No | `object` | — | Opt-in navigability reachability gate. Absent or empty routeGlobs is a silent no-op. |
+| `navigation.routeGlobs` | No | `array<string>` | — | Glob patterns (e.g. pages/**, app/**/route.ts) marking paths that add a user-facing route. |
 | `navigation.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference. |
 
 ### `delivery` (optional)
@@ -127,14 +121,12 @@ top-level keys are validation errors.
 | --- | --- | --- | --- | --- |
 | `execution` | No | `object` | — | Nested configuration block. |
 | `execution.timeoutMs` | No | `integer` | — | — |
-| `maxTokenBudget` | No | `integer` | — | — |
 | `lease` | No | `object` | — | Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner has not emitted a story.heartbeat within this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js. |
 | `lease.ttlMs` | No | `integer` | — | — |
 | `docsFreshness` | No | `object` | — | Nested configuration block. |
 | `docsFreshness.paths` | No | `array` | — | — |
 | `deliverRunner` | No | `object` | — | Nested configuration block. |
-| `deliverRunner.concurrencyCap` | No | `integer` | — | Maximum Stories dispatched in parallel within one wave. Default 3. Conservative by design — keeps host-quota consumption predictable on small waves and avoids GitHub API saturation. Operators running wide-wave Epics on hosts with adequate parallel-agent quota should raise this value to reduce wall-clock time proportionally. See epic-deliver.md § Phase 2b for the dispatch model and the throughput tradeoff discussion. |
-| `deliverRunner.progressReportIntervalSec` | No | `integer` | — | — |
+| `deliverRunner.concurrencyCap` | No | `integer` | — | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
 | `deliverRunner.verifyConcurrencyCap` | No | `integer` | — | Bounded-concurrency cap for the per-wave verifyWaveResults loop (Epic #3019 Tech Spec §1.4). Separate from the wave-execution `concurrencyCap` so operators can tune ticket-verification parallelism independently of Story dispatch parallelism. Default 4. |
 | `worktreeIsolation` | No | `object` | — | Nested configuration block. |
 | `worktreeIsolation.enabled` | No | `boolean` | — | — |
@@ -143,11 +135,8 @@ top-level keys are validation errors.
 | `worktreeIsolation.primeFromPath` | No | `string` \| `null` | — | — |
 | `worktreeIsolation.allowSymlinkOnWindows` | No | `boolean` | — | — |
 | `worktreeIsolation.reapOnSuccess` | No | `boolean` | — | — |
-| `worktreeIsolation.reapOnCancel` | No | `boolean` | — | — |
-| `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json"]` | — |
+| `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json",".agentrc.local.json",".agents/instructions.local.md"]` | — |
 | `signals` | No | `object` | — | Nested configuration block. |
-| `signals.hotspot` | No | `object` | — | Nested configuration block. |
-| `signals.hotspot.p95Multiplier` | No | `number` | — | — |
 | `signals.rework` | No | `object` | — | Nested configuration block. |
 | `signals.rework.editsPerFile` | No | `integer` | — | — |
 | `signals.retry` | No | `object` | — | Nested configuration block. |
@@ -262,52 +251,36 @@ top-level keys are validation errors.
 | `quality.baselineEpsilon.lighthouse` | No | `number` | — | — |
 | `quality.baselineEpsilon.bundle-size` | No | `number` | — | — |
 | `quality.baselineEpsilon.duplication` | No | `number` | — | — |
-| `quality.navigability` | No | `object` | — | Navigability lens + post-wave integration gate config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and the deliver-epic.md Phase 6.5 gate (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
+| `quality.requireBaselines` | No | `boolean` | — | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
+| `quality.navigability` | No | `object` | — | Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's risk-routed ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
 | `quality.navigability.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against. |
 | `quality.navigability.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against. |
-| `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite the deliver-epic.md Phase 6.5 post-wave integration gate runs. |
-| `lifecycle` | No | `object` | — | Knobs consumed by the lifecycle event bus (Epic #2172). `timeouts` is a per-event budget map (eventName → seconds) used by `TimeoutWatchdog`; missing entries fall back to in-listener defaults. `heartbeatWarnSeconds` is the no-progress threshold consumed by `HeartbeatMonitor`. Story #2227 lays down the keys; consumers land in later stories. |
-| `lifecycle.timeouts` | No | `object<map>` | — | — |
-| `lifecycle.heartbeatWarnSeconds` | No | `integer` | — | — |
+| `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite /deliver's risk-routed ceremony runs. |
 | `mergeWatch` | No | `object` | — | Knobs consumed by the MergeWatcher lifecycle listener (Story #2896, Epic #2880). `intervalSeconds` is the poll cadence between `gh pr view --json mergeCommit,mergedAt` probes after epic.merge.armed; `maxBudgetSeconds` is the total wall-clock budget before the watcher surfaces `agent::blocked` with reason `budget-exceeded`. |
 | `mergeWatch.intervalSeconds` | No | `integer` | `30` | Seconds between MergeWatcher polls. Default 30. |
 | `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Total wall-clock budget (seconds) for the MergeWatcher poll loop. Default 3600 (60 minutes). |
-| `epicAudit` | No | `object` | — | Nested configuration block. |
-| `epicAudit.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3. |
-| `epicAudit.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
-| `epicAudit.autoFixSeverity` | No | `"high"` \| `"medium"` | `"high"` | Severity threshold for on-branch remediation of the Epic-close lens findings walked inside the /deliver Phase 5 code-review pass (Story #4412 folded the former Phase 4 lens walk into that single cumulative-diff pass). `high` (default) routes only 🔴 Critical / 🟠 High lens findings into the host-LLM remediation loop while 🟡 Medium and 🟢 Suggestion findings graduate to follow-up issues (🟡 Medium concerns are already remediated shift-left at the write-time and Story-scope tiers); `medium` opts back into routing 🔴/🟠/🟡 (Mediums batched per lens). Hard cutover — no back-compat flag. |
 | `codeReview` | No | `object` | — | Nested configuration block. |
-| `codeReview.provider` | No | `"native"` \| `"codex"` \| `"security-review"` | `"native"` | Legacy single-adapter selection. ReviewProvider that produces the Finding[] consumed by runCodeReview(). Story #2833 registered `native` (in-process maintainability/lint); Story #2830 added `codex` (invokes `/codex:review` plugin); Story #2871 added `security-review` (shells out to `claude --print /security-review`). When `providers` (chain shape) is set this field is ignored with a warning. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. |
-| `codeReview.providers[]` | No | `array<object>` | — | Multi-provider chain (Story #2871). When set and non-empty, takes precedence over the legacy `provider` field. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Each item has: name, scopes, optional, manualPrompt, when. |
+| `codeReview.providers[]` | No | `array<object>` | — | Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
 | `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
 | `codeReview.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
 | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
-| `retro` | No | `object` | — | Story #3042 (Epic #3019). Operator-tunable retro behaviour. Currently exposes `perfThresholds`, the gates the retro perf-signals classifier uses to decide which signals to surface in the `## Performance Signals` / `## Recommended Follow-Ons` retro sections. |
-| `retro.perfThresholds` | No | `object` | — | Gates for `classifyPerfSignals` (lib/orchestration/retro-perf-heuristics.js). Defaults are 0.6 / 0.4 / 2. |
-| `retro.perfThresholds.utilisation` | No | `number` | — | Per-wave utilisation threshold. Waves whose `utilisation` is strictly below this value emit a `low-utilisation` signal. Default 0.6. |
-| `retro.perfThresholds.bootstrapShare` | No | `number` | — | Maximum acceptable share of cumulative Story execution time spent in the story-init phase. When exceeded the retro emits a `high-bootstrap-share` signal. Default 0.4. |
-| `retro.perfThresholds.capBindingRunLength` | No | `integer` | — | Minimum run length of consecutive cap-binding waves before the retro emits a `cap-binding-run` signal. Default 2. |
 | `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
-| `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (refactorer persona + core/refactoring-discipline skill) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
+| `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
 | `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the working diff against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on). |
 | `acceptanceEval.maxRounds` | No | `integer` | — | Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1). |
+| `acceptanceEval.clusterCeiling` | No | `integer` | — | Epic #4475 (M4-B). Max acceptance criteria one single-delivery acceptance critic scores in a single fresh-context pass. Single delivery clusters the Epic ## Acceptance Table ACs into ceil(totalACs / clusterCeiling) groups and spawns one maker-blind critic per cluster, restoring the distributed acceptance coverage the per-Story critic fan-out gave for free. Default 4; clamped into [1, 8] by lib/config/acceptance-eval.js so a large value cannot collapse the fan-out to a single diluted critic. Ignored on the fan-out route. |
 | `ci` | No | `object` | — | Nested configuration block. |
-| `ci.skipForStoryPushes` | No | `boolean` | — | Story #2899 (Epic #2880, F13). When true (default), pre-push tooling appends a '[skip ci]' trailer to Story-branch commit subjects so intermediate pushes do not stampede the CI fleet. The Epic-branch merge commit produced by story-close.js never carries the marker, regardless of this flag. |
-| `ci.earlyPr` | No | `boolean` | — | Story #4356 (Epic #4355). When true (default), /deliver opens the Epic PR early — before every Story merges — so CI starts warming while later waves run. Set false to defer PR creation until the Epic branch is complete. |
 | `ci.watch` | No | `object` | — | Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall. |
 | `ci.watch.pollIntervalMs` | No | `integer` | — | — |
 | `ci.watch.maxPolls` | No | `integer` | — | — |
 | `ci.watch.maxResumes` | No | `integer` | — | — |
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | — | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
-| `ci.requireChecks` | No | `boolean` | — | Story #4472. Fail-closed-without-checks policy. When true, the AutomergePredicate refuses to arm merge in a repo that reports zero required checks ('no checks reported'), treating the absent CI gate as a hard block. Defaults to false so a checks-less repo with green close-validation gates lands headlessly instead of parking on the operator-merges path. |
-| `preflight` | No | `object` | — | Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /deliver Phase 1 surfaces it via agent::blocked. |
-| `preflight.maxStories` | No | `integer` | — | — |
-| `preflight.maxWaves` | No | `integer` | — | — |
-| `preflight.maxInstallCostSeconds` | No | `integer` | — | — |
-| `preflight.maxGithubApiRequests` | No | `integer` | — | — |
-| `preflight.maxClaudeQuotaTokens` | No | `integer` | — | — |
-| `failOnConcurrencyHazards` | No | `boolean` | — | — |
+| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
+| `routing.roleScopedAgents` | No | `boolean` | — | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure (≈50KB → ≈8KB per spawn — the payoff of the context diet). When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
+| `routing.freshCriticSampleRate` | No | `number` | — | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Risk-routed ceremony sends a low-risk acceptance cluster down the contract-identical inline critic path, but this fraction of low-risk clusters is still forced through a fresh-context critic so low risk never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |
+| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | — | Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = risk-routed with the maker-checker sampling floor. |
+| `routing.closeAndLand` | No | `boolean` | — | When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge. |
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the Epic finalize listener auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Epic. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
@@ -447,13 +420,41 @@ suppress a channel entirely, set its array to `[]`.
 
 ## `planning`
 
-`/plan` tuning. All fields optional.
-
-| Field                          | Required | Default    | Purpose                                                                                          |
-| ------------------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
-| `riskHeuristics`               | No       | `[]`       | Free-form rubric for `risk::high` decisions (informational only — `risk::high` does not gate runtime). Accepts a plain array or the `{ append/prepend }` extender form. |
-| `failOnSharedEditors`          | No       | (none)     | Hard-fail Phase 7 when two Stories declare the same editor.                                       |
-| `requireExplicitCrossStoryDeps`| No       | (none)     | Require explicit cross-Story `blocked by` declarations rather than inferring from shared paths.   |
+`/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 |
+| --- | --- | --- | --- |
+| `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.context`
 
@@ -468,19 +469,20 @@ planning agent's context budget.
 
 ### `planning.codebaseSnapshot`
 
-Controls the Phase 7 codebase-snapshot fetcher that grounds story decomposition.
+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       | (none)      | Number of recent commits to summarise in the snapshot header.            |
+| `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`, and `coverage`. Override only when the
-project's source layout differs.
+`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
@@ -490,10 +492,21 @@ rather than a flat lexicographic slice — so a large, dot-prefixed tree like
 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` Phase 7 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.
+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. |
 
 ---
 
@@ -504,15 +517,14 @@ fall back to documented defaults (or are no-ops when omitted).
 
 ### `delivery.execution`
 
-| Field       | Required | Default | Purpose                                                            |
-| ----------- | -------- | ------- | ------------------------------------------------------------------ |
-| `timeoutMs` | No       | (none)  | Per-spawn timeout (ms) for child processes the framework launches. |
-
-### `delivery.maxTokenBudget`
+| Field       | Required | Default    | Purpose                                                            |
+| ----------- | -------- | ---------- | ------------------------------------------------------------------ |
+| `timeoutMs` | No       | `600000`   | Per-spawn timeout (ms) for child processes the framework launches. |
 
-| Field             | Required | Default | Purpose                                                            |
-| ----------------- | -------- | ------- | ------------------------------------------------------------------ |
-| `maxTokenBudget`  | No       | (none)  | Hydrated prompt cap for `hydrate-context` (character-based estimate + section elision). |
+> 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`
 
@@ -525,7 +537,7 @@ fall back to documented defaults (or are no-ops when omitted).
 | Field                       | Required | Default | Purpose                                          |
 | --------------------------- | -------- | ------- | ------------------------------------------------ |
 | `concurrencyCap`            | No       | `3`     | Max parallel Story sub-agents per wave.          |
-| `progressReportIntervalSec` | No       | `120`   | Progress-report cadence (seconds).               |
+| `verifyConcurrencyCap`      | No       | `4`     | Max parallel verify steps per wave.              |
 
 ### `delivery.worktreeIsolation`
 
@@ -535,14 +547,13 @@ checkout's HEAD.
 
 | Field                   | Required        | Default          | Purpose                                                     |
 | ----------------------- | --------------- | ---------------- | ----------------------------------------------------------- |
-| `enabled`               | No              | `false`          | Master switch.                                              |
+| `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.            |
-| `reapOnCancel`          | No              | `true`           | Reap the worktree if the Story is cancelled.                 |
-| `bootstrapFiles`        | No              | `[".env", ".mcp.json"]` | Untracked files copied into each new worktree. |
+| `bootstrapFiles`        | No              | `[".env", ".mcp.json", ".agentrc.local.json", ".agents/instructions.local.md"]` | Untracked files copied into each new worktree (local overrides included). |
 
 ### `delivery.signals`
 
@@ -550,7 +561,6 @@ Friction-detector thresholds consumed by progress-signal listeners.
 
 | Field                  | Required | Default | Purpose                                                                  |
 | ---------------------- | -------- | ------- | ------------------------------------------------------------------------ |
-| `hotspot.p95Multiplier`| No       | (none)  | Hot-file threshold expressed as a multiplier of the p95 edit frequency.   |
 | `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.                   |
 
@@ -686,74 +696,36 @@ baseline.
 | `lighthouse`      | No       | (none)  | Epsilon for Lighthouse rows.           |
 | `bundle-size`     | No       | (none)  | Epsilon for bundle-size rows.          |
 
-### `delivery.lifecycle`
-
-Knobs consumed by the lifecycle event bus (Epic #2172). `timeouts` is a
-per-event budget map (eventName → seconds) used by `TimeoutWatchdog`;
-missing entries fall back to in-listener defaults.
-
-| Field                  | Required | Default | Purpose                                                |
-| ---------------------- | -------- | ------- | ------------------------------------------------------ |
-| `timeouts`             | No       | `{}`    | `{ <eventName>: <seconds> }` watchdog budgets.         |
-| `heartbeatWarnSeconds` | No       | (none)  | No-progress threshold consumed by `HeartbeatMonitor`.  |
-
-### `delivery.epicAudit`
+### `delivery.codeReview`
 
-`/deliver` Phase 4 (epic-audit) auto-fix budget.
+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                                                              |
 | ------------------ | -------- | ------- | -------------------------------------------------------------------- |
-| `maxFixAttempts`   | No       | `3`     | Max auto-fix retry attempts per finding. `0` disables auto-fix.       |
+| `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`. |
-
-### `delivery.codeReview`
-
-Configuration block for the code-review pipeline that runs at **both**
-Story-close (`story-close.js`) and Epic-close (`/deliver` Phase 5).
-Selects the review backend, exposes an escape-hatch for adapter-specific
-configuration, and sets the auto-fix budget enforced at each close scope.
-
-| Field              | Required | Default    | Purpose                                                              |
-| ------------------ | -------- | ---------- | -------------------------------------------------------------------- |
-| `provider`         | No       | `"native"` | ReviewProvider adapter that produces the `Finding[]` consumed by `runCodeReview()`. See enum values below. |
-| `providerConfig`   | No       | `{}`       | Optional escape hatch for adapter-specific configuration. Reserved so future adapters can be configured without another schema migration; no documented keys in Epic #2815. |
-| `maxFixAttempts`   | No       | `3`        | Max auto-fix retry attempts per finding. `0` disables auto-fix. Applied at **both** Story-close and Epic-close. |
-| `maxFixScopeFiles` | No       | `5`        | Max file count a single auto-fix may modify before escalating to `agent::blocked`. Applied at **both** Story-close and Epic-close. |
-
-#### `provider` enum
-
-| Value      | Behaviour                                                                                                                                                                                                                                                          |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `native`   | Default. In-process maintainability/lint pass that runs without any external plugin. Always available.                                                                                                                                                              |
-| `codex`    | Invokes the `/codex:review` Claude Code plugin via the [`codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) backend. Selecting `codex` when the plugin is not installed hard-fails at factory construction with remediation guidance — there is no silent fallback to `native`. |
+| `autoFixSeverity`  | No       | `"medium"` | Severity threshold for on-branch remediation (`medium` or `high`). |
 
 #### Dual-scope fix budget
 
-`maxFixAttempts` and `maxFixScopeFiles` are enforced at two distinct
-points in the SDLC, using the **same configured values** for both scopes:
-
-- **Story-close** — `story-close.js` runs `runCodeReview()` against the
-  Story branch's diff and applies the budget per finding before merging
-  into `epic/<epicId>`.
-- **Epic-close** — `/deliver` Phase 5 runs `runCodeReview()` against
-  the integrated Epic branch and applies the same per-finding budget
-  before opening the PR to `main`.
-
-Setting `maxFixAttempts: 0` disables auto-fix at both scopes; there is no
-per-scope override.
-
-### `delivery.failOnConcurrencyHazards`
-
-| Field                       | Required | Default | Purpose                                                                                         |
-| --------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `failOnConcurrencyHazards`  | No       | (none)  | When `true`, hard-fail the plan if Phase 7 detects shared-editor or unsequenced cross-Story deps. |
+`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 Epic finalize listener 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`, the retro runner auto-files the retro's actionable routed proposals as GitHub follow-up issues (Story #4418). |
+| `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). |
 
 ---
 
@@ -765,7 +737,7 @@ number of keys.
 
 | File                              | Audience                            | Role                                                                                                                                |
 | --------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `.agentrc.json` (repo root)       | The framework dogfooding itself     | Live config used when running `/epic-*` and `/deliver` workflows against this repo. Exercises the framework end-to-end on its own source tree. |
+| `.agentrc.json` (repo root)       | The framework dogfooding itself     | Live config used when running `/plan` and `/deliver` against this repo. Exercises the framework end-to-end on its own source tree. |
 | `.agents/starter-agentrc.json`    | Downstream consumer repos           | Bootstrap delta-seed a consumer copies via `cp .agents/starter-agentrc.json .agentrc.json`. Minimum schema-required keys only.      |
 | `.agents/docs/agentrc-reference.json`       | Operators and reviewers             | Exhaustive editor reference enumerating every schema key with its framework default. Not a copy target.                             |
 
@@ -776,7 +748,7 @@ number of keys.
 | `delivery.quality.gates.crap.targetDirs`             | `[".agents/scripts"]`                 | `["src"]`                                  | Same reason as maintainability above.                                                                                            |
 | `github.owner` / `.repo` / `.projectNumber` | Populated for `dsj1984/mandrel` | `[OWNER]` / `[REPO]` / `null` | Shared repo identifiers; placeholders in the template are replaced by `node .agents/scripts/bootstrap.js` (or by hand). |
 | `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json` | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
-| `delivery.worktreeIsolation.nodeModulesStrategy`     | `per-worktree`                        | `per-worktree`                             | npm-only repo (`package-lock.json`); worktree init runs `npm ci` per tree.                                                       |
+| `delivery.worktreeIsolation.nodeModulesStrategy`     | `clone`                               | `clone`                                    | Platform default on darwin/linux (copy-on-write clone of donor `node_modules`); Windows dogfood/template use `per-worktree`.     |
 
 When a consumer runs `/mandrel-update`, the
 [`mandrel-sync-config`](../workflows/helpers/mandrel-sync-config.md)

package/.agents/docs/execution-reference.md

@@ -9,6 +9,30 @@ links here from the sections that used to inline this content.
 
 ---
 
+## Friction telemetry
+
+Reference mechanics behind the friction-telemetry MUST in
+[`instructions.md` § 1.H](../instructions.md). The always-loaded core keeps the
+MUST, the command, and the when-to-fire triggers; the detail below is consulted
+only when reasoning about **where** a friction record lands and **how** it is
+validated.
+
+- **Canonical record + schema validation**: `diagnose-friction.js` appends one
+  `kind: friction` record, validated write-time against
+  `signal-event.schema.json`, to the per-Epic/per-Story `signals.ndjson`
+  stream on local disk. The retro roll-up reads that stream back to aggregate
+  friction into routed proposals; nothing is posted to the GitHub ticket at
+  capture time.
+- **No-Epic context**: Outside an Epic/Story loop there is no per-Epic stream
+  to anchor to, so the record lands on the **standalone signal stream**
+  (`temp/standalone/stories/story-<sid>/signals.ndjson`) under the same
+  canonical schema.
+- **Never silently dropped**: The signal is never silently dropped — a
+  best-effort write failure is logged, not swallowed into a promise of a
+  side-file that no reader consumes.
+
+---
+
 ## Log-level control
 
 The orchestrator logger (`lib/Logger.js`) emits progress/trace output based on
@@ -17,36 +41,34 @@ the `AGENT_LOG_LEVEL` environment variable:
 - `silent` — only `fatal` emits; useful for script embedding where the caller
   owns presentation.
 - `info` — default. Emits `info` / `warn` / `error` / `fatal`.
-- `verbose` — adds `debug` trace output on top of the `info` set. `debug` is
-  accepted as a backward-compatible alias.
+- `verbose` — adds `debug` trace output (`Logger.debug`) on top of the `info`
+  set.
+
+Unrecognized `AGENT_LOG_LEVEL` values fall back to `info`. There is no
+`debug` level alias.
 
 This is a diagnostic knob: set it when you need quieter script embedding
 (`silent`) or a deeper trace (`verbose`). The friction-telemetry MUST it sits
-under — post friction to the relevant ticket via `diagnose-friction.js` — stays
-in [`instructions.md` § 1.H](../instructions.md).
+under — capture friction as a local NDJSON signal via `diagnose-friction.js` —
+stays in [`instructions.md` § 1.H](../instructions.md); its record-landing and
+schema mechanics are in [§ Friction telemetry](#friction-telemetry) above.
 
 ---
 
 ## FinOps & token budgeting (economic guardrails)
 
 Mandrel does **not** enforce live LLM spend from response metadata. The
-framework limits **hydrated prompt size** and optional **pre-dispatch
-estimates**; your host runtime (editor / CLI) owns session quota and hard
-stops. Consult this section when reasoning about why a task prompt was elided
-or why `/deliver` refused a fan-out on budget grounds.
-
-### Token budget (hydration + pre-dispatch estimates)
-
-- **`delivery.maxTokenBudget`** (`.agentrc.json`, resolved via
-  `lib/config/limits.js`): caps the task prompt built by
-  `hydrate-context` / `hydrateContext`. The pipeline uses a rough token
-  estimate (≈4 characters per token) and applies section-aware elision
-  (`elideEnvelope`) so oversized envelopes drop or summarize lower-priority
-  sections before you receive the prompt.
-- **`delivery.preflight.*`** (optional): before `/deliver` fan-out,
-  `epic-deliver-preflight.js` compares **estimated** story count, waves,
-  install time, GitHub API volume, and Claude quota tokens against configured
-  ceilings (`maxClaudeQuotaTokens`, etc.). A breach surfaces via
-  `agent::blocked`; there is no per-tool-call metering.
+framework limits **hydrated prompt size** via section-aware elision
+(`elideEnvelope`) and optional **pre-dispatch estimates**; your host
+runtime (editor / CLI) owns session quota and hard stops. Consult this
+section when reasoning about why a task prompt was elided or why `/deliver`
+refused a fan-out on budget grounds.
+
+### Session-mass capacity (plan-time sizing)
+
+- **`DEFAULT_MODEL_CAPACITY`** (`lib/orchestration/ticket-validator-sizing.js`):
+  absolute authored-token ceilings for plan-time Story sizing (soft 30k /
+  hard 75k). Not operator-configurable via `.agentrc.json`; programmatic
+  override via `opts.modelCapacity` on validateTickets / runPlanPersist only.
 - **Host runtime**: session billing, quota exhaustion, and operator overrides
   are enforced by your provider (e.g. Claude Code), not by Mandrel scripts.