mandrel 1.91.0 → 1.92.0

package/.agents/scripts/lib/orchestration/plan-persist/summary.js

@@ -0,0 +1,191 @@
+/**
+ * summary.js — plan-persist terminal summary (Epic #4474, PR3).
+ *
+ * Owns the single `plan-summary` structured comment the collapsed persist
+ * surface upserts at terminal success, closing with the dry-run wave table.
+ * This replaces two retired round-trips of the 12-phase pipeline:
+ *
+ *   - the Phase 9 plan-time `dispatch-manifest` comment, whose claimed
+ *     consumer ("Wave Completeness Gate, /deliver Step 0.5") does not exist
+ *     — the live manifest is written at deliver time by `wave-record-io.js`
+ *     (#4474 design §3: DROP, keep the wave table as summary text only);
+ *   - the Phase 12 notify round-trip ("informational — no webhook for
+ *     planning").
+ *
+ * The wave table is computed from the validated ticket set's `depends_on`
+ * slug edges via the same `computeStoryWaves` layering the deliver-time
+ * dispatch pipeline uses, so the preview matches what `/deliver` will
+ * actually fan out (barring later manual ticket edits).
+ *
+ * @module lib/orchestration/plan-persist/summary
+ */
+
+import { computeStoryWaves } from '../dependency-analyzer.js';
+
+/**
+ * Structured-comment type for the persist summary. Registered in
+ * `ticketing/reads.js` `STRUCTURED_COMMENT_TYPES`; upsert-idempotent so a
+ * `--force`/`--resume` re-persist replaces the prior summary in place.
+ */
+export const PLAN_SUMMARY_COMMENT_TYPE = 'plan-summary';
+
+/**
+ * Compute the dry-run wave assignment for a validated ticket set.
+ *
+ * Adapts the slug-keyed ticket shape onto `computeStoryWaves`' storyGroups
+ * contract (slug → { storyId, tasks: [] }; explicit deps from `depends_on`).
+ * Under the 2-tier hierarchy Stories carry no tasks, so all edges are
+ * explicit.
+ *
+ * @param {Array<{ slug: string, title?: string, depends_on?: string[] }>} tickets
+ * @returns {Array<{ wave: number, stories: Array<{ slug: string, title: string }> }>}
+ *   Waves in execution order.
+ */
+export function buildWaveTable(tickets) {
+  const list = Array.isArray(tickets) ? tickets : [];
+  if (list.length === 0) return [];
+  const storyGroups = new Map();
+  const explicitDeps = new Map();
+  for (const t of list) {
+    storyGroups.set(t.slug, { storyId: t.slug, tasks: [] });
+    explicitDeps.set(
+      t.slug,
+      (t.depends_on ?? []).filter((dep) => typeof dep === 'string'),
+    );
+  }
+  const assignment = computeStoryWaves(storyGroups, explicitDeps);
+  const byWave = new Map();
+  for (const t of list) {
+    const wave = assignment.get(t.slug) ?? 0;
+    if (!byWave.has(wave)) byWave.set(wave, []);
+    byWave.get(wave).push({ slug: t.slug, title: t.title ?? t.slug });
+  }
+  return [...byWave.keys()]
+    .sort((a, b) => a - b)
+    .map((wave) => ({ wave, stories: byWave.get(wave) }));
+}
+
+/**
+ * Render the dry-run wave table as GitHub-flavoured markdown.
+ *
+ * @param {ReturnType<typeof buildWaveTable>} waveTable
+ * @returns {string[]} markdown lines
+ */
+function renderWaveTableLines(waveTable) {
+  if (!Array.isArray(waveTable) || waveTable.length === 0) {
+    return ['_No stories to wave (empty plan)._'];
+  }
+  const rows = waveTable.map(
+    ({ wave, stories }) =>
+      `| ${wave + 1} | ${stories.map((s) => `\`${s.slug}\``).join(', ')} |`,
+  );
+  return ['| Wave | Stories |', '| --- | --- |', ...rows];
+}
+
+/**
+ * Build the `plan-summary` structured-comment body: risk + routing +
+ * freshness + healthcheck receipts, closing with the mode-specific tail —
+ * the dry-run wave table for fan-out/amend, or the single-delivery routing
+ * record `{ deliveryShape, sliceCount, routingReasons }` (Epic #4474 PR4)
+ * for the spec-only mode.
+ *
+ * @param {{
+ *   epicId: number,
+ *   ticketCount: number,
+ *   planningRisk: { overallLevel?: string, gateDecision?: string },
+ *   reviewRouting: { decision?: string },
+ *   freshness?: { stale?: number, ambiguous?: number },
+ *   healthcheck?: { ok?: boolean, waived?: boolean, skipped?: boolean },
+ *   waveTable: ReturnType<typeof buildWaveTable>,
+ *   mode?: 'fan-out'|'single'|'amend',
+ *   planMetricsLine?: string|null,
+ *   single?: { deliveryShape: 'single', sliceCount: number|null, routingReasons: string[] }|null,
+ *   amend?: {
+ *     closed: Array<{ slug: string, issueNumber: number }>,
+ *     recreated: Array<{ slug: string, oldIssueNumber: number, issueNumber: number }>,
+ *     created: Array<{ slug: string, issueNumber: number }>,
+ *     keptCount: number,
+ *   }|null,
+ * }} input
+ * @returns {string}
+ */
+export function buildPlanSummaryCommentBody({
+  epicId,
+  ticketCount,
+  planningRisk,
+  reviewRouting,
+  freshness,
+  healthcheck,
+  waveTable,
+  mode = 'fan-out',
+  planMetricsLine = null,
+  single = null,
+  amend = null,
+}) {
+  const freshnessLine =
+    (freshness?.stale ?? 0) > 0 || (freshness?.ambiguous ?? 0) > 0
+      ? `- ⚠️ Spec freshness: ${freshness.stale} stale / ${freshness.ambiguous} ambiguous reference(s) — see the spec-freshness comment.`
+      : '- Spec freshness: clean.';
+  const healthcheckLine = healthcheck?.skipped
+    ? '- Healthcheck: skipped (test seam).'
+    : healthcheck?.ok
+      ? '- Healthcheck: passed.'
+      : `- Healthcheck: failed, waived by operator label.`;
+
+  const headLine =
+    mode === 'single'
+      ? `- Single-delivery plan (\`delivery::single\`): no Story tree — the Delivery Slicing table is the audit trail.`
+      : `- ${ticketCount} Story ticket(s) persisted across ${waveTable.length} wave(s).`;
+
+  const amendLines = amend
+    ? [
+        `- Amend delta: ${amend.created.length} added, ${amend.recreated.length} modified (closed + recreated), ${amend.closed.length} closed, ${amend.keptCount} kept untouched.`,
+      ]
+    : [];
+
+  const tail =
+    mode === 'single'
+      ? [
+          '#### Delivery routing record',
+          '',
+          '```json',
+          JSON.stringify(
+            {
+              deliveryShape: 'single',
+              sliceCount: single?.sliceCount ?? null,
+              routingReasons: single?.routingReasons ?? [],
+            },
+            null,
+            2,
+          ),
+          '```',
+          '',
+          '_Marker is inert until #4475 lands the deliver-side reader — `/deliver` still treats this Epic as fan-out until then._',
+        ]
+      : [
+          '#### Dry-run wave table',
+          '',
+          ...renderWaveTableLines(waveTable),
+          '',
+          '_Preview only — the authoritative dispatch manifest is written at deliver time (`wave-record-io.js`)._',
+        ];
+
+  return [
+    `### 📋 Plan Summary — Epic #${epicId} is \`agent::ready\``,
+    '',
+    headLine,
+    ...amendLines,
+    `- Risk: ${planningRisk?.overallLevel ?? 'unknown'} · ${planningRisk?.gateDecision ?? 'unknown'} (review routing: ${reviewRouting?.decision ?? 'unknown'}).`,
+    freshnessLine,
+    healthcheckLine,
+    // G2 measurement receipt (Epic #4474 PR1/PR7): the plan-CLI invocation
+    // ledger roll-up (turns-per-plan proxy, per-mode counts, critic skips)
+    // rides the summary comment so the cohort reader never has to pull the
+    // temp ledger off the runner's disk. Omitted when the ledger is empty.
+    ...(typeof planMetricsLine === 'string' && planMetricsLine.length > 0
+      ? [`- ${planMetricsLine}`]
+      : []),
+    '',
+    ...tail,
+  ].join('\n');
+}

package/.agents/scripts/lib/orchestration/plan-reachability.js

@@ -0,0 +1,160 @@
+/**
+ * plan-reachability.js — deterministic draft-ticket reachability check for
+ * the persist surface (Epic #4474 PR6, design §4: the 8.4 reachability
+ * critic demoted from a fresh-context sub-agent to a persist-side scan).
+ *
+ * Mirrors the mechanics of the existing `--paranoid` F7 healthcheck
+ * (`epic-plan-healthcheck.js#checkReachability`) — route-glob scan of the
+ * paths a Story declares vs the `planning.navigation.navRegistry` token
+ * list — but runs it over the **draft** ticket set inside `plan-persist.js`
+ * step 4.5, before any provider call, so an orphaned surface is caught
+ * while a one-line targeted amend is still free (nothing has been written
+ * to GitHub yet).
+ *
+ * Plan-level coverage semantics (the convergence contract): a route-adding
+ * story that never references the nav registry produces orphan surfaces —
+ * UNLESS every one of its route paths is also mentioned by some story in
+ * the plan that DOES reference the registry (the "navigation owner"). That
+ * is exactly what the documented recovery produces: the author appends the
+ * single reachability Story (which cites the orphaned routes and the nav
+ * registry) in one targeted amend, and the re-run persist passes.
+ *
+ * Silent no-op when `planning.navigation` is unconfigured (`routeGlobs`
+ * empty) — same opt-in contract as F7 / AC-13 — reported as
+ * `status: 'skipped'` so the caller can append the audit record to the
+ * plan-metrics ledger.
+ *
+ * Pure over its inputs (tickets + resolved config), no I/O.
+ */
+
+import {
+  extractStoryPaths,
+  globToRegExp,
+  resolveNavConfig,
+} from '../../epic-plan-healthcheck.js';
+
+/**
+ * Fallback tokens when `navRegistry` is unconfigured but `routeGlobs` is —
+ * identical to the F7 healthcheck's fallback, so the two checks agree on
+ * what counts as a registry reference.
+ */
+const FALLBACK_REGISTRY_TOKENS = ['nav registry', 'navigation'];
+
+/**
+ * @typedef {Object} ReachabilityOrphan
+ * @property {string} story The offending draft story's slug (or title).
+ * @property {string[]} paths The route-matching paths with no navigation
+ *   owner anywhere in the plan.
+ */
+
+/**
+ * @typedef {Object} DraftReachabilityResult
+ * @property {'skipped'|'ok'|'orphans'} status
+ * @property {string[]} reasons
+ * @property {ReachabilityOrphan[]} orphans Empty unless `status` is
+ *   `'orphans'`.
+ * @property {number} scanned Draft stories scanned (0 when skipped).
+ */
+
+/**
+ * Evaluate draft-ticket reachability against the configured navigation
+ * surface.
+ *
+ * @param {object} input
+ * @param {Array<{ slug?: string, title?: string, body?: string }>} input.tickets
+ *   The draft ticket set the persist is about to create (fan-out: the
+ *   authored `tickets.json`; amend: the merged set).
+ * @param {object} [input.config] Resolved `.agentrc.json` (threads
+ *   `planning.navigation`).
+ * @returns {DraftReachabilityResult}
+ */
+export function evaluateDraftReachability({ tickets, config }) {
+  const { routeGlobs, navRegistry } = resolveNavConfig(config);
+
+  if (routeGlobs.length === 0) {
+    return {
+      status: 'skipped',
+      reasons: ['No planning.navigation.routeGlobs configured — skipped.'],
+      orphans: [],
+      scanned: 0,
+    };
+  }
+
+  const stories = Array.isArray(tickets) ? tickets : [];
+  const matchers = routeGlobs.map(globToRegExp);
+  const registryTokens =
+    navRegistry.length > 0
+      ? navRegistry.map((t) => t.toLowerCase())
+      : FALLBACK_REGISTRY_TOKENS;
+
+  // Pass 1: per-story scan — declared paths, route matches, registry refs.
+  const scannedStories = stories.map((story) => {
+    const body = typeof story?.body === 'string' ? story.body : '';
+    const paths = extractStoryPaths(body);
+    const routePaths = paths.filter((p) => matchers.some((rx) => rx.test(p)));
+    const text = [body, story?.title ?? ''].join('\n').toLowerCase();
+    const referencesRegistry = registryTokens.some((tok) => text.includes(tok));
+    return { story, paths, routePaths, referencesRegistry };
+  });
+
+  // Pass 2: navigation owners — every path mentioned by a
+  // registry-referencing story is covered plan-wide.
+  const coveredPaths = new Set();
+  for (const s of scannedStories) {
+    if (!s.referencesRegistry) continue;
+    for (const p of s.paths) coveredPaths.add(p);
+  }
+
+  const orphans = [];
+  for (const s of scannedStories) {
+    if (s.referencesRegistry || s.routePaths.length === 0) continue;
+    const uncovered = s.routePaths.filter((p) => !coveredPaths.has(p));
+    if (uncovered.length === 0) continue;
+    orphans.push({
+      story: s.story?.slug ?? s.story?.title ?? '<unnamed story>',
+      paths: uncovered,
+    });
+  }
+
+  if (orphans.length > 0) {
+    const registryHint =
+      navRegistry.length > 0 ? navRegistry.join(', ') : 'the nav registry';
+    return {
+      status: 'orphans',
+      reasons: [
+        `${orphans.length} route-adding draft story(ies) leave orphan surfaces with no navigation owner (registry: ${registryHint}).`,
+      ],
+      orphans,
+      scanned: stories.length,
+    };
+  }
+
+  return {
+    status: 'ok',
+    reasons: [
+      `${stories.length} draft story(ies) scanned — every route-adding story has a navigation owner.`,
+    ],
+    orphans: [],
+    scanned: stories.length,
+  };
+}
+
+/**
+ * Render the named soft-failure message the persist CLI prints — the
+ * orphan-surface list plus the one-targeted-amend recovery contract.
+ *
+ * @param {DraftReachabilityResult} result A `status: 'orphans'` result.
+ * @returns {string}
+ */
+export function renderReachabilityOrphans(result) {
+  const lines = [
+    '[plan-persist] SOFT FAILURE — reachability orphans (route-glob vs navRegistry):',
+    ...result.orphans.map((o) => `  - ${o.story}: ${o.paths.join(', ')}`),
+    '',
+    'Nothing was written to GitHub. Apply ONE targeted amend to tickets.json',
+    'adding a navigation owner (at most one reachability Story per plan) that',
+    'cites the orphaned routes and the nav registry, then re-run the persist',
+    'once.',
+  ];
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -1,9 +1,9 @@
 /**
  * plan-runner/worktree-sweep.js
  *
- * Reap-sweep used at the start of `/epic-plan-spec` and
- * `/epic-plan-decompose` (via `drainPendingCleanupAtBoot` in
- * `epic-plan-spec.js`, which see). Iterates the `.worktrees/story-<id>/`
+ * Reap-sweep run at plan boot (via `drainPendingCleanupAtBoot` in
+ * `lib/orchestration/epic-plan-spec/phases/drain.js`, wired into
+ * `plan-persist.js`). Iterates the `.worktrees/story-<id>/`
  * entries registered with git, looks up each parent Story, and force-removes
  * any whose Story is already closed or labeled `agent::done`.
  *

package/.agents/scripts/lib/orchestration/planning-risk.js

@@ -138,7 +138,7 @@ function resolveRequiresReview(overallLevel, axes) {
 /**
  * Derive the stable planningRisk envelope from a schema-validated planner
  * verdict. Pure derivation — schema validation happens at the read boundary
- * (`epic-plan-spec.js`), never here, so a malformed verdict fails closed
+ * (`plan-persist.js` via `loadRiskVerdict`), never here, so a malformed verdict fails closed
  * before this function runs.
  *
  * **No-BDD-runner waiver (Story #4145).** The acceptance disposition the risk

package/.agents/scripts/lib/orchestration/spec-freshness.js

@@ -10,7 +10,7 @@
  *
  * `validateSpecFreshness` scans a Tech Spec body for path-shaped references,
  * probes each against `baseBranchRef` (via `git cat-file -e`), and returns a
- * `{ stale, fresh, ambiguous }` envelope. The caller (epic-plan-spec.js)
+ * `{ stale, fresh, ambiguous }` envelope. The caller (plan-persist.js)
  * uses the result to write a JSON report and post an advisory structured
  * comment on the Epic. The check is intentionally non-blocking —
  * planning continues even when stale references are present, because the

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -33,7 +33,7 @@ import {
  * 5xx, transport timeouts) inside the cascade transition. Three attempts with
  * exponential backoff (250ms / 500ms / 1000ms) mirrors the budget used by
  * `gitFetchWithRetry` (see `lib/git-utils.js`) and the HTTP-client retry path
- * referenced by `epic-plan-decompose.js`. Backoff is overridable via
+ * referenced by the plan persist surface. Backoff is overridable via
  * {@link __setCascadeRetryDelays} so tests don't pay real wall-clock time.
  */
 const CASCADE_RETRY_BACKOFF_MS = [250, 500, 1000];

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -102,7 +102,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // a `clarity-gate-update` comment on the Epic when the operator approves
   // a sharpened body rewrite, recording the persistence event for audit.
   'clarity-gate-update',
-  // Story #2635 — Phase 7 Tech Spec freshness check. `epic-plan-spec.js`
+  // Story #2635 — Tech Spec freshness check. `plan-persist.js`
   // upserts a `spec-freshness` comment on the Epic listing any
   // path-shaped references that don't exist at the base branch, so the
   // operator can correct drift before Phase 8 decomposes from a stale
@@ -147,7 +147,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // the documented remediation actually executable
   // (assertValidStructuredCommentType would otherwise throw).
   'wave-stall',
-  // Story #3873 (Epic #3865) — `epic-plan-spec.js` upserts a `risk-verdict`
+  // Story #3873 (Epic #3865) — `plan-persist.js` upserts a `risk-verdict`
   // comment on the Epic at persist time, recording the planner-authored,
   // schema-validated risk verdict and the planningRisk envelope derived
   // from it (`deriveRiskEnvelope`). One entry per Epic; re-plans upsert in
@@ -171,6 +171,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="audit-results|code-review"` attr so the two graduators
   // upsert independent comments; re-runs upsert in place.
   'cross-repo-deferred',
+  // Epic #4474 (PR3) — `plan-persist.js` upserts a single `plan-summary`
+  // comment on the Epic at terminal persist success, carrying the risk /
+  // routing / freshness / healthcheck receipts and the dry-run wave table
+  // as closing text. Replaces the retired plan-time `dispatch-manifest`
+  // comment (whose claimed consumer did not exist — the live manifest is
+  // written at deliver time by `wave-record-io.js`) and the Phase 12
+  // notify round-trip. One entry per Epic; a --force/--resume re-persist
+  // upserts in place.
+  'plan-summary',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;

package/.agents/scripts/lib/plan-phase-cleanup.js

@@ -41,6 +41,22 @@ export const PHASE_TEMP_BASENAMES = Object.freeze({
     'acceptance-spec.md',
   ]),
   decompose: Object.freeze(['decomposer-context.json', 'tickets.json']),
+  // Epic #4474 (PR3) — the collapsed `plan-persist.js` surface owns every
+  // plan-phase artifact and deletes them ONLY at terminal success (after
+  // the `agent::ready` flip), fixing the mid-pipeline deletion defect where
+  // per-phase cleanup removed artifacts a `--force`/`--resume` re-persist
+  // was still entitled to reuse. `risk-verdict.json` joins the set here:
+  // the split-phase cleanup never owned it, which orphaned it in temp/.
+  // `plan-metrics.json` stays deliberately excluded (PR1) — the ledger
+  // must survive cleanup so the whole plan run is visible in one stream.
+  persist: Object.freeze([
+    'planner-context.json',
+    'techspec.md',
+    'acceptance-spec.md',
+    'risk-verdict.json',
+    'decomposer-context.json',
+    'tickets.json',
+  ]),
 });
 
 /**

package/.agents/scripts/lib/presentation/manifest-persistence.js

@@ -120,10 +120,9 @@ export function deleteLegacyFlatManifest(epicId, opts = {}) {
  * Atomic write-then-rename. On any failure, best-effort remove the `.tmp`
  * file and rethrow so the caller can surface a structured result.
  *
- * Exported so other writers (e.g. `render-manifest.js`) can route their
- * `.md` / `.json` artefact writes through the same crash-safe primitive.
+ * Internal crash-safe write primitive for the manifest artefact pair.
  */
-export function atomicWrite(finalPath, content) {
+function atomicWrite(finalPath, content) {
   const tmpPath = `${finalPath}.tmp`;
   try {
     fs.writeFileSync(tmpPath, content, 'utf8');

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

@@ -0,0 +1,74 @@
+/**
+ * spec-author-prompts.js — single source of the Tech Spec and Acceptance
+ * Spec authoring system prompts (Epic #4474, M3 PR2).
+ *
+ * **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.
+ */
+
+/**
+ * The Tech Spec authoring system prompt (verbatim from the
+ * `epic-plan-spec-author` SKILL's authoritative block).
+ *
+ * @returns {string}
+ */
+export function renderTechSpecSystemPrompt() {
+  return TECH_SPEC_SYSTEM_PROMPT;
+}
+
+/**
+ * The Acceptance Spec authoring system prompt (verbatim from the
+ * `epic-plan-spec-author` SKILL's authoritative block).
+ *
+ * @returns {string}
+ */
+export function renderAcceptanceSpecSystemPrompt() {
+  return ACCEPTANCE_SPEC_SYSTEM_PROMPT;
+}
+
+const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
+Your job is to convert an Epic into a Technical Specification for implementation.
+
+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
+
+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.
+- 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.`;
+
+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.
+
+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
+
+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.
+
+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.`;