mandrel 1.81.0 → 1.83.0

package/.agents/scripts/lib/findings/severity.js

@@ -5,8 +5,8 @@
  * the shared findings core previously each declared their own severity list —
  * `classify-finding.js` (`[unknown, low, medium, high, critical]`),
  * `promote-finding.js` (`SEVERITY_RANK` over `[critical … info]`), and the
- * `qa-finding` / `qa-ledger` JSON schemas (`[critical, high, medium, low,
- * info]`). Because `severity` is a `fingerprintFinding` identity field
+ * `qa-ledger` JSON schema (`[critical, high, medium, low, info]`). Because
+ * `severity` is a `fingerprintFinding` identity field
  * (`route-finding.js`), the same finding could hash to different SHAs depending
  * on which path normalised its severity, silently weakening dedup. This module
  * collapses all three onto one enum + one normaliser so the fingerprint is
@@ -14,9 +14,8 @@
  *
  * The canonical order is `critical | high | medium | low | info`, highest →
  * lowest, and it MUST match the `severity` enum in
- * `.agents/schemas/qa-ledger.schema.json` (and the mirrored `qa-finding`
- * schema). Pure module: no I/O, no module-level state beyond the frozen
- * constants.
+ * `.agents/schemas/qa-ledger.schema.json`. Pure module: no I/O, no
+ * module-level state beyond the frozen constants.
  */
 
 /**
@@ -24,7 +23,7 @@
  * This is the ONLY definition of the severity vocabulary in the findings core;
  * `classify-finding.js` and `promote-finding.js` re-export / import it rather
  * than re-declaring their own list. Mirrors the `severity` enum in
- * `qa-ledger.schema.json` / `qa-finding.schema.json`.
+ * `qa-ledger.schema.json`.
  */
 export const SEVERITIES = Object.freeze([
   'critical',

package/.agents/scripts/lib/label-constants.js

@@ -91,22 +91,13 @@ export const STATUS_LABELS = {
  */
 export const PERSONA_LABEL_PREFIX = 'persona::';
 
-export const CONTEXT_LABELS = {
-  PRD: 'context::prd',
-  TECH_SPEC: 'context::tech-spec',
-  ACCEPTANCE_SPEC: 'context::acceptance-spec',
-};
-
-/** Convenience aliases so callers can reach the new constants by name without
- * indexing into CONTEXT_LABELS. Mirrors the export ergonomics used by other
- * consumers that import named constants (e.g. PERSONA_LABEL_PREFIX). */
-export const CONTEXT_ACCEPTANCE_SPEC = CONTEXT_LABELS.ACCEPTANCE_SPEC;
-
 /**
- * Acceptance-axis labels for opt-out signalling on Stories that
- * intentionally have no acceptance-spec coverage. Separate namespace from
- * `context::` because it expresses absence rather than a linked context
- * ticket.
+ * Acceptance-axis labels for opt-out signalling on Epics that
+ * intentionally have no acceptance-table coverage. (Story #4324 retired
+ * the `context::tech-spec` / `context::acceptance-spec` label classes —
+ * planning content now lives as managed sections of the Epic body. This
+ * waiver survives with unchanged meaning: it waives the Epic body's
+ * `## Acceptance Table` section instead of a ticket.)
  */
 export const ACCEPTANCE_LABELS = {
   N_A: 'acceptance::n-a',
@@ -149,7 +140,7 @@ export const PLANNING_LABELS = {
 /**
  * Convenience named export so callers can reach the constant without
  * indexing into PLANNING_LABELS — mirrors the ergonomics used by
- * ACCEPTANCE_NA / CONTEXT_ACCEPTANCE_SPEC. The literal value is
+ * ACCEPTANCE_NA. The literal value is
  * duplicated here (rather than aliased through PLANNING_LABELS) so a
  * grep for `PLANNING_HEALTHCHECK_WAIVED.*planning::healthcheck-waived`
  * matches a single line — see Story #2921 Task #2933 AC #1.
@@ -162,7 +153,6 @@ export const LABEL_COLORS = {
   AGENT: '#0E8A16',
   STATUS_BLOCKED: '#D93F0B',
   PERSONA: '#C5DEF5',
-  CONTEXT: '#D4C5F9',
   ACCEPTANCE: '#FBCA04',
   PLANNING: '#FEF2C0',
 };

package/.agents/scripts/lib/label-taxonomy.js

@@ -12,7 +12,6 @@ import { fileURLToPath } from 'node:url';
 import {
   ACCEPTANCE_LABELS,
   AGENT_LABELS,
-  CONTEXT_LABELS,
   LABEL_COLORS,
   PERSONA_LABEL_PREFIX,
   PLANNING_LABELS,
@@ -64,7 +63,7 @@ export const LABEL_TAXONOMY = [
     name: AGENT_LABELS.REVIEW_SPEC,
     color: LABEL_COLORS.AGENT,
     description:
-      'Parking state — PRD + Tech Spec exist; awaiting human review before decomposition',
+      'Parking state — Tech Spec exists; awaiting human review before decomposition',
   },
   {
     name: AGENT_LABELS.READY,
@@ -98,25 +97,9 @@ export const LABEL_TAXONOMY = [
   // Persona — dynamically derived from .agents/personas/*.md
   ...buildPersonaLabels(),
 
-  // Context
-  {
-    name: CONTEXT_LABELS.PRD,
-    color: LABEL_COLORS.CONTEXT,
-    description: 'Product Requirements Document',
-  },
-  {
-    name: CONTEXT_LABELS.TECH_SPEC,
-    color: LABEL_COLORS.CONTEXT,
-    description: 'Technical Specification',
-  },
-  {
-    name: CONTEXT_LABELS.ACCEPTANCE_SPEC,
-    color: LABEL_COLORS.CONTEXT,
-    description: 'Acceptance Specification (Gherkin scenarios)',
-  },
-
-  // Acceptance axis — explicit opt-out signal for Stories that
-  // intentionally have no acceptance-spec coverage.
+  // Acceptance axis — explicit opt-out signal for Epics that
+  // intentionally have no acceptance-table coverage (waives the Epic
+  // body's ## Acceptance Table section — Story #4324).
   {
     name: ACCEPTANCE_LABELS.N_A,
     color: LABEL_COLORS.ACCEPTANCE,

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -8,12 +8,69 @@
  */
 
 import { resolveBundleSizeEnvOverrides } from '../../../baselines/env-overrides.js';
-import { checkKernelVersion } from '../../../baselines/kernel.js';
+import {
+  checkKernelVersion,
+  getKindModule,
+} from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
 import { Logger } from '../../../Logger.js';
+import { isIgnoredByGlobs } from '../../../maintainability-utils.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
 
+/**
+ * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
+ * incident). The generation path already drops `ignoreGlobs`-matched files
+ * before they reach `rows` (both the canonical `buildDefaultMaintainabilityScorer`
+ * and the story-close `buildKindScorer`), so a freshly-generated baseline's
+ * `rollup["*"]` never includes an ignored file. But the floor check trusts the
+ * *stored* `rollup["*"]`: if a baseline is poisoned by some other route — a
+ * stale branch's older tooling, a hand-edit, a future generation bug — an
+ * ignored file's metric can still drag the global floor axis (e.g.
+ * maintainability `min`) below its floor and block every downstream close.
+ *
+ * This recomputes the global `*` aggregate over the baseline rows that are NOT
+ * matched by the gate's `ignoreGlobs`, using the kind's own canonical
+ * `rollup()` aggregator, so the floor axis reflects only the files the gate is
+ * meant to police. It is a **no-op for a correctly-generated baseline** (no
+ * ignored file is present in `rows`, so the filtered set is identical and the
+ * stored `rollup["*"]` is returned unchanged) and only affects the `*`
+ * component the incident poisons; named-component rollups are left as stored.
+ * The compare/regression stage is untouched — this only reshapes the floor
+ * input. All three `ignoreGlobs`-configured gates (maintainability, crap,
+ * duplication) are `path`-keyed, so the shared path matcher applies uniformly.
+ *
+ * Kept module-local (not exported): the poison-exclusion behaviour is covered
+ * end-to-end through `evaluateKind` by the `check-baselines.min-floor` suite,
+ * so there is no external consumer to justify widening the surface.
+ *
+ * @param {{ kind: string, baseline: { rollup?: object, rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
+ * @returns {object} the effective rollup to feed the floor check
+ */
+function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
+  const rollup = baseline?.rollup;
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return rollup;
+  const rows = baseline?.rows;
+  if (!Array.isArray(rows) || rows.length === 0) return rollup;
+  let mod;
+  try {
+    mod = getKindModule(kind);
+  } catch {
+    return rollup;
+  }
+  if (mod?.keyField !== 'path' || typeof mod.rollup !== 'function')
+    return rollup;
+  const kept = rows.filter((row) => {
+    const p = row?.path;
+    return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
+  });
+  // Nothing ignored is present → the stored rollup already excludes ignored
+  // files (the correct-baseline fast path); return it untouched.
+  if (kept.length === rows.length) return rollup;
+  const recomputed = mod.rollup(kept);
+  return { ...rollup, '*': recomputed?.['*'] ?? rollup?.['*'] };
+}
+
 function loadHeadBaseline(kind, cwd, configPath) {
   try {
     return { baseline: reader.load(kind, { cwd, configPath }) };
@@ -100,7 +157,13 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
-  const findings = applyFloors(kind, baseline.rollup, gateBlock.floors ?? {});
+  const floorRollup = rollupExcludingIgnored({
+    kind,
+    baseline,
+    ignoreGlobs: gateBlock.ignoreGlobs,
+    cwd,
+  });
+  const findings = applyFloors(kind, floorRollup, gateBlock.floors ?? {});
   const breaches = flattenBreaches(findings);
   const cmp = await evaluateCompare({ kind, gateBlock, scope, cwd });
   const rawCompare = runCompareStage(baseline, cmp);

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -27,7 +27,7 @@ import {
   PROJECT_ROOT,
   resolveConfig,
 } from '../config-resolver.js';
-
+import { sliceEpicBodyForDelivery } from '../epic-body-sections.js';
 import { Logger } from '../Logger.js';
 import {
   buildEnvelope,
@@ -163,8 +163,7 @@ function getVersion() {
 /**
  * Parse the work-breakdown hierarchy from a Task ticket body.
  *
- * Looks for patterns like: `Epic: #1`, `Story: #3`,
- * `PRD: #4`, `Tech Spec: #5`.
+ * Looks for patterns like: `Epic: #1`, `Story: #3`.
  *
  * @param {string} body
  * @returns {Record<string, number>}
@@ -177,7 +176,7 @@ export function parseHierarchy(body) {
   for (const match of matches) {
     const key = match[1].trim().toLowerCase().replace(/\s+/g, '');
     const val = Number.parseInt(match[2], 10);
-    result[key] = val; // e.g. { epic: 1, story: 3, prd: 4, techspec: 5 }
+    result[key] = val; // e.g. { epic: 1, story: 3 }
   }
   return result;
 }
@@ -234,6 +233,71 @@ export function extractStorySections(body) {
   return { acceptance, verify };
 }
 
+/**
+ * Remove one `## <heading>` section (heading line through the last line
+ * before the next `## ` heading, or EOF) from a Story body. Byte-preserving
+ * outside the removed span. No-op when the heading is absent. Case- and
+ * whitespace-tolerant to match `extractSectionList`.
+ *
+ * @param {string} body
+ * @param {string} heading
+ * @returns {string}
+ */
+function stripSection(body, heading) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  const pattern = new RegExp(
+    `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+    'mi',
+  );
+  const startMatch = body.match(pattern);
+  if (!startMatch || startMatch.index == null) return body;
+  const start = startMatch.index;
+  const afterHeading = start + startMatch[0].length;
+  const rest = body.slice(afterHeading);
+  const nextHeading = rest.search(/^##\s+/m);
+  const end = nextHeading === -1 ? body.length : afterHeading + nextHeading;
+  const before = body.slice(0, start).replace(/\n+$/, '\n');
+  const after = body.slice(end).replace(/^\n+/, '');
+  return (before + after).replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+/**
+ * Strip the inline `## Acceptance Criteria` / `## Acceptance` and `## Verify`
+ * sections from a Story body. Used to build the `taskInstructions` section
+ * when the dedicated `acceptanceCriteria` / `verificationCommands` envelope
+ * sections already carry those lists — so the binding acceptance/verify
+ * content appears exactly once in the hydrated envelope rather than being
+ * duplicated between the dedicated sections and the full task body.
+ *
+ * Each heading group is stripped only when its own dedicated section was
+ * emitted (`acceptance` gates `## Acceptance Criteria` + `## Acceptance`;
+ * `verify` gates `## Verify`). This keeps the strip symmetric with what was
+ * reproduced elsewhere in the envelope: a `## Verify` section that carried no
+ * bullets (so no dedicated `verificationCommands` section fired) is left
+ * intact in `taskInstructions` rather than being silently dropped. Both flags
+ * default to `true` so a no-argument call preserves the original
+ * strip-everything behaviour.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: boolean, verify?: boolean }} [opts]
+ * @returns {string}
+ */
+export function stripStorySectionsForTaskInstructions(
+  body,
+  { acceptance = true, verify = true } = {},
+) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  let out = body;
+  if (acceptance) {
+    out = stripSection(out, 'Acceptance Criteria');
+    out = stripSection(out, 'Acceptance');
+  }
+  if (verify) {
+    out = stripSection(out, 'Verify');
+  }
+  return out;
+}
+
 /**
  * Detect whether the dispatched unit is a 2-tier Story (Story is the
  * leaf, carries inline acceptance/verify) vs. a 4-tier Task (Task is
@@ -351,14 +415,16 @@ async function buildHierarchySections(task, provider, epicId, agentSettings) {
   const depth = agentSettings?.contextDepth ?? 'standard';
   const idsToFetch = [];
 
+  // Story #4324 — the context-ticket classes are retired: the Epic body IS
+  // the planning document (ideation sections + folded Tech Spec sections).
+  // `full` and `standard` fetch the identical Epic / Story pair; both
+  // branches are kept so the `contextDepth` setting stays a stable API
+  // surface.
   if (depth === 'full') {
     idsToFetch.push({ key: 'Epic', id: epicId || hierarchyKeys.epic });
-    idsToFetch.push({ key: 'PRD', id: hierarchyKeys.prd });
-    idsToFetch.push({ key: 'Tech Spec', id: hierarchyKeys.techspec });
     idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
   } else if (depth === 'standard') {
     idsToFetch.push({ key: 'Epic', id: epicId || hierarchyKeys.epic });
-    idsToFetch.push({ key: 'Tech Spec', id: hierarchyKeys.techspec });
     idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
   } else if (depth === 'minimal') {
     idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
@@ -370,7 +436,16 @@ async function buildHierarchySections(task, provider, epicId, agentSettings) {
       try {
         const t = await provider.getTicket(item.id);
         provenance.push(ticketSnapshot(t, retrievedAt));
-        return `### ${item.key}: ${t.title} (#${t.id})\n\n${t.body}\n`;
+        // Hydration section-slicing guardrail (Story #4340): the Epic body
+        // is sliced down to only the sections a delivery story agent acts
+        // on — Goal / Non-Goals / User Stories / Tech Spec (plus any
+        // operator-authored section, fail-open). Ideation / authoring /
+        // close machinery (## Context, ## Scope, ## Acceptance Criteria,
+        // and the ## Acceptance Table managed region) is dropped so
+        // per-story prompt size stays flat versus the pre-fold baseline.
+        const body =
+          item.key === 'Epic' ? sliceEpicBodyForDelivery(t.body ?? '') : t.body;
+        return `### ${item.key}: ${t.title} (#${t.id})\n\n${body}\n`;
       } catch (err) {
         const detail = err?.message ? `: ${err.message}` : '';
         Logger.warn(
@@ -474,9 +549,16 @@ function buildStaticSections(
     }
   }
 
+  // Track which dedicated section(s) were emitted so taskInstructions drops
+  // only the inline sections that were actually reproduced elsewhere in the
+  // envelope — keeping each binding acceptance/verify item present exactly
+  // once, without dropping a bulletless section that has no dedicated twin.
+  let acceptanceEmitted = false;
+  let verifyEmitted = false;
   if (isTwoTierStoryTask(task)) {
     const { acceptance, verify } = extractStorySections(task.body ?? '');
     if (acceptance.length > 0) {
+      acceptanceEmitted = true;
       sections.push({
         name: 'acceptanceCriteria',
         priority: DEFAULT_SECTION_PRIORITIES.acceptanceCriteria,
@@ -488,6 +570,7 @@ function buildStaticSections(
       });
     }
     if (verify.length > 0) {
+      verifyEmitted = true;
       sections.push({
         name: 'verificationCommands',
         priority: DEFAULT_SECTION_PRIORITIES.verificationCommands,
@@ -500,11 +583,24 @@ function buildStaticSections(
     }
   }
 
+  // When a dedicated acceptance/verify section carries that list, strip the
+  // matching inline heading(s) from the task body so they are not duplicated
+  // in taskInstructions. Each group is gated on its own section: an inline
+  // section with no dedicated twin (e.g. a bulletless `## Verify`) is left
+  // intact. When neither fired, taskInstructions is byte-identical to the
+  // full body.
+  const taskBody =
+    acceptanceEmitted || verifyEmitted
+      ? stripStorySectionsForTaskInstructions(task.body ?? '', {
+          acceptance: acceptanceEmitted,
+          verify: verifyEmitted,
+        })
+      : task.body;
   sections.push({
     name: 'taskInstructions',
     priority: DEFAULT_SECTION_PRIORITIES.taskInstructions,
     elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.taskInstructions,
-    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${task.body}`,
+    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${taskBody}`,
     source: { kind: 'ticket', ref: String(task.id) },
   });
 

package/.agents/scripts/lib/orchestration/doc-reader.js

@@ -4,6 +4,35 @@ import { getPaths } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
 import { applyBudget } from './planning-context-budget.js';
 
+/**
+ * Read an explicit list of doc files relative to `docsRoot`, returning one
+ * `{ name, path, content }` object per file that exists and reads cleanly.
+ * Missing or unreadable files are skipped silently (mirrors
+ * {@link readDocsFromRoot}'s per-file try/catch). Order is preserved from the
+ * input list. This is the shared read/normalize seam the per-Epic docs digest
+ * builds on (Story #4338) so there is a single home for the fs read path.
+ *
+ * @param {{ files: string[], docsRoot?: string }} args
+ * @returns {Promise<Array<{ name: string, path: string, content: string }>>}
+ */
+export async function readDocFiles({ files, docsRoot } = {}) {
+  const list = Array.isArray(files) ? files : [];
+  const root =
+    typeof docsRoot === 'string' && docsRoot.length > 0 ? docsRoot : '.';
+  const reads = list.map(async (name) => {
+    const full = path.join(root, name);
+    try {
+      const stat = await fs.promises.stat(full);
+      if (!stat.isFile()) return null;
+      const content = await fs.promises.readFile(full, 'utf-8');
+      return { name, path: name, content };
+    } catch (_e) {
+      return null;
+    }
+  });
+  return (await Promise.all(reads)).filter(Boolean);
+}
+
 async function readDocsFromRoot(docsRoot, settings) {
   const explicit =
     Array.isArray(settings.docsContextFiles) &&

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -0,0 +1,134 @@
+/**
+ * docs-digest.js — per-Epic docs digest builder (Story #4338).
+ *
+ * `/deliver` story sub-agents previously re-read every file in
+ * `project.docsContextFiles` on every Story, re-paying the full docs payload
+ * per child. This module produces a single **digest** — one compact markdown
+ * outline per configured doc — that the parent threads into every child prompt
+ * once. The digest gives each child enough shape (path, size, heading outline
+ * with line numbers, and the first paragraph under each `##` section) to decide
+ * which full files to pull on demand, instead of ingesting the whole set up
+ * front.
+ *
+ * The heavy lifting of reading + normalizing doc bodies is delegated to
+ * `doc-reader.js` (`readDocFiles`), keeping a single home for the fs read path.
+ */
+
+import { readDocFiles } from './doc-reader.js';
+
+/**
+ * Level-2 / level-3 markdown heading matcher. Mirrors the outline granularity
+ * the planning-context budget already uses so the two surfaces agree on what a
+ * "section" is.
+ */
+const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
+
+function byteLen(s) {
+  if (s == null) return 0;
+  return Buffer.byteLength(String(s), 'utf-8');
+}
+
+/**
+ * Extract the heading outline (level + text + 1-based line number) from a
+ * markdown body. Line numbers let a child jump straight to the section it
+ * needs when it pulls the full file.
+ *
+ * @param {string} content
+ * @returns {Array<{ level: number, text: string, line: number }>}
+ */
+function extractOutline(content) {
+  if (!content) return [];
+  const lines = String(content).split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = HEADING_RE.exec(lines[i]);
+    if (m) out.push({ level: m[1].length, text: m[2], line: i + 1 });
+  }
+  return out;
+}
+
+/**
+ * The first non-empty paragraph that follows a given heading line, up to the
+ * next heading or a blank-line paragraph break. Returns '' when the section
+ * has no prose (e.g. a heading immediately followed by a sub-heading).
+ *
+ * @param {string[]} lines full doc split into lines
+ * @param {number} headingLine 1-based line of the heading
+ * @returns {string}
+ */
+function firstParagraphAfter(lines, headingLine) {
+  const para = [];
+  for (let i = headingLine; i < lines.length; i++) {
+    const line = lines[i];
+    if (HEADING_RE.test(line)) break;
+    if (line.trim() === '') {
+      if (para.length > 0) break;
+      continue;
+    }
+    para.push(line.trim());
+  }
+  return para.join(' ').trim();
+}
+
+/**
+ * Render one doc's digest section: path + byte size, then a bulleted heading
+ * outline where each `##` bullet carries the first paragraph beneath it.
+ *
+ * @param {{ path: string, content: string }} doc
+ * @returns {string} markdown block
+ */
+function renderDocSection(doc) {
+  const content = typeof doc.content === 'string' ? doc.content : '';
+  const lines = content.split(/\r?\n/);
+  const outline = extractOutline(content);
+  const size = byteLen(content);
+
+  const parts = [`### \`${doc.path}\` (${size} bytes)`, ''];
+  if (outline.length === 0) {
+    parts.push('_No `##`/`###` headings._', '');
+    return parts.join('\n');
+  }
+
+  for (const h of outline) {
+    const indent = h.level === 3 ? '  ' : '';
+    parts.push(`${indent}- L${h.line} \`${'#'.repeat(h.level)}\` ${h.text}`);
+    if (h.level === 2) {
+      const para = firstParagraphAfter(lines, h.line);
+      if (para) parts.push(`${indent}  ${para}`);
+    }
+  }
+  parts.push('');
+  return parts.join('\n');
+}
+
+/**
+ * Build the per-Epic docs digest markdown from the configured docs context
+ * files. Missing files are skipped silently (the read seam returns only the
+ * files it could stat + read). Returns `null` when there is nothing to digest
+ * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
+ * `docsDigestPath` rather than writing an empty file.
+ *
+ * @param {{ docsContextFiles?: string[], docsRoot?: string }} args
+ * @returns {Promise<string|null>} the digest markdown, or null when there are
+ *   no files to digest.
+ */
+export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
+  const files = Array.isArray(docsContextFiles) ? docsContextFiles : [];
+  if (files.length === 0) return null;
+
+  const docs = await readDocFiles({ files, docsRoot });
+  if (docs.length === 0) return null;
+
+  const header = [
+    '# Docs digest',
+    '',
+    'Per-Epic outline of the project docs context set. Each entry lists the',
+    'file path, byte size, and its heading outline (with line numbers) plus',
+    'the first paragraph under each `##` section. Read the full file on demand',
+    'when a section looks relevant — do **not** ingest the whole set per Story.',
+    '',
+  ].join('\n');
+
+  const sections = docs.map(renderDocSection).join('\n');
+  return `${header}\n${sections}`.replace(/\n+$/, '\n');
+}

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

@@ -1,9 +1,11 @@
 /**
  * context.js — Phase 3 of the epic-plan-decompose pipeline (Story #2466).
  *
- * Builds the authoring context (PRD + Tech Spec bodies, heuristics, system
- * prompt, ticket cap) the host LLM / `epic-plan-decompose-author` Skill
- * consumes when producing the ticket JSON array.
+ * Builds the authoring context (the Epic body — which carries the folded
+ * Tech Spec sections and Acceptance Table per Story #4324 — plus
+ * heuristics, system prompt, ticket cap) the host LLM /
+ * `epic-plan-decompose-author` Skill consumes when producing the ticket
+ * JSON array.
  *
  * Extracted verbatim from `epic-plan-decompose.js`; both
  * `buildDecomposerSystemPrompt` and `buildDecompositionContext` retain
@@ -16,6 +18,7 @@ import {
   getLimits,
   resolvePreflightCeilings,
 } from '../../../config-resolver.js';
+import { hasTechSpecContent } from '../../../epic-body-sections.js';
 import { renderDecomposerSystemPrompt } from '../../../templates/decomposer-prompts.js';
 import { read as readPlanState } from '../../epic-plan-state-store.js';
 import { applyBudget } from '../../planning-context-budget.js';
@@ -83,27 +86,25 @@ async function readPlanningDecision(provider, epicId) {
   };
 }
 
-async function fetchPlanningTickets(provider, epicId) {
+async function fetchPlanningEpic(provider, epicId) {
   const epic = await provider.getEpic(epicId);
-  if (!epic?.linkedIssues?.prd || !epic.linkedIssues.techSpec) {
+  if (!epic || !hasTechSpecContent(epic.body ?? '')) {
     throw new Error(
-      `[Decomposer] Epic #${epicId} is missing linked PRD or Tech Spec. Run the Epic Planner first.`,
+      `[Decomposer] Epic #${epicId} body carries no Tech Spec sections (no ## Delivery Slicing). Run the Epic Planner (Phase 7) first.`,
     );
   }
-  const [prd, techSpec] = await Promise.all([
-    provider.getTicket(epic.linkedIssues.prd),
-    provider.getTicket(epic.linkedIssues.techSpec),
-  ]);
-  return { epic, prd, techSpec };
+  return { epic };
 }
 
 /**
  * Build the authoring context the host LLM (or the
  * `epic-plan-decompose-author` Skill) needs to produce the ticket JSON.
  *
- * PRD and Tech Spec bodies are bounded by the planning-context budget
- * (Epic #817 Story 9). Pass `{ fullContext: true }` (CLI: `--full-context`)
- * to restore the unbounded full bodies.
+ * The Epic body (ideation sections + folded Tech Spec sections +
+ * Acceptance Table — the AC-ID source for wave-0 BDD scaffold tags) is
+ * bounded by the planning-context budget (Epic #817 Story 9). Pass
+ * `{ fullContext: true }` (CLI: `--full-context`) to restore the
+ * unbounded full body.
  */
 export async function buildDecompositionContext(
   epicId,
@@ -111,7 +112,7 @@ export async function buildDecompositionContext(
   config = {},
   opts = {},
 ) {
-  const { epic, prd, techSpec } = await fetchPlanningTickets(provider, epicId);
+  const { epic } = await fetchPlanningEpic(provider, epicId);
   const { planningRisk, reviewRouting } = await readPlanningDecision(
     provider,
     epicId,
@@ -129,18 +130,18 @@ export async function buildDecompositionContext(
   });
 
   const budgeted = applyBudget(
-    [
-      { path: `prd-${prd.id}.md`, content: prd.body ?? '' },
-      { path: `tech-spec-${techSpec.id}.md`, content: techSpec.body ?? '' },
-    ],
+    [{ path: `epic-${epic.id}.md`, content: epic.body ?? '' }],
     planningLimits,
     { fullContext },
   );
-  const [prdItem, techSpecItem] = budgeted.items;
+  const [epicItem] = budgeted.items;
   return {
     epic: { id: epic.id, title: epic.title },
-    prd: projectBudgetedEntry(prdItem, prd, budgeted.mode),
-    techSpec: projectBudgetedEntry(techSpecItem, techSpec, budgeted.mode),
+    // Story #4324 — the Epic body is the single planning document: it
+    // carries the ideation sections, the folded Tech Spec sections
+    // (## Delivery Slicing first), and the ## Acceptance Table the wave-0
+    // BDD scaffold reads its AC IDs from.
+    epicBody: projectBudgetedEntry(epicItem, epic, budgeted.mode),
     heuristics,
     systemPrompt,
     maxTickets,