mandrel 1.94.0 → 2.1.0

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

@@ -32,9 +32,11 @@ const EXECUTION_SCHEMA = {
 
 /**
  * `delivery.lease` — assignee-as-lease primitive (Story #3480). `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`.
+ * the staleness window: a ticket claim whose owner's last heartbeat is older
+ * than this many milliseconds is reclaimable by another operator. Defaults to
+ * 900000 (15 min) in `lib/config/limits.js`. Note the shipped guards fail
+ * closed (no live heartbeat source since A22 removed the inert emitter), so
+ * a stranded claim is cleared with `--steal` rather than by TTL expiry.
  */
 const LEASE_SCHEMA = {
   type: 'object',
@@ -64,40 +66,13 @@ 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 +85,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 +111,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: {
@@ -165,115 +138,73 @@ const SIGNALS_SCHEMA = {
 };
 
 /**
- * `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
- * 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`. Both keys default in the listener when omitted
- * (30s / 3600s).
+ * `delivery.mergeWatch` — knobs consumed by the close-and-land merge wait
+ * listener (Story #2896, Epic #2880) and by the close-and-land merge wait
+ * (`single-story-close/phases/confirm-merge.js`). `intervalSeconds` is the
+ * poll cadence between `gh pr view` probes after the arm.
+ *
+ * The two budgets are deliberately separate axes (Story #4543):
+ *
+ *   - `maxWaitSeconds` bounds **one invocation** of the merge wait. Its
+ *     default (300s) fits inside a single host tool invocation, whose
+ *     ceiling is ~10 minutes; the gates that run before the wait already
+ *     consume minutes of that. Expiry is NOT a block — the wait returns a
+ *     resumable `pending` terminal with no label mutation. A headless caller
+ *     with no such ceiling raises it to keep land-in-one-block semantics.
+ *   - `maxBudgetSeconds` bounds the **cumulative** wait across resumes,
+ *     anchored at the PR's `createdAt` so re-entering the wait does not
+ *     restart the clock. Exhausting *this* is the genuine give-up condition
+ *     that classifies and blocks.
+ *
+ * `updateAttempts` caps how many times the wait will bring a
+ * behind-the-base PR up to date before giving the branch up as unwinnable,
+ * rather than waiting out the budget behind a base it could have merged.
+ * All keys default in the consumer when omitted (30s / 300s / 3600s / 3).
  */
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   properties: {
     intervalSeconds: { type: 'integer', minimum: 1 },
+    maxWaitSeconds: { type: 'integer', minimum: 1 },
     maxBudgetSeconds: { type: 'integer', minimum: 1 },
+    updateAttempts: { type: 'integer', minimum: 0 },
   },
   additionalProperties: false,
 };
 
 /**
- * `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 = {
-  type: 'object',
-  properties: {
-    maxFixAttempts: { type: 'integer', minimum: 0 },
-    maxFixScopeFiles: { type: 'integer', minimum: 1 },
-    autoFixSeverity: { type: 'string', enum: ['high', 'medium'] },
-  },
-  additionalProperties: false,
-};
 
-// Epic #4475 (M4-A) — single-delivery routing kill-switch.
-// `delivery.routing.singleDelivery` (default true via getDeliveryRouting) is
-// the global kill-switch for the single-delivery route. When true (the
-// default), an Epic marked `delivery::single` at plan time routes to the
-// single-delivery helper; when false, EVERY Epic — even a single-marked one —
-// is forced down the fan-out path (the instant, code-rollback-free per-consumer
-// revert). Shipped INERT in M4-A: the router's single verdict falls through to
-// fan-out until M4-B wires the executor, so the knob has no observable effect
-// yet.
 // 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.
+// maker-checker sampling floor forcing a fraction of low-derived-level
+// acceptance clusters through a fresh critic.
 const ROUTING_SCHEMA = {
   type: 'object',
   properties: {
-    singleDelivery: { type: 'boolean' },
     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: {
@@ -287,33 +218,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,
 };
@@ -401,31 +307,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,
     routing: ROUTING_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' },
   },
   additionalProperties: false,
 };

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

@@ -14,12 +14,20 @@
 // aggregate into per-gate files under `config/gates/`.
 import { GATES_SCHEMA } from './config/gates/index.js';
 
+// Story #4531: miDropMustRefactor (here) and autoRefresh.miDropCap (below)
+// were retired. Both were schema-validated, defaulted, and resolved, but
+// never consumed by the gate they were named for — quality-preview.js's
+// computeExitCode short-circuits on miExit (derived from the ALREADY-
+// consumed delivery.quality.gates.maintainability.tolerance) before either
+// knob is ever read. maintainability.tolerance is now the single documented
+// MI-drop control. See lib/migrations/index.js for the consumer-config
+// migration that strips these keys on upgrade (additionalProperties: false
+// below means a leftover key is a hard AJV failure, not a silent no-op).
 const CODING_GUARDRAILS_SCHEMA = {
   type: 'object',
   properties: {
     cyclomaticFlag: { type: 'integer', minimum: 1 },
     cyclomaticMustFix: { type: 'integer', minimum: 1 },
-    miDropMustRefactor: { type: 'number', minimum: 0 },
     requireSiblingTest: { type: 'boolean' },
   },
   additionalProperties: false,
@@ -29,7 +37,6 @@ const AUTO_REFRESH_SCHEMA = {
   type: 'object',
   properties: {
     enabled: { type: 'boolean' },
-    miDropCap: { type: 'number', minimum: 0 },
     crapJumpCap: { type: 'number', minimum: 0 },
     scope: { type: 'string', enum: ['diff', 'full'] },
   },
@@ -123,12 +130,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.
  */
@@ -144,15 +150,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

@@ -109,25 +109,57 @@ const PROJECT_SCHEMA = {
 
 /**
  * Curated webhook event vocabulary. The webhook channel is gated by an
- * explicit allowlist of event names — the webhook narrative is "epic %
- * progress + blockers", not the firehose of per-story transitions that the
- * GitHub-comment channel still receives.
+ * explicit allowlist of event names — the vocabulary mirrors the events the
+ * v2 runtime actually emits through `notify()` (Story transitions, merge
+ * outcomes, loop lifecycle beats).
+ *
+ * `story.heartbeat` was retired here (A22): the vocabulary's contract is
+ * "events the runtime actually emits", and nothing could emit this one. Its
+ * emitter (`emit-story-heartbeat.js`) demanded an `epicId >= 1` while the
+ * sole call path (`single-story-init.js` → `setActiveStoryEnv`) passed
+ * `epicId: null`, so `CC_EPIC_ID` was never set and the hook that would have
+ * fired the beat always short-circuited. Emitter, hook, and schema are all
+ * deleted; keeping the name allowlistable would let an operator subscribe to
+ * a channel that can never deliver. Removing it from the enum makes a
+ * resurrection fail loudly at config-validation time rather than silently
+ * never firing.
  */
 export const WEBHOOK_EVENT_NAMES = Object.freeze([
-  'epic-started',
-  'epic-progress',
-  'epic-blocked',
-  'epic-unblocked',
-  'epic-complete',
+  'state-transition',
+  'story-merged',
+  'story-closing',
+  'operator-message',
+  'merge.unlanded',
+  'merge.flip-failed',
+  'loop.tick',
 ]);
 
 /**
  * Curated GitHub-comment event vocabulary. The comment channel is gated by
  * an explicit allowlist of event names — same model as `webhookEvents`.
+ *
+ * **Deliberately narrower than {@link WEBHOOK_EVENT_NAMES}**, and the axis
+ * is ticket scope, not importance. A comment is written *onto a Story
+ * issue*, so only events that are about one Story, and whose message reads
+ * as narrative an operator wants durably on the ticket, belong here. The
+ * webhook-only remainder — `merge.unlanded`, `merge.flip-failed`,
+ * `loop.tick` — are run-scoped or firehose beats;
+ * mirroring them onto the ticket would bury the narrative under machine
+ * chatter, and `notify()` drops a comment for any dispatch without a
+ * resolvable ticket id regardless.
+ *
+ * `story-closing` IS in scope by that rule (Story-scoped, `level: 'story'`,
+ * human-readable — the same shape as `story-merged`) and its earlier
+ * absence was an oversight: the event was emittable to webhooks but could
+ * not be allowlisted for comments at all. It is in the vocabulary but NOT
+ * in the shipped default (`config/github.js` `NOTIFICATIONS_DEFAULTS`) —
+ * opting in is an operator choice, not a behaviour change forced on every
+ * consumer.
  */
 export const COMMENT_EVENT_NAMES = Object.freeze([
   'state-transition',
   'story-merged',
+  'story-closing',
   'operator-message',
 ]);
 
@@ -208,19 +240,14 @@ const GITHUB_SCHEMA = {
 // planning.* — inputs to /plan
 // ---------------------------------------------------------------------------
 
-/**
- * `planning.context` — bounded planning-context budget for `--emit-context`
- * payloads. When the full payload would exceed `maxBytes`, planners switch
- * to a summary representation.
- */
-const PLANNING_CONTEXT_SCHEMA = {
-  type: 'object',
-  properties: {
-    maxBytes: { type: 'integer', minimum: 1024 },
-    summaryMode: { type: 'string', enum: ['auto', 'always', 'never'] },
-  },
-  additionalProperties: false,
-};
+// Story #4541: `planning.context.{maxBytes, summaryMode}` was retired. The
+// `applyBudget` pass it fed lost its last caller in the v2 cutover, and it
+// bounded a field the envelope builders discarded before shipping the raw seed
+// anyway — so the key resolved but capped nothing. The live bound on
+// planner-context size is the fixed `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` in
+// `lib/orchestration/plan-context.js`. Setting `planning.context` is now
+// rejected as an additional property, so a resurrected key fails loudly rather
+// than silently doing nothing.
 
 /**
  * Story #2634 — `planning.codebaseSnapshot` controls the structural
@@ -246,66 +273,79 @@ 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,
     },