mandrel 1.63.0 → 1.65.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -277,7 +277,7 @@ export function ensureDependenciesInstalled(ctx) {
   });
   if (result.status !== 0) {
     throw new Error(
-      `[bootstrap] ${manager} install failed (exit ${result.status}). Resolve the install error and re-run.`,
+      `[Bootstrap] ${manager} install failed (exit ${result.status}). Resolve the install error and re-run.`,
     );
   }
   return { ran: true, manager, skipped: false };
@@ -462,7 +462,7 @@ export function runSyncCommands(ctx) {
   });
   if (result.status !== 0) {
     throw new Error(
-      `[bootstrap] sync-claude-commands.js failed (exit ${result.status}): ${(
+      `[Bootstrap] sync-claude-commands.js failed (exit ${result.status}): ${(
         result.stderr ?? ''
       )
         .trim()
@@ -615,12 +615,12 @@ export function checkWindowsGitPerf(ctx) {
 const fatalNodeCheck = (result) =>
   result.ok
     ? null
-    : `[bootstrap] Node ${result.version} is below required ${result.required}. Upgrade Node and re-run.`;
+    : `[Bootstrap] Node ${result.version} is below required ${result.required}. Upgrade Node and re-run.`;
 
 const fatalValidation = (result) =>
   result.ok
     ? null
-    : `[bootstrap] .agentrc.json failed schema validation: ${JSON.stringify(
+    : `[Bootstrap] .agentrc.json failed schema validation: ${JSON.stringify(
         result.errors,
         null,
         2,
@@ -629,7 +629,7 @@ const fatalValidation = (result) =>
 const fatalParity = (result) =>
   result.ok
     ? null
-    : `[bootstrap] Parity check failed — workflows missing commands: ${
+    : `[Bootstrap] Parity check failed — workflows missing commands: ${
         result.missingCommand.join(', ') || '(none)'
       }; orphan commands: ${result.orphanCommand.join(', ') || '(none)'}`;
 

package/.agents/scripts/lib/bootstrap/prompt.js

@@ -286,7 +286,11 @@ export async function resolveFromPicker(ctx) {
 
   const normalized = choices.map(normalizePickerChoice);
   const rl = await ctx.getRl();
-  ctx.output.write(`${ctx.q.message}:\n`);
+  // The picker header uses `pickerMessage` when set, so a question can show
+  // list-oriented guidance here (e.g. "Select existing or press ENTER to create
+  // new one") while the manual-entry fall-through prompt (`askOnce`) uses the
+  // shorter `message` (e.g. "New GitHub repo name"). Falls back to `message`.
+  ctx.output.write(`${ctx.q.pickerMessage ?? ctx.q.message}:\n`);
   normalized.forEach((choice, index) => {
     ctx.output.write(`  ${index + 1}) ${choice.label}\n`);
   });

package/.agents/scripts/lib/detect-package-manager.js

@@ -1,11 +1,11 @@
 /**
  * detect-package-manager — shared lockfile-probe helper (Story #4048 B3).
  *
- * Five independent copies of this lockfile probe existed across the codebase:
+ * Several independent copies of this lockfile probe existed across the
+ * codebase before this consolidation:
  *   - `lib/cli/update.js#detectPackageManager`
  *   - `lib/bootstrap/project-bootstrap.js#detectPackageManager`
  *   - `lib/runtime-deps/preflight.js#detectPackageManager`
- *   - `lib/onboard/detect-stack.js#detectPackageManager`
  *   - `lib/worktree/node-modules-strategy.js#selectInstallCommand` (inline)
  *
  * This module is the single authoritative implementation. It uses the

package/.agents/scripts/lib/onboard/init-tail.js

@@ -2,18 +2,17 @@
  * init-tail.js — post-bootstrap onboarding tail for `mandrel init`.
  *
  * Called by `mandrel init` after `bootstrap.js` completes successfully on
- * the "configure now" path. Sequences the four phases that walk an operator
+ * the "configure now" path. Sequences the three phases that walk an operator
  * from a freshly bootstrapped project to a ready-to-plan workspace:
  *
- *   Phase 1 — Detect the consumer stack (lib/onboard/detect-stack.js).
- *   Phase 2 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
- *   Phase 3 — Run `mandrel doctor` as a readiness gate.
- *   Phase 4 — Print the /plan handoff next-step text.
+ *   Phase 1 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
+ *   Phase 2 — Run `mandrel doctor` as a readiness gate.
+ *   Phase 3 — Print the /plan handoff next-step text.
  *
  * The whole tail is idempotent: re-running after an already-onboarded project
- * re-detects, re-checks, and re-offers scaffolding without duplicating stubs
- * (the scaffolder only writes genuinely absent files) and without modifying
- * anything (doctor is read-only).
+ * re-checks and re-offers scaffolding without duplicating stubs (the scaffolder
+ * only writes genuinely absent files) and without modifying anything (doctor is
+ * read-only).
  *
  * Injectable seams: `runDoctor`, `stdout`, `confirmScaffold`, and `isTTY`
  * allow the unit suite to drive every branch without real I/O.
@@ -22,10 +21,9 @@
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
-import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
 
-import { detectStack } from './detect-stack.js';
 import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
 
 // ---------------------------------------------------------------------------
@@ -38,7 +36,7 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
  * @type {string}
  */
 export const PLAN_HANDOFF_TEXT =
-  '\n✅  Mandrel is ready. Start your first Epic:\n\n' +
+  '\n✅  Mandrel is ready. Start your first project:\n\n' +
   '    /plan --idea "<one-line description of what you want to build>"\n\n' +
   'Or, if you already have a `type::epic` Issue open:\n\n' +
   '    /plan <epicId>\n';
@@ -47,24 +45,6 @@ export const PLAN_HANDOFF_TEXT =
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Format a stack-detection result as a human-readable report line.
- *
- * @param {{ packageManager: string|null, testRunner: string|null, primaryLanguage: string|null }} stack
- * @returns {string}
- */
-function formatStackReport(stack) {
-  const pm = stack.packageManager ?? '(unknown)';
-  const runner = stack.testRunner ?? '(unknown)';
-  const lang = stack.primaryLanguage ?? '(unknown)';
-  return (
-    '\n[init] Stack detection:\n' +
-    `  Package manager : ${pm}\n` +
-    `  Test runner     : ${runner}\n` +
-    `  Primary language: ${lang}\n`
-  );
-}
-
 /**
  * Format a list of missing docs as a human-readable report (no prompt).
  *
@@ -75,30 +55,54 @@ function formatMissingList(missing) {
   if (missing.length === 0) return '';
   const list = missing.map((f) => `  • ${f}`).join('\n');
   return (
-    '\n[init] The following docsContextFiles are missing — agents load\n' +
-    'these before every task:\n' +
+    '\n[Final Checks] The following docsContextFiles are missing,\n' +
+    'agents will load degraded context until you create them:\n' +
     `${list}\n`
   );
 }
 
 /** Prompt text shown only on a TTY when asking to scaffold. */
-const SCAFFOLD_PROMPT = '\nScaffold stubs now? [y/N]: ';
+const SCAFFOLD_PROMPT = '\nCreate placeholders? [Y/n]: ';
 
 /**
- * Synchronous y/N read from stdin (fd 0). Returns `false` on any read error
- * or when the user enters something other than `y` / `yes`.
+ * Async y/N read from stdin via `node:readline` (mirrors the prompt mechanism
+ * in `bootstrap.js`). Returns on Enter and never blocks waiting for EOF the way
+ * `fs.readFileSync(0)` did — that EOF-blocking read hung `mandrel init` on an
+ * interactive TTY. Yes is the default (`[Y/n]`): a bare Enter — or anything but
+ * an explicit `n`/`no` — resolves to `true` (create the placeholders), since the
+ * missing docs are known-needed and the stubs carry a `MANDREL:STUB` marker the
+ * `/plan` preflight still flags until they are fleshed out. A read error
+ * resolves to `false` so a genuine I/O failure never writes unattended. The
+ * prompt text is written by the caller via `stdout`, so the question string
+ * passed here is empty.
+ *
+ * `terminal: false` is **load-bearing**: with terminal mode on (the default
+ * when stdout is a TTY) readline emits cursor-control escapes
+ * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [Y/n]:` prompt already
+ * written via the caller's `stdout`, leaving the operator staring at a blank,
+ * dead-looking line. Disabling terminal mode preserves the pre-written prompt
+ * and reads the line via the TTY's cooked-mode echo. `createInterface` is
+ * injectable so a test can assert this option is set (regression guard).
  *
- * @returns {boolean}
+ * @param {{ createInterface?: typeof readline.createInterface }} [opts]
+ * @returns {Promise<boolean>}
  */
-function syncConfirm() {
-  let answer = '';
+export async function readConfirm({
+  createInterface = readline.createInterface,
+} = {}) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
   try {
-    const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+    const answer = (await rl.question('')).trim().toLowerCase();
+    return answer !== 'n' && answer !== 'no';
   } catch {
-    answer = '';
+    return false;
+  } finally {
+    rl.close();
   }
-  return answer === 'y' || answer === 'yes';
 }
 
 // ---------------------------------------------------------------------------
@@ -119,14 +123,13 @@ function syncConfirm() {
  *   - Run `mandrel doctor`; injectable for tests.
  * @param {boolean} [opts.isTTY] - Whether stdin is a TTY (defaults to
  *   `Boolean(process.stdin.isTTY)`).
- * @returns {{
- *   stack: { packageManager: string|null, testRunner: string|null, primaryLanguage: string|null },
+ * @returns {Promise<{
  *   scaffoldResult: object,
  *   doctorStatus: number,
  *   ok: boolean,
- * }}
+ * }>}
  */
-export function runInitTail({
+export async function runInitTail({
   root,
   stdout = (s) => process.stdout.write(s),
   confirmScaffold,
@@ -140,7 +143,7 @@ export function runInitTail({
   // it. When using the default, auto-decline on non-TTY so the scaffolder
   // never writes unattended.
   const usingDefaultConfirm = confirmScaffold == null;
-  const confirmFn = confirmScaffold ?? (() => syncConfirm());
+  const confirmFn = confirmScaffold ?? readConfirm;
 
   // Default doctor runner — spawns `mandrel doctor` via the locally installed
   // bin; inherits stdio so the report streams to the terminal.
@@ -159,21 +162,12 @@ export function runInitTail({
 
   const doctorFn = runDoctor ?? defaultRunDoctor;
 
-  // --- Phase 1: Detect the stack -------------------------------------------
-  let stack;
-  try {
-    stack = detectStack(projectRoot);
-  } catch {
-    stack = { packageManager: null, testRunner: null, primaryLanguage: null };
-  }
-  stdout(formatStackReport(stack));
-
-  // --- Phase 2: Offer to scaffold missing docsContextFiles -----------------
+  // --- Phase 1: Offer to scaffold missing docsContextFiles -----------------
   const preview = scaffoldDocs({ root: projectRoot, write: false });
   let scaffoldResult = preview;
 
   if (preview.missing.length === 0) {
-    stdout('\n[init] All docsContextFiles are present.\n');
+    stdout('\n[Final Checks] All docsContextFiles are present.\n');
   } else {
     stdout(formatMissingList(preview.missing));
     // On non-TTY without an injected confirm, auto-decline so the scaffolder
@@ -181,38 +175,35 @@ export function runInitTail({
     // the prompt and consult the confirm function.
     const canPrompt = tty || !usingDefaultConfirm;
     if (canPrompt) stdout(SCAFFOLD_PROMPT);
-    const accepted = canPrompt ? confirmFn() : false;
+    const accepted = canPrompt ? await confirmFn() : false;
     if (accepted) {
       scaffoldResult = scaffoldDocs({ root: projectRoot, write: true });
       if (scaffoldResult.created.length > 0) {
         stdout(
-          `[init] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
+          `[Final Checks] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
             `Each carries a \`${STUB_MARKER}\` marker — replace placeholder ` +
             'content before planning.\n',
         );
       }
     } else {
-      stdout(
-        '[init] Scaffolding declined. docsContextFiles are still missing — ' +
-          'agents will load degraded context until you create them.\n',
-      );
+      stdout('[Final Checks] Placeholders declined.\n');
     }
   }
 
-  // --- Phase 3: Readiness gate (mandrel doctor) ----------------------------
-  stdout('\n[init] Running mandrel doctor…\n');
+  // --- Phase 2: Readiness gate (mandrel doctor) ----------------------------
+  stdout('\n[Final Checks] Final installation summary via mandrel doctor…\n');
   const doctorResult = doctorFn();
   const doctorStatus = doctorResult?.status ?? 1;
 
   if (doctorStatus !== 0) {
     stdout(
-      '\n[init] ❌  Doctor check failed. Resolve the remedies above and\n' +
+      '\n[Final Checks] ❌  Doctor check failed. Resolve the remedies above and\n' +
         'then re-run: mandrel init\n',
     );
-    return { stack, scaffoldResult, doctorStatus, ok: false };
+    return { scaffoldResult, doctorStatus, ok: false };
   }
 
-  // --- Phase 4: Handoff to /plan -------------------------------------------
+  // --- Phase 3: Handoff to /plan -------------------------------------------
   stdout(PLAN_HANDOFF_TEXT);
-  return { stack, scaffoldResult, doctorStatus, ok: true };
+  return { scaffoldResult, doctorStatus, ok: true };
 }

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

@@ -26,6 +26,28 @@ export const INTEGRATION_INCLUDE = [
 
 const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
 
+/**
+ * Repo-relative roots the tier walker scans for test files (names ending in
+ * `.test.js`).
+ *
+ * `tests` holds the framework's suite tree; `lib` holds the published CLI
+ * (under `lib/cli` and `lib/migrations`) whose tests are colocated in
+ * `__tests__` directories per the unit-tier convention in
+ * `rules/testing-standards.md`. Without `lib` here, both the quick /
+ * integration walk and the full-tier glob set miss the colocated CLI tests,
+ * leaving that coverage dark in `npm test`. The matching full-tier globs
+ * live in `FULL_TIER_GLOBS`.
+ */
+const TEST_WALK_ROOTS = ['tests', 'lib'];
+
+/**
+ * Glob targets for the `full` tier — one per walk root in `TEST_WALK_ROOTS`.
+ * The `tests` glob is a flat recursive sweep; the `lib` glob is scoped to
+ * `__tests__` subtrees so it only matches colocated tests, never the shipped
+ * source modules themselves.
+ */
+const FULL_TIER_GLOBS = ['tests/**/*.test.js', 'lib/**/__tests__/**/*.test.js'];
+
 /**
  * @param {string} dir
  * @param {string} prefix
@@ -56,13 +78,11 @@ function walkTestFiles(dir, prefix, fsLike) {
  * @returns {string[]}
  */
 export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
-  const all = walkTestFiles(
-    path.join(repoRoot, 'tests'),
-    'tests',
-    fsLike,
+  const all = TEST_WALK_ROOTS.flatMap((root) =>
+    walkTestFiles(path.join(repoRoot, root), root, fsLike),
   ).sort();
   if (tier === 'full') {
-    return ['tests/**/*.test.js'];
+    return [...FULL_TIER_GLOBS];
   }
   const integration = all.filter((file) => matchesIntegration(file));
   if (tier === 'integration') {

package/.agents/scripts/providers/github/tickets.js

@@ -77,7 +77,7 @@ export function composeStoryBody({
 }) {
   const head = typeof body === 'string' ? body : '';
   const lines = ['---', `parent: #${parentId}`];
-  if (epicId !== undefined && epicId !== null && epicId !== parentId) {
+  if (epicId !== undefined && epicId !== null) {
     lines.push(`Epic: #${epicId}`);
   }
   if (dependencies.length > 0) {

package/.agents/workflows/helpers/deliver-stories.md

@@ -192,7 +192,18 @@ Each Agent call:
 1. Names the Story ID and instructs the child to invoke
    [`helpers/single-story-deliver`](single-story-deliver.md)
    for that Story.
-2. States the **return contract** (see § 2c).
+2. States the **return contract** (see § 2c) and the **no-park rule**: the
+   child MUST drive the close → CI-watch → merge-confirm → `agent::done`
+   sequence to a terminal state *within its own turn* and end **only** by
+   returning the § 2c JSON object. The auto-merge wait is an
+   internally-blocking step (`gh pr checks --watch` blocks the turn), **not**
+   a reason to suspend and hand back. A child that ends its turn with
+   free-form prose and an unconfirmed merge (e.g. "I'll wait for the
+   background watch task…") has violated the contract — the wave loop cannot
+   advance, and the Story strands at `agent::closing` (the Story #1553 /
+   PR #1554 failure mode). There is no "pending" return status: the child
+   returns `done` (merge confirmed), `blocked` (transitioned + friction
+   posted), or `failed`.
 3. Reminds the child of the **non-interactive contract**: no clarifying
    questions — if stuck, transition to `agent::blocked`, post a
    `friction` comment, and exit non-zero.
@@ -209,7 +220,8 @@ Agent call has returned a result (success, blocked, or failed).
 
 ### 2c. Per-Story return contract
 
-Each child returns:
+Each child ends its turn by returning **exactly one** JSON object — never
+free-form prose:
 
 ```json
 {
@@ -223,6 +235,16 @@ Each child returns:
 }
 ```
 
+The status enum is **closed** — `done`, `blocked`, or `failed`. There is no
+"pending" / "waiting" status, because the close-phase auto-merge wait is
+**not** a returnable suspension: the child blocks on `gh pr checks --watch`
+*inside its own turn*, confirms the merge, flips `agent::done`, and only then
+returns `status: "done"`. A child that returns prose instead — parking on the
+CI wait with an unconfirmed merge — breaks the wave loop's ability to advance
+and leaves the Story at `agent::closing` (Story #1553 / PR #1554). The
+single-homed restatement of this no-park rule for the child's own perspective
+is [`single-story-deliver.md` § Step 7](single-story-deliver.md#return-contract).
+
 ### 2d. Wave outcome handling
 
 After every Story in a wave returns:

package/.agents/workflows/helpers/single-story-deliver.md

@@ -336,6 +336,26 @@ coverage rounding, platform-conditional branches, and timing-sensitive
 tests routinely drift between the two. The agent owns the green-CI
 outcome, not just the push.
 
+> **The auto-merge wait is an internally-blocking step, not a reason to end
+> your turn.** This is the single most important contract of this workflow,
+> and the seam where a worker most often misbehaves: it delivers up to arming
+> auto-merge, then ends its turn with **free-form prose** — e.g. "I'll wait
+> for the background watch task to complete" or "the next event will be its
+> completion notification" — leaving the merge unconfirmed and the Story
+> stranded at `agent::closing` (observed on Story #1553 / PR #1554). **Do not
+> do this.** `gh pr checks <prNumber> --watch` *blocks the current turn* until
+> CI resolves — that is the mechanism by which you wait. You MUST keep your
+> turn alive across the wait: watch → (fix + push + re-watch on red) → confirm
+> the merge (Step 5) → flip `agent::done` → run the post-merge steps → and
+> only then return the terminal JSON status contract (Step 4 of
+> [`deliver-stories.md` § 2c](deliver-stories.md), mirrored in
+> [§ Return contract](#return-contract) for the standalone caller). The CI
+> wait NEVER terminates your turn; **only** a confirmed-`MERGED` PR (→
+> `status: "done"`), an `agent::blocked` transition (→ `status: "blocked"`),
+> or an unrecoverable failure (→ `status: "failed"`) does. Ending your turn
+> with prose and an unconfirmed merge is a contract violation — it is the very
+> bug this workflow exists to prevent.
+
 After `single-story-close.js` succeeds, enter the watch + fix loop:
 
 ```bash
@@ -348,7 +368,9 @@ When the watch exits:
   still at `agent::closing` with its issue OPEN at this point (Step 3
   deferred the `agent::done` flip). The `Closes #<id>` footer closes the
   Story issue when the merge lands; Step 5 confirms the merge and Step 5.5
-  flips the Story to `agent::done`. Proceed to Step 5.
+  flips the Story to `agent::done`. **Proceed to Step 5 within the same
+  turn** — do not end your turn here. Green CI is the *start* of the
+  merge-confirm sequence, not a terminal state (see Step 7's no-park rule).
 - **Any check ✗** — diagnose, fix, and push a new commit on
   `story-<storyId>`, then re-watch. Auto-merge stays enabled across
   retries; no need to re-arm it. The Story stays at `agent::closing`
@@ -582,6 +604,67 @@ cleanup.
 
 ---
 
+## Step 7 — Return contract (**required when dispatched as a sub-agent**) {#return-contract}
+
+When this workflow runs as a per-Story sub-agent (dispatched by `/deliver`
+via [`deliver-stories.md` § 2a/2c](deliver-stories.md)), the **only**
+acceptable way to end your turn is to **return a single terminal JSON status
+object** — never free-form prose:
+
+```json
+{
+  "storyId": <number>,
+  "status": "done" | "blocked" | "failed",
+  "phase": "init|implementing|closing|blocked|done",
+  "branchDeleted": <boolean>,
+  "blockerCommentId": <string|null>,
+  "detail": "<one-liner: what changed + what was verified, e.g. PR #N merged>",
+  "renderedBody": "<terminal Story body>"
+}
+```
+
+This is the same envelope [`deliver-stories.md` § 2c](deliver-stories.md)
+mandates; this section is its single-homed restatement for the standalone
+worker so the contract is self-contained when this workflow is the entry
+point.
+
+**The auto-merge wait does not produce a fourth status.** There is no
+"pending" or "waiting" terminal — the CI/auto-merge wait is handled
+*internally* by blocking on `gh pr checks --watch` (Step 4) and confirming
+the merge (Step 5). You return **only** when you have reached a genuinely
+terminal state:
+
+- **`status: "done"`** — the PR is confirmed `state: "MERGED"` (Step 5),
+  the Story carries `agent::done`, and Steps 5.5 / 6 have run. `phase: "done"`,
+  `branchDeleted: true`.
+- **`status: "blocked"`** — you transitioned the Story to `agent::blocked`
+  and posted a `friction` comment (acceptance self-eval block in Step 1a, a
+  base-sync conflict, or an operator-blocking CI failure / Anti-Thrashing
+  stop in Step 4). `phase: "blocked"`, `blockerCommentId` set.
+- **`status: "failed"`** — an unrecoverable failure outside the blocked
+  protocol. `phase` reflects where it died.
+
+A turn that ends with prose ("I'll wait for the watch task…", "the next event
+will be its completion notification…") and an **unconfirmed merge** is a
+**contract violation** (the Story #1553 / PR #1554 failure mode): the parent
+wave loop cannot distinguish "still working" from "done but silent", and the
+Story strands at `agent::closing`. If you genuinely cannot confirm the merge,
+that is a `blocked` or `failed` outcome with the JSON contract above — not a
+prose hand-off.
+
+> **Handoff discipline — report state, not process.** Populate the envelope
+> with essential terminal state only (mirroring the fields
+> `single-story-close.js` / `story-phase.js` already emit). Do not narrate the
+> steps you took, and do not prescribe how the next stage should work. Prose
+> process commentary only bloats the hydrated prompt
+> (`delivery.maxTokenBudget` elision). When run **interactively** (no parent
+> aggregator), this JSON envelope is optional — relay terminal state to the
+> operator in prose instead — but the **no-park rule still holds**: never end
+> an interactive turn with an unconfirmed merge either; block on the watch,
+> confirm, and report the merged outcome.
+
+---
+
 ## Idempotence
 
 - `single-story-init.js` re-prints the same `workCwd` without recreating

package/.agents/workflows/qa-assist.md

@@ -239,24 +239,61 @@ and optionally route or promote it — with the operator deciding each write.
    `regression-of-closed`. Stamp the `fingerprintFooter(sha)` marker into any
    Issue body so future runs dedup against it.
 
-3. **Optionally promote** the finding to a follow-up ticket via
+3. **Promote `file`-dispositioned findings through `/plan`** (never a raw
+   GitHub Issue) via
    [`promote-finding.js`](../scripts/lib/findings/promote-finding.js), which
-   clusters, routes, and files through the same ports — never hand-roll the
-   promotion:
+   clusters, sizes, routes, and files through the same ports `/qa-explore` and
+   `/audit-to-stories` consume — never hand-roll the promotion, the clustering,
+   or the sizing:
 
    ```js
    import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
-   const promotions = await promoteFindings(ledgerItems, { searchIssues, createStory });
+   const { promotions } = await promoteFindings(ledgerItems, {
+     searchIssues, // GitHub provider, open + closed
+     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
+     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+   });
    ```
 
-4. **Gate:** any ledger append, ticket-filing, or label mutation is a write —
-   confirm **each one** with the operator before it happens. Redaction has
-   already run, so nothing unredacted reaches disk or GitHub.
+   - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
+     `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
+     distinct coverage surfaces routes to `createStory`; **>2** routes to
+     `createEpic`. Do not re-cluster, re-size, or re-dedup in the workflow —
+     [`route-finding.js`](../scripts/lib/findings/route-finding.js) /
+     [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) are the
+     single implementation.
+   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
+     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5b notes shape; redaction already ran in Phase 2), **stamp the
+     cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
+     chain `/plan --from-notes <seed>`. The footer must survive into the issue
+     body the Story create path writes — it round-trips through
+     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
+     deterministic round-trip test under `tests/`) so a later `routeFinding`
+     dedups the same finding instead of re-filing it.
+   - **`createEpic` (`/plan --idea`)** — carry the cluster's
+     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
+     `/plan --idea <seed>`. **Known limitation (not solved here):**
+     per-child-Story fingerprint propagation through full Epic decomposition is
+     *not* guaranteed — the fingerprint is carried in the Epic seed only; the
+     child Stories `/plan` spawns from that seed are not individually
+     footer-stamped.
+   - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
+     finding flows through `promoteFindings` → `/plan`; only `defer` (carry
+     forward as backlog) and `dismiss` (non-actionable) skip the `/plan`
+     handoff.
+
+4. **Gate:** any ledger append, seed write, `/plan` invocation, ticket-filing,
+   or label mutation is a write — confirm **each one** with the operator before
+   it happens. The plan→deliver hard stop is preserved: each `/plan` chain
+   pauses at its own HITL gates and never auto-delivers. Redaction has already
+   run, so nothing unredacted reaches disk or GitHub.
 
 After recording, summarize: the finding recorded, its coverage verdict and
 `missingTest`, any route/promotion decision
-(`new`/`update-existing`/`duplicate`/`regression-of-closed`), and the rolling
-backlog a resumed session will pick up.
+(`new`/`update-existing`/`duplicate`/`regression-of-closed`) and whether it was
+promoted to a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and the
+rolling backlog a resumed session will pick up.
 
 ---
 
@@ -291,3 +328,24 @@ backlog a resumed session will pick up.
   promotion ([`promote-finding.js`](../scripts/lib/findings/promote-finding.js)),
   and session resolution ([`qa-session.js`](../scripts/lib/qa/qa-session.js))
   are deterministic — never re-derive them in prose.
+- **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
+  finding is promoted via `promoteFindings`, which chains into
+  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-assist`
+  never opens a bare GitHub Issue for a `file` finding. The cluster's
+  `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
+  `routeFinding` dedups it.
+
+## See also
+
+- [`/plan`](plan.md) — the planning pipeline `/qa-assist` chains into when an
+  operator dispositions a finding `file` (`--from-notes` for a Story, `--idea`
+  for an Epic). The plan→deliver hard stop is preserved across the handoff.
+- [`/qa-explore`](qa-explore.md) — the agent-led sibling that drives a named
+  surface and triages through the same `/plan` handoff.
+- [`/audit-to-stories`](audit-to-stories.md) — the precedent for the
+  findings → `/plan` handoff and the shared fingerprint-footer dedup contract.
+- [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) /
+  [`route-finding.js`](../scripts/lib/findings/route-finding.js) — the shared
+  cluster/size/promote and dedup/route/fingerprint-footer helpers. There is no
+  second clustering, sizing, or dedup implementation.