mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/templates/spec-author-prompts.js

@@ -1,23 +1,14 @@
 /**
- * spec-author-prompts.js — single source of the Tech Spec and Acceptance
- * Spec authoring system prompts (Epic #4474, M3 PR2).
+ * spec-author-prompts.js — Story-scoped Spec / Acceptance authoring prompts.
  *
- * **Single source of the prompt bodies.** These two prompts were lifted
- * VERBATIM from the "(authoritative)" fenced blocks in
- * `.agents/skills/core/epic-plan-spec-author/SKILL.md` (§ "Tech Spec system
- * prompt" and § "Acceptance Spec system prompt") as the M3 side of the
- * M3/M8 boundary handshake: the `plan-context.js` envelope renders them
- * into `systemPrompts.spec` / `systemPrompts.acceptance` so the envelope
- * is authoritative from day one, and M8 (#4479) then deletes the
- * skill-side copies. This mirrors the Story #4162 pattern established by
- * `decomposer-prompts.js` for the decompose prompt: one rendered carrier,
- * no second verbatim copy to drift.
+ * v2 keeps a single executable document per Story. These prompts used to
+ * author a separate Epic Tech Spec + Acceptance Spec that were folded into
+ * the Epic body and then restated on Stories — a duplication source. They
+ * now author only Story `## Spec` approach prose and remind authors that
+ * acceptance lives once on the Story (`acceptance[]` / `## Acceptance`).
  */
 
 /**
- * The Tech Spec authoring system prompt (verbatim from the
- * `epic-plan-spec-author` SKILL's authoritative block).
- *
  * @returns {string}
  */
 export function renderTechSpecSystemPrompt() {
@@ -25,9 +16,6 @@ export function renderTechSpecSystemPrompt() {
 }
 
 /**
- * The Acceptance Spec authoring system prompt (verbatim from the
- * `epic-plan-spec-author` SKILL's authoritative block).
- *
  * @returns {string}
  */
 export function renderAcceptanceSpecSystemPrompt() {
@@ -35,40 +23,54 @@ export function renderAcceptanceSpecSystemPrompt() {
 }
 
 const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
-Your job is to convert an Epic into a Technical Specification for implementation.
+Your job is to author the Story's \`## Spec\` approach section — the technical
+how for one cohesive, executable Story. There is no separate Epic Tech Spec
+document and no spill-to-docs path.
 
-The Tech Spec should outline:
-1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
-2. Architecture & Design
-3. Data Models (if any)
-4. API Changes (if any)
-5. Core Components
-6. Security & Privacy Considerations
+The Spec should outline only what an implementing agent needs beyond Goal /
+Changes / Acceptance:
+1. Architecture & Design (approach, seams, reuse)
+2. Data Models (if any)
+3. API Changes (if any)
+4. Core Components
+5. Security & Privacy Considerations
 
 CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Open the document with the \`## Delivery Slicing\` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
-- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional \`## Technical Overview\` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
+- Respond ONLY with valid Markdown suitable to paste into a Story \`## Spec\`.
+- Do not use top-level <h1> (# ) tags. Prefer \`##\` / \`###\` under Spec.
+- Do NOT restate the Story's Goal, Acceptance, Verify, Changes, or Non-Goals —
+  those sections already live on the same Story body. Restatement is
+  duplication and a drift risk. If a brief orientation helps, keep a
+  \`## Technical Overview\` to 2–3 sentences naming the technical approach only.
+- Do NOT author a Delivery Slicing / fan-out table. If the work needs multiple
+  independent Stories, say so in one short note and stop — oversized Specs
+  mean the Story should be split, not documented elsewhere.
 - Format architectural decisions clearly with bullet points.
-- Author the \`## Delivery Slicing\` section as a markdown table with columns \`Slice | What ships | Independent?\`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.`;
+- Keep the Spec lean enough to stay inline on the Story (persist rejects
+  over-budget Specs; they are never written under docs/).`;
 
 const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
-Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+Your job is to help author the Story's binding acceptance contract — not a
+separate Acceptance Spec document.
 
-The Acceptance Spec should outline:
-1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
-2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
-3. Disposition — tag each row with one of: new | updated | unchanged
+v2 rule: acceptance lives **once**, on the Story:
+- Machine contract: top-level \`acceptance[]\` (and \`verify[]\`) on the ticket JSON
+- Human document: the same items rendered under \`## Acceptance\` / \`## Verify\`
+  on the Story body (persist syncs top-level into the body)
 
-The Epic body's \`## Acceptance Criteria\` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
+Do **not** author an Epic Acceptance Table, PRD restatement, or a second
+criteria list inside \`## Spec\`.
 
 CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
-- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
-- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
-- Each Outcome MUST be a **terse restatement keyed to a specific Epic \`## Acceptance Criteria\` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
-- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
-- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
-- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.
-- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy \`baseline-refresh\` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (\`ticket-validator.js\` → \`validateAcceptanceSubjectPrefix\`) will reject the decompose with \`code: 'forbidden-subject-prefix'\`. Use a Conventional-Commits subject (e.g. \`chore(baselines): refresh ...\`) and a body trailer (e.g. \`baseline-refresh: true\` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.`;
+- Respond ONLY with guidance or a draft \`acceptance[]\` / \`verify[]\` list for
+  one Story — never a parallel "Acceptance Spec" markdown artifact.
+- Every acceptance item MUST be observable from outside the agent (command
+  exits 0, file exists, selector resolves, fixture count matches). Reject
+  vague "matches the spec" / "looks good" items.
+- Every verify entry MUST name a tier in parentheses: unit | contract | e2e |
+  validate (or \`manual:<reason>\` when genuinely unverifiable in isolation).
+- Do NOT re-elaborate Goal or Spec prose inside acceptance items — bind the
+  outcome, not the approach.
+- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a
+  non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|
+  refactor|perf|docs|style|test|build|ci|revert).`;

package/.agents/scripts/lib/{epic-body-sections.js → ticket-body-sections.js}

@@ -1,19 +1,19 @@
 /**
- * epic-body-sections.js — marker-delimited managed sections of the Epic body.
+ * ticket-body-sections.js — marker-delimited managed sections of a
+ * planning ticket body.
  *
  * Story #4324 retired the `context::tech-spec` / `context::acceptance-spec`
- * ticket classes: the Epic body is now the single planning document. The
- * Tech Spec (opening with `## Delivery Slicing`, per #4316) and the
- * Acceptance Spec's AC-ID table (`## Acceptance Table`, Outcomes keyed to
- * Epic AC bullets per #4315) land as **managed sections** of the Epic body,
- * delimited by invisible HTML comment markers so each writer can update
- * *only its own region* without rewriting the rest of the body.
+ * ticket classes: the planning ticket body is the single planning document.
+ * The Tech Spec (opening with `## Delivery Slicing`, per #4316) and the
+ * Acceptance Spec's AC-ID table (`## Acceptance Table`) land as **managed
+ * sections**, delimited by invisible HTML comment markers so each writer
+ * can update *only its own region* without rewriting the rest of the body.
  *
  * Section-scoped writes are the load-bearing contract (extending the
  * single-writer discipline #4303 established for the body trailer):
  *
- *   - The Phase 7 spec persist path (`epic-plan-spec/phases/plan-epic.js`)
- *     upserts the `techSpec` and `acceptanceTable` regions.
+ *   - The `/plan` persist path upserts the `techSpec` and `acceptanceTable`
+ *     regions.
  *   - The close-time acceptance reconciler
  *     (`acceptance-spec-reconciler.js`) reads and rewrites the
  *     `acceptanceTable` region only (verification dispositions).
@@ -32,7 +32,7 @@
  *
  * @type {Readonly<Record<'techSpec'|'acceptanceTable', { start: string, end: string, label: string }>>}
  */
-export const EPIC_BODY_SECTIONS = Object.freeze({
+export const TICKET_BODY_SECTIONS = Object.freeze({
   techSpec: Object.freeze({
     start: '<!-- mandrel:tech-spec:start -->',
     end: '<!-- mandrel:tech-spec:end -->',
@@ -47,7 +47,7 @@ export const EPIC_BODY_SECTIONS = Object.freeze({
 
 /**
  * Canonical heading the acceptance-table region opens with. Distinct from
- * the Epic's ideation `## Acceptance Criteria` bullets (which remain the
+ * the ticket's ideation `## Acceptance Criteria` bullets (which remain the
  * SSOT for *what* the table verifies — the table anchors to those bullets).
  */
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
@@ -56,7 +56,7 @@ export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
  * Regex matching the Tech Spec's required opening heading (same variants
  * `spec-section-validator.js` accepts). Exported so it is the single
  * source of truth for this pattern — `spec-section-validator.js`,
- * `epic-plan-clarity.js`, and `consolidation-precondition.js` all import
+ * `consolidation-precondition.js` all import
  * it rather than each carrying their own copy.
  */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
@@ -66,10 +66,10 @@ export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
  * @returns {{ start: string, end: string, label: string }}
  */
 function descriptor(kind) {
-  const d = EPIC_BODY_SECTIONS[kind];
+  const d = TICKET_BODY_SECTIONS[kind];
   if (!d) {
     throw new TypeError(
-      `epic-body-sections: unknown section kind "${kind}" (expected ${Object.keys(EPIC_BODY_SECTIONS).join(' | ')})`,
+      `ticket-body-sections: unknown section kind "${kind}" (expected ${Object.keys(TICKET_BODY_SECTIONS).join(' | ')})`,
     );
   }
   return d;
@@ -103,7 +103,7 @@ function locate(body, kind) {
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {boolean}
  */
-export function hasEpicSection(body, kind) {
+export function hasTicketSection(body, kind) {
   return locate(body, kind) !== null;
 }
 
@@ -115,7 +115,7 @@ export function hasEpicSection(body, kind) {
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {string|null}
  */
-export function extractEpicSection(body, kind) {
+export function extractTicketSection(body, kind) {
   const loc = locate(body, kind);
   if (!loc) return null;
   return body.slice(loc.contentStart, loc.contentEnd).trim();
@@ -136,7 +136,7 @@ export function extractEpicSection(body, kind) {
  * @param {string} content Section content (headings included).
  * @returns {string}
  */
-export function upsertEpicSection(body, kind, content) {
+export function upsertTicketSection(body, kind, content) {
   const { start, end } = descriptor(kind);
   const safeBody = typeof body === 'string' ? body : '';
   const trimmedContent = typeof content === 'string' ? content.trim() : '';
@@ -179,7 +179,7 @@ export function upsertEpicSection(body, kind, content) {
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {string}
  */
-export function stripEpicSection(body, kind) {
+export function stripTicketSection(body, kind) {
   const { end } = descriptor(kind);
   const loc = locate(body, kind);
   if (!loc) return typeof body === 'string' ? body : '';
@@ -189,7 +189,7 @@ export function stripEpicSection(body, kind) {
 }
 
 /**
- * Re-plan / decompose detection: true when the Epic body carries folded
+ * Re-plan / decompose detection: true when the ticket body carries folded
  * Tech Spec content — the managed region, or (defence in depth for a
  * hand-authored body) a bare `## Delivery Slicing` heading.
  *
@@ -197,7 +197,7 @@ export function stripEpicSection(body, kind) {
  * @returns {boolean}
  */
 export function hasTechSpecContent(body) {
-  if (hasEpicSection(body, 'techSpec')) return true;
+  if (hasTicketSection(body, 'techSpec')) return true;
   return typeof body === 'string' && DELIVERY_SLICING_RE.test(body);
 }
 
@@ -217,9 +217,9 @@ const DELIVERY_DROP_HEADINGS = new Set([
 ]);
 
 /**
- * Slice an Epic body down to the sections a delivery story agent acts on.
+ * Slice a planning ticket body down to the sections a delivery story agent acts on.
  *
- * KEEP: the Epic title / preamble before the first `##`, `## Goal`,
+ * KEEP: the ticket title / preamble before the first `##`, `## Goal`,
  * `## Non-Goals`, `## User Stories`, the `techSpec` managed region, and —
  * fail-open — any unknown / operator-authored `##` section not in the drop
  * list. DROP: `## Context`, `## Scope`, `## Acceptance Criteria`, and the
@@ -236,12 +236,12 @@ const DELIVERY_DROP_HEADINGS = new Set([
  * @param {string} body
  * @returns {string}
  */
-export function sliceEpicBodyForDelivery(body) {
+export function sliceTicketBodyForDelivery(body) {
   if (typeof body !== 'string' || body.length === 0) return '';
 
   // 1. Drop the acceptance-table managed region outright (authoring/close
   //    machinery, never delivery context).
-  let working = stripEpicSection(body, 'acceptanceTable');
+  let working = stripTicketSection(body, 'acceptanceTable');
 
   // 2. Protect the techSpec managed region from heading-boundary slicing by
   //    lifting it out behind an opaque placeholder, then restoring it after
@@ -261,7 +261,7 @@ export function sliceEpicBodyForDelivery(body) {
 
   // 3. Slice plain `##` sections by heading boundaries, dropping only the
   //    known ideation/authoring headings. The preamble before the first
-  //    `##` (Epic title / lede) is always kept.
+  //    `##` (ticket title / lede) is always kept.
   const kept = [];
   let dropping = false;
   for (const line of working.split('\n')) {
@@ -291,7 +291,7 @@ export function sliceEpicBodyForDelivery(body) {
 
 /**
  * Strip the retired machine-managed `## Planning Artifacts` checklist from
- * an Epic body (the section that linked the now-retired context tickets).
+ * a planning ticket body (the section that linked the now-retired context tickets).
  * The slice ends at the next `## ` heading, a managed-region marker, or
  * EOF. Historical bodies without the section pass through untouched.
  *

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

@@ -336,7 +336,7 @@ 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.
  *

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

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/reap.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,7 +65,7 @@ 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);
@@ -483,7 +481,7 @@ function checkReapPreconditions(ctx, _storyId, opts, wtPath) {
 
 async function ensureSafeOrForceDiscard(ctx, storyId, wtPath, opts) {
   const safety = await isSafeToRemove(ctx, wtPath, {
-    epicRef: opts.epicBranch ?? opts.epicRef ?? null,
+    epicBranch: opts.epicBranch ?? null,
   });
   if (safety.safe) return { ok: true, discardedPaths: null };
 

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.
  *

package/.agents/scripts/notify.js

@@ -33,7 +33,8 @@
  *      (% progress + blockers), not the firehose of per-story transitions;
  *      the default allowlist is the five `epic-*` events. Payload envelope:
  *      `{ text, severity, event?, level?, ticketId?, epicId?, phase? }` —
- *      `text` always populated for back-compat with `{text}`-only consumers.
+ *      `text` is the primary human-readable body (Slack-style incoming
+ *      webhooks read this field).
  *
  * Each channel filters independently — no fallback chain. Severity is
  * carried as envelope metadata (so Slack consumers can color-code by it
@@ -93,8 +94,8 @@ function buildWebhookPayload({
       : '';
   const text = `${prefix}${ticketPart}: ${cleanMessage}`;
 
-  // `text` first for back-compat with `{text}`-only consumers (Slack-style
-  // incoming webhooks). Typed fields follow for routable subscribers.
+  // `text` is the primary human-readable body; typed fields follow for
+  // routable subscribers.
   const envelope = { text, severity };
   if (Number.isFinite(numericTicketId) && numericTicketId > 0) {
     envelope.ticketId = numericTicketId;