mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/config/worktree-isolation.js

@@ -33,7 +33,6 @@ export const WORKTREE_ISOLATION_DEFAULTS = Object.freeze({
   primeFromPath: null,
   allowSymlinkOnWindows: false,
   reapOnSuccess: true,
-  reapOnCancel: true,
   // Gitignored workspace files copied into each new worktree. Includes the
   // operator's local-override files (`.agentrc.local.json`,
   // `.agents/instructions.local.md`) so a worktree-isolated agent honors the
@@ -84,10 +83,6 @@ export function getWorktreeIsolation(config) {
       typeof wi.reapOnSuccess === 'boolean'
         ? wi.reapOnSuccess
         : WORKTREE_ISOLATION_DEFAULTS.reapOnSuccess,
-    reapOnCancel:
-      typeof wi.reapOnCancel === 'boolean'
-        ? wi.reapOnCancel
-        : WORKTREE_ISOLATION_DEFAULTS.reapOnCancel,
     bootstrapFiles: Array.isArray(wi.bootstrapFiles)
       ? wi.bootstrapFiles
       : [...WORKTREE_ISOLATION_DEFAULTS.bootstrapFiles],

package/.agents/scripts/lib/config-resolver.js

@@ -19,7 +19,7 @@
  * deleted from the resolver wrapper. Every internal call site reads the
  * canonical `project` / `github` / `planning` / `delivery` blocks
  * directly; consumers upgrade in lockstep with the framework bump
- * (see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`).
+ * (see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`).
  */
 
 import fs from 'node:fs';
@@ -27,7 +27,6 @@ import path from 'node:path';
 import { getCiDelivery } from './config/ci.js';
 import { getCommands } from './config/commands.js';
 import { getGitHub } from './config/github.js';
-import { getLifecycle } from './config/lifecycle.js';
 import { resolvePaths } from './config/paths.js';
 import { validateOrchestrationConfig } from './config/validate-orchestration.js';
 import { getWorktreeIsolation } from './config/worktree-isolation.js';
@@ -43,10 +42,8 @@ export { NOTIFICATIONS_DEFAULTS } from './config/github.js';
 export {
   getLimits,
   LIMITS_DEFAULTS,
-  resolvePreflightCeilings,
 } from './config/limits.js';
 export { getPaths } from './config/paths.js';
-export { getPreflight, PREFLIGHT_DEFAULTS } from './config/preflight.js';
 export {
   CODING_GUARDRAILS_DEFAULTS,
   getQuality,
@@ -107,10 +104,8 @@ function applyDeliveryDefaults(rawDelivery) {
   delivery.worktreeIsolation = getWorktreeIsolation({
     worktreeIsolation: delivery.worktreeIsolation,
   });
-  delivery.lifecycle = getLifecycle({ lifecycle: delivery.lifecycle });
-  // Story #2899 (Epic #2880) — `delivery.ci` always carries
-  // `skipForStoryPushes: true` by default so Story-branch commit
-  // tooling applies the `[skip ci]` trailer without operator opt-in.
+  // `delivery.ci` always carries autoMerge (and passes watch through) so
+  // CI-aware delivery knobs resolve without operator opt-in.
   delivery.ci = getCiDelivery({ ci: delivery.ci });
   return delivery;
 }

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -64,40 +64,14 @@ const DELIVER_RUNNER_SCHEMA = {
   type: 'object',
   properties: {
     concurrencyCap: { type: 'integer', minimum: 1 },
-    progressReportIntervalSec: { type: 'integer', minimum: 0 },
     verifyConcurrencyCap: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };
 
 /**
- * `delivery.retro.perfThresholds` (Story #3042, Task #3043) — operator-tunable
- * gates for the retro perf-signals classifier. Defaults are documented inline
- * here and mirrored in `lib/orchestration/retro-perf-heuristics.js
- * (DEFAULT_RETRO_PERF_THRESHOLDS)` and the static schema mirror.
- *
- * `utilisation` / `bootstrapShare` are unit-interval ratios; values outside
- * [0, 1] fall back to defaults at the resolver. `capBindingRunLength` is a
- * positive integer count of consecutive cap-binding waves.
+ * `delivery.worktreeIsolation` — per-Story git worktree provisioning.
  */
-const RETRO_PERF_THRESHOLDS_SCHEMA = {
-  type: 'object',
-  properties: {
-    utilisation: { type: 'number', minimum: 0, maximum: 1 },
-    bootstrapShare: { type: 'number', minimum: 0, maximum: 1 },
-    capBindingRunLength: { type: 'integer', minimum: 1 },
-  },
-  additionalProperties: false,
-};
-
-const RETRO_SCHEMA = {
-  type: 'object',
-  properties: {
-    perfThresholds: RETRO_PERF_THRESHOLDS_SCHEMA,
-  },
-  additionalProperties: false,
-};
-
 const WORKTREE_ISOLATION_SCHEMA = {
   type: 'object',
   properties: {
@@ -110,11 +84,15 @@ const WORKTREE_ISOLATION_SCHEMA = {
     primeFromPath: { type: ['string', 'null'], minLength: 1 },
     allowSymlinkOnWindows: { type: 'boolean' },
     reapOnSuccess: { type: 'boolean' },
-    reapOnCancel: { type: 'boolean' },
     bootstrapFiles: {
       type: 'array',
       items: { type: 'string', minLength: 1 },
-      default: ['.env', '.mcp.json'],
+      default: [
+        '.env',
+        '.mcp.json',
+        '.agentrc.local.json',
+        '.agents/instructions.local.md',
+      ],
     },
   },
   additionalProperties: false,
@@ -132,20 +110,14 @@ const WORKTREE_ISOLATION_SCHEMA = {
 };
 
 /**
- * `delivery.signals` — detector thresholds for the three surviving
- * performance-signal categories. `churn` and `idle` were dropped (low
- * signal-to-noise). Each block is shallow-merged by the resolver.
+ * `delivery.signals` — detector thresholds for the surviving
+ * performance-signal categories. `hotspot` was retired with its detector
+ * (Epic #4406); `churn` and `idle` were dropped earlier (low signal-to-noise).
+ * Each block is shallow-merged by the resolver.
  */
 const SIGNALS_SCHEMA = {
   type: 'object',
   properties: {
-    hotspot: {
-      type: 'object',
-      properties: {
-        p95Multiplier: { type: 'number', minimum: 0 },
-      },
-      additionalProperties: false,
-    },
     rework: {
       type: 'object',
       properties: {
@@ -164,26 +136,6 @@ const SIGNALS_SCHEMA = {
   additionalProperties: false,
 };
 
-/**
- * `delivery.lifecycle` — knobs consumed by the lifecycle event bus
- * (Epic #2172). `timeouts` is a per-event budget map (eventName → seconds)
- * used by Story 11's `TimeoutWatchdog` listener; 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.
- */
-const LIFECYCLE_SCHEMA = {
-  type: 'object',
-  properties: {
-    timeouts: {
-      type: 'object',
-      additionalProperties: { type: 'integer', minimum: 1 },
-    },
-    heartbeatWarnSeconds: { type: 'integer', minimum: 1 },
-  },
-  additionalProperties: false,
-};
-
 /**
  * `delivery.mergeWatch` — knobs consumed by the MergeWatcher lifecycle
  * listener (Story #2896, Epic #2880). `intervalSeconds` is the poll
@@ -203,50 +155,38 @@ const MERGE_WATCH_SCHEMA = {
 };
 
 /**
- * `delivery.epicAudit` — bounded-retry knobs for /deliver Phase 4
- * (epic-audit). `maxFixAttempts` caps how many times the auto-fix loop
- * retries a single finding (Story #2611, Epic #2586). `maxFixScopeFiles`
- * caps how many files a single auto-fix may touch before escalating to
- * `agent::blocked` (default 5) — a deliberately narrow bound for
- * unattended auto-fixes, independent of the Story-sizing thresholds in
- * `ticket-validator-sizing.js`.
- *
- * `autoFixSeverity` (Story #4399) is the threshold that governs which findings
- * the Epic-close host-LLM remediation loop fixes on-branch. It is **tier-aware**
- * (Story #4412, Epic #4405): the Epic-close audit tier defaults to `high`
- * (route only 🔴 Critical + 🟠 High into remediation; 🟡 Medium + 🟢 Suggestion
- * graduate to follow-up issues) because 🟡 Medium code-quality concerns are
- * already remediated shift-left at the write-time and Story-scope tiers — the
- * slim outermost tier stops re-paying to fix them where a fix is most
- * expensive. Setting `medium` opts back into routing 🔴/🟠/🟡 on-branch. The
- * enum is the single validation seam: a configured value round-trips through
- * the resolver, and any value outside `['high', 'medium']` is rejected at load.
- * Hard cutover per `rules/git-conventions.md` — there is no back-compat flag.
+ * `delivery.epicAudit` was removed on v2 (Story-only delivery — no
+ * epic-audit runner). Remediation policy lives on `delivery.codeReview`
+ * (`CODE_REVIEW_SCHEMA` imported from the quality schema module).
  */
-const EPIC_AUDIT_SCHEMA = {
+
+// Epic #4478 (M7-B) — role-scoped-agent kill-switch + maker-checker floor.
+// Stage 6 dropped `delivery.routing.singleDelivery` (v1 epic route switch).
+// `delivery.routing.roleScopedAgents` (default true via getDeliveryRouting)
+// flips converted delivery spawns onto their `.claude/agents/<role>.md` boot
+// context; false falls back to `subagent_type: general-purpose` (the instant
+// per-consumer revert + the escape for hosts that ignore `.claude/agents/`).
+// `delivery.routing.freshCriticSampleRate` (default 0.2, clamped [0, 1]) is the
+// maker-checker sampling floor forcing a fraction of low-risk acceptance
+// clusters through a fresh critic.
+const ROUTING_SCHEMA = {
   type: 'object',
   properties: {
-    maxFixAttempts: { type: 'integer', minimum: 0 },
-    maxFixScopeFiles: { type: 'integer', minimum: 1 },
-    autoFixSeverity: { type: 'string', enum: ['high', 'medium'] },
+    roleScopedAgents: { type: 'boolean' },
+    freshCriticSampleRate: { type: 'number', minimum: 0, maximum: 1 },
+    ceremonyProfile: {
+      type: 'string',
+      enum: ['minimal', 'standard', 'strict'],
+    },
+    closeAndLand: { type: 'boolean' },
   },
   additionalProperties: false,
 };
 
-// Story #2899 (Epic #2880) — performance defaults + preflight (F13).
-// `delivery.ci.skipForStoryPushes` (default true via getCiDelivery): when
-// true, 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's merge
-// runner never carries the marker, regardless of this flag.
-//
-// Story #4356 (Epic #4355) — CI-aware delivery namespace. `earlyPr` gates
-// whether /deliver opens the Epic PR early (before every Story merges) so CI
-// starts warming while later waves run; defaults to `true` via getCiDelivery.
-// `watch.*` tunes the merge/CI watch poll loop (poll cadence, poll cap, and
-// how many times the watcher may resume after a transient stall).
-// `autoMerge` selects the merge posture: `"trust-ci"` (default) merges once
-// required checks pass, `"strict"` additionally requires a clean review gate.
+// Story #4356 (Epic #4355) — CI-aware delivery namespace. `watch.*` tunes
+// the merge/CI watch poll loop; `autoMerge` selects the merge posture.
+// Retired: `earlyPr` (Epic early-PR warmup) and `requireChecks` (no
+// AutomergePredicate reader on v2).
 const CI_WATCH_SCHEMA = {
   type: 'object',
   properties: {
@@ -260,33 +200,8 @@ const CI_WATCH_SCHEMA = {
 const CI_DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
-    skipForStoryPushes: { type: 'boolean' },
-    earlyPr: { type: 'boolean' },
     watch: CI_WATCH_SCHEMA,
     autoMerge: { type: 'string', enum: ['trust-ci', 'strict'] },
-    // 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 absence of a CI
-    // gate as a hard block instead of green. Defaults to `false` so a
-    // checks-less repo with green close-validation gates lands headlessly
-    // rather than parking on the operator-merges path.
-    requireChecks: { type: 'boolean' },
-  },
-  additionalProperties: false,
-};
-
-// Story #2899 (Epic #2880) — `delivery.preflight.*` thresholds consumed
-// by `epic-deliver-preflight.js`. When any value is exceeded the CLI
-// surfaces a breach in its envelope and the workflow flips the Epic to
-// `agent::blocked` (see /deliver Phase 1 prelude).
-const PREFLIGHT_SCHEMA = {
-  type: 'object',
-  properties: {
-    maxStories: { type: 'integer', minimum: 1 },
-    maxWaves: { type: 'integer', minimum: 1 },
-    maxInstallCostSeconds: { type: 'integer', minimum: 1 },
-    maxGithubApiRequests: { type: 'integer', minimum: 1 },
-    maxClaudeQuotaTokens: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };
@@ -296,8 +211,8 @@ const PREFLIGHT_SCHEMA = {
  * checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly
  * additive and default-OFF: when `enabled` is unset or `false`, story-deliver
  * behaves exactly as before. When `true`, the worker runs an advisory
- * post-green refactor pass (the `refactorer` persona +
- * `core/refactoring-discipline` skill) after the suite is green. The stage is
+ * post-green refactor pass (the `core/code-review-and-quality` skill's
+ * Post-Green Refactor Pass) after the suite is green. The stage is
  * advisory only — it never changes existing close-validation gate semantics.
  */
 const REFACTOR_STAGE_SCHEMA = {
@@ -306,7 +221,7 @@ const REFACTOR_STAGE_SCHEMA = {
     enabled: {
       type: 'boolean',
       description:
-        '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.',
+        '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.',
     },
   },
   additionalProperties: false,
@@ -337,6 +252,12 @@ const ACCEPTANCE_EVAL_SCHEMA = {
       description:
         'Maximum number of redraft rounds the acceptance self-eval loop runs before escalating to agent::blocked when criteria remain unmet. Default 2; clamped into [1, hard ceiling] by the resolver so the cap can never be disabled.',
     },
+    clusterCeiling: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        '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 the resolver so a large value cannot collapse the fan-out to a single diluted critic. Ignored on the fan-out route.',
+    },
   },
   additionalProperties: false,
 };
@@ -368,30 +289,19 @@ export const DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
     execution: EXECUTION_SCHEMA,
-    maxTokenBudget: { type: 'integer', minimum: 1 },
     lease: LEASE_SCHEMA,
     docsFreshness: DOCS_FRESHNESS_SCHEMA,
     deliverRunner: DELIVER_RUNNER_SCHEMA,
     worktreeIsolation: WORKTREE_ISOLATION_SCHEMA,
     signals: SIGNALS_SCHEMA,
     quality: QUALITY_SCHEMA,
-    lifecycle: LIFECYCLE_SCHEMA,
     mergeWatch: MERGE_WATCH_SCHEMA,
-    epicAudit: EPIC_AUDIT_SCHEMA,
     codeReview: CODE_REVIEW_SCHEMA,
-    retro: RETRO_SCHEMA,
     refactorStage: REFACTOR_STAGE_SCHEMA,
     acceptanceEval: ACCEPTANCE_EVAL_SCHEMA,
     feedbackLoop: FEEDBACK_LOOP_SCHEMA,
     ci: CI_DELIVERY_SCHEMA,
-    preflight: PREFLIGHT_SCHEMA,
-    // Cross-Story concurrency-hazard gate (Story #2297). When true,
-    // `epic-deliver-prepare` refuses to flip the Epic to
-    // `agent::executing` if the upcoming waves still carry any conflict
-    // finding (Story #2296). Off by default; operators using the gate
-    // also need to wire findings into prepare via the runtime injection
-    // surface.
-    failOnConcurrencyHazards: { type: 'boolean' },
+    routing: ROUTING_SCHEMA,
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config-settings-schema-quality.js

@@ -96,6 +96,15 @@ export const QUALITY_SCHEMA = {
     codingGuardrails: CODING_GUARDRAILS_SCHEMA,
     autoRefresh: AUTO_REFRESH_SCHEMA,
     baselineEpsilon: BASELINE_EPSILON_SCHEMA,
+    // Story #4495. Fail-closed baseline-enforcement policy for the unified
+    // check-baselines close-validation gate. Default false: a consumer that
+    // enables baseline gates but has not committed baseline artifacts under
+    // baselines/ gets a clean skip-with-reason from buildDefaultGates rather
+    // than 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 (the fail-closed posture, analogous to
+    // delivery.ci.requireChecks).
+    requireBaselines: { type: 'boolean' },
     // 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
@@ -114,12 +123,11 @@ export const QUALITY_SCHEMA = {
 };
 
 /**
- * `delivery.codeReview` — sibling to `delivery.epicAudit`. Same bounded
- * retry + scope cap, applied to /deliver Phase 5 (code-review).
+ * `delivery.codeReview` — review-provider chain + bounded-retry knobs for
+ * the /deliver code-review ceremony (Story-close and plan-run close).
  *
- * `autoFixSeverity` (Story #4399) is the sibling of
- * `delivery.epicAudit.autoFixSeverity`: the threshold that governs which
- * Phase 5 findings the host-LLM focused-fix routing remediates on-branch —
+ * `autoFixSeverity` (Story #4399) is the threshold that governs which
+ * findings the host-LLM focused-fix routing remediates on-branch —
  * `medium` (default) routes 🔴/🟠/🟡 while 🟢 still graduates, `high`
  * reproduces the pre-4399 Critical/High-only routing.
  */
@@ -135,15 +143,10 @@ export const CODE_REVIEW_SCHEMA = {
     // hatch reserved for adapter-specific options.
     //
     // Story #2871 added `security-review` to the inline registry plus
-    // a multi-provider `providers: []` chain shape. When `providers` is
-    // set and non-empty, it wins over the legacy single-string
-    // `provider` field. Chain entries can also reference the
-    // `ultrareview` manual-prompt provider via `manualPrompt: true`.
-    provider: {
-      type: 'string',
-      enum: ['native', 'codex', 'security-review'],
-      default: 'native',
-    },
+    // the `providers: []` chain shape. Chain entries can also reference
+    // the `ultrareview` manual-prompt provider via `manualPrompt: true`.
+    // When `providers` is unset or empty, the factory defaults to
+    // `[{ name: 'native' }]`.
     providers: {
       type: 'array',
       items: {

package/.agents/scripts/lib/config-settings-schema.js

@@ -246,66 +246,80 @@ const CODEBASE_SNAPSHOT_SCHEMA = {
   additionalProperties: false,
 };
 
-/**
- * `planning.taskSizing` — Story-sizing thresholds consumed by
- * `ticket-validator-sizing.js`. Operator overrides shallow-merge with
- * `DEFAULT_TASK_SIZING` defaults (softFiles 15, hardFiles 30,
- * softAcceptanceCount 10 — the uniform relaxed profile from Story #3874).
- * 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. The hard `maxAcceptance` ceiling was removed after
- * the Epic #4355 decomposition experiment — acceptance mass is advisory-only.
- */
-const TASK_SIZING_SCHEMA = {
-  type: 'object',
-  properties: {
-    softFiles: { type: 'integer', minimum: 1 },
-    hardFiles: { type: 'integer', minimum: 1 },
-    softAcceptanceCount: { type: 'integer', minimum: 1 },
-    // Under-size (merge-candidate) thresholds (Story #4312). A Story whose
-    // footprint is at or below BOTH ceilings and that carries a `depends_on`
-    // edge to a sibling trips the advisory `merge-candidate` soft finding.
-    mergeCandidateMaxFiles: { type: 'integer', minimum: 1 },
-    mergeCandidateMaxAcceptance: { type: 'integer', minimum: 1 },
-  },
-  additionalProperties: false,
-};
-
 const PLANNING_SCHEMA = {
   type: 'object',
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
     context: PLANNING_CONTEXT_SCHEMA,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
-    taskSizing: TASK_SIZING_SCHEMA,
     // Cross-Story conflict-finding severity gates. Off by default so
     // existing repos keep advisory-only behaviour; flipping either to
     // `true` upgrades the matching finding class to `'hard'`, which routes
     // it through the validator's `errors[]` channel and trips the bounded
     // decompose loop's re-prompt gate.
-    failOnSharedEditors: { type: 'boolean' },
-    requireExplicitCrossStoryDeps: { type: 'boolean' },
+    // `planning.modelCapacity` was collapsed to the framework constant
+    // `DEFAULT_MODEL_CAPACITY` in ticket-validator-sizing.js (authored-
+    // tokens-only mass); setting it in a config is rejected as an
+    // additional property.
+    failOnSharedEditors: {
+      type: 'boolean',
+      description:
+        'When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only).',
+    },
+    requireExplicitCrossStoryDeps: {
+      type: 'boolean',
+      description:
+        'When true, upgrade implicit cross-Story dependency findings to hard errors (default false — advisory soft findings only).',
+    },
     // Cross-cutting registry conflict knobs consumed by
     // `ticket-validator-conflicts.js` (wired through
     // `epic-plan-decompose/phases/planning-artifacts.js`).
     // `crossCuttingRegistries` names the registry paths whose concurrent
     // edits are flagged; `failOnRegistryConflicts` upgrades that finding to
     // `'hard'`. `failOnLargeFanOut` / `largeFanOutThreshold` gate the
-    // single-Story fan-out finding.
-    crossCuttingRegistries: LIST_OR_EXTENDER_OF_STRINGS,
-    failOnRegistryConflicts: { type: 'boolean' },
-    failOnLargeFanOut: { type: 'boolean' },
-    largeFanOutThreshold: { type: 'integer', minimum: 0 },
+    // delete blast-radius finding (call sites of a module a Story marks
+    // `assumption: "deletes"`).
+    crossCuttingRegistries: {
+      ...LIST_OR_EXTENDER_OF_STRINGS,
+      description:
+        'Registry path patterns whose concurrent edits across Stories are flagged as conflicts. Defaults to the framework listener/handler index patterns when omitted.',
+    },
+    failOnRegistryConflicts: {
+      type: 'boolean',
+      description:
+        'When true, upgrade cross-cutting registry conflict findings to hard errors (default false).',
+    },
+    failOnLargeFanOut: {
+      type: 'boolean',
+      description:
+        'When true, upgrade fan-out-warning findings (delete blast radius) to hard errors (default false — soft advisory).',
+    },
+    largeFanOutThreshold: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        '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.',
+    },
     // Navigability-reachability config consumed by the plan-persist draft
-    // reachability gate (Epic #4131 F7; demoted into persist by #4474 PR6 —
-    // the manual epic-plan-healthcheck --paranoid re-check reads it too).
+    // reachability gate (Epic #4131 F7; demoted into persist by #4474 PR6).
     // Opt-in: absent or empty routeGlobs degrades to a silent no-op.
     navigation: {
       type: 'object',
+      description:
+        'Opt-in navigability reachability gate. Absent or empty routeGlobs is a silent no-op.',
       properties: {
-        routeGlobs: { type: 'array', items: { type: 'string' } },
-        navRegistry: { type: 'array', items: { type: 'string' } },
+        routeGlobs: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Glob patterns (e.g. pages/**, app/**/route.ts) marking paths that add a user-facing route.',
+        },
+        navRegistry: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference.',
+        },
       },
       additionalProperties: false,
     },

package/.agents/scripts/lib/dependency-parser.js

@@ -2,8 +2,9 @@
  * dependency-parser.js — Shared Dependency & Metadata Parsing Utilities
  *
  * Canonical implementation of dependency-related regex parsing and
- * ticket metadata extraction. Eliminates duplicated implementations
- * across dispatcher.js, verify-prereqs.js, and providers/github.js.
+ * ticket metadata extraction, shared by the ticketing provider and the
+ * orchestration layer (e.g. providers/github/tickets.js,
+ * lib/story-adjacency.js, lib/branch-name-guard.js).
  */
 
 /**

package/.agents/scripts/lib/doc-tiers.js

@@ -7,8 +7,8 @@
  *
  *   - `alwaysLoaded`  — `CLAUDE.md` plus the transitive closure of its
  *                       `@`-import references (`@AGENTS.md`,
- *                       `@.agents/instructions.md`, the persona, the always-on
- *                       rules, …). This is the context every session re-pays
+ *                       `@.agents/instructions.md`, the always-on rules, …).
+ *                       This is the context every session re-pays
  *                       on every subagent spawn (instructions.md § 4), so it is
  *                       the primary budget the context-budget ratchet gates.
  *   - `mandatoryRead` — the resolved `project.docsContextFiles` set (prefixed
@@ -24,10 +24,16 @@
  *   - `onDemand`      — the on-demand `.agents/rules/*.md` set (instructions.md
  *                       § 1.F): every rule file that is **not** part of the
  *                       always-on core already captured in `alwaysLoaded`.
+ *   - `agentBoot`     — the role-scoped boot contexts `.agents/agents/*.md`
+ *                       (issue #4478). Each is a standalone system prompt a
+ *                       converted spawn boots on **instead of** the always-loaded
+ *                       closure, so it is budgeted independently (per-file ≤8KB
+ *                       ceiling gated by `check-context-budget.js`).
  *
  * A file that could appear in more than one tier is kept in its **highest**
  * tier only (alwaysLoaded > mandatoryRead > digestVisible > onDemand), so the
- * four arrays partition the doc set with no double-counting.
+ * arrays partition the doc set with no double-counting. `agentBoot` is disjoint
+ * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set).
  *
  * The closure is discovered by parsing `@`-import references and following
  * them recursively (cycle-safe via a visited set). A candidate `@`-token only
@@ -216,6 +222,7 @@ export function docsContextPaths(config) {
  *   mandatoryRead: Array<{ path: string, bytes: number }>,
  *   digestVisible: Array<{ path: string, bytes: number }>,
  *   onDemand: Array<{ path: string, bytes: number }>,
+ *   agentBoot: Array<{ path: string, bytes: number }>,
  * } }}
  */
 export function resolveDocTiers(
@@ -254,7 +261,35 @@ export function resolveDocTiers(
   //    (the always-on ones already live in the alwaysLoaded closure).
   const onDemand = collect(listOnDemandRules(root, fs));
 
-  return { tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } };
+  // 5. agent-boot: role-scoped boot contexts .agents/agents/*.md (#4478). These
+  //    are standalone system prompts, disjoint from the doc read-tiers.
+  const agentBoot = collect(listAgentDefs(root, fs));
+
+  return {
+    tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand, agentBoot },
+  };
+}
+
+/**
+ * List the role-scoped agent-boot defs (repo-relative posix): every
+ * `.agents/agents/*.md`. Returns [] when the directory is absent.
+ *
+ * @param {string} root absolute repo root
+ * @param {FsLike} fs
+ * @returns {string[]}
+ */
+function listAgentDefs(root, fs) {
+  const agentsDir = path.resolve(root, '.agents', 'agents');
+  let names;
+  try {
+    names = fs.readdirSync(agentsDir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith('.md'))
+    .map((n) => path.posix.join('.agents', 'agents', n))
+    .sort();
 }
 
 /**