mandrel 2.0.0 → 2.1.0

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

@@ -5,7 +5,6 @@
  * Post-reshape, the surviving operator-configurable keys are split across
  * `planning.*` and `delivery.*`:
  *
- *   - `planning.context.{maxBytes, summaryMode}` (planning-context budget)
  *   - `delivery.execution.timeoutMs` (per-process execution timeout)
  *   - `delivery.lease.ttlMs` (assignee-as-lease staleness window — Story #3480)
  *   - `delivery.signals.{rework, retry}` (performance-signal detector
@@ -17,7 +16,12 @@
  * Dropped entirely: `maxInstructionSteps`, `friction.*`, `executionMaxBuffer`,
  * `signals.{churn, idle}`, `delivery.preflight`, `delivery.maxTokenBudget`
  * (planning no longer sizes against a token-budget envelope; session-mass
- * ceilings are absolute in `DEFAULT_MODEL_CAPACITY`).
+ * ceilings are absolute in `DEFAULT_MODEL_CAPACITY`), and
+ * `planning.context.{maxBytes, summaryMode}` (Story #4541 — the `applyBudget`
+ * pass they fed lost its last caller in the v2 cutover, and it bounded a field
+ * the envelope builders discarded; the live bound on planner-context size is
+ * the fixed `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` in
+ * `lib/orchestration/plan-context.js`).
  *
  * The historic combined accessor `getLimits(config)` is preserved as a
  * compatibility surface: it returns a wrapper carrying the surviving
@@ -37,10 +41,14 @@ export const SIGNALS_DEFAULTS = Object.freeze({
 
 /**
  * Default TTL for the assignee-as-lease primitive (Story #3480). A claim
- * whose owner has not emitted a `story.heartbeat` within this window is
- * considered stale and may be reclaimed by another operator. 15 minutes
- * gives a healthy run comfortable headroom over the §2e idle watchdog's
- * 10-minute re-tick while still releasing a genuinely dead claim promptly.
+ * whose owner's last heartbeat is older than this window is considered stale
+ * and may be reclaimed by another operator.
+ *
+ * Note: no shipped caller supplies a real heartbeat — the emitter was inert
+ * and was deleted (A22), so the guards anchor liveness to `now` and every
+ * foreign claim reads live (fail-closed; clear a stranded claim with
+ * `--steal`). This value is therefore only consulted by a caller that threads
+ * its own `heartbeatAt`, and is kept as the documented default for that seam.
  */
 export const LEASE_TTL_MS_DEFAULT = 900000;
 
@@ -51,10 +59,6 @@ export const LIMITS_DEFAULTS = Object.freeze({
   maxTickets: 80,
   executionTimeoutMs: 600000,
   leaseTtlMs: LEASE_TTL_MS_DEFAULT,
-  planningContext: Object.freeze({
-    maxBytes: 50000,
-    summaryMode: 'auto',
-  }),
   signals: SIGNALS_DEFAULTS,
 });
 
@@ -83,8 +87,7 @@ function mergeSignals(userSignals) {
 /**
  * Resolve the surviving limits surface against a `.agentrc.json` shape
  * (post-reshape). `maxTickets` is a framework constant (never read from
- * config); pulls `planningContext` from `planning.*`, pulls
- * `executionTimeoutMs` from `delivery.*`, pulls signals from
+ * config); pulls `executionTimeoutMs` from `delivery.*`, pulls signals from
  * `delivery.signals.*`.
  *
  * @param {object|undefined} config
@@ -92,23 +95,14 @@ function mergeSignals(userSignals) {
  *   maxTickets: number,
  *   executionTimeoutMs: number,
  *   leaseTtlMs: number,
- *   planningContext: { maxBytes: number, summaryMode: string },
  *   signals: ReturnType<typeof mergeSignals>,
  * }}
  */
 export function resolveLimits(config) {
-  const planning =
-    config?.planning && typeof config.planning === 'object'
-      ? config.planning
-      : {};
   const delivery =
     config?.delivery && typeof config.delivery === 'object'
       ? config.delivery
       : {};
-  const planningContextUser =
-    planning.context && typeof planning.context === 'object'
-      ? planning.context
-      : {};
   const execution =
     delivery.execution && typeof delivery.execution === 'object'
       ? delivery.execution
@@ -120,10 +114,6 @@ export function resolveLimits(config) {
     executionTimeoutMs:
       execution.timeoutMs ?? LIMITS_DEFAULTS.executionTimeoutMs,
     leaseTtlMs: lease.ttlMs ?? LIMITS_DEFAULTS.leaseTtlMs,
-    planningContext: {
-      ...LIMITS_DEFAULTS.planningContext,
-      ...planningContextUser,
-    },
     signals: mergeSignals(delivery.signals),
   };
 }

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: {

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