mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/config/quality.js

@@ -366,14 +366,19 @@ function resolveCoverageGate(userBlock) {
 }
 
 /**
- * Framework defaults for `delivery.quality.codingGuardrails`. The legacy
- * field name `miDropRefactor` was renamed to `miDropMustRefactor` in
- * Story 1 to avoid semantic collision with `autoRefresh.miDropCap`.
+ * Framework defaults for `delivery.quality.codingGuardrails`.
+ *
+ * `miDropMustRefactor` was retired in Story #4531: schema-validated,
+ * defaulted, and resolved, but never consumed — the gate it named
+ * (`quality-preview.js`'s `computeExitCode`) short-circuits on `miExit`
+ * (derived from the already-consumed `gates.maintainability.tolerance`)
+ * before this value is ever read. `maintainability.tolerance` is the one
+ * documented MI-drop control now; see `lib/migrations/index.js` for the
+ * consumer-config migration that strips a leftover key on upgrade.
  */
 export const CODING_GUARDRAILS_DEFAULTS = Object.freeze({
   cyclomaticFlag: 8,
   cyclomaticMustFix: 12,
-  miDropMustRefactor: 1.5,
   requireSiblingTest: false,
 });
 
@@ -393,8 +398,6 @@ export function resolveCodingGuardrails(userBlock) {
     cyclomaticFlag: userBlock.cyclomaticFlag ?? defaults.cyclomaticFlag,
     cyclomaticMustFix:
       userBlock.cyclomaticMustFix ?? defaults.cyclomaticMustFix,
-    miDropMustRefactor:
-      userBlock.miDropMustRefactor ?? defaults.miDropMustRefactor,
     requireSiblingTest:
       typeof userBlock.requireSiblingTest === 'boolean'
         ? userBlock.requireSiblingTest
@@ -402,9 +405,10 @@ export function resolveCodingGuardrails(userBlock) {
   };
 }
 
+// autoRefresh.miDropCap was retired alongside codingGuardrails.
+// miDropMustRefactor in Story #4531 — same unconsumed-knob shape, same fix.
 const AUTO_REFRESH_DEFAULTS = Object.freeze({
   enabled: true,
-  miDropCap: 1.5,
   crapJumpCap: 5,
   scope: 'diff',
 });
@@ -416,7 +420,6 @@ function resolveAutoRefresh(userBlock) {
   if (userBlock == null || typeof userBlock !== 'object') {
     return {
       enabled: defaults.enabled,
-      miDropCap: defaults.miDropCap,
       crapJumpCap: defaults.crapJumpCap,
       scope: defaults.scope,
     };
@@ -429,12 +432,6 @@ function resolveAutoRefresh(userBlock) {
       typeof userBlock.enabled === 'boolean'
         ? userBlock.enabled
         : defaults.enabled,
-    miDropCap:
-      typeof userBlock.miDropCap === 'number' &&
-      Number.isFinite(userBlock.miDropCap) &&
-      userBlock.miDropCap >= 0
-        ? userBlock.miDropCap
-        : defaults.miDropCap,
     crapJumpCap:
       typeof userBlock.crapJumpCap === 'number' &&
       Number.isFinite(userBlock.crapJumpCap) &&

package/.agents/scripts/lib/config/runners.js

@@ -3,18 +3,11 @@
  *
  * Post-reshape, only `delivery.deliverRunner` and `delivery.codeReview` are
  * configurable via this accessor; everything else lives in framework-internal
- * constants exported alongside (`DEFAULT_STORY_MERGE_RETRY`,
- * `DEFAULT_DECOMPOSER`). `delivery.epicAudit` was removed on v2 (Story-only
- * delivery — no epic-audit runner; remediation policy lives on
- * `delivery.codeReview`).
+ * constants exported alongside (`DEFAULT_DECOMPOSER`).
+ * `delivery.epicAudit` was removed on v2 (Story-only delivery — no
+ * epic-audit runner; remediation policy lives on `delivery.codeReview`).
  */
 
-/** Hardcoded story-merge retry policy (was `orchestration.runners.storyMergeRetry`). */
-export const DEFAULT_STORY_MERGE_RETRY = Object.freeze({
-  maxAttempts: 3,
-  backoffMs: Object.freeze([250, 500, 1000]),
-});
-
 /** Hardcoded decomposer concurrency cap (was `orchestration.runners.decomposer.concurrencyCap`). */
 export const DEFAULT_DECOMPOSER = Object.freeze({
   concurrencyCap: 3,
@@ -33,14 +26,13 @@ export const DEFAULT_DECOMPOSER = Object.freeze({
  * reduces wall-clock time where dependencies allow. See `deliver.md` and
  * `agentrc-reference.json` `delivery.deliverRunner.concurrencyCap`.
  *
- * **`verifyConcurrencyCap`** (Epic #3019 Tech Spec §1.4 / Story #3024) is a
- * separate knob that bounds the `verifyWaveResults` loop independently of
- * Story-dispatch concurrency, so operators can tune ticket-verify parallelism
- * without raising the wave fan-out. Default 4.
+ * Story #4545 removed the sibling `verifyConcurrencyCap`: the
+ * `verifyWaveResults` loop it claimed to bound never existed in the tree, and
+ * its only reader was the retired execution-analysis CLI, which echoed the
+ * number into a report rather than bounding anything.
  */
 const DEFAULT_DELIVER_RUNNER = Object.freeze({
   concurrencyCap: 3,
-  verifyConcurrencyCap: 4,
 });
 
 /**
@@ -59,9 +51,8 @@ export const DEFAULT_CODE_REVIEW = Object.freeze({
  *
  * @param {object | null | undefined} config
  * @returns {{
- *   deliverRunner: { concurrencyCap: number, verifyConcurrencyCap: number },
+ *   deliverRunner: { concurrencyCap: number },
  *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
- *   storyMergeRetry: { maxAttempts: number, backoffMs: readonly number[] },
  *   decomposer: { concurrencyCap: number },
  * }}
  */
@@ -73,9 +64,6 @@ export function getRunners(config) {
       concurrencyCap:
         deliverRunnerUser.concurrencyCap ??
         DEFAULT_DELIVER_RUNNER.concurrencyCap,
-      verifyConcurrencyCap:
-        deliverRunnerUser.verifyConcurrencyCap ??
-        DEFAULT_DELIVER_RUNNER.verifyConcurrencyCap,
     },
     codeReview: {
       maxFixAttempts:
@@ -85,7 +73,6 @@ export function getRunners(config) {
       autoFixSeverity:
         codeReviewUser.autoFixSeverity ?? DEFAULT_CODE_REVIEW.autoFixSeverity,
     },
-    storyMergeRetry: DEFAULT_STORY_MERGE_RETRY,
     decomposer: DEFAULT_DECOMPOSER,
   };
 }

package/.agents/scripts/lib/config/temp-paths.js

@@ -13,15 +13,13 @@
  *     ├─ techspec.md
  *     ├─ manifest.md          (dispatch manifest)
  *     ├─ retro.md             (mirror of GitHub retro at Epic close)
- *     ├─ perf-report.md       (analyzer output, Epic-level)
  *     ├─ lifecycle.ndjson     (lifecycle bus ledger)
  *     ├─ checkpoints/...      (pre-v2 epic-runner state store; retained layout)
- *     ├─ <name>               (epicArtifactPath escape hatch)
+ *     ├─ <name>               (runArtifactPath escape hatch)
  *     └─ stories/
  *        └─ story-<sid>/
  *           ├─ manifest.md       (story dispatch manifest)
  *           ├─ signals.ndjson    (append-only signals writer)
- *           ├─ perf-summary.md
  *           └─ <name>            (storyArtifactPath escape hatch)
  *
  * Standalone Stories (no parent Epic) follow the same shape under
@@ -42,11 +40,12 @@
  * resolve a *relative* `tempRoot` against the **main checkout root** (the
  * parent of `git rev-parse --git-common-dir`) rather than `process.cwd()`.
  * Without this, a story child that `cd`s into `.worktrees/story-<id>/` before
- * calling `story-phase.js` would append `story.heartbeat` records to
+ * emitting a lifecycle record would append it to
  * `<worktree>/temp/run-N/lifecycle.ndjson`, while the `/deliver` host
  * (running from the main checkout) reads the main-checkout copy — so the
- * idle-watchdog never sees heartbeats and the Epic-lease guard silently
- * reclaims live foreign claims (the audit-#3513 bug class). Anchoring the
+ * host never sees the child's records (the audit-#3513 bug class; its
+ * original `story.heartbeat` instance is gone with that emitter, but the
+ * divergence applies to every ledger writer). Anchoring the
  * ledger to the git common dir makes the worktree child writer and the
  * main-checkout host reader converge on a single file regardless of cwd. An
  * absolute `tempRoot` is honoured verbatim; only relative roots are anchored.
@@ -155,11 +154,9 @@ export function tempRootFrom(config) {
     : 'temp';
 }
 
-const epicId = (id) => {
+const runId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
-    throw new Error(
-      `[temp-paths] epicId must be a positive integer; got ${id}`,
-    );
+    throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);
   }
   return id;
 };
@@ -206,19 +203,14 @@ const artifactName = (name) => {
 };
 
 /**
- * `temp/run-<eid>/` — every Epic-scoped artifact lives under here.
+ * `temp/run-<id>/` — every run-scoped artifact lives under here.
  *
- * @param {number} eid
+ * @param {number} rid
  * @param {object} [config]
  * @returns {string}
  */
 export function runTempDir(rid, config) {
-  return path.join(anchorTempRoot(tempRootFrom(config)), `run-${epicId(rid)}`);
-}
-
-/** @deprecated Use {@link runTempDir}. */
-export function epicTempDir(eid, config) {
-  return runTempDir(eid, config);
+  return path.join(anchorTempRoot(tempRootFrom(config)), `run-${runId(rid)}`);
 }
 
 /**
@@ -246,7 +238,7 @@ export function storyTempDir(eid, sid, config) {
   const parent =
     checkedEid === null
       ? path.join(anchorTempRoot(tempRootFrom(config)), 'standalone')
-      : epicTempDir(checkedEid, config);
+      : runTempDir(checkedEid, config);
   return path.join(parent, 'stories', `story-${storyId(sid)}`);
 }
 
@@ -272,7 +264,7 @@ export function signalsFile(eid, sid, config) {
  * needs an on-disk home even though there is no `run-<id>/` directory to
  * anchor the event to.
  *
- * Mirrors `epicLedgerPath` exactly, one level down: `eid === null` routes
+ * Mirrors `runLedgerPath` exactly, one level down: `eid === null` routes
  * through `storyTempDir`'s standalone branch to
  * `<tempRoot>/standalone/stories/story-<sid>/lifecycle.ndjson`; a real
  * `eid` routes to `<tempRoot>/run-<eid>/stories/story-<sid>/lifecycle.ndjson`,
@@ -298,14 +290,13 @@ export const storyLedgerPath = (eid, sid, config) =>
  * @param {object} [config]
  * @returns {string}
  */
-export function epicArtifactPath(eid, name, config) {
-  return path.join(epicTempDir(eid, config), artifactName(name));
+export function runArtifactPath(eid, name, config) {
+  return path.join(runTempDir(eid, config), artifactName(name));
 }
 
 /**
  * Escape hatch for a Story-level artifact whose name isn't part of the
- * canonical layout (signals.ndjson + perf-summary.md + manifest.md ship
- * named helpers).
+ * canonical layout (signals.ndjson + manifest.md ship named helpers).
  *
  * @param {number} eid
  * @param {number} sid
@@ -313,37 +304,10 @@ export function epicArtifactPath(eid, name, config) {
  * @param {object} [config]
  * @returns {string}
  */
-export function storyArtifactPath(eid, sid, name, config) {
+function storyArtifactPath(eid, sid, name, config) {
   return path.join(storyTempDir(eid, sid, config), artifactName(name));
 }
 
-// --- Canonical Epic-level filenames (Tech Spec #1032 §tempRoot) ---
-
-export const epicTechSpecPath = (eid, config) =>
-  epicArtifactPath(eid, 'techspec.md', config);
-export const epicManifestPath = (eid, config) =>
-  epicArtifactPath(eid, 'manifest.md', config);
-export const epicRetroMirrorPath = (eid, config) =>
-  epicArtifactPath(eid, 'retro.md', config);
-export const epicPerfReportPath = (eid, config) =>
-  epicArtifactPath(eid, 'perf-report.md', config);
-
-/**
- * `temp/run-<eid>/epic-perf-report.json` — canonical JSON snapshot of
- * the `epic-perf-report` payload persisted at /deliver close
- * (Epic #3019 / Story #3029 / Task #3040). When present alongside the
- * `epic-perf-report` structured comment, the report is discoverable
- * from the file system without round-tripping the ticketing provider,
- * and the `epic-handoff` structured close comment links it by relative
- * path.
- *
- * @param {number} eid
- * @param {object} [config]
- * @returns {string}
- */
-export const epicPerfReportJsonPath = (eid, config) =>
-  epicArtifactPath(eid, 'epic-perf-report.json', config);
-
 /**
  * `temp/run-<eid>/lifecycle.ndjson` — append-only lifecycle bus ledger
  * (Story #2510). The LedgerWriter persists every emitted/completed/failed
@@ -357,12 +321,10 @@ export const epicPerfReportJsonPath = (eid, config) =>
  * @param {object} [config]
  * @returns {string}
  */
-export const epicLedgerPath = (eid, config) =>
-  epicArtifactPath(eid, 'lifecycle.ndjson', config);
+export const runLedgerPath = (eid, config) =>
+  runArtifactPath(eid, 'lifecycle.ndjson', config);
 
 // --- Canonical Story-level filenames ---
 
 export const storyManifestPath = (eid, sid, config) =>
   storyArtifactPath(eid, sid, 'manifest.md', config);
-export const storyPerfSummaryPath = (eid, sid, config) =>
-  storyArtifactPath(eid, sid, 'perf-summary.md', config);

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,7 +66,6 @@ const DELIVER_RUNNER_SCHEMA = {
   type: 'object',
   properties: {
     concurrencyCap: { type: 'integer', minimum: 1 },
-    verifyConcurrencyCap: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };
@@ -137,19 +138,36 @@ const SIGNALS_SCHEMA = {
 };
 
 /**
- * `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,
 };
@@ -167,8 +185,8 @@ const MERGE_WATCH_SCHEMA = {
 // 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: {
@@ -231,9 +249,9 @@ const REFACTOR_STAGE_SCHEMA = {
  * `delivery.acceptanceEval` — bounded per-Story acceptance self-eval loop
  * (Story #3819). 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.
+ * (fresh-context) critic pass scores the caller-injected change set against
+ * each inline `acceptance[]` item, redrafts the unmet items, and
+ * re-evaluates — capped at `maxRounds` redraft rounds.
  *
  * `maxRounds` is the operator-tunable redraft ceiling (default 2 via
  * `lib/config/acceptance-eval.js`). It is a soft knob inside an

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'] },
   },

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
@@ -250,7 +277,6 @@ const PLANNING_SCHEMA = {
   type: 'object',
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
-    context: PLANNING_CONTEXT_SCHEMA,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
     // Cross-Story conflict-finding severity gates. Off by default so
     // existing repos keep advisory-only behaviour; flipping either to

package/.agents/scripts/lib/dead-exports-knip.js

@@ -0,0 +1,105 @@
+/**
+ * dead-exports-knip.js — the knip driver behind the dead-export ratchet.
+ *
+ * Owns everything about talking to knip and normalising what comes back:
+ * spawning it, reading a pre-captured report, and flattening its report into
+ * `{ file, symbol }` rows. `check-dead-exports.js` stays a thin CLI over this.
+ *
+ * @module lib/dead-exports-knip
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import process from 'node:process';
+
+/**
+ * Spawn `npx knip --reporter json --no-progress` and return the parsed
+ * envelope. Never throws — the caller logs the error and treats current rows as
+ * empty, which surfaces every baseline row as "removed": loud, but safe.
+ *
+ * `production` adds knip's `--production` flag, which restricts analysis to
+ * entry/project patterns carrying the `!` suffix in `knip.json`. The test globs
+ * deliberately lack that suffix, so production mode drops them as entry points
+ * and an export reachable only from a test reads as dead. Without those
+ * suffixes production mode has no entry patterns at all and reports nothing —
+ * `knip.json` and this flag are a matched pair.
+ *
+ * Exported as a hook so tests can stub the spawn without a working knip
+ * workspace.
+ *
+ * @param {{ cwd?: string, spawn?: typeof spawnSync, production?: boolean }} [opts]
+ * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
+ */
+export function runKnip({
+  cwd = process.cwd(),
+  spawn = spawnSync,
+  production = false,
+} = {}) {
+  const args = ['knip', '--reporter', 'json', '--no-progress'];
+  if (production) args.push('--production');
+  const result = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx', args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+  });
+  if (result.error) {
+    return { ok: false, error: `spawn failed: ${result.error.message}` };
+  }
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  if (stdout.trim().length === 0) {
+    return { ok: false, error: 'knip produced empty stdout' };
+  }
+  try {
+    return { ok: true, envelope: JSON.parse(stdout) };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `knip JSON parse failed: ${err?.message ?? err}`,
+    };
+  }
+}
+
+/**
+ * Read a pre-captured knip JSON envelope from disk (the `--knip-output` test
+ * seam). Returns the parsed envelope or `null` on failure.
+ *
+ * @param {string} filePath
+ * @returns {unknown}
+ */
+export function readKnipOutput(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Flatten knip's `--reporter json` output into `{ file, symbol }` rows. Knip
+ * emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`. Only
+ * `exports` rows are mapped — the ratchet ignores file-, dependency- and
+ * duplicate-level issues, which knip surfaces under separate `rules` keys.
+ *
+ * @param {unknown} knipEnvelope The parsed knip JSON report.
+ * @returns {Array<{ file: string, symbol: string }>}
+ */
+export function extractRowsFromKnip(knipEnvelope) {
+  const rows = [];
+  if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
+  const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
+  for (const issue of issues) {
+    const file = issue?.file;
+    if (typeof file !== 'string' || file.length === 0) continue;
+    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
+    for (const e of exports_) {
+      const symbol =
+        (e && typeof e.name === 'string' && e.name) ||
+        (e && typeof e.symbol === 'string' && e.symbol) ||
+        null;
+      if (!symbol) continue;
+      rows.push({ file, symbol });
+    }
+  }
+  return rows;
+}