mandrel 1.91.0 → 1.92.0

package/.agents/scripts/epic-plan-spec.js

@@ -1,191 +1,64 @@
 #!/usr/bin/env node
 
+/* node:coverage ignore file */
+
 /**
- * epic-plan-spec.js — Phase 7 (spec) entry point for the split planning flow.
- *
- * Two idempotent modes and a single-purpose label lifecycle:
+ * epic-plan-spec.js — RETIRED delegate CLI (Epic #4474, PR7).
  *
- *   1. --emit-context   Prints the planner authoring context (Epic body,
- *                       scraped project docs, recommended system prompts) as
- *                       JSON. The authoring middle is the
- *                       `epic-plan-spec-author` Skill (see
- *                       `.agents/skills/core/epic-plan-spec-author/SKILL.md`),
- *                       which consumes this envelope and writes the Tech Spec
- *                       markdown file.
+ * The 12-phase plan pipeline collapsed to context → author → persist:
  *
- *   2. (default)        Given author-provided Tech Spec and risk-verdict
- *                       files, validates the risk verdict against
- *                       `risk-verdict.schema.json`, derives the planningRisk
- *                       envelope, folds the authored content into managed
- *                       sections of the Epic body (Story #4324 — no separate
- *                       context tickets), records the verdict as a
- *                       `risk-verdict` structured comment, flips the Epic to
- *                       `agent::review-spec`, and upserts the
- *                       `epic-plan-state` structured comment.
+ *   - `--emit-context` moved to `plan-context.js` (single authoring
+ *     envelope: Epic body + docs digest + codebase snapshot + duplicate
+ *     search + clarity + system prompts).
+ *   - The persist half (section gate, risk verdict, managed sections,
+ *     checkpoint) moved to `plan-persist.js` (single GitHub-write surface).
  *
- * --force regenerates the existing Tech Spec.
- * --steal forcibly transfers a foreign Epic-lease claim (the plan-lease guard
- *   fails closed, so any foreign assignee blocks the run unless stolen).
+ * This file is a **re-export shim only** — it carries external importers of
+ * the historic named-export surface one more release (#4474 design §6 PR7
+ * risk note) and is deleted in the next release. Internal consumers import
+ * the phase modules directly; do not add new imports of this file.
  *
- * Exit codes:
- *   0 — phase complete, Epic is now `agent::review-spec`.
- *   1 — fatal error (see stderr).
- *
- * The phase implementations live under
- * `lib/orchestration/epic-plan-spec/phases/`. This file is now a thin CLI
- * entry that wires argv → phases.
+ * Invoking it as a CLI is refused with a pointer to the successor CLIs.
  */
 
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
-import './lib/runtime-deps/ensure-installed.js';
-import { readFile } from 'node:fs/promises';
-import {
+// cli-opt-out: retired delegate shim (Epic #4474 PR7) — deliberately
+// refuses CLI execution with a pointer to plan-context.js/plan-persist.js
+// instead of wiring runAsCli around a dead main().
+import { pathToFileURL } from 'node:url';
+
+export {
   forkAndCommitEpicSnapshot,
   forkMainToEpic,
 } from './lib/baseline-snapshot.js';
-
-// Re-exported so the historic import path
-// (`epic-plan-spec.js#forkAndCommitEpicSnapshot`) and existing tests keep
-// working after Story #1585 relocated the wrapper into the lower-level
-// `lib/baseline-snapshot.js` module. `forkMainToEpic` is also re-exported
-// for the same reason.
-export { forkAndCommitEpicSnapshot, forkMainToEpic };
-
-import { runAsCli } from './lib/cli-utils.js';
-import {
-  PROJECT_ROOT,
-  resolveConfig,
-  validateOrchestrationConfig,
-} from './lib/config-resolver.js';
-import { Logger, routeAllOutputToStderr, STDERR_LOGGER } from './lib/Logger.js';
-import {
+export {
   buildAuthoringContext,
   resolveMemoryDir,
 } from './lib/orchestration/epic-plan-spec/phases/authoring-context.js';
-import { parseEpicPlanSpecArgs } from './lib/orchestration/epic-plan-spec/phases/cli-args.js';
-import { drainPendingCleanupAtBoot } from './lib/orchestration/epic-plan-spec/phases/drain.js';
-import {
+export { drainPendingCleanupAtBoot } from './lib/orchestration/epic-plan-spec/phases/drain.js';
+export {
   planEpic,
   resolveAcceptancePersistence,
 } from './lib/orchestration/epic-plan-spec/phases/plan-epic.js';
-import {
-  loadRiskVerdict,
-  validateRiskVerdict,
-} from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-import { runSpecPhase } from './lib/orchestration/epic-plan-spec/phases/run-spec-phase.js';
-import { runSpecFreshnessCheck } from './lib/orchestration/epic-plan-spec/phases/spec-freshness.js';
-import { resolveReviewRouting } from './lib/orchestration/plan-review-routing.js';
-import { createProvider } from './lib/provider-factory.js';
-
-// Re-exports for stable public API: tests and external callers import these
-// from `epic-plan-spec.js`. The implementations live in `phases/`.
 export {
-  buildAuthoringContext,
-  drainPendingCleanupAtBoot,
   loadRiskVerdict,
-  planEpic,
-  resolveAcceptancePersistence,
-  resolveMemoryDir,
-  resolveReviewRouting,
-  runSpecFreshnessCheck,
-  runSpecPhase,
   validateRiskVerdict,
-};
-
-async function main() {
-  const { values, epicId } = parseEpicPlanSpecArgs();
-
-  let config;
-  let settings;
-  try {
-    config = resolveConfig();
-    // `settings` retains the legacy bag shape used by buildAuthoringContext
-    // and friends: `{ baseBranch, paths, planning, ... }`. Build it from the
-    // canonical blocks rather than the legacy shim.
-    settings = {
-      baseBranch: config.project?.baseBranch,
-      paths: config.project?.paths,
-      planning: config.planning,
-      docsContextFiles: config.project?.docsContextFiles,
-    };
-    validateOrchestrationConfig(config);
-  } catch (err) {
-    throw new Error(`Config schema validation failed:\n${err.message}`);
-  }
-  const provider = createProvider(config);
-
-  const emitContext = values['emit-context'];
-  // Story #2278 — in --emit-context mode stdout is reserved for the JSON
-  // envelope. Flip every Logger sink that could land on stdout to stderr
-  // *before* any pipeline code runs (drainPendingCleanupAtBoot,
-  // buildAuthoringContext → ensureDocsDigest — Story #4433 cut the digest
-  // build over from the old buildDocsContext/scrapeProjectDocs full-content
-  // read path), so a captured file is unconditionally parseable by
-  // `JSON.parse`.
-  if (emitContext) routeAllOutputToStderr();
-
-  try {
-    await drainPendingCleanupAtBoot({
-      repoRoot: PROJECT_ROOT,
-      config,
-      provider,
-      // In --emit-context mode stdout is reserved for the JSON envelope;
-      // route every drain/sweep log line through stderr so the captured
-      // file is unconditionally parseable.
-      logger: emitContext ? STDERR_LOGGER : undefined,
-    });
-  } catch (err) {
-    Logger.warn(
-      `[epic-plan-spec] pending-cleanup drain skipped: ${err.message}`,
-    );
-  }
-
-  if (emitContext) {
-    const ctx = await buildAuthoringContext(epicId, provider, settings, {
-      fullContext: values['full-context'],
-      github: config.github ?? null,
-    });
-    const json = values.pretty
-      ? JSON.stringify(ctx, null, 2)
-      : JSON.stringify(ctx);
-    process.stdout.write(`${json}\n`);
-    return;
-  }
-
-  if (!values['tech-spec'] || !values['risk-verdict']) {
-    throw new Error(
-      'Missing --tech-spec and/or --risk-verdict file paths. (Use --emit-context first to gather authoring context; the epic-plan-spec-author Skill writes all artifacts including risk-verdict.json.)',
-    );
-  }
-
-  // Read + schema-validate the planner-authored risk verdict before any
-  // GitHub mutation: a malformed verdict fails closed here (Epic #3865).
-  const riskVerdict = loadRiskVerdict(values['risk-verdict']);
-
-  const readPromises = [readFile(values['tech-spec'], 'utf8')];
-  if (values['acceptance-table']) {
-    readPromises.push(readFile(values['acceptance-table'], 'utf8'));
-  }
-  const [techSpecContent, acceptanceSpecContent = null] =
-    await Promise.all(readPromises);
-
-  const result = await runSpecPhase(
-    epicId,
-    provider,
-    { techSpecContent, acceptanceSpecContent },
-    settings,
-    {
-      force: values.force,
-      forceReview: values['force-review'],
-      steal: values.steal === true,
-      config,
-      riskVerdict,
-    },
+} from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
+export { runSpecPhase } from './lib/orchestration/epic-plan-spec/phases/run-spec-phase.js';
+export { runSpecFreshnessCheck } from './lib/orchestration/epic-plan-spec/phases/spec-freshness.js';
+export { resolveReviewRouting } from './lib/orchestration/plan-review-routing.js';
+
+// CLI execution is retired — fail loudly with the successor surface instead
+// of silently doing nothing (a stale automation script should break visibly).
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  process.stderr.write(
+    '[epic-plan-spec] retired (Epic #4474): the plan pipeline is ' +
+      'context → author → persist.\n' +
+      '  - authoring envelope:  node .agents/scripts/plan-context.js --epic <id>\n' +
+      '  - persist (all gates): node .agents/scripts/plan-persist.js --epic <id> ...\n' +
+      'This file survives one release as an import shim only.\n',
   );
-
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(1);
 }
-
-runAsCli(import.meta.url, main, { source: 'epic-plan-spec' });

package/.agents/scripts/epic-reconcile.js

@@ -291,7 +291,13 @@ export function reseedMappingFromGh(state, spec, ghState) {
   }
 
   for (const entity of flattenSpecForReseed(spec)) {
-    if (mapping[entity.slug]) continue; // already mapped
+    // Epic #4474 (PR3) — a mapping entry WITHOUT an issue number is a
+    // partial-failure tombstone (the apply's state writer persists every
+    // spec slug; only completed creations carry `issueNumber`). Treat it
+    // as unmapped here so a title-matched live issue reseeds it instead
+    // of leaving a numberless entry the diff engine can neither update
+    // nor (post-fix) skip-create.
+    if (Number.isInteger(mapping[entity.slug]?.issueNumber)) continue; // already mapped
     const candidates = openByTitle.get(entity.title) ?? [];
     // Pick the lowest unclaimed candidate for determinism.
     const match = candidates

package/.agents/scripts/lib/Logger.js

@@ -106,8 +106,8 @@ let progressStdoutSink = (msg) => console.log(msg);
  * Flip every Logger output that can land on stdout (`info`, `warn`, and the
  * stdout branch of `createProgress`) to stderr for the lifetime of the
  * process. Idempotent. Use when stdout is reserved for a structured payload
- * — for example the `--emit-context` JSON envelopes emitted by
- * `epic-plan-spec.js` and `epic-plan-decompose.js`, where any interleaved
+ * — for example the JSON envelope emitted by
+ * `plan-context.js`, where any interleaved
  * `[Orchestrator] ℹ️ …` log line corrupts the captured file
  * (Story #2278).
  */
@@ -180,8 +180,8 @@ export const NOOP_LOGGER = Object.freeze({
 
 /**
  * Frozen logger that routes every level to **stderr**. Use this when a
- * caller's stdout is a structured payload (e.g. `--emit-context` JSON
- * envelopes from `epic-plan-spec.js` / `epic-plan-decompose.js`) and any
+ * caller's stdout is a structured payload (e.g. the authoring-context JSON
+ * envelope from `plan-context.js`) and any
  * progress/telemetry log must not interleave with the payload. Mirrors the
  * `{ info, warn, error, debug }` shape that the orchestration helpers
  * accept via optional `logger` arguments.

package/.agents/scripts/lib/audit-suite/index.js

@@ -3,12 +3,11 @@
  *
  * Single library entry point for the audit-suite. Exports the two public
  * functions (`runAuditSuite`, `selectAudits`) plus the pure rule-matching
- * helpers (`matchesFilePattern`, `matchesAnyFilePattern`) used by the
- * top-level CLIs (`run-audit-suite.js`, `select-audits.js`).
+ * helpers (`matchesFilePattern`, `matchesAnyFilePattern`).
  *
- * Consumers import from this file rather than reaching upward into the
- * CLI scripts (`../../run-audit-suite.js`, `../../select-audits.js`) —
- * that direction inversion is the goal of Story #1083 / Epic #1072.
+ * Consumers import from this file — the former top-level CLI wrappers
+ * (`run-audit-suite.js`, `select-audits.js`) were retired in #4482; this
+ * barrel is the only supported entry point (Story #1083 / Epic #1072).
  *
  * @example
  *   import { runAuditSuite, selectAudits } from './lib/audit-suite/index.js';

package/.agents/scripts/lib/audit-suite/runner.js

@@ -1,7 +1,9 @@
 /**
  * lib/audit-suite/runner.js — `runAuditSuite` aggregation core.
  *
- * Extracted from `.agents/scripts/run-audit-suite.js` (Story #963, Epic #946).
+ * Extracted from the former `run-audit-suite.js` CLI (Story #963, Epic #946;
+ * the CLI wrapper itself was retired in #4482 — `runAuditSuite` via the
+ * barrel is the only supported entry point).
  *
  * The runner composes the focused helpers from this directory:
  *   - frontmatter.js     → `summarizeWorkflow`
@@ -10,9 +12,9 @@
  *   - workflow-loader.js → `loadWorkflow`, `defaultWriteArtifact`
  *
  * It owns the audit envelope shape (`metadata`, `findings`, `workflows`) and
- * the per-audit fan-out + result reduction. The CLI entry-point in
- * `.agents/scripts/run-audit-suite.js` reduces to argument parsing and
- * stdout/stderr glue around this function.
+ * the per-audit fan-out + result reduction. The former CLI entry-point
+ * (`run-audit-suite.js`) was retired in #4482; callers invoke
+ * `runAuditSuite` via the `lib/audit-suite/index.js` barrel.
  */
 
 import fs from 'node:fs/promises';

package/.agents/scripts/lib/audit-suite/selector.js

@@ -11,9 +11,8 @@
  *   - selectAudits          — main entry; reads audit-rules.json, runs `git
  *                             diff --name-only`, applies keyword + glob rules.
  *
- * The CLI wrapper at `.agents/scripts/select-audits.js` reduces to argv
- * parsing, provider construction, JSON stdout, and degraded-mode exit-code
- * mapping. All rule-matching lives here.
+ * All rule-matching lives here; the former `select-audits.js` CLI wrapper
+ * was retired in #4482 (consumers call `selectAudits` via the barrel).
  */
 
 import { readFileSync } from 'node:fs';

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -2,7 +2,7 @@
  * BDD runner detection + pending-tag verification (Epic #2001 Story #2094
  * Task #2103; workspace-aware extension from Story #2956).
  *
- * Used by `epic-plan-spec.js#buildAuthoringContext` to decide whether the
+ * Used by `buildAuthoringContext` (the `plan-context.js` envelope) to decide whether the
  * acceptance-table section should plan **features-first** Story ordering (a real
  * pending-tag is available, so the features-first Story can ship `.feature`
  * files marked `@pending` / `@skip` ahead of the implementation Stories) or

package/.agents/scripts/lib/command-header.js

@@ -31,3 +31,23 @@ export function applyHeader(content, header) {
   const body = content.slice(block.length).replace(/^\r?\n/, '');
   return `${block}\n${header}${body}`;
 }
+
+/**
+ * True when a workflow opts out of slash-command projection via a
+ * `command: false` key in its YAML frontmatter (#4482). Used for dual-use
+ * lens files (e.g. `audit-security.md`, `audit-lighthouse.md`) that stay in
+ * the payload as `/deliver` audit-suite prompts but must NOT surface as
+ * standalone slash commands because the host ships a native equivalent.
+ *
+ * Both `sync-claude-commands.js` (projection + orphan-reap) and the
+ * `commands-in-sync` doctor check (parity expectation) consult this flag so
+ * an excluded workflow never reads as "not synced".
+ *
+ * @param {string} content - Raw workflow `.md` content.
+ * @returns {boolean}
+ */
+export function isCommandExcluded(content) {
+  const frontmatter = String(content).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!frontmatter) return false;
+  return /^command:\s*false\s*$/m.test(frontmatter[1]);
+}

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

@@ -8,15 +8,13 @@
  * drives both:
  *
  *   - `/agents-bootstrap-github` — registers GitHub required-status checks.
- *   - `/git-merge-pr` → `git-pr-quality-gate.js` — runs each check locally
- *     before merge.
  */
 
 /**
  * Default required-check suite. Mirrors the live CI required-check set
  * (`lint` + `test` + `baselines`); consumers override via
  * `github.branchProtection.requiredChecks` in `.agentrc.json`. Kept in sync
- * with `DEFAULT_CHECKS` in `git-pr-quality-gate.js` and the CI job names in
+ * with the CI job names in
  * `.github/workflows/ci.yml` — the retired `format:check` folded into `lint`
  * (Story #1829) and `lifecycle-doc-drift` collapsed into `lint`/`docs:check`
  * (Epic #1943), so neither belongs in the default set.

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

@@ -297,9 +297,10 @@ const PLANNING_SCHEMA = {
     failOnRegistryConflicts: { type: 'boolean' },
     failOnLargeFanOut: { type: 'boolean' },
     largeFanOutThreshold: { type: 'integer', minimum: 0 },
-    // Navigability-reachability config consumed by the epic-plan-healthcheck
-    // --paranoid reachability check (Epic #4131, F7). Opt-in: absent or empty
-    // routeGlobs degrades to a silent no-op.
+    // 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).
+    // Opt-in: absent or empty routeGlobs degrades to a silent no-op.
     navigation: {
       type: 'object',
       properties: {

package/.agents/scripts/lib/degraded-mode.js

@@ -2,7 +2,7 @@
  * Shared helper for the explicit-degraded contract used by soft-failing gates.
  *
  * Tech Spec #819 §"Degraded-mode contract (Story 3)" — three soft-fail sites
- * (select-audits diff-timeout, lint-baseline JSON-parse, baseline-refresh
+ * (audit-suite selector diff-timeout, lint-baseline JSON-parse, baseline-refresh
  * guardrail git-diff) historically returned a silent zero/empty result. The
  * new contract is:
  *

package/.agents/scripts/lib/label-constants.js

@@ -123,9 +123,9 @@ export const META_LABELS = {
 /**
  * Planning-axis labels (Epic #2880 F7). Currently scoped to the
  * `planning::healthcheck-waived` operator-applied waiver, which is the
- * documented escape hatch for the `/plan` Phase 10 readiness
- * healthcheck (`epic-plan-healthcheck.js`). The persist half of
- * `epic-plan-decompose.js` refuses to flip an Epic to `agent::ready`
+ * documented escape hatch for the inline post-plan readiness
+ * healthcheck (`runPlanHealthcheck`). The persist surface
+ * (`plan-persist.js`) refuses to flip an Epic to `agent::ready`
  * when the healthcheck returned `ok: false` unless this label is
  * present — see `.agents/docs/SDLC.md` § "`agent::ready` exit conditions"
  * for the full handoff contract.
@@ -147,6 +147,20 @@ export const PLANNING_LABELS = {
  */
 export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
 
+/**
+ * Delivery-routing labels (Epic #4474 PR4 — design §2 mode matrix).
+ * `delivery::single` marks an Epic whose plan was persisted in the
+ * spec-only single-delivery mode: no Story tree exists and the Delivery
+ * Slicing table of the Epic body's Tech Spec is the audit trail.
+ * `plan-persist.js` applies it when the risk verdict declares
+ * `deliveryShape: "single"`; a fan-out re-persist over the same Epic
+ * removes it. The marker is **inert until #4475** lands the deliver-side
+ * reader — nothing in the deliver path consumes it yet.
+ */
+export const DELIVERY_LABELS = {
+  SINGLE: 'delivery::single',
+};
+
 /** Palette for the taxonomy; consumed by label-taxonomy.js. */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',
@@ -155,4 +169,5 @@ export const LABEL_COLORS = {
   PERSONA: '#C5DEF5',
   ACCEPTANCE: '#FBCA04',
   PLANNING: '#FEF2C0',
+  DELIVERY: '#BFD4F2',
 };

package/.agents/scripts/lib/label-taxonomy.js

@@ -12,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import {
   ACCEPTANCE_LABELS,
   AGENT_LABELS,
+  DELIVERY_LABELS,
   LABEL_COLORS,
   PERSONA_LABEL_PREFIX,
   PLANNING_LABELS,
@@ -108,15 +109,25 @@ export const LABEL_TAXONOMY = [
 
   // Planning axis — operator-applied waivers for the planning → delivery
   // handoff gates. Currently the sole entry is the `healthcheck-waived`
-  // override consumed by the persist half of `epic-plan-decompose.js`
-  // when `epic-plan-healthcheck.js` returned `ok: false` for a reason
-  // the operator has triaged and accepted.
+  // override consumed by `plan-persist.js` when the inline healthcheck
+  // (`runPlanHealthcheck`) returned `ok: false` for a reason the
+  // operator has triaged and accepted.
   {
     name: PLANNING_LABELS.HEALTHCHECK_WAIVED,
     color: LABEL_COLORS.PLANNING,
     description:
       'Operator override — allows agent::ready handoff despite a failing post-plan healthcheck',
   },
+
+  // Delivery routing — applied by `plan-persist.js` when the risk verdict
+  // declares `deliveryShape: "single"` (Epic #4474 PR4). Inert until #4475
+  // lands the deliver-side reader.
+  {
+    name: DELIVERY_LABELS.SINGLE,
+    color: LABEL_COLORS.DELIVERY,
+    description:
+      'Single-delivery plan — no Story tree; the Delivery Slicing table is the audit trail (#4474/#4475)',
+  },
 ];
 
 /** @type {Array<{ name: string, type: 'single_select', options?: string[] }>} */

package/.agents/scripts/lib/mutation/baseline-snapshot.js

@@ -28,9 +28,10 @@
  * `lib/baseline-snapshot.js`: the fs surface and the clock are injected so
  * unit tests never touch real files. The two writer paths
  * (`readBaseline`, `writeBaseline`) are split because the typical caller
- * sequence is read-then-merge-then-write — for instance,
- * `update-mutation-baseline.js` reads the prior baseline to preserve the
- * configured `tolerancePct` if the Stryker run does not override it.
+ * sequence is read-then-merge-then-write — a refresh CLI reads the prior
+ * baseline to preserve the configured `tolerancePct` if the Stryker run
+ * does not override it (the former `update-mutation-baseline.js` wrapper
+ * was retired in #4482; the gate ships dormant).
  */
 
 import fs from 'node:fs';
@@ -89,9 +90,9 @@ export function readBaseline(baselinePath, opts = {}) {
  * The on-disk shape is canonicalised: `workspaces` keys are sorted
  * alphabetically (with `"*"` always first) and the file ends with a
  * trailing newline. This produces a byte-stable serialisation, which
- * the `update-mutation-baseline.js` entry-point relies on to detect
- * "no change" runs (skip the baseline-refresh commit when re-running
- * Stryker produces an identical baseline).
+ * lets a refresh caller detect "no change" runs (skip the
+ * baseline-refresh commit when re-running Stryker produces an identical
+ * baseline).
  *
  * @param {string} baselinePath
  * @param {{ generatedAt?: string, tolerancePct?: number, workspaces: Record<string, number> }} payload

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -19,9 +19,12 @@
  * Delivery Slicing section, an unparseable "Independent?" cell — resolves to
  * `dispatch: true`. This gate can only ever *save* a dispatch when it is
  * confident the critic has nothing to do; it never disables the critic's
- * ability to catch a real divergence. Phase 8.4 (reachability critic), 8.5
- * (pre-mortem critic), and the deterministic ticket validator are
- * unconditional — this precondition governs only the 8.3 dispatch.
+ * ability to catch a real divergence. Since Epic #4474 PR6 this precondition
+ * is one input to the risk/size-conditional dispatch layer
+ * (`plan-critic-conditions.js`): reachability (8.4) is a deterministic
+ * persist-side check (`plan-reachability.js`) and the pre-mortem critic
+ * (8.5) is risk/size-gated; the deterministic ticket validator remains
+ * unconditional.
  *
  * Pure, synchronous, no I/O — callers own reading `tickets.json` and the
  * Epic body off disk / the GitHub API.
@@ -146,10 +149,14 @@ function isBddScaffoldStory(story) {
  *   top-level `slug` / `depends_on` / `body` (serialized string).
  * @param {string} input.epicBody - The Epic body carrying the folded Tech
  *   Spec sections (`## Delivery Slicing` onward).
- * @returns {{ dispatch: boolean, reasons: string[] }} `dispatch: false` only
- *   when the draft matches the Delivery Slicing table 1:1 in count and
- *   dependency shape; `dispatch: true` (with `reasons`) otherwise, including
- *   every fail-open case.
+ * @returns {{ dispatch: boolean, cause: 'match'|'divergence'|'fail-open', reasons: string[] }}
+ *   `dispatch: false` only when the draft matches the Delivery Slicing table
+ *   1:1 in count and dependency shape; `dispatch: true` (with `reasons`)
+ *   otherwise, including every fail-open case. `cause` distinguishes a
+ *   **confirmed** divergence (count or dependency-shape mismatch) from the
+ *   fail-open ambiguity (missing/unparseable table) — the #4474 PR6
+ *   conditional-dispatch layer treats only the former as a firing condition
+ *   on small drafts.
  */
 export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (!Array.isArray(draftStories)) {
@@ -162,6 +169,7 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (!slicing) {
     return {
       dispatch: true,
+      cause: 'fail-open',
       reasons: [
         'Delivery Slicing section is missing or unparseable — fail-open to the critic.',
       ],
@@ -175,6 +183,7 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (slicedStories.length !== slicing.length) {
     return {
       dispatch: true,
+      cause: 'divergence',
       reasons: [
         `Story count diverges from Delivery Slicing: ${slicing.length} proposed slice(s) vs ${slicedStories.length} non-scaffold draft Story(ies).`,
       ],
@@ -201,11 +210,12 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   }
 
   if (reasons.length > 0) {
-    return { dispatch: true, reasons };
+    return { dispatch: true, cause: 'divergence', reasons };
   }
 
   return {
     dispatch: false,
+    cause: 'match',
     reasons: [
       `Draft matches Delivery Slicing 1:1 in count and dependency shape (${slicing.length} slice(s)) — skipping the 8.3 consolidation dispatch.`,
     ],

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -9,9 +9,8 @@
  * file I/O decisions, or process.exit(). All I/O choices are delegated
  * to the caller.
  *
- * Consumers:
- *   - `.agents/scripts/hydrate-context.js`   — the only supported CLI wrapper
- *     (imports hydrateContext; `--emit prompt` writes the raw hydrated prompt)
+ * Consumers import `hydrateContext` from this module directly — the former
+ * `hydrate-context.js` CLI wrapper was retired (#4482) with no live consumer.
  *
  * @see .agents/scripts/lib/ITicketingProvider.js
  */
@@ -153,7 +152,7 @@ function getVersion() {
  * @param {string} body
  * @returns {Record<string, number>}
  */
-export function parseHierarchy(body) {
+function parseHierarchy(body) {
   const result = {};
   if (!body) return result;
 

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -15,7 +15,7 @@
  *
  * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
  * generate-and-write export so the planner-context surface
- * (`epic-plan-spec.js` / `authoring-context.js`) can produce a session docs
+ * (`plan-context.js` / `authoring-context.js`) can produce a session docs
  * digest without duplicating the mkdir+writeFile plumbing
  * `epic-deliver-prepare.js` already owns for the delivery-children digest.
  */
@@ -146,7 +146,7 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
  * write) when there is nothing to digest. This is the single shared
  * generate-and-persist export both digest producers call: the per-Epic
  * delivery-children digest (`epic-deliver-prepare.js`) and the planner-
- * context digest (`epic-plan-spec.js` → `authoring-context.js`, Story
+ * context digest (`plan-context.js` → `authoring-context.js`, Story
  * #4433). Callers own path construction (temp-root layout, epic id, etc.)
  * so both surfaces can keep — or deliberately share — their own convention;
  * this function only owns "build digest, ensure parent dir, write file".

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/persist-helpers.js

@@ -104,6 +104,10 @@ export function validateTickets(tickets, config, opts = {}) {
   const validated = validateAndNormalizeTickets(tickets, {
     baseBranchRef,
     conflictPolicy,
+    // Thread the repo cwd into the AC-freshness / file-assumption git
+    // probes (#4474 PR7) — without it they silently ran against
+    // process.cwd(), which is only the repo root by coincidence.
+    cwd: opts.cwd,
   });
   validateTaskBodies(validated);
   return validated;