mandrel 1.80.0 → 1.82.0

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/plan-epic.js

@@ -1,25 +1,39 @@
 /**
- * phases/plan-epic.js — PRD / Tech Spec / Acceptance Spec persistence phase.
+ * phases/plan-epic.js — Tech Spec / Acceptance Table persistence phase.
  *
- * Heals any prior planning artifacts (PRD / Tech Spec issues, "Planning
- * Artifacts" body section, lifecycle labels) before writing the new issues.
- * Idempotent against partial state: when the Epic already has a PRD but no
- * Tech Spec, the existing PRD is reused. Pass `force: true` to re-plan: the
- * canonical context tickets (PRD / Tech Spec / Acceptance Spec) are
- * **overwritten in place** — same issue numbers, refreshed bodies, kept open,
- * with a one-line regeneration audit comment on each. Only redundant
- * duplicate artifacts are closed; Feature/Story child tickets retain
- * close-and-recreate behaviour (handled by the decomposer, not here).
+ * Story #4324: the `context::tech-spec` / `context::acceptance-spec` ticket
+ * classes are retired. The Epic body is the single planning document: this
+ * phase upserts the authored Tech Spec (opening with `## Delivery Slicing`)
+ * and the Acceptance Spec's AC-ID table (`## Acceptance Table`) as
+ * marker-delimited managed sections of the Epic body — see
+ * `lib/epic-body-sections.js`. Each write is **section-scoped**: only the
+ * managed region is replaced; the rest of the body is byte-preserved.
+ *
+ * Idempotent against partial state: when the Epic body already carries all
+ * requested sections, the phase short-circuits with `already-planned`.
+ * Pass `force: true` to re-plan: the managed sections are overwritten in
+ * place and a one-line regeneration audit comment lands on the Epic.
+ *
+ * The retired machine-managed `## Planning Artifacts` checklist (which
+ * linked the old context tickets) is stripped on every persist so a
+ * re-planned historical Epic stops advertising stale ticket links; the
+ * legacy tickets themselves are ignored (forward-only cutover — no
+ * backfill, no fetch).
  */
 
+import {
+  hasEpicSection,
+  stripEpicSection,
+  stripPlanningArtifactsSection,
+  upsertEpicSection,
+} from '../../../epic-body-sections.js';
 import { Logger } from '../../../Logger.js';
 import { ACCEPTANCE_NA } from '../../../label-constants.js';
-import { PlanningStateManager } from '../../planning-state-manager.js';
 
 /**
- * Resolve whether Phase 7 should persist an acceptance-spec ticket or apply
- * the `acceptance::n-a` waiver, from the planningRisk envelope derived off
- * the planner-authored risk verdict (`deriveRiskEnvelope`, Epic #3865).
+ * Resolve whether Phase 7 should persist an acceptance-table section or
+ * apply the `acceptance::n-a` waiver, from the planningRisk envelope derived
+ * off the planner-authored risk verdict (`deriveRiskEnvelope`, Epic #3865).
  *
  * @param {import('../../planning-risk.js').PlanningRiskEnvelope|null} planningRisk
  *   Derived envelope; `null` (direct invocations without a verdict) never
@@ -50,52 +64,10 @@ export function resolveAcceptancePersistence(
   };
 }
 
-/**
- * Overwrite an existing context ticket (PRD / Tech Spec / Acceptance Spec)
- * in place: push the freshly-authored body and refresh the title prefix so a
- * clarity-gate Epic rename does not strand a stale spec title, then post a
- * single one-line regeneration audit comment so the preserved discussion
- * history stays self-explanatory.
- *
- * The ticket keeps its issue number, its sub-issue link to the Epic, and all
- * pre-existing comments — only the body, title, and a new audit comment are
- * added.
- *
- * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
- * @param {number} ticketId           Existing context-ticket issue number.
- * @param {{ title: string, body: string, artifact: string }} fields
- *   `title` is the refreshed `[PRD] <epic title>`-style prefix; `body` is the
- *   regenerated content; `artifact` is the human label used in the audit
- *   comment (`PRD`, `Tech Spec`, `Acceptance Spec`).
- * @returns {Promise<void>}
- */
-export async function overwriteContextTicket(
-  provider,
-  ticketId,
-  { title, body, artifact },
-) {
-  await provider.updateTicket(ticketId, { title, body });
-  try {
-    await provider.postComment(ticketId, {
-      type: 'notification',
-      body: `♻️ **Regeneration Audit**: This ${artifact} body was regenerated in place by a \`/plan --force\` re-plan. The issue number and prior discussion history are preserved.`,
-    });
-  } catch (_err) {
-    // Audit comment is best-effort — never fail the overwrite on a comment
-    // post error.
-  }
-}
-
 export function validatePlanEpicInputs({
-  prdContent,
   techSpecContent,
   acceptanceSpecContent,
 }) {
-  if (typeof prdContent !== 'string' || prdContent.trim() === '') {
-    throw new Error(
-      '[Epic Planner] prdContent is required and must be non-empty.',
-    );
-  }
   if (typeof techSpecContent !== 'string' || techSpecContent.trim() === '') {
     throw new Error(
       '[Epic Planner] techSpecContent is required and must be non-empty.',
@@ -112,184 +84,46 @@ export function validatePlanEpicInputs({
   }
 }
 
-export function getExistingArtifactIds(epic) {
+/**
+ * Snapshot which managed planning sections the Epic body already carries.
+ *
+ * @param {{ body?: string }} epic
+ * @returns {{ techSpec: boolean, acceptanceTable: boolean }}
+ */
+export function getExistingSections(epic) {
+  const body = epic?.body ?? '';
   return {
-    prd: epic.linkedIssues?.prd ?? null,
-    techSpec: epic.linkedIssues?.techSpec ?? null,
-    acceptanceSpec: epic.linkedIssues?.acceptanceSpec ?? null,
+    techSpec: hasEpicSection(body, 'techSpec'),
+    acceptanceTable: hasEpicSection(body, 'acceptanceTable'),
   };
 }
 
-export function hasAllRequestedArtifacts({ existing, wantsAcceptanceSpec }) {
+export function hasAllRequestedSections({ existing, wantsAcceptanceSpec }) {
   return Boolean(
-    existing.prd &&
-      existing.techSpec &&
-      (wantsAcceptanceSpec ? existing.acceptanceSpec : true),
-  );
-}
-
-async function persistPrd({
-  provider,
-  epicId,
-  epic,
-  prdContent,
-  existingId,
-  force,
-}) {
-  if (existingId) {
-    if (force) {
-      Logger.info(
-        `[Epic Planner] --force: Overwriting PRD #${existingId} in place.`,
-      );
-      await overwriteContextTicket(provider, existingId, {
-        title: `[PRD] ${epic.title}`,
-        body: prdContent,
-        artifact: 'PRD',
-      });
-    } else {
-      Logger.info(
-        `[Epic Planner] Reusing existing PRD #${existingId}. Skipping PRD creation.`,
-      );
-    }
-    return existingId;
-  }
-
-  Logger.info(`[Epic Planner] Creating PRD issue for "${epic.title}"...`);
-  const prdTicket = await provider.createTicket(epicId, {
-    title: `[PRD] ${epic.title}`,
-    body: prdContent,
-    labels: ['context::prd'],
-    dependencies: [],
-  });
-  Logger.info(
-    `[Epic Planner] Created PRD Issue #${prdTicket.id} (${prdTicket.url})`,
-  );
-  return prdTicket.id;
-}
-
-async function persistTechSpec({
-  provider,
-  epicId,
-  epic,
-  techSpecContent,
-  prdId,
-  existingId,
-  force,
-}) {
-  if (existingId) {
-    if (force) {
-      Logger.info(
-        `[Epic Planner] --force: Overwriting Tech Spec #${existingId} in place.`,
-      );
-      await overwriteContextTicket(provider, existingId, {
-        title: `[Tech Spec] ${epic.title}`,
-        body: techSpecContent,
-        artifact: 'Tech Spec',
-      });
-    } else {
-      Logger.info(
-        `[Epic Planner] Reusing existing Tech Spec #${existingId}. Skipping Tech Spec creation.`,
-      );
-    }
-    return existingId;
-  }
-
-  Logger.info(
-    `[Epic Planner] Creating Tech Spec issue linking to PRD #${prdId}...`,
-  );
-  const techSpecTicket = await provider.createTicket(epicId, {
-    title: `[Tech Spec] ${epic.title}`,
-    body: techSpecContent,
-    labels: ['context::tech-spec'],
-    dependencies: [prdId],
-  });
-  Logger.info(
-    `[Epic Planner] Created Tech Spec Issue #${techSpecTicket.id} (${techSpecTicket.url})`,
+    existing.techSpec &&
+      (wantsAcceptanceSpec ? existing.acceptanceTable : true),
   );
-  return techSpecTicket.id;
-}
-
-async function persistAcceptanceSpec({
-  provider,
-  epicId,
-  epic,
-  acceptanceSpecContent,
-  techSpecId,
-  existingId,
-  force,
-}) {
-  if (existingId) {
-    if (force) {
-      Logger.info(
-        `[Epic Planner] --force: Overwriting Acceptance Spec #${existingId} in place.`,
-      );
-      await overwriteContextTicket(provider, existingId, {
-        title: `[Acceptance Spec] ${epic.title}`,
-        body: acceptanceSpecContent,
-        artifact: 'Acceptance Spec',
-      });
-    } else {
-      Logger.info(
-        `[Epic Planner] Reusing existing Acceptance Spec #${existingId}. Skipping Acceptance Spec creation.`,
-      );
-    }
-    return existingId;
-  }
-
-  Logger.info(
-    `[Epic Planner] Creating Acceptance Spec issue linking to Tech Spec #${techSpecId}...`,
-  );
-  const acceptanceTicket = await provider.createTicket(epicId, {
-    title: `[Acceptance Spec] ${epic.title}`,
-    body: acceptanceSpecContent,
-    labels: ['context::acceptance-spec'],
-    dependencies: [techSpecId],
-  });
-  Logger.info(
-    `[Epic Planner] Created Acceptance Spec Issue #${acceptanceTicket.id} (${acceptanceTicket.url})`,
-  );
-  return acceptanceTicket.id;
-}
-
-async function closeWaivedAcceptanceSpec({
-  provider,
-  epicId,
-  epic,
-  existingAcceptanceSpecId,
-}) {
-  Logger.info(
-    `[Epic Planner] Acceptance disposition now waived — closing existing Acceptance Spec #${existingAcceptanceSpecId}.`,
-  );
-  try {
-    await provider.updateTicket(existingAcceptanceSpecId, {
-      state: 'closed',
-      state_reason: 'not_planned',
-    });
-  } catch (err) {
-    if (!err.message.includes('404') && !err.message.includes('410')) {
-      throw err;
-    }
-  }
-  try {
-    await provider.removeSubIssue(epicId, existingAcceptanceSpecId);
-  } catch (_err) {
-    // Already detached or unsupported — safe to ignore.
-  }
-  if (epic.linkedIssues) epic.linkedIssues.acceptanceSpec = null;
 }
 
 /**
- * Persist the host-authored PRD and Tech Spec under the Epic.
+ * Persist the host-authored Tech Spec (and optional Acceptance Table) as
+ * managed sections of the Epic body.
+ *
+ * @returns {Promise<{
+ *   persisted: boolean,
+ *   reason: 'already-planned'|'persisted'|'force-replan',
+ *   techSpecPersisted: boolean,
+ *   acceptanceTable: 'persisted'|'waived'|'none',
+ * }>}
  */
 export async function planEpic(
   epicId,
   provider,
-  { prdContent, techSpecContent, acceptanceSpecContent = null },
+  { techSpecContent, acceptanceSpecContent = null },
   _settings = {},
   { force = false, planningRisk = null } = {},
 ) {
   validatePlanEpicInputs({
-    prdContent,
     techSpecContent,
     acceptanceSpecContent,
   });
@@ -301,111 +135,59 @@ export async function planEpic(
     throw new Error(`Epic #${epicId} not found.`);
   }
 
-  const stateManager = new PlanningStateManager(provider);
-  await stateManager.healAndCleanupArtifacts(epic, force);
-
   const { wantsAcceptanceSpec, applyAcceptanceWaiver } =
     resolveAcceptancePersistence(planningRisk, acceptanceSpecContent);
 
   Logger.info(
     `[Epic Planner] Acceptance disposition: ${planningRisk?.acceptanceDisposition ?? 'unspecified'}` +
       (applyAcceptanceWaiver
-        ? ` — applying ${ACCEPTANCE_NA} waiver (no acceptance-spec ticket).`
+        ? ` — applying ${ACCEPTANCE_NA} waiver (no acceptance-table section).`
         : wantsAcceptanceSpec
-          ? ' — persisting context::acceptance-spec.'
+          ? ' — persisting the ## Acceptance Table section.'
           : ' — no acceptance-spec content supplied.'),
   );
 
-  const existing = getExistingArtifactIds(epic);
-  if (!force && hasAllRequestedArtifacts({ existing, wantsAcceptanceSpec })) {
+  const existing = getExistingSections(epic);
+  if (!force && hasAllRequestedSections({ existing, wantsAcceptanceSpec })) {
     Logger.warn(
-      `[Epic Planner] Epic #${epicId} already has all requested planning artifacts. Aborting to prevent duplicates. Use --force to re-plan.`,
+      `[Epic Planner] Epic #${epicId} body already carries all requested planning sections. Aborting to prevent an unintended overwrite. Use --force to re-plan.`,
     );
     return {
       persisted: false,
       reason: 'already-planned',
-      prdId: existing.prd,
-      techSpecId: existing.techSpec,
-      acceptanceSpecId: existing.acceptanceSpec,
+      techSpecPersisted: existing.techSpec,
+      acceptanceTable: existing.acceptanceTable ? 'persisted' : 'none',
     };
   }
-  // Under --force we now OVERWRITE the canonical context tickets in place
-  // (same issue numbers, refreshed bodies) rather than closing + recreating
-  // them. `healAndCleanupArtifacts(epic, force=true)` preserved the canonical
-  // IDs on `epic.linkedIssues`, so reuse them in both the force and non-force
-  // paths. The difference: under force we push the freshly-authored body via
-  // `provider.updateTicket`, whereas the non-force partial-state reuse keeps
-  // the existing body untouched.
-  const prdId = await persistPrd({
-    provider,
-    epicId,
-    epic,
-    prdContent,
-    existingId: existing.prd,
-    force,
-  });
-  const techSpecId = await persistTechSpec({
-    provider,
-    epicId,
-    epic,
-    techSpecContent,
-    prdId,
-    existingId: existing.techSpec,
-    force,
-  });
 
-  let acceptanceSpecId = null;
+  // Section-scoped writes: each upsert replaces only its own managed
+  // region; the ideation sections and any operator-authored prose are
+  // byte-preserved. The retired `## Planning Artifacts` checklist is
+  // stripped so re-planned historical Epics stop advertising the old
+  // context-ticket links (the legacy tickets themselves are ignored).
+  let newBody = stripPlanningArtifactsSection(epic.body ?? '');
+  newBody = upsertEpicSection(newBody, 'techSpec', techSpecContent);
+
+  let acceptanceTable = 'none';
   if (wantsAcceptanceSpec) {
-    acceptanceSpecId = await persistAcceptanceSpec({
-      provider,
-      epicId,
-      epic,
+    newBody = upsertEpicSection(
+      newBody,
+      'acceptanceTable',
       acceptanceSpecContent,
-      techSpecId,
-      existingId: existing.acceptanceSpec,
-      force,
-    });
-  } else if (applyAcceptanceWaiver && existing.acceptanceSpec) {
-    // Acceptance-spec transition: was present, now waived (acceptance::n-a).
-    // This is a genuine close — there is no longer an acceptance spec to
-    // overwrite — and the stale ticket must be detached so the Epic body's
-    // Planning Artifacts section stops referencing it.
-    await closeWaivedAcceptanceSpec({
-      provider,
-      epicId,
-      epic,
-      existingAcceptanceSpecId: existing.acceptanceSpec,
-    });
-  }
-
-  Logger.info(
-    `[Epic Planner] Updating Epic #${epicId} with linked documents...`,
-  );
-
-  // Format exactly so the issue-link-parser regexes still catch each line.
-  // The parser is the source of truth for which prefixes are accepted; we
-  // emit the canonical "PRD: #N" / "Tech Spec: #N" / "Acceptance Spec: #N"
-  // shape so the epic-deliver finalize/cascade-close call shape and the
-  // Phase 2 decomposer-context picker both see the third link.
-  const artifactLines = [
-    `- [ ] PRD: #${prdId}`,
-    `- [ ] Tech Spec: #${techSpecId}`,
-  ];
-  if (acceptanceSpecId !== null) {
-    artifactLines.push(`- [ ] Acceptance Spec: #${acceptanceSpecId}`);
+    );
+    acceptanceTable = 'persisted';
+  } else if (applyAcceptanceWaiver) {
+    // Acceptance transition: was present, now waived (acceptance::n-a).
+    // Strip the stale table so the close-time reconciler cannot read a
+    // section the planner no longer stands behind.
+    if (existing.acceptanceTable) {
+      Logger.info(
+        `[Epic Planner] Acceptance disposition now waived — removing the stale ## Acceptance Table section from Epic #${epicId}.`,
+      );
+      newBody = stripEpicSection(newBody, 'acceptanceTable');
+    }
+    acceptanceTable = 'waived';
   }
-  // Idempotent append (Story #4019): strip any pre-existing
-  // `## Planning Artifacts` section before re-appending. The `--force`
-  // path already stripped it in `healAndCleanupArtifacts`, but the
-  // partial-recovery rerun (e.g. PRD present, Tech Spec missing) reaches
-  // here with a body that may still carry a stale section — without the
-  // strip, every rerun stacked a duplicate section onto the Epic body.
-  const appendBody = `\n\n## Planning Artifacts\n${artifactLines.join('\n')}\n`;
-  const strippedBody = epic.body.replace(
-    /\n*## Planning Artifacts[\s\S]*$/,
-    '',
-  );
-  const newBody = strippedBody + appendBody;
 
   /** @type {{ add?: string[], remove?: string[] }} */
   const labelMutations = {};
@@ -418,6 +200,9 @@ export async function planEpic(
     labelMutations.remove = [ACCEPTANCE_NA];
   }
 
+  Logger.info(
+    `[Epic Planner] Updating Epic #${epicId} body with the planning sections...`,
+  );
   await provider.updateTicket(epicId, {
     body: newBody,
     ...(labelMutations.add || labelMutations.remove
@@ -425,14 +210,27 @@ export async function planEpic(
       : {}),
   });
 
+  if (force) {
+    // Preserve the regeneration audit trail the retired per-ticket
+    // overwrite used to leave. Best-effort — never fail the persist on a
+    // comment post error.
+    try {
+      await provider.postComment(epicId, {
+        type: 'notification',
+        body: '♻️ **Regeneration Audit**: the Tech Spec / Acceptance Table sections of this Epic body were regenerated in place by a `/plan --force` re-plan. Content outside the managed sections was preserved.',
+      });
+    } catch (_err) {
+      // Swallow: audit comment is advisory.
+    }
+  }
+
   Logger.info(`[Epic Planner] Epic #${epicId} updated successfully.`);
   Logger.info(`[Epic Planner] Planning pipeline complete!`);
 
   return {
     persisted: true,
     reason: force ? 'force-replan' : 'persisted',
-    prdId,
-    techSpecId,
-    acceptanceSpecId,
+    techSpecPersisted: true,
+    acceptanceTable,
   };
 }

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/prompts.js

@@ -1,55 +1,58 @@
 /**
- * phases/prompts.js — Canonical PRD / Tech Spec / Acceptance Spec system
- * prompts for the spec phase of `/plan`.
+ * phases/prompts.js — Canonical Tech Spec / Acceptance Spec system prompts for
+ * the spec phase of `/plan`.
  *
  * These ride along on the `--emit-context` envelope as a backstop. The
  * `epic-plan-spec-author` Skill
  * (`.agents/skills/core/epic-plan-spec-author/SKILL.md`) embeds the
  * authoritative copies of these strings — keep the two surfaces in sync when
  * either is edited.
+ *
+ * Story #4314: the PRD artifact class is retired. The Epic body (which now
+ * carries its `## User Stories` section inline) is the sole authoring input;
+ * both prompts consume the Epic body directly rather than a paraphrased PRD.
+ *
+ * Story #4324: the Tech Spec and Acceptance Spec are no longer separate
+ * `context::*` tickets — the authored content lands as managed sections of
+ * the same Epic body (`## Delivery Slicing`-led Tech Spec sections, and the
+ * `## Acceptance Table` AC-ID table). Content semantics are unchanged; only
+ * WHERE the output lives moved.
  */
 
-export const PRD_SYSTEM_PROMPT = `You are an expert Technical Product Manager.
-Your job is to convert a high-level Epic description into a structured Product Requirements Document (PRD).
-
-The PRD should outline:
-1. Context & Goals
-2. User Stories
-3. Acceptance Criteria
-4. Out of Scope
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Overview.
-- Format requirements clearly with bullet points and bold text where appropriate.`;
-
 export const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
-Your job is to convert a PRD into a Technical Specification for implementation.
+Your job is to convert an Epic into a Technical Specification for implementation.
 
 The Tech Spec should outline:
-1. Architecture & Design
-2. Data Models (if any)
-3. API Changes (if any)
-4. Core Components
-5. Security & Privacy Considerations
+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. Start with ## Technical Overview.
-- Format architectural decisions clearly with bullet points.`;
+- 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.`;
 
 export const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
-Your job is to convert a PRD and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+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 Criteria — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
+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 Criteria.
+- 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.
-- Each Outcome MUST be a single user-visible behaviour — no DB assertions, no HTTP status codes, no internal implementation details.
+- 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.`;