mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -0,0 +1,213 @@
+/**
+ * consolidation-precondition.js — deterministic dispatch gate for the Phase
+ * 8.3 Holistic Consolidation sub-agent (Story #4431, Epic #4429).
+ *
+ * The Phase 8.3 consolidation critic (`epic-plan-consolidate`) is a genuine
+ * fresh-context `Agent` dispatch — every call re-pays the full always-loaded
+ * context (`.agents/instructions.md` and its always-on rules, § 4). When the
+ * decomposer's draft `tickets.json` already matches the Tech Spec's `##
+ * Delivery Slicing` target 1:1 (same shippable-Story count, and the
+ * `depends_on` shape already agrees with each slice's declared
+ * "Independent?" answer), there is nothing left for the critic to
+ * reconcile — dispatching it is pure token spend for a no-op. This module
+ * computes that decision **deterministically**, off the same two inputs the
+ * critic itself reads (the draft array and the Epic body's Delivery Slicing
+ * table), so `helpers/plan-epic.md` Phase 8.3 can skip the sub-agent
+ * dispatch when it is provably safe to.
+ *
+ * **Fail-open by design.** Every ambiguous case — a missing or unparseable
+ * Delivery Slicing section, an unparseable "Independent?" cell — resolves to
+ * `dispatch: true`. This gate can only ever *save* a dispatch when it is
+ * confident the critic has nothing to do; it never disables the critic's
+ * ability to catch a real divergence. Phase 8.4 (reachability critic), 8.5
+ * (pre-mortem critic), and the deterministic ticket validator are
+ * unconditional — this precondition governs only the 8.3 dispatch.
+ *
+ * Pure, synchronous, no I/O — callers own reading `tickets.json` and the
+ * Epic body off disk / the GitHub API.
+ */
+
+import { DELIVERY_SLICING_RE as DELIVERY_SLICING_HEADING_RE } from '../epic-body-sections.js';
+
+/** A row is a markdown table line: starts with `|` once trimmed. */
+const TABLE_ROW_RE = /^\|/;
+
+/** A markdown table separator row: `|---|:---:|---:|` (dashes, colons, pipes only). */
+const TABLE_SEPARATOR_RE = /^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?$/;
+
+/** The literal goal-section token that marks the wave-0 BDD scaffold Story. */
+const BDD_SCAFFOLD_GOAL_TOKEN = 'bdd-scaffold';
+
+/**
+ * Split one markdown table row into trimmed cell strings.
+ *
+ * @param {string} line
+ * @returns {string[]}
+ */
+function splitTableRow(line) {
+  let trimmed = line.trim();
+  if (trimmed.startsWith('|')) trimmed = trimmed.slice(1);
+  if (trimmed.endsWith('|')) trimmed = trimmed.slice(0, -1);
+  return trimmed.split('|').map((cell) => cell.trim());
+}
+
+/**
+ * Parse an "Independent?" cell per the pinned rule: match the cell's
+ * leading word case-insensitively as `Yes` or `No`. Any other leading word
+ * (or an empty cell) is unparseable and returns `null` — the caller must
+ * fail open (`dispatch: true`) rather than guess.
+ *
+ * @param {string} cell
+ * @returns {boolean|null} `true` for Yes, `false` for No, `null` when unparseable.
+ */
+function parseIndependentCell(cell) {
+  const match = String(cell ?? '')
+    .trim()
+    .match(/^[A-Za-z]+/);
+  if (!match) return null;
+  const word = match[0].toLowerCase();
+  if (word === 'yes') return true;
+  if (word === 'no') return false;
+  return null;
+}
+
+/**
+ * Locate and parse the `## Delivery Slicing` markdown table out of the Epic
+ * body (which carries the folded Tech Spec sections — Story #4324). Returns
+ * `null` when the heading is absent, no table follows it, the table has no
+ * "Independent?" column, or any data row's "Independent?" cell is
+ * unparseable — every one of those is a fail-open signal for the caller.
+ *
+ * @param {string} epicBody
+ * @returns {{ slice: string, independent: boolean }[] | null}
+ */
+export function parseDeliverySlicingTable(epicBody) {
+  if (typeof epicBody !== 'string' || epicBody.length === 0) return null;
+
+  const lines = epicBody.split(/\r?\n/);
+  const headingIdx = lines.findIndex((line) =>
+    DELIVERY_SLICING_HEADING_RE.test(line.trim()),
+  );
+  if (headingIdx === -1) return null;
+
+  let i = headingIdx + 1;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  if (i >= lines.length || !TABLE_ROW_RE.test(lines[i].trim())) return null;
+
+  const headerCells = splitTableRow(lines[i]);
+  i++;
+  if (i >= lines.length || !TABLE_SEPARATOR_RE.test(lines[i].trim())) {
+    return null;
+  }
+  i++;
+
+  const independentIdx = headerCells.findIndex((cell) =>
+    /independent/i.test(cell),
+  );
+  if (independentIdx === -1) return null;
+
+  const rows = [];
+  while (i < lines.length && TABLE_ROW_RE.test(lines[i].trim())) {
+    const cells = splitTableRow(lines[i]);
+    const independent = parseIndependentCell(cells[independentIdx]);
+    if (independent === null) return null; // unparseable cell → fail open
+    rows.push({ slice: (cells[0] ?? '').trim(), independent });
+    i++;
+  }
+
+  return rows.length > 0 ? rows : null;
+}
+
+/**
+ * True when `story` is the recognized wave-0 BDD scaffold Story — identified
+ * by the literal `bdd-scaffold` goal token the `epic-plan-decompose-author`
+ * skill's WAVE-0 BDD SCAFFOLD STORY section requires. Scaffold Stories are
+ * not a Delivery Slicing slice, so they are excluded from the count
+ * comparison — BDD-adopting consumer repos still benefit from the
+ * precondition gate rather than always paying the 8.3 dispatch.
+ *
+ * @param {{ body?: unknown }} story
+ * @returns {boolean}
+ */
+function isBddScaffoldStory(story) {
+  const body = story?.body;
+  return (
+    typeof body === 'string' &&
+    body.toLowerCase().includes(BDD_SCAFFOLD_GOAL_TOKEN)
+  );
+}
+
+/**
+ * Evaluate whether the Phase 8.3 consolidation sub-agent needs to run.
+ *
+ * @param {object} input
+ * @param {object[]} input.draftStories - The draft `tickets.json` array
+ *   (`epic-plan-decompose-author`'s output) — raw Story ticket objects with
+ *   top-level `slug` / `depends_on` / `body` (serialized string).
+ * @param {string} input.epicBody - The Epic body carrying the folded Tech
+ *   Spec sections (`## Delivery Slicing` onward).
+ * @returns {{ dispatch: boolean, reasons: string[] }} `dispatch: false` only
+ *   when the draft matches the Delivery Slicing table 1:1 in count and
+ *   dependency shape; `dispatch: true` (with `reasons`) otherwise, including
+ *   every fail-open case.
+ */
+export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
+  if (!Array.isArray(draftStories)) {
+    throw new TypeError(
+      'evaluateConsolidationPrecondition: draftStories must be an array',
+    );
+  }
+
+  const slicing = parseDeliverySlicingTable(epicBody);
+  if (!slicing) {
+    return {
+      dispatch: true,
+      reasons: [
+        'Delivery Slicing section is missing or unparseable — fail-open to the critic.',
+      ],
+    };
+  }
+
+  const slicedStories = draftStories.filter(
+    (story) => !isBddScaffoldStory(story),
+  );
+
+  if (slicedStories.length !== slicing.length) {
+    return {
+      dispatch: true,
+      reasons: [
+        `Story count diverges from Delivery Slicing: ${slicing.length} proposed slice(s) vs ${slicedStories.length} non-scaffold draft Story(ies).`,
+      ],
+    };
+  }
+
+  const reasons = [];
+  for (let idx = 0; idx < slicing.length; idx++) {
+    const slice = slicing[idx];
+    const story = slicedStories[idx];
+    const dependsOn = Array.isArray(story?.depends_on) ? story.depends_on : [];
+    const hasDeps = dependsOn.length > 0;
+    const storyLabel = story?.slug ?? story?.title ?? `<story ${idx + 1}>`;
+
+    if (slice.independent === false && !hasDeps) {
+      reasons.push(
+        `Slice "${slice.slice}" (position ${idx + 1}) is marked Independent: No but draft Story "${storyLabel}" declares no depends_on.`,
+      );
+    } else if (slice.independent === true && hasDeps) {
+      reasons.push(
+        `Slice "${slice.slice}" (position ${idx + 1}) is marked Independent: Yes but draft Story "${storyLabel}" declares depends_on [${dependsOn.join(', ')}].`,
+      );
+    }
+  }
+
+  if (reasons.length > 0) {
+    return { dispatch: true, reasons };
+  }
+
+  return {
+    dispatch: false,
+    reasons: [
+      `Draft matches Delivery Slicing 1:1 in count and dependency shape (${slicing.length} slice(s)) — skipping the 8.3 consolidation dispatch.`,
+    ],
+  };
+}

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

@@ -1,16 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
-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.
+ * Missing or unreadable files are skipped silently. 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 }>>}
@@ -32,92 +29,3 @@ export async function readDocFiles({ files, docsRoot } = {}) {
   });
   return (await Promise.all(reads)).filter(Boolean);
 }
-
-async function readDocsFromRoot(docsRoot, settings) {
-  const explicit =
-    Array.isArray(settings.docsContextFiles) &&
-    settings.docsContextFiles.length > 0;
-  const usedFallback = !explicit;
-  let targetFiles;
-  if (explicit) {
-    targetFiles = settings.docsContextFiles.map((f) => ({
-      name: f,
-      full: path.join(docsRoot, f),
-    }));
-  } else {
-    const entries = fs.readdirSync(docsRoot, { withFileTypes: true });
-    targetFiles = entries
-      .filter((e) => e.isFile() && e.name.endsWith('.md'))
-      .map((e) => ({ name: e.name, full: path.join(docsRoot, e.name) }));
-  }
-
-  const reads = targetFiles.map(async ({ name, full }) => {
-    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;
-    }
-  });
-
-  const docs = (await Promise.all(reads)).filter(Boolean);
-  return { docs, usedFallback };
-}
-
-/**
- * Read project documentation, returning raw doc objects so callers can apply
- * the planning-context budget themselves. Each entry is `{ name, path,
- * content }`. The legacy single-string concatenation is no longer the public
- * surface — use {@link buildDocsContext} when an envelope-shaped value is
- * needed.
- *
- * @param {object} settings — Resolved config bag (`project.paths.docsRoot`,
- *   `project.docsContextFiles`) or legacy-shim view (same shape).
- * @returns {Promise<{ docs: Array<{name: string, path: string, content: string}>, usedFallback: boolean }>}
- */
-export async function scrapeProjectDocs(settings) {
-  // `settings` is the legacy-shim view (`{ paths, docsContextFiles, ... }`)
-  // OR the post-reshape canonical (`{ project: { paths, ... } }`). Under the
-  // resolver shim `agentSettings.paths === project.paths`, so re-wrap to the
-  // canonical shape `getPaths` consumes.
-  const docsRoot = getPaths({
-    project: { paths: settings?.project?.paths ?? settings?.paths },
-  }).docsRoot;
-  if (!docsRoot || !fs.existsSync(docsRoot)) {
-    return { docs: [], usedFallback: false };
-  }
-  Logger.info(`[Epic Planner] Scraping project docs from ${docsRoot}...`);
-  try {
-    const result = await readDocsFromRoot(docsRoot, settings);
-    if (result.usedFallback) {
-      Logger.warn(
-        '[Epic Planner] ⚠️  project.docsContextFiles is unset — falling back to every top-level *.md under docsRoot. Configure docsContextFiles for production planning.',
-      );
-    }
-    return result;
-  } catch (err) {
-    Logger.warn(
-      `[Epic Planner] Warning: Failed to read docsRoot: ${err.message}`,
-    );
-    return { docs: [], usedFallback: false };
-  }
-}
-
-/**
- * Build the `docsContext` value emitted in `--emit-context` envelopes.
- * Reads the docs and applies the planning-context budget so over-budget
- * payloads downgrade to summary mode automatically. Callers pass
- * `{ fullContext: true }` to honour the `--full-context` CLI opt-in.
- *
- * @param {object} settings — Resolved config bag (same shape as `scrapeProjectDocs`).
- * @param {{ maxBytes?: number, summaryMode?: 'auto'|'always'|'never' }} [planningLimits]
- * @param {{ fullContext?: boolean }} [opts]
- * @returns {Promise<{ mode: 'full'|'summary', items: Array<object>, totalBytes: number, usedFallback: boolean }>}
- */
-export async function buildDocsContext(settings, planningLimits, opts = {}) {
-  const { docs, usedFallback } = await scrapeProjectDocs(settings);
-  const budgeted = applyBudget(docs, planningLimits, opts);
-  return { ...budgeted, usedFallback };
-}

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

@@ -12,8 +12,16 @@
  *
  * The heavy lifting of reading + normalizing doc bodies is delegated to
  * `doc-reader.js` (`readDocFiles`), keeping a single home for the fs read path.
+ *
+ * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
+ * generate-and-write export so the planner-context surface
+ * (`epic-plan-spec.js` / `authoring-context.js`) can produce a session docs
+ * digest without duplicating the mkdir+writeFile plumbing
+ * `epic-deliver-prepare.js` already owns for the delivery-children digest.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { readDocFiles } from './doc-reader.js';
 
 /**
@@ -132,3 +140,29 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
   const sections = docs.map(renderDocSection).join('\n');
   return `${header}\n${sections}`.replace(/\n+$/, '\n');
 }
+
+/**
+ * Build the docs digest and write it to `outputPath`, returning `null` (no
+ * write) when there is nothing to digest. This is the single shared
+ * generate-and-persist export both digest producers call: the per-Epic
+ * delivery-children digest (`epic-deliver-prepare.js`) and the planner-
+ * context digest (`epic-plan-spec.js` → `authoring-context.js`, Story
+ * #4433). Callers own path construction (temp-root layout, epic id, etc.)
+ * so both surfaces can keep — or deliberately share — their own convention;
+ * this function only owns "build digest, ensure parent dir, write file".
+ *
+ * @param {{ docsContextFiles?: string[], docsRoot?: string, outputPath: string }} args
+ * @returns {Promise<{ digest: string, outputPath: string } | null>}
+ */
+export async function ensureDocsDigest({
+  docsContextFiles,
+  docsRoot,
+  outputPath,
+} = {}) {
+  const digest = await buildDocsDigest({ docsContextFiles, docsRoot });
+  if (digest == null) return null;
+
+  await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.promises.writeFile(outputPath, digest, 'utf-8');
+  return { digest, outputPath };
+}

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

@@ -15,18 +15,14 @@ import {
 } from '../../../bdd-runner-detect.js';
 import { scanBddScenarios } from '../../../bdd-scenario-scanner.js';
 import { buildCodebaseSnapshot } from '../../../codebase-snapshot.js';
-import { getLimits, PROJECT_ROOT } from '../../../config-resolver.js';
+import { getLimits, getPaths, 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';
-import { buildDocsContext } from '../../doc-reader.js';
+import { ensureDocsDigest } from '../../docs-digest.js';
 import { applyBudget } from '../../planning-context-budget.js';
 import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
-import {
-  ACCEPTANCE_SPEC_SYSTEM_PROMPT,
-  TECH_SPEC_SYSTEM_PROMPT,
-} from './prompts.js';
 import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
@@ -57,16 +53,59 @@ export function resolveMemoryDir({ github } = {}) {
   return path.join(os.homedir(), '.claude', 'projects', repo, 'memory');
 }
 
+/**
+ * Build the digest-first `docsContext` envelope field (Story #4433 — hard
+ * cutover of the § 3.1 planning read contract to digest-first with
+ * pull-on-demand, mirroring the Story #4324 delivery-children cutover).
+ *
+ * Ensures a docs digest exists at the **same** per-Epic temp path the
+ * `/deliver` story sub-agents already consume
+ * (`<tempRoot>/epic-<epicId>/docs-digest.md`) via the shared
+ * `ensureDocsDigest` export in `docs-digest.js` — one generator, one file,
+ * reused across the planning and delivery surfaces for the same Epic. The
+ * envelope carries only the digest path, not embedded doc content; the
+ * planner (host LLM or the `epic-plan-spec-author` Skill) reads the digest
+ * and pulls a full file/section on demand when it bears on the decision.
+ *
+ * Returns `null` — a silent no-op — when `project.docsContextFiles` is not
+ * configured. There is no scrape-every-markdown-under-docsRoot fallback for
+ * planning; that fallback remains a `doc-reader.js` primitive used
+ * elsewhere, not part of this envelope.
+ *
+ * @param {{ epicId: number, settings: object, cwd: string }} args
+ * @returns {Promise<{ mode: 'digest', digestPath: string } | null>}
+ */
+async function buildPlanningDocsContext({ epicId, settings, cwd }) {
+  const docsContextFiles = Array.isArray(settings?.docsContextFiles)
+    ? settings.docsContextFiles
+    : [];
+  if (docsContextFiles.length === 0) return null;
+
+  const paths = getPaths({ project: { paths: settings?.paths } });
+  const docsRoot = path.resolve(cwd, paths.docsRoot);
+  const relPath = path.join(paths.tempRoot, `epic-${epicId}`, 'docs-digest.md');
+  const absPath = path.resolve(cwd, relPath);
+
+  const result = await ensureDocsDigest({
+    docsContextFiles,
+    docsRoot,
+    outputPath: absPath,
+  });
+  if (!result) return null;
+  return { mode: 'digest', digestPath: relPath };
+}
+
 /**
  * Build the authoring context the host LLM (or the
  * `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 +
- * bounded excerpts. Pass `{ fullContext: true }` (CLI: `--full-context`) to
- * restore the unbounded full-body envelope. The Epic body itself is always
- * subject to the same budget so a sprawling Epic narrative cannot bypass the
- * cap by riding on top of `docsContext`.
+ * `docsContext` is digest-first (Story #4433): a pointer at the per-Epic
+ * docs digest rather than embedded doc content, `null` when
+ * `project.docsContextFiles` is unset. The Epic body itself stays bounded by
+ * the planning-context budget (Epic #817 Story 9) — over-budget bodies
+ * downgrade to a summary representation with headings + bounded excerpts.
+ * Pass `{ fullContext: true }` (CLI: `--full-context`) to restore the
+ * unbounded full Epic body.
  */
 export async function buildAuthoringContext(
   epicId,
@@ -80,10 +119,12 @@ export async function buildAuthoringContext(
   }
 
   const planningLimits = getLimits(settings).planningContext;
-  const { fullContext = false } = opts;
+  const { fullContext = false, cwd = PROJECT_ROOT } = opts;
 
-  const docsContext = await buildDocsContext(settings, planningLimits, {
-    fullContext,
+  const docsContext = await buildPlanningDocsContext({
+    epicId: epic.id,
+    settings,
+    cwd,
   });
 
   const epicBody = applyBudget(
@@ -216,10 +257,6 @@ export async function buildAuthoringContext(
     },
     docsContext,
     codebaseSnapshot,
-    systemPrompts: {
-      techSpec: TECH_SPEC_SYSTEM_PROMPT,
-      acceptanceSpec: ACCEPTANCE_SPEC_SYSTEM_PROMPT,
-    },
     bddRunner,
     bddScenarios,
     memoryFreshness,

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

@@ -20,6 +20,10 @@ import {
 } from '../../epic-plan-state-store.js';
 import { resolveReviewRouting } from '../../plan-review-routing.js';
 import { deriveRiskEnvelope } from '../../planning-risk.js';
+import {
+  formatMissingSectionMessage,
+  validateSpecSections,
+} from '../../spec-section-validator.js';
 import { upsertStructuredComment } from '../../ticketing.js';
 import { planEpic } from './plan-epic.js';
 import { runSpecFreshnessCheck } from './spec-freshness.js';
@@ -109,6 +113,24 @@ export async function runSpecPhase(
     );
   }
 
+  // Story #4403 (Finding 3): the "## Delivery Slicing" presence gate — the
+  // Phase 8-side anchor the Holistic Consolidation pass reconciles against —
+  // is validated here, against the in-memory authored content, before any
+  // GitHub mutation (lease acquisition, Epic body write, structured
+  // comments). This replaces the retired standalone `epic-plan-spec-validate.js`
+  // CLI / Phase 7.5 workflow step, whose documented ordering ran the check
+  // AFTER the persist path had already written to GitHub and deleted the
+  // temp file it read — so the "blocking gate" could never actually block.
+  const sectionCheck = validateSpecSections({ body: techSpecContent });
+  if (!sectionCheck.ok) {
+    throw new Error(
+      formatMissingSectionMessage({
+        techspecPath: `Epic #${epicId} authored Tech Spec`,
+        missing: sectionCheck.missing,
+      }),
+    );
+  }
+
   // Story #4145 — probe the project's BDD runner. When none is detected
   // (`fallback === true`, e.g. a node:test repo with no tests/features/**),
   // the acceptance disposition is forced to not-applicable inside