mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/validation-evidence.js

@@ -3,15 +3,12 @@
  *
  * Tech Spec #819 §"Evidence record (Story 7)". Each successful gate run
  * writes a record keyed by `{ gateName, commitSha, commandConfigHash }` to
- * a per-Epic-tree path under the resolved `tempRoot`:
+ * a storyId-anchored path under the resolved `tempRoot`:
  *
- *   - Epic-scoped (scopeId === epicId):
- *       `<tempRoot>/epic-<epicId>/validation-evidence.json`
- *   - Story-scoped (scopeId === storyId):
- *       `<tempRoot>/epic-<epicId>/story-<storyId>/validation-evidence.json`
+ *   `<tempRoot>/standalone/stories/story-<storyId>/validation-evidence.json`
  *
- * Both paths sit inside the per-Epic durable workspace (Epic #1030, Stories
- * #1039 + #1054) and are gitignored via `temp/`.
+ * The path is gitignored via `temp/`. v2.0.0 removed the Epic tier along
+ * with the Epic-keyed `<tempRoot>/epic-<epicId>/…` keyspace.
  *
  * A subsequent caller can `shouldSkip(...)` to learn whether the same gate
  * has already passed against the current HEAD with an identical
@@ -34,7 +31,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
-import { epicTempDir, storyTempDir } from './config/temp-paths.js';
+import { storyTempDir } from './config/temp-paths.js';
 
 export const SCHEMA_VERSION = 1;
 const DEFAULT_TEMP_DIR = 'temp';
@@ -97,37 +94,28 @@ function requirePositiveInt(value, label) {
 
 /**
  * Compute the absolute path of the evidence file for `scopeId` under the
- * per-Epic temp tree.
+ * storyId-anchored temp tree.
  *
- * The resolution rule mirrors `lib/config/temp-paths.js`:
- *   - `scopeId === epicId` → `<tempRoot>/epic-<epicId>/validation-evidence.json`
- *   - `scopeId !== epicId` → treated as a Story id → `<tempRoot>/epic-<epicId>/story-<scopeId>/validation-evidence.json`
- *
- * **Standalone keyspace (Story #4250).** When `opts.standalone === true`,
+ * **Standalone keyspace (Story #4250).** `opts.standalone` must be `true`:
  * the Story has no parent Epic, so the evidence file is anchored on the
  * Story id alone at
  * `<tempRoot>/standalone/stories/story-<scopeId>/validation-evidence.json`
- * (the `storyTempDir(null, sid)` layout from Story #2874). In this mode
- * `epicId` is ignored — callers MUST NOT feed a `0`/`null` epicId into the
- * Epic-keyed branch (the historical bug this keyspace replaces). Outside
- * standalone mode `epicId` remains required.
+ * (the `storyTempDir(null, sid)` layout from Story #2874).
  *
- * The legacy flat `temp/validation-evidence-<scopeId>.json` layout is no
- * longer supported — Epic-scoped callers must thread the Epic id through
- * (Epic #1030 follow-up to Story #1054). The synthetic config bag passed to
- * `epicTempDir` / `storyTempDir` keeps the resolver from doing a disk-bound
- * `.agentrc.json` lookup; bare callers can pass `tempDir` via `opts` to
- * override the default `'temp'`.
+ * The legacy flat `temp/validation-evidence-<scopeId>.json` layout and the
+ * Epic-keyed `<tempRoot>/epic-<epicId>/…` layout are both gone. The
+ * synthetic config bag passed to `storyTempDir` keeps the resolver from
+ * doing a disk-bound `.agentrc.json` lookup; bare callers can pass
+ * `tempDir` via `opts` to override the default `'temp'`.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean }} opts
  * @returns {string}
  */
 export function evidencePath(scopeId, opts = {}) {
-  const standalone = opts.standalone === true;
-  if (!standalone && opts.epicId == null) {
+  if (opts.standalone !== true) {
     throw new Error(
-      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution) unless opts.standalone is set.',
+      '[validation-evidence] evidencePath requires opts.standalone (the storyId-anchored keyspace is the only keyspace).',
     );
   }
   const { cwd, tempDir } = resolveOpts(opts);
@@ -143,18 +131,9 @@ export function evidencePath(scopeId, opts = {}) {
     ? tempDir
     : path.join(cwd, tempDir);
   const configBag = { project: { paths: { tempRoot: absTempRoot } } };
-  let dir;
-  if (standalone) {
-    // Story #4250 — storyId-anchored standalone keyspace. `null` is the
-    // standalone-story sentinel `storyTempDir` accepts (Story #2874).
-    dir = storyTempDir(null, scope, configBag);
-  } else {
-    const epicId = requirePositiveInt(opts.epicId, 'epicId');
-    dir =
-      scope === epicId
-        ? epicTempDir(epicId, configBag)
-        : storyTempDir(epicId, scope, configBag);
-  }
+  // Story #4250 — storyId-anchored standalone keyspace. `null` is the
+  // standalone-story sentinel `storyTempDir` accepts (Story #2874).
+  const dir = storyTempDir(null, scope, configBag);
   return path.join(dir, EVIDENCE_FILENAME);
 }
 
@@ -189,19 +168,17 @@ function emptyDoc(scopeId) {
  * cross-scopeId cases — callers don't have to branch on those failure
  * modes; they manifest as `shouldSkip()` returning `skip: false`.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ storyId: number, schemaVersion: number, records: object[] }}
  */
 export function loadEvidence(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
   const file = evidencePath(scopeId, {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   });
   if (!resolved.fs.existsSync(file)) return emptyDoc(scopeId);
@@ -223,9 +200,8 @@ export function loadEvidence(scopeId, opts = {}) {
  * Validates the resulting document against the schema before writing — a
  * malformed write throws so the bug surfaces immediately.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {{
  *   storyId: number|string,
@@ -235,7 +211,7 @@ export function loadEvidence(scopeId, opts = {}) {
  *   exitCode?: number,
  *   durationMs?: number|null,
  * }} input
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object, now?: Function }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object, now?: Function }} opts
  * @returns {object} The persisted record.
  */
 export function recordPass(
@@ -258,7 +234,6 @@ export function recordPass(
   const resolved = resolveOpts(opts);
   const evidenceOpts = {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   };
   const doc = loadEvidence(storyId, evidenceOpts);
@@ -297,13 +272,12 @@ export function recordPass(
  * with a machine-readable `reason` so callers can log why the skip didn't
  * fire.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace. `opts` is forwarded verbatim to
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace. `opts` is forwarded verbatim to
  * `loadEvidence`, so `standalone` flows through unchanged.
  *
  * @param {{ storyId: number|string, gateName: string, currentSha: string, configHash: string }} input
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ skip: boolean, reason: string, record?: object }}
  */
 export function shouldSkip(
@@ -336,23 +310,21 @@ export function shouldSkip(
 }
 
 /**
- * Delete the evidence file for `scopeId`. Called by `story-init.js` at the
+ * Delete the evidence file for `scopeId`. Called by `single-story-init.js` at the
  * start of each Story so a re-run always starts clean. Idempotent —
  * absent file is not an error.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ cleared: boolean, path: string }}
  */
 export function forceClear(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
   const file = evidencePath(scopeId, {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   });
   if (!resolved.fs.existsSync(file)) return { cleared: false, path: file };

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -2,8 +2,8 @@
  * lib/wave-runner/ready-set.js — the path-agnostic ready-set scheduling
  * core.
  *
- * This module is the scheduling kernel both the Epic and standalone
- * delivery paths dispatch through. It replaces wave-*batch* selection
+ * This module is the scheduling kernel the v2 `/deliver` multi-Story path
+ * dispatches through (`stories-wave-tick.js`). It replaces wave-*batch* selection
  * (group N must fully drain before group N+1 opens) with *continuous*,
  * dependency-driven selection: a Story becomes dispatchable the instant
  * **its own** dependencies are satisfied, regardless of whether unrelated
@@ -15,14 +15,14 @@
  * reads GitHub, the lifecycle ledger, nor a checkpoint, and it dispatches
  * nothing. Callers supply the live Story records (already fetched), the
  * resolved `inFlight` count, and the `globalCap`, and receive back the set
- * of Stories that are safe to dispatch on this beat. Later Stories wire the
- * Epic / standalone adapters on top of this core; this Story ships the core
- * alone and does not modify `tick.js` or `stories-wave-tick.js`.
+ * of Stories that are safe to dispatch on this beat. The
+ * `stories-wave-tick.js` adapter wires this core; this module does not
+ * modify that CLI surface.
  *
  * Three exports:
  *   - `classifyStory(story)` — live-label classifier mapping a Story
  *     record's labels + issue state to one of `done | blocked | executing |
- *     ready`. Mirrors the done-predicate `tick.js` already uses
+ *     ready`. Mirrors the done-predicate this module uses
  *     (`agent::done` OR closed issue) so a Story closed manually through
  *     the GitHub UI is recognised as done.
  *   - `storiesOverlap(a, b)` — the file-overlap co-dispatch guard: true
@@ -156,15 +156,37 @@ export function storyFootprint(story) {
   return out;
 }
 
+/**
+ * Does a declared path contain a glob metacharacter? Mirrors the detection
+ * in `story-body.js#extractChangePaths`, whose `isGlob` flag documents an
+ * "unknown-width footprint" policy that was never implemented downstream.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+function isGlobPath(path) {
+  return path.includes('*') || path.includes('?') || path.includes('{');
+}
+
 /**
  * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
- * file footprints intersect on at least one path — meaning they would race
- * the same file if dispatched onto parallel `story-<id>` branches in the
- * same beat. Two Stories that overlap MUST NOT both appear in one dispatch
- * set; one is withheld until the other clears.
+ * file footprints intersect — meaning they would race the same file if
+ * dispatched onto parallel `story-<id>` branches in the same beat. Two
+ * Stories that overlap MUST NOT both appear in one dispatch set; one is
+ * withheld until the other clears.
  *
- * An empty footprint on either side means "no known overlap" → `false`. A
- * Story that declares no files is therefore never withheld by this guard.
+ * Two deliberate asymmetries:
+ *
+ *   - **An empty footprint means "no known overlap"** → `false`. A Story that
+ *     declares no files is never withheld. This is permissive by necessity:
+ *     an undeclared footprint carries no information, and withholding on
+ *     absence would serialize every run.
+ *   - **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
+ *     Comparison is exact-string, so a Story declaring
+ *     `.agents/scripts/lib/**` would not match another declaring
+ *     `.agents/scripts/lib/story-adjacency.js` — the guard would silently
+ *     pass two Stories that genuinely race. Unknown width is not the same as
+ *     no width: fail safe by serializing.
  *
  * @param {StoryRecord} a
  * @param {StoryRecord} b
@@ -176,8 +198,12 @@ export function storiesOverlap(a, b) {
   const fb = storyFootprint(b);
   if (fb.size === 0) return false;
   for (const path of fa) {
+    if (isGlobPath(path)) return true;
     if (fb.has(path)) return true;
   }
+  for (const path of fb) {
+    if (isGlobPath(path)) return true;
+  }
   return false;
 }
 

package/.agents/scripts/lib/workspace-provisioner.js

@@ -145,7 +145,7 @@ export function provision({
 /**
  * Throw if any required workspace file is missing from `worktree`. Used as a
  * runtime guard (called right after every worktree create in
- * `story-init.js`) and as a test oracle.
+ * `single-story-init.js`) and as a test oracle.
  *
  * When `sourceRoot` is supplied, the thrown error carries the missing target
  * path and an exact `cp`/`copy` command the operator can paste to remediate.

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -7,7 +7,7 @@
  * on a Windows lock-class failure, the entry is appended to
  * `.worktrees/.pending-cleanup.json`. The plan-time `worktree-sweep.js`
  * reader (shipped in Epic #349) picks up the manifest on the next
- * `/epic-plan-spec` / `/epic-plan-decompose` runs and retries removal
+ * `/plan` run and retries removal
  * (`git worktree remove` then `fs.rm`) — by then the live file handles from Node / AV / the Windows
  * Search indexer are almost always gone. If `MAX_SWEEP_ATTEMPTS` elapses
  * without clearing, an `OPERATOR ACTION REQUIRED: persistent-lock` line

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -15,7 +15,7 @@
 
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
-import { isInsideWorktree, samePath, storyIdFromPath } from '../inspector.js';
+import { isInsideWorktree, samePath } from '../inspector.js';
 import { sleepSync } from '../node-modules-strategy.js';
 import { checkMergeReachability } from './merge-reachability.js';
 import { recordPendingCleanup } from './pending-cleanup.js';
@@ -52,14 +52,12 @@ const WINDOWS_CWD_RE =
  * proves the Story branch was integrated even though the current HEAD
  * has diverged, so the worktree is still safe to reap.
  *
- * `opts.epicRef` is the canonical option name (e.g. `epic/1114`).
- * `opts.epicBranch` is accepted as a back-compat alias so existing call
- * sites that thread `{ epicBranch }` through `reap()` keep working until
- * they migrate.
+ * `opts.epicBranch` is the integration / base ref the Story must already
+ * be merged into (e.g. `main` or a plan-run branch).
  *
  * @param {object} ctx
  * @param {string} wtPath
- * @param {{ epicRef?: string|null, epicBranch?: string|null }} [opts]
+ * @param {{ epicBranch?: string|null }} [opts]
  * @returns {Promise<{ safe: boolean, reason?: string }>}
  */
 export async function isSafeToRemove(ctx, wtPath, opts = {}) {
@@ -67,28 +65,65 @@ export async function isSafeToRemove(ctx, wtPath, opts = {}) {
   if (!local.safe) return local;
   if (local.reason === 'path-missing') return local;
 
-  const epicRef = opts.epicRef ?? opts.epicBranch ?? null;
+  const epicRef = opts.epicBranch ?? opts.epicRef ?? null;
   if (!epicRef) return { safe: true };
 
   return checkMergeReachability(ctx, wtPath, local.branch, epicRef);
 }
 
 /**
- * Returns true iff `branch` is already fully merged into `epicBranch`
- * (i.e. `merge-base --is-ancestor branch epicBranch` exits 0). A missing
- * epicBranch or a git failure both yield false so callers default to the
- * safe, non-forcing behavior.
+ * Returns true iff `branch`'s work is demonstrably already integrated into
+ * `baseRef`. Used only to license discarding a **dirty** tree, so it must
+ * err toward `false`.
+ *
+ * Two-phase:
+ *   1. `merge-base --is-ancestor` — cheap SHA reachability; true for
+ *      fast-forward and merge-commit integration.
+ *   2. `git cherry <baseRef> <branch>` — compares **patch-ids** rather than
+ *      SHAs, marking a commit `-` when an equivalent change already exists
+ *      upstream. All-`-` (or empty) means every commit on the branch is
+ *      present in the base under some SHA.
+ *
+ * **Known limit — this is not a general squash detector.** A squash collapses
+ * N commits into ONE new commit whose patch equals their *combined* diff, so
+ * no individual original commit has an upstream patch-id equivalent and
+ * `git cherry` marks them all `+`. Phase 2 therefore only recognises a
+ * squash-landed branch when the branch had a **single** commit (verified
+ * empirically, Story #4539). A multi-commit squash still reads as unmerged
+ * and the dirty tree is refused — the safe direction, and the same answer
+ * the previous ancestor-only check gave. Detecting the general case needs
+ * the PR's merged state, which this module has no client for.
+ *
+ * A missing ref or a git failure yields false, so callers default to the
+ * safe, non-forcing behavior. Module-private: `ensureSafeOrForceDiscard` is
+ * its only caller, and the symbol it replaced was exported with no consumer
+ * and then baselined as a dead export — repeating that would just hide a
+ * new corpse.
+ *
+ * @param {object} ctx
+ * @param {string} branch
+ * @param {string} baseRef
+ * @returns {boolean}
  */
-export function isStoryAlreadyMergedIntoEpic(ctx, branch, epicBranch) {
-  if (!branch || !epicBranch) return false;
-  const res = ctx.git.gitSpawn(
+function isBranchMergedIntoBase(ctx, branch, baseRef) {
+  if (!branch || !baseRef) return false;
+  const ancestor = ctx.git.gitSpawn(
     ctx.repoRoot,
     'merge-base',
     '--is-ancestor',
     branch,
-    epicBranch,
+    baseRef,
   );
-  return res.status === 0;
+  if (ancestor.status === 0) return true;
+
+  const cherry = ctx.git.gitSpawn(ctx.repoRoot, 'cherry', baseRef, branch);
+  if (cherry.status !== 0) return false;
+  const lines = (cherry.stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  // Every line starting with '+' is a commit with no upstream equivalent.
+  return lines.every((line) => line.startsWith('-'));
 }
 
 /**
@@ -472,28 +507,40 @@ function checkReapPreconditions(ctx, _storyId, opts, wtPath) {
       ok: false,
       result: { removed: false, reason: 'not-a-worktree', path: wtPath },
     };
-  if (storyIdFromPath(wtPath, ctx.worktreeRoot) !== null && !opts.epicBranch) {
-    return {
-      ok: false,
-      result: { removed: false, reason: 'epic-branch-required', path: wtPath },
-    };
-  }
+  // Story #4539 removed an `epic-branch-required` gate here: a
+  // `story-<id>` worktree used to be unreapable unless the caller supplied
+  // an Epic integration branch. v2 has no Epic branch, and the only v2
+  // caller (the close path) never passed one — so EVERY close silently
+  // failed to reap while reporting success, and cleanup fell to the next
+  // boot-sweep.
+  //
+  // Nothing is lost by dropping it. The close path reaps AFTER pushing
+  // `story-<id>` to origin and opening the PR, so the work is durable
+  // off-machine; and the real safety net is unchanged — `isSafeToRemove`
+  // still refuses a dirty tree (`uncommitted-changes`), which is what
+  // actually protects unsaved work.
   return { ok: true };
 }
 
 async function ensureSafeOrForceDiscard(ctx, storyId, wtPath, opts) {
+  const baseRef = opts.baseRef ?? opts.epicBranch ?? null;
   const safety = await isSafeToRemove(ctx, wtPath, {
-    epicRef: opts.epicBranch ?? opts.epicRef ?? null,
+    epicBranch: baseRef,
   });
   if (safety.safe) return { ok: true, discardedPaths: null };
 
   const discardAfterMerge = opts.discardAfterMerge !== false;
   const branchName = `story-${validateStoryId(storyId)}`;
+  // Discarding a dirty tree is only permissible when the branch's work is
+  // demonstrably already integrated. See `isBranchMergedIntoBase` for what
+  // that can and cannot prove — notably a multi-commit squash reads as
+  // unmerged, so the discard is refused and the tree survives. Refusing is
+  // the safe direction: the cost is a stale worktree, not lost work.
   const canForceReap =
     discardAfterMerge &&
     safety.reason === 'uncommitted-changes' &&
-    opts.epicBranch &&
-    isStoryAlreadyMergedIntoEpic(ctx, branchName, opts.epicBranch);
+    baseRef &&
+    isBranchMergedIntoBase(ctx, branchName, baseRef);
   if (!canForceReap) {
     ctx.logger.warn(
       `reap-skipped storyId=${storyId} reason=${safety.reason} path=${wtPath}`,

package/.agents/scripts/lib/worktree/lifecycle-manager.js

@@ -7,7 +7,7 @@
  *   - `creation.js`         — `ensure`
  *   - `registry-sync.js`    — `pathFor`, `list`, `prune`, `getWorktreeList`,
  *                             `invalidateWorktreeCache`, `findByPath`
- *   - `reap.js`             — `isSafeToRemove`, `isStoryAlreadyMergedIntoEpic`,
+ *   - `reap.js`             — `isSafeToRemove`,
  *                             `removeWorktreeWithRecovery`, `reap`
  *   - `gc.js`               — `gc`
  *   - `drift-detection.js`  — `sweepStaleLocks`
@@ -26,7 +26,6 @@ export { sweepStaleLocks } from './lifecycle/drift-detection.js';
 export { gc } from './lifecycle/gc.js';
 export {
   isSafeToRemove,
-  isStoryAlreadyMergedIntoEpic,
   reap,
   removeWorktreeWithRecovery,
 } from './lifecycle/reap.js';

package/.agents/scripts/lint-issue-body.js

@@ -4,7 +4,7 @@
  * Issue-body conformance lint (Story #4227).
  *
  * Runs the canonical `story-body.parse()` against a human-opened
- * `type::story` / `type::epic` issue body and reports whether the body
+ * `type::story` issue body and reports whether the body
  * round-trips. This is the drift guard between the generated GitHub Issue
  * Forms (`lib/bootstrap/issue-forms-template.js`) and the parser: if a
  * human files a ticket whose body `parse()` rejects (or which lacks the
@@ -114,12 +114,12 @@ export function evaluateIssueBody(body) {
 
   const problems = [];
 
-  // A legacy string body parses but carries no structured sections — that
+  // An unstructured body parses but carries no structured sections — that
   // is exactly the human-filed shape this lint exists to catch.
-  if (result.info.isLegacyStringBody) {
+  if (result.info.isUnstructuredBody) {
     problems.push(
       'The body has no recognised `## Goal` / `## Acceptance` / `## Verify` sections. ' +
-        'File via the Story/Epic issue form so it round-trips through the parser.',
+        'File via the Story issue form so it round-trips through the parser.',
     );
   }
 
@@ -162,7 +162,7 @@ export function renderConformanceComment(verdict) {
     '',
     ...verdict.problems.map((p) => `- ${p}`),
     '',
-    'The quickest fix is to refile using the **Story** or **Epic** issue form ' +
+    'The quickest fix is to refile using the **Story** issue form ' +
       '(New issue → pick the template), which lays out the required sections.',
   ];
   if (verdict.warnings.length > 0) {
@@ -196,32 +196,40 @@ function gh(args) {
 }
 
 /**
- * CLI entry. Reads the target issue (number from `--issue` or the
- * `ISSUE_NUMBER` env), fetches its body + labels, and — when the body is
- * non-conformant — upserts a single marker comment. Always exits 0 (the
- * lint *informs*, it does not block), unless an unexpected I/O error occurs.
+ * Stage 5: only `type::story` tickets are in scope (type::epic retired).
  *
- * Flags:
- *   --issue <n>   Issue number (defaults to env ISSUE_NUMBER).
- *   --repo <o/r>  owner/repo (defaults to env GITHUB_REPOSITORY).
- *   --dry-run     Evaluate + print the verdict, never touch GitHub.
+ * @param {string[]} labelNames
+ * @returns {boolean}
  */
-async function main() {
-  const args = process.argv.slice(2);
-  const get = (flag) => {
-    const i = args.indexOf(flag);
-    return i >= 0 ? args[i + 1] : undefined;
-  };
-  const dryRun = args.includes('--dry-run');
-  const issue = get('--issue') ?? process.env.ISSUE_NUMBER;
-  const repo = get('--repo') ?? process.env.GITHUB_REPOSITORY;
-
-  if (!issue) {
-    throw new Error('lint-issue-body: --issue <n> or ISSUE_NUMBER is required');
-  }
+export function isStoryTicket(labelNames) {
+  return Array.isArray(labelNames) && labelNames.includes('type::story');
+}
 
+/**
+ * Evaluate an issue payload and optionally post a conformance comment.
+ * Pure with respect to GitHub when `ghFn` is injected — the CLI `main`
+ * is a thin argv wrapper around this helper.
+ *
+ * @param {{
+ *   issue: string|number,
+ *   repo?: string,
+ *   dryRun?: boolean,
+ *   ghFn?: (args: string[]) => string,
+ *   write?: (s: string) => void,
+ * }} opts
+ * @returns {{ skipped?: string, conformant?: boolean, problems?: string[] }}
+ */
+export function runLintIssueBody({
+  issue,
+  repo,
+  dryRun = false,
+  ghFn = gh,
+  write = (s) => {
+    process.stdout.write(s);
+  },
+}) {
   const repoArgs = repo ? ['--repo', repo] : [];
-  const raw = gh([
+  const raw = ghFn([
     'issue',
     'view',
     String(issue),
@@ -231,20 +239,14 @@ async function main() {
   ]);
   const { body, labels } = JSON.parse(raw);
   const labelNames = (labels ?? []).map((l) => l.name);
-  const isTicket =
-    labelNames.includes('type::story') || labelNames.includes('type::epic');
-
-  if (!isTicket) {
-    // Machine-parsable JSON envelope → process.stdout.write (not console.log),
-    // per the .agents/scripts logging contract (tests/enforcement/no-console).
-    process.stdout.write(
-      `${JSON.stringify({ issue: Number(issue), skipped: 'not-a-ticket' })}\n`,
-    );
-    return;
+  if (!isStoryTicket(labelNames)) {
+    const envelope = { issue: Number(issue), skipped: 'not-a-ticket' };
+    write(`${JSON.stringify(envelope)}\n`);
+    return envelope;
   }
 
   const verdict = evaluateIssueBody(body ?? '');
-  process.stdout.write(
+  write(
     `${JSON.stringify({
       issue: Number(issue),
       conformant: verdict.conformant,
@@ -252,10 +254,39 @@ async function main() {
     })}\n`,
   );
 
-  if (verdict.conformant || dryRun) return;
+  if (verdict.conformant || dryRun) {
+    return {
+      conformant: verdict.conformant,
+      problems: verdict.problems,
+    };
+  }
 
   const comment = renderConformanceComment(verdict);
-  gh(['issue', 'comment', String(issue), ...repoArgs, '--body', comment]);
+  ghFn(['issue', 'comment', String(issue), ...repoArgs, '--body', comment]);
+  return { conformant: false, problems: verdict.problems };
+}
+
+/**
+ * CLI entry. Reads the target issue (number from `--issue` or the
+ * `ISSUE_NUMBER` env), fetches its body + labels, and — when the body is
+ * non-conformant — upserts a single marker comment. Always exits 0 (the
+ * lint *informs*, it does not block), unless an unexpected I/O error occurs.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const issue = get('--issue') ?? process.env.ISSUE_NUMBER;
+  if (!issue) {
+    throw new Error('lint-issue-body: --issue <n> or ISSUE_NUMBER is required');
+  }
+  runLintIssueBody({
+    issue,
+    repo: get('--repo') ?? process.env.GITHUB_REPOSITORY,
+    dryRun: args.includes('--dry-run'),
+  });
 }
 
 runAsCli(import.meta.url, main, { source: 'lint-issue-body' });

package/.agents/scripts/mandrel-update-preflight.js

@@ -25,7 +25,7 @@
  *      friendlier "you're offline" signal before any version probe.
  *
  * Severity is consistent with framework preflight conventions
- * (cf. `story-close.js` runStoryClosePreflight, `epic-deliver-preflight.js`):
+ * (cf. `single-story-close.js` runStoryClosePreflight, `mandrel-update-preflight.js`):
  * the consumer-shape check is a hard stop (blocker), dirty-index and offline
  * are warn-only and never block the run.
  *