mandrel 1.81.0 → 1.83.0

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]',
     );
   }