mandrel 1.81.0 → 1.82.0

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/context-hydration-engine.js

@@ -27,7 +27,7 @@ import {
   PROJECT_ROOT,
   resolveConfig,
 } from '../config-resolver.js';
-
+import { stripEpicSection } 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;
 }
@@ -351,14 +350,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 +371,17 @@ 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-elision guardrail (Story #4324): the Epic
+        // body's ## Acceptance Table managed section is authoring/close
+        // machinery — never delivery context. Strip it before it reaches
+        // a story agent's prompt so per-story prompt size stays flat
+        // versus the pre-fold baseline (the old acceptance-spec ticket
+        // was never hydrated either).
+        const body =
+          item.key === 'Epic'
+            ? stripEpicSection(t.body ?? '', 'acceptanceTable')
+            : t.body;
+        return `### ${item.key}: ${t.title} (#${t.id})\n\n${body}\n`;
       } catch (err) {
         const detail = err?.message ? `: ${err.message}` : '';
         Logger.warn(

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,

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

@@ -5,7 +5,7 @@
  * Exports:
  *   - `assertDecomposeInputs(epic, epicId, tickets)` — entry guards.
  *   - `buildEpicSpecInput(epic, epicId)` — projection used by
- *     `renderSpec`; runs `ensurePlanningArtifacts` defensively so the
+ *     `renderSpec`; the Epic body already carries the folded planning
  *     spec body carries the `## Planning Artifacts` section the
  *     cascade-close path depends on.
  *   - `validateTickets(tickets, config)` — runs the cross-link / freshness
@@ -19,6 +19,7 @@
  * @module lib/orchestration/epic-plan-decompose/phases/persist-helpers
  */
 
+import { hasTechSpecContent } from '../../../epic-body-sections.js';
 import { gitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
 import { TYPE_LABELS } from '../../../label-constants.js';
@@ -29,10 +30,7 @@ import {
 } from '../../epic-plan-state-store.js';
 import { validateTaskBodies } from '../../task-body-validator.js';
 import { validateAndNormalizeTickets } from '../../ticket-validator.js';
-import {
-  ensurePlanningArtifacts,
-  resolveConflictPolicy,
-} from './planning-artifacts.js';
+import { resolveConflictPolicy } from './planning-artifacts.js';
 
 export function assertDecomposeInputs(epic, epicId, tickets) {
   if (!epic) {
@@ -43,9 +41,9 @@ export function assertDecomposeInputs(epic, epicId, tickets) {
       `[epic-plan-decompose] Ticket #${epicId} is not a ${TYPE_LABELS.EPIC}.`,
     );
   }
-  if (!epic.linkedIssues?.prd || !epic.linkedIssues?.techSpec) {
+  if (!hasTechSpecContent(epic.body ?? '')) {
     throw new Error(
-      `[epic-plan-decompose] Epic #${epicId} is missing a linked PRD or Tech Spec. Run /epic-plan-spec first.`,
+      `[epic-plan-decompose] Epic #${epicId} body carries no Tech Spec sections (no ## Delivery Slicing). Run /plan Phase 7 first.`,
     );
   }
   if (!Array.isArray(tickets)) {
@@ -56,7 +54,7 @@ export function assertDecomposeInputs(epic, epicId, tickets) {
 }
 
 export function buildEpicSpecInput(epic, epicId) {
-  const epicBody = ensurePlanningArtifacts(epic.body ?? '', epic.linkedIssues);
+  const epicBody = epic.body ?? '';
   const epicSpecInput = { id: epicId, title: epic.title };
   if (epicBody.length > 0) epicSpecInput.body = epicBody;
   return epicSpecInput;
@@ -117,8 +115,7 @@ export async function seedPlanState(provider, epicId, epic) {
     epicId,
     seed: {
       spec: {
-        prdId: epic.linkedIssues.prd,
-        techSpecId: epic.linkedIssues.techSpec,
+        techSpecPersisted: hasTechSpecContent(epic.body ?? ''),
         completedAt: null,
       },
     },

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

@@ -1,11 +1,10 @@
 /**
  * planning-artifacts.js — Phase 1 of the epic-plan-decompose pipeline
- * (Story #2466). Owns the `## Planning Artifacts` body shim and the
- * cross-Story conflict-policy resolver.
+ * (Story #2466). Owns the cross-Story conflict-policy resolver.
  *
- * Extracted verbatim from `epic-plan-decompose.js` so the named exports
- * the existing unit tests import (`ensurePlanningArtifacts`) keep their
- * public surface byte-identical.
+ * Story #4324 retired the `## Planning Artifacts` body shim
+ * (`ensurePlanningArtifacts`) with the context-ticket classes — the Epic
+ * body now carries the planning content itself as managed sections.
  *
  * @module lib/orchestration/epic-plan-decompose/phases/planning-artifacts
  */
@@ -13,39 +12,6 @@
 import { resolveListValue } from '../../../config/shared.js';
 import { DEFAULT_REGISTRY_PATTERNS } from '../../ticket-validator-conflicts.js';
 
-/**
- * Ensure the supplied Epic body carries a `## Planning Artifacts` section.
- * Idempotent — when the section already exists the body is returned
- * verbatim; when it's missing and `linkedIssues` carries resolved ids
- * the section is appended exactly once using the canonical
- * `- [ ] PRD: #N` / `Tech Spec: #N` / `Acceptance Spec: #N` lines that
- * `issue-link-parser.js` recognises (so cascade-close still resolves the
- * linked tickets).
- *
- * Story #2283.
- *
- * @param {string} body
- * @param {{ prd: number|null, techSpec: number|null, acceptanceSpec: number|null } | undefined | null} linkedIssues
- * @returns {string}
- */
-export function ensurePlanningArtifacts(body, linkedIssues) {
-  const safeBody = typeof body === 'string' ? body : '';
-  if (safeBody.includes('## Planning Artifacts')) return safeBody;
-  if (!linkedIssues) return safeBody;
-  const lines = [];
-  if (Number.isInteger(linkedIssues.prd)) {
-    lines.push(`- [ ] PRD: #${linkedIssues.prd}`);
-  }
-  if (Number.isInteger(linkedIssues.techSpec)) {
-    lines.push(`- [ ] Tech Spec: #${linkedIssues.techSpec}`);
-  }
-  if (Number.isInteger(linkedIssues.acceptanceSpec)) {
-    lines.push(`- [ ] Acceptance Spec: #${linkedIssues.acceptanceSpec}`);
-  }
-  if (lines.length === 0) return safeBody;
-  return `${safeBody}\n\n## Planning Artifacts\n${lines.join('\n')}\n`;
-}
-
 /**
  * Resolve the cross-Story conflict-finding policy from `_config.planning`.
  * Both flags default to `false` so existing repos keep the advisory-only

package/.agents/scripts/lib/orchestration/epic-plan-lease-guard.js

@@ -28,9 +28,10 @@
  *                                operator passed `--force` (a deliberate
  *                                re-decompose that closes the old tree).
  *
- * The PRD / Tech Spec find-or-create idempotency already lives in
- * `phases/plan-epic.js` (keyed on `epic.linkedIssues`); these guards add the
- * cross-run mutual exclusion and the child-duplication refusal around it.
+ * The spec-persist idempotency already lives in `phases/plan-epic.js`
+ * (keyed on the Epic body's managed planning sections); these guards add
+ * the cross-run mutual exclusion and the child-duplication refusal
+ * around it.
  */
 
 import { getGitHub } from '../config/github.js';
@@ -341,12 +342,10 @@ export async function assertNoOpenPlanChildren({
   const openChildren = (children ?? []).filter((t) => {
     const labels = Array.isArray(t.labels) ? t.labels : [];
     const isOpen = t.state === undefined || t.state === 'open';
-    // Context spec tickets (PRD / Tech Spec / Acceptance Spec) carry a
-    // `context::*` label and — since the `createTicket` factory injects
-    // `type::story` by default — also `type::story`. They are reference
-    // artifacts that stay open across delivery, NOT plan children, so they
-    // MUST be excluded here: counting them would make every first decompose
-    // (where the three context tickets are the only open children) refuse.
+    // Legacy context spec tickets (the pre-#4324 Tech Spec / Acceptance
+    // Spec artifacts) carry a `context::*` label. Historical Epics keep
+    // them (forward-only cutover, no backfill), so they are still
+    // excluded here: they are reference artifacts, not plan children.
     const isContext = labels.some(
       (l) => typeof l === 'string' && l.startsWith('context::'),
     );

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

@@ -2,7 +2,7 @@
  * phases/authoring-context.js — emit-context phase.
  *
  * Builds the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the PRD and Tech Spec.
+ * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
  * Returns a plain JSON-serialisable object; never hits the network beyond
  * the provider call needed to load the Epic.
  */
@@ -16,6 +16,7 @@ import {
 import { scanBddScenarios } from '../../../bdd-scenario-scanner.js';
 import { buildCodebaseSnapshot } from '../../../codebase-snapshot.js';
 import { getLimits, PROJECT_ROOT } from '../../../config-resolver.js';
+import { hasEpicSection } from '../../../epic-body-sections.js';
 import { scanMemoryFreshness } from '../../../feedback-loop/memory-freshness.js';
 import { fetchPriorFeedback } from '../../../feedback-loop/prior-feedback-fetcher.js';
 import { Logger } from '../../../Logger.js';
@@ -24,7 +25,6 @@ import { applyBudget } from '../../planning-context-budget.js';
 import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
 import {
   ACCEPTANCE_SPEC_SYSTEM_PROMPT,
-  PRD_SYSTEM_PROMPT,
   TECH_SPEC_SYSTEM_PROMPT,
 } from './prompts.js';
 import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
@@ -59,7 +59,7 @@ export function resolveMemoryDir({ github } = {}) {
 
 /**
  * Build the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the PRD and Tech Spec.
+ * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
  *
  * `docsContext` is bounded by the planning-context budget (Epic #817 Story 9):
  * over-budget payloads downgrade to a summary representation with headings +
@@ -205,12 +205,18 @@ export async function buildAuthoringContext(
       title: epic.title,
       body: epicBody.mode === 'full' ? epic.body : null,
       bodySummary: epicBody.mode === 'summary' ? epicBody.items[0] : null,
-      linkedIssues: epic.linkedIssues ?? { prd: null, techSpec: null },
+      // Story #4324: the context-ticket classes are retired. A re-planned
+      // Epic's previous Tech Spec / Acceptance Table content rides along
+      // inside `body` (managed sections), which is how the author keeps
+      // AC IDs stable across re-plans.
+      planningSections: {
+        techSpec: hasEpicSection(epic.body ?? '', 'techSpec'),
+        acceptanceTable: hasEpicSection(epic.body ?? '', 'acceptanceTable'),
+      },
     },
     docsContext,
     codebaseSnapshot,
     systemPrompts: {
-      prd: PRD_SYSTEM_PROMPT,
       techSpec: TECH_SPEC_SYSTEM_PROMPT,
       acceptanceSpec: ACCEPTANCE_SPEC_SYSTEM_PROMPT,
     },

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

@@ -4,25 +4,46 @@
  * Extracted from `epic-plan-spec.js` (refs #3685) so the top-level entry
  * stays a thin wire-up that scores at or above the maintainability floor;
  * the option schema and the epic-id guards live here.
+ *
+ * Story #4324: the separate-ticket persist flags `--techspec` /
+ * `--acceptance-spec` are retired with the context-ticket classes. The
+ * authored content now lands as sections of the Epic body; pass it via
+ * `--tech-spec <file>` and `--acceptance-table <file>`. The old flags fail
+ * with a usage error naming the removal.
  */
 
 import { parseArgs } from 'node:util';
 
+/** Retired flags → the replacement guidance surfaced in the usage error. */
+const RETIRED_FLAGS = Object.freeze({
+  '--techspec':
+    '--techspec was retired by the context-ticket fold (Story #4324): the Tech Spec is no longer a separate context::tech-spec ticket. Pass --tech-spec <file> — the content lands as a managed section of the Epic body.',
+  '--acceptance-spec':
+    '--acceptance-spec was retired by the context-ticket fold (Story #4324): the Acceptance Spec is no longer a separate context::acceptance-spec ticket. Pass --acceptance-table <file> — the AC-ID table lands as the ## Acceptance Table section of the Epic body.',
+});
+
 /**
  * Parse and validate the `epic-plan-spec` CLI arguments.
  *
  * @param {string[]} [argv] Defaults to `process.argv.slice(2)`.
  * @returns {{ values: Record<string, unknown>, epicId: number }}
- * @throws {Error} when `--epic` is missing or not a number.
+ * @throws {Error} when `--epic` is missing or not a number, or when a
+ *   retired separate-ticket persist flag is supplied.
  */
 export function parseEpicPlanSpecArgs(argv = process.argv.slice(2)) {
+  for (const arg of argv) {
+    const flag = arg.split('=')[0];
+    if (RETIRED_FLAGS[flag]) {
+      throw new Error(`[epic-plan-spec] ${RETIRED_FLAGS[flag]}`);
+    }
+  }
+
   const { values } = parseArgs({
     args: argv,
     options: {
       epic: { type: 'string' },
-      prd: { type: 'string' },
-      techspec: { type: 'string' },
-      'acceptance-spec': { type: 'string' },
+      'tech-spec': { type: 'string' },
+      'acceptance-table': { type: 'string' },
       'risk-verdict': { type: 'string' },
       force: { type: 'boolean', default: false },
       'force-review': { type: 'boolean', default: false },
@@ -35,7 +56,7 @@ export function parseEpicPlanSpecArgs(argv = process.argv.slice(2)) {
 
   if (!values.epic) {
     throw new Error(
-      'Usage: epic-plan-spec.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --prd <file> --techspec <file> --risk-verdict <file> [--acceptance-spec <file>]) [--force]',
+      'Usage: epic-plan-spec.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --tech-spec <file> --risk-verdict <file> [--acceptance-table <file>]) [--force]',
     );
   }