mandrel 1.81.0 → 1.83.0

package/.agents/scripts/hierarchy-gate.js

@@ -10,16 +10,16 @@
  *
  * The two gates catch different problems and are intentionally distinct:
  *   - The wave gate misses descendants that exist on GitHub but were never
- *     in the manifest — context::prd / context::tech-spec tickets, mid-sprint
- *     additions, or recuts that bypassed the dispatcher.
+ *     in the manifest — mid-sprint additions, recuts that bypassed the
+ *     dispatcher, or legacy `context::*` artifacts on historical Epics.
  *   - The hierarchy gate misses parked follow-ons that live as separate
  *     top-level Stories outside the Epic's sub-issue graph.
  *
  * Per ticket type the rule is:
  *   - Stories   — must be closed.
- *   - Auxiliary (context::prd, context::tech-spec) — ignored.
- *     These are closed by the operator after the Epic PR merges, so
- *     requiring them closed here would block every Epic.
+ *   - Auxiliary (legacy `context::*` artifacts) — ignored. Story #4324
+ *     folded planning content into the Epic body; historical Epics keep
+ *     their old context tickets, which are reference-only here.
  *
  * **2-tier hierarchy (Story #4041).** Mandrel ships only Epic / Story
  * tickets. `getSubTickets(<storyId>)` returns `[]`; the walk
@@ -39,7 +39,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import { CONTEXT_LABELS, TYPE_LABELS } from './lib/label-constants.js';
+import { TYPE_LABELS } from './lib/label-constants.js';
 import { createProvider } from './lib/provider-factory.js';
 import { concurrentMap } from './lib/util/concurrent-map.js';
 
@@ -52,10 +52,10 @@ const SUB_TICKET_FETCH_CONCURRENCY = 4;
 function classify(ticket) {
   const labels = ticket.labels ?? [];
   if (labels.includes(TYPE_LABELS.STORY)) return 'story';
-  if (
-    labels.includes(CONTEXT_LABELS.PRD) ||
-    labels.includes(CONTEXT_LABELS.TECH_SPEC)
-  ) {
+  // Legacy planning artifacts (pre-#4324 `context::*` tickets on
+  // historical Epics) are ignored — they are reference artifacts, not
+  // deliverables. New Epics carry planning content on the body itself.
+  if (labels.some((l) => typeof l === 'string' && l.startsWith('context::'))) {
     return 'auxiliary';
   }
   return 'other';
@@ -165,7 +165,7 @@ export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
 
   const auxNote =
     auxiliaryDeferred > 0
-      ? ` (${auxiliaryDeferred} auxiliary ticket${auxiliaryDeferred === 1 ? '' : 's'} deferred to Phase 7)`
+      ? ` (${auxiliaryDeferred} legacy auxiliary ticket${auxiliaryDeferred === 1 ? '' : 's'} ignored)`
       : '';
   Logger.info(
     `[hierarchy-gate] ✅ All ${descendants.length - auxiliaryDeferred} planned descendant(s) under Epic #${epicId} are closed${auxNote}.`,

package/.agents/scripts/lib/ITicketingProvider.js

@@ -33,15 +33,16 @@ export class ITicketingProvider {
   }
 
   /**
-   * Fetch the Epic issue with body and linked context issues (PRD, Tech Spec).
+   * Fetch the Epic issue with its body — the single planning document
+   * (ideation sections plus the folded Tech Spec / Acceptance Table
+   * managed sections, Story #4324).
    *
    * @param {number} epicId - GitHub Issue number of the Epic.
    * @returns {Promise<{
    *   id: number,
    *   title: string,
    *   body: string,
-   *   labels: string[],
-   *   linkedIssues: { prd: number|null, techSpec: number|null }
+   *   labels: string[]
    * }>}
    */
   async getEpic(_epicId) {

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -3,7 +3,7 @@
  * Task #2103; workspace-aware extension from Story #2956).
  *
  * Used by `epic-plan-spec.js#buildAuthoringContext` to decide whether the
- * acceptance-spec body should plan **features-first** Story ordering (a real
+ * acceptance-table section should plan **features-first** Story ordering (a real
  * pending-tag is available, so the features-first Story can ship `.feature`
  * files marked `@pending` / `@skip` ahead of the implementation Stories) or
  * fall back to **dependencies-first** ordering (no pending tag → cannot

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -3,7 +3,7 @@
  *
  * Story #2637 (sibling to #2634 codebase-snapshot, #2635 spec-freshness,
  * #2636 file-assumption gate). The Acceptance Engineer step of
- * `epic-plan-spec-author` currently writes ACs from PRD/Tech Spec narrative
+ * `epic-plan-spec-author` currently writes ACs from Epic/Tech Spec narrative
  * alone — it never inspects the consumer project's existing `.feature`
  * files. Planned ACs frequently duplicate scenarios that already exist or
  * re-specify behaviour the codebase already proves; the duplication is

package/.agents/scripts/lib/cli-args.js

@@ -60,8 +60,6 @@ export function parseSprintArgs(args = process.argv) {
       'no-full-scope-crap': { type: 'boolean', default: false },
       executor: { type: 'string' },
       cwd: { type: 'string' },
-      prd: { type: 'string' },
-      'tech-spec': { type: 'string' },
       'recut-of': { type: 'string' },
       resume: { type: 'boolean', default: false },
       restart: { type: 'boolean', default: false },
@@ -88,10 +86,8 @@ export function parseSprintArgs(args = process.argv) {
       process.env.AGENT_WORKTREE_ROOT ||
       null,
     recutOf: parseTicketId(values['recut-of']),
-    // Story #4253: pre-resolved Epic linkages threaded by the /deliver
+    // Story #4253: pre-resolved Epic linkage threaded by the /deliver
     // fan-out so `story-init.js` can skip the per-Story `getEpic` round-trip.
-    prdId: parseTicketId(values.prd),
-    techSpecId: parseTicketId(values['tech-spec']),
     resume: values.resume ?? false,
     restart: values.restart ?? false,
     noEvidence: values['no-evidence'] ?? false,

package/.agents/scripts/lib/codebase-snapshot.js

@@ -2,7 +2,7 @@
  * codebase-snapshot.js — Bounded structural view of the consumer repo.
  *
  * Story #2634 (sibling to #2635 spec-freshness). `/plan` Phase 7
- * authors PRD + Tech Spec from documentation alone — `architecture.md`,
+ * authors the Tech Spec from documentation alone — `architecture.md`,
  * `data-dictionary.md`, `decisions.md`, `patterns.md`. When those docs
  * drift from the real source tree, the Architect persona cites modules
  * and paths that no longer exist, and the mismatch only surfaces at

package/.agents/scripts/lib/config/explain.js

@@ -232,7 +232,10 @@ const PREFIX_MEANINGS = Object.freeze([
     'planning.taskSizing',
     'Story-sizing threshold for the decompose validator.',
   ],
-  ['qa.signInSeam', 'QA harness sign-in seam configuration.'],
+  [
+    'qa.environments',
+    'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate).',
+  ],
   ['qa.personas', 'QA harness persona / credential mapping.'],
 ]);
 

package/.agents/scripts/lib/config/temp-paths.js

@@ -10,7 +10,6 @@
  *
  * Layout:
  *   temp/epic-<eid>/
- *     ├─ prd.md
  *     ├─ techspec.md
  *     ├─ manifest.md          (dispatch manifest)
  *     ├─ retro.md             (mirror of GitHub retro at Epic close)
@@ -228,7 +227,7 @@ export function epicTempDir(eid, config) {
  * location instead of being dropped on the floor.
  *
  * Story #2940 introduced the intermediate `stories/` segment so that
- * per-Epic top-level artifacts (`prd.md`, `techspec.md`, `manifest.md`,
+ * per-Epic top-level artifacts (`techspec.md`, `manifest.md`,
  * `retro.md`, `lifecycle.ndjson`, `baselines/`, `checkpoints/`) are
  * visually and structurally separated from the per-Story siblings.
  *
@@ -291,8 +290,6 @@ export function storyArtifactPath(eid, sid, name, config) {
 
 // --- Canonical Epic-level filenames (Tech Spec #1032 §tempRoot) ---
 
-export const epicPrdPath = (eid, config) =>
-  epicArtifactPath(eid, 'prd.md', config);
 export const epicTechSpecPath = (eid, config) =>
   epicArtifactPath(eid, 'techspec.md', config);
 export const epicManifestPath = (eid, config) =>

package/.agents/scripts/lib/config-settings-schema.js

@@ -263,6 +263,11 @@ const TASK_SIZING_SCHEMA = {
     hardFiles: { type: 'integer', minimum: 1 },
     maxAcceptance: { type: 'integer', minimum: 1 },
     softAcceptanceCount: { type: 'integer', minimum: 1 },
+    // Under-size (merge-candidate) thresholds (Story #4312). A Story whose
+    // footprint is at or below BOTH ceilings and that carries a `depends_on`
+    // edge to a sibling trips the advisory `merge-candidate` soft finding.
+    mergeCandidateMaxFiles: { type: 'integer', minimum: 1 },
+    mergeCandidateMaxAcceptance: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };
@@ -401,12 +406,36 @@ const QA_PERSONAS_SCHEMA = {
   ],
 };
 
+// `environments` is the environment-keyed contract (Epic #4326, Story #4327).
+// It replaces the retired top-level single `signInSeam` shape: each named
+// environment carries its own `baseUrl`, its own per-environment `signInSeam`
+// (reusing the same url-template/skill union), and an optional `allowWrites`
+// gate. Downstream, `resolveQaEnvironment` selects one environment per
+// invocation by name or by raw-URL origin match against `baseUrl`. The map
+// must carry at least one environment. This is a hard cutover — there is no
+// top-level `signInSeam` acceptance branch (see
+// `.agents/rules/git-conventions.md` § Contract Cutovers).
+const QA_ENVIRONMENTS_SCHEMA = {
+  type: 'object',
+  minProperties: 1,
+  additionalProperties: {
+    type: 'object',
+    properties: {
+      baseUrl: { ...SAFE_STRING, minLength: 1 },
+      signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
+      allowWrites: { type: 'boolean' },
+    },
+    required: ['baseUrl', 'signInSeam'],
+    additionalProperties: false,
+  },
+};
+
 export const QA_SCHEMA = {
   type: 'object',
   properties: {
     featureRoot: { ...SAFE_STRING, minLength: 1 },
     fixturesManifest: { ...SAFE_STRING, minLength: 1 },
-    signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
+    environments: QA_ENVIRONMENTS_SCHEMA,
     personas: QA_PERSONAS_SCHEMA,
     consoleAllowlist: {
       type: 'array',

package/.agents/scripts/lib/epic-body-sections.js

@@ -0,0 +1,310 @@
+/**
+ * epic-body-sections.js — marker-delimited managed sections of the Epic 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.
+ *
+ * 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 close-time acceptance reconciler
+ *     (`acceptance-spec-reconciler.js`) reads and rewrites the
+ *     `acceptanceTable` region only (verification dispositions).
+ *
+ * Everything outside a managed region is byte-preserved by every helper in
+ * this module. Markers are chosen so GitHub renders nothing for them; the
+ * human-visible headings (`## Delivery Slicing`, `## Acceptance Table`)
+ * live INSIDE the regions as ordinary content.
+ *
+ * Pure ESM, no I/O.
+ */
+
+/**
+ * Managed-region descriptors. `start`/`end` are the literal marker lines;
+ * `label` is the human name used in log lines and error messages.
+ *
+ * @type {Readonly<Record<'techSpec'|'acceptanceTable', { start: string, end: string, label: string }>>}
+ */
+export const EPIC_BODY_SECTIONS = Object.freeze({
+  techSpec: Object.freeze({
+    start: '<!-- mandrel:tech-spec:start -->',
+    end: '<!-- mandrel:tech-spec:end -->',
+    label: 'Tech Spec',
+  }),
+  acceptanceTable: Object.freeze({
+    start: '<!-- mandrel:acceptance-table:start -->',
+    end: '<!-- mandrel:acceptance-table:end -->',
+    label: 'Acceptance Table',
+  }),
+});
+
+/**
+ * Canonical heading the acceptance-table region opens with. Distinct from
+ * the Epic'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';
+
+/**
+ * Regex matching the Tech Spec's required opening heading (same variants
+ * `spec-section-validator.js` accepts).
+ */
+const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
+
+/**
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @returns {{ start: string, end: string, label: string }}
+ */
+function descriptor(kind) {
+  const d = EPIC_BODY_SECTIONS[kind];
+  if (!d) {
+    throw new TypeError(
+      `epic-body-sections: unknown section kind "${kind}" (expected ${Object.keys(EPIC_BODY_SECTIONS).join(' | ')})`,
+    );
+  }
+  return d;
+}
+
+/**
+ * Locate a managed region. Returns `null` when either marker is absent or
+ * the end marker precedes the start marker (malformed body — treated as
+ * absent so a writer re-appends a well-formed region rather than
+ * corrupting the body further).
+ *
+ * @param {string} body
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @returns {{ startIdx: number, contentStart: number, contentEnd: number, endIdx: number }|null}
+ */
+function locate(body, kind) {
+  const { start, end } = descriptor(kind);
+  if (typeof body !== 'string' || body.length === 0) return null;
+  const startIdx = body.indexOf(start);
+  if (startIdx === -1) return null;
+  const contentStart = startIdx + start.length;
+  const endIdx = body.indexOf(end, contentStart);
+  if (endIdx === -1) return null;
+  return { startIdx, contentStart, contentEnd: endIdx, endIdx };
+}
+
+/**
+ * True when the body carries a well-formed managed region of `kind`.
+ *
+ * @param {string} body
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @returns {boolean}
+ */
+export function hasEpicSection(body, kind) {
+  return locate(body, kind) !== null;
+}
+
+/**
+ * Extract a managed region's content (between the markers, trimmed).
+ * Returns `null` when the region is absent.
+ *
+ * @param {string} body
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @returns {string|null}
+ */
+export function extractEpicSection(body, kind) {
+  const loc = locate(body, kind);
+  if (!loc) return null;
+  return body.slice(loc.contentStart, loc.contentEnd).trim();
+}
+
+/**
+ * Insert or replace a managed region, preserving every byte outside it.
+ *
+ * When the region exists, only the content between the markers is
+ * replaced. When absent, the region is appended at the end of the body
+ * (trailing whitespace normalised to a single blank-line separator). The
+ * `techSpec` region is appended before an existing `acceptanceTable`
+ * region so the rendered document keeps its canonical order
+ * (ideation sections → Tech Spec → Acceptance Table).
+ *
+ * @param {string} body
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @param {string} content Section content (headings included).
+ * @returns {string}
+ */
+export function upsertEpicSection(body, kind, content) {
+  const { start, end } = descriptor(kind);
+  const safeBody = typeof body === 'string' ? body : '';
+  const trimmedContent = typeof content === 'string' ? content.trim() : '';
+  const region = `${start}\n\n${trimmedContent}\n\n${end}`;
+
+  const loc = locate(safeBody, kind);
+  if (loc) {
+    return (
+      safeBody.slice(0, loc.startIdx) +
+      region +
+      safeBody.slice(loc.endIdx + end.length)
+    );
+  }
+
+  // Keep canonical order when appending: the Tech Spec region goes before
+  // an already-present acceptance-table region.
+  if (kind === 'techSpec') {
+    const acceptanceLoc = locate(safeBody, 'acceptanceTable');
+    if (acceptanceLoc) {
+      const head = safeBody
+        .slice(0, acceptanceLoc.startIdx)
+        .replace(/\s+$/, '');
+      const tail = safeBody.slice(acceptanceLoc.startIdx);
+      return `${head}\n\n${region}\n\n${tail}`;
+    }
+  }
+
+  const trimmedBody = safeBody.replace(/\s+$/, '');
+  return trimmedBody.length > 0
+    ? `${trimmedBody}\n\n${region}\n`
+    : `${region}\n`;
+}
+
+/**
+ * Remove a managed region (markers and content). Byte-preserving outside
+ * the region; collapses the surrounding blank lines the writer added.
+ * No-op when the region is absent.
+ *
+ * @param {string} body
+ * @param {'techSpec'|'acceptanceTable'} kind
+ * @returns {string}
+ */
+export function stripEpicSection(body, kind) {
+  const { end } = descriptor(kind);
+  const loc = locate(body, kind);
+  if (!loc) return typeof body === 'string' ? body : '';
+  const before = body.slice(0, loc.startIdx).replace(/\n+$/, '\n');
+  const after = body.slice(loc.endIdx + end.length).replace(/^\n+/, '\n');
+  return (before + after).replace(/\n{3,}/g, '\n\n');
+}
+
+/**
+ * Re-plan / decompose detection: true when the Epic body carries folded
+ * Tech Spec content — the managed region, or (defence in depth for a
+ * hand-authored body) a bare `## Delivery Slicing` heading.
+ *
+ * @param {string} body
+ * @returns {boolean}
+ */
+export function hasTechSpecContent(body) {
+  if (hasEpicSection(body, 'techSpec')) return true;
+  return typeof body === 'string' && DELIVERY_SLICING_RE.test(body);
+}
+
+/**
+ * `##` headings dropped from the delivery-hydrated Epic body. These are
+ * ideation / authoring / close-machinery sections a story agent never acts
+ * on: keeping them out of the per-Story prompt trims token cost without
+ * losing any binding context (the Story carries its own inline
+ * acceptance[] / verify[]).
+ *
+ * @type {ReadonlySet<string>}
+ */
+const DELIVERY_DROP_HEADINGS = new Set([
+  'context',
+  'scope',
+  'acceptance criteria',
+]);
+
+/**
+ * Slice an Epic body down to the sections a delivery story agent acts on.
+ *
+ * KEEP: the Epic 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
+ * `acceptanceTable` managed region.
+ *
+ * The `techSpec` region is located by its markers (not by heading
+ * boundaries) so its inner `## Delivery Slicing` heading is preserved
+ * verbatim and never mistaken for a plain droppable section. Plain `##`
+ * sections outside the managed regions are sliced by heading boundaries.
+ *
+ * Fail-open is load-bearing: any heading not explicitly in the drop set is
+ * kept, so operator-authored content is never silently lost.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function sliceEpicBodyForDelivery(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');
+
+  // 2. Protect the techSpec managed region from heading-boundary slicing by
+  //    lifting it out behind an opaque placeholder, then restoring it after
+  //    the plain-section pass. Its inner `## Delivery Slicing` heading must
+  //    survive verbatim.
+  const techLoc = locate(working, 'techSpec');
+  let techRegion = null;
+  const PLACEHOLDER = 'MANDREL_TECH_SPEC_PLACEHOLDER';
+  if (techLoc) {
+    const { end } = descriptor('techSpec');
+    techRegion = working.slice(techLoc.startIdx, techLoc.endIdx + end.length);
+    working =
+      working.slice(0, techLoc.startIdx) +
+      PLACEHOLDER +
+      working.slice(techLoc.endIdx + end.length);
+  }
+
+  // 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.
+  const kept = [];
+  let dropping = false;
+  for (const line of working.split('\n')) {
+    const headingMatch = line.match(/^##\s+(.*?)\s*$/);
+    if (headingMatch) {
+      dropping = DELIVERY_DROP_HEADINGS.has(
+        headingMatch[1].trim().toLowerCase(),
+      );
+      if (dropping) continue;
+    }
+    if (dropping) continue;
+    kept.push(line);
+  }
+  working = kept.join('\n');
+
+  // 4. Restore the techSpec region in place.
+  if (techRegion !== null) {
+    working = working.replace(PLACEHOLDER, () => techRegion);
+  }
+
+  // 5. Normalise the blank-line runs left by the drops.
+  return working
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+/, '')
+    .trimEnd();
+}
+
+/**
+ * Strip the retired machine-managed `## Planning Artifacts` checklist from
+ * an Epic 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.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function stripPlanningArtifactsSection(body) {
+  if (typeof body !== 'string' || body.length === 0) return '';
+  const headingMatch = body.match(/^##\s+Planning Artifacts[^\n]*$/m);
+  if (!headingMatch || typeof headingMatch.index !== 'number') return body;
+  const start = headingMatch.index;
+  const afterHeading = start + headingMatch[0].length;
+  const rest = body.slice(afterHeading);
+  const boundary = rest.search(/^(?:##\s|<!-- mandrel:)/m);
+  const end = boundary === -1 ? body.length : afterHeading + boundary;
+  const before = body.slice(0, start).replace(/\n+$/, '\n');
+  const after = body.slice(end);
+  return (before + after).replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+}

package/.agents/scripts/lib/epic-plan-clarity.js

@@ -28,6 +28,15 @@
  *     `## Work Breakdown`
  *   - `## Acceptance Criteria`, `## Acceptance`, `## AC`
  *
+ * Story #4324 folded the Tech Spec and Acceptance Spec into the Epic body
+ * as managed sections (`## Delivery Slicing`-led spec sections and the
+ * `## Acceptance Table`). The gate *recognises* those planning sections —
+ * reporting their presence under `planningSections[]` so a post-fold Epic
+ * body scores exactly as its ideation content deserves — but they never
+ * count toward (or against) the five-ideation-section verdict: Phase 6
+ * runs before Phase 7 authors them, and a re-planned Epic that already
+ * carries them must not be penalised or auto-passed by their presence.
+ *
  * Pure ESM, no I/O.
  */
 
@@ -54,6 +63,26 @@ export const SECTION_NAMES = Object.freeze([
   'acceptanceCriteria',
 ]);
 
+/**
+ * Post-fold planning sections (Story #4324) — recognised and reported,
+ * never scored. `deliverySlicing` accepts the same heading variants as
+ * `spec-section-validator.js`.
+ */
+const PLANNING_SECTION_RE = {
+  deliverySlicing: /^##\s+(?:Delivery\s+)?Slicing\s*$/im,
+  acceptanceTable: /^##\s+Acceptance\s+Table\s*$/im,
+};
+
+/**
+ * Names of the recognised (unscored) planning sections, in document order.
+ * Module-private: consumers read the reported `planningSections[]` rows on
+ * the scoreEpicBody result rather than importing the name list.
+ */
+const PLANNING_SECTION_NAMES = Object.freeze([
+  'deliverySlicing',
+  'acceptanceTable',
+]);
+
 const CLEAR_THRESHOLD = 4;
 const PLACEHOLDER_PATTERN = /^_\(not\s+specified\)_$/i;
 
@@ -80,6 +109,7 @@ function classify(content) {
  *   verdict: 'clear' | 'needs-refinement',
  *   sections: Array<{ name: string, status: 'present' | 'placeholder' | 'missing' }>,
  *   missingOrPlaceholder: string[],
+ *   planningSections: Array<{ name: string, status: 'present' | 'missing' }>,
  * }}
  */
 const REQUIRED_SECTION = 'acceptanceCriteria';
@@ -138,5 +168,12 @@ export function scoreEpicBody({ body } = {}) {
       ? 'clear'
       : 'needs-refinement';
 
-  return { verdict, sections, missingOrPlaceholder };
+  // Informational only: presence of the post-fold planning sections
+  // (Story #4324). Never feeds the verdict.
+  const planningSections = PLANNING_SECTION_NAMES.map((name) => ({
+    name,
+    status: PLANNING_SECTION_RE[name].test(source) ? 'present' : 'missing',
+  }));
+
+  return { verdict, sections, missingOrPlaceholder, planningSections };
 }

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -5,7 +5,7 @@
  * using the canonical template at `.agents/templates/epic-from-idea.md`.
  * Phase 4: open the GitHub Issue via an injected provider with the
  * `type::epic` label only — no `state::draft` (the Epic carries only
- * `type::epic` until PRD authoring writes `agent::review-spec`).
+ * `type::epic` until spec authoring writes `agent::review-spec`).
  *
  * The template is parsed from a string the caller has already loaded
  * (typically via `fs.readFile`). The renderer is pure — no I/O — and
@@ -30,13 +30,23 @@ const SECTION_RE = {
     /^##\s+(?:Non[\s-]?Goals|Out\s+of\s+Scope|Not\s+Doing(?:\s+\(and\s+Why\))?)\s*$/im,
   scope:
     /^##\s+(?:MVP\s+|Proposed\s+)?Scope(?:\s+\([^)]+\))?\s*$|^##\s+Work\s+Breakdown\s*$/im,
+  // Story #4314 — the PRD's one novel section (User Stories) now folds into
+  // the Epic body as a canonical section.
+  userStories: /^##\s+(?:User\s+Stories|Stories|Personas?\s+&\s+Stories)\s*$/im,
   acceptanceCriteria: /^##\s+(?:Acceptance(?:\s+Criteria)?|AC)\s*$/im,
 };
 
-const ORDER = ['context', 'goal', 'nonGoals', 'scope', 'acceptanceCriteria'];
+const ORDER = [
+  'context',
+  'goal',
+  'nonGoals',
+  'scope',
+  'userStories',
+  'acceptanceCriteria',
+];
 
 /**
- * Extract the five canonical sections from an idea-refinement one-pager.
+ * Extract the six canonical sections from an idea-refinement one-pager.
  *
  * @param {string} onePager - Markdown produced by Phase 3 of the
  *   `idea-refinement` skill.
@@ -46,6 +56,7 @@ const ORDER = ['context', 'goal', 'nonGoals', 'scope', 'acceptanceCriteria'];
  *   goal: string,
  *   nonGoals: string,
  *   scope: string,
+ *   userStories: string,
  *   acceptanceCriteria: string,
  * }}
  */
@@ -72,6 +83,7 @@ export function parseOnePager(onePager) {
     goal: '',
     nonGoals: '',
     scope: '',
+    userStories: '',
     acceptanceCriteria: '',
   };
 

package/.agents/scripts/lib/findings/promote-finding.js

@@ -196,8 +196,8 @@ function clusterToFinding(cluster) {
 /**
  * Build the `routedTo` link the schema stamps onto a promoted ledger item.
  *
- * The `routedTo.url` field is `minLength: 1` in both `qa-finding.schema.json`
- * and `qa-ledger.schema.json`, and the search/create port contract requires a
+ * The `routedTo.url` field is `minLength: 1` in `qa-ledger.schema.json`,
+ * and the search/create port contract requires a
  * routed issue to carry its canonical URL. So rather than silently stamp an
  * empty string (which would persist a schema-invalid ledger item), this guards
  * the url and throws when it is absent or blank (Story #3816, AC #4).
@@ -213,7 +213,7 @@ function routedToLink(issue, kind) {
     throw new Error(
       `promoteFindings: routed issue #${issue?.number ?? '?'} is missing a url; ` +
         'the search/create port contract requires a non-empty url ' +
-        '(routedTo.url is minLength:1 in the qa-finding/qa-ledger schemas)',
+        '(routedTo.url is minLength:1 in the qa-ledger schema)',
     );
   }
   return {