mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -0,0 +1,361 @@
+/**
+ * story-ops.js — flat Story creation for v2 plan-persist (Stage 3).
+ *
+ * Under the Story collapse (`docs/roadmap.md` § Stage 3), `/plan` persists
+ * zero-or-more Story issues directly — no Epic parent, no reconciler tree,
+ * no `deliveryShape` mode matrix. Default is **one Story**; N>1 is gated by
+ * the Stage-1 split-policy validator (`assertAcceptancePartition`).
+ *
+ * Each Story body is the single executable document: Tech Spec stays inline
+ * under `## Spec`. Over-budget Specs fail closed (split / tighten) — never
+ * spill to `docs/`. Top-level `acceptance[]` / `verify[]` are the machine
+ * contract and are synced into the body so the GitHub issue stays complete
+ * without requiring the LLM to dual-author the same lists.
+ *
+ * @module lib/orchestration/plan-persist/story-ops
+ */
+
+import { randomBytes } from 'node:crypto';
+
+import { AGENT_LABELS, TYPE_LABELS } from '../../label-constants.js';
+import {
+  parse as parseStoryBody,
+  serialize as serializeStoryBody,
+} from '../../story-body/story-body.js';
+import { assertSpecWithinBudget } from '../spec-spill.js';
+import { assertAcceptancePartition } from '../split-policy-validator.js';
+
+/** Label prefix grouping sibling Stories from one plan run (N>1). */
+export const PLAN_RUN_LABEL_PREFIX = 'plan-run::';
+
+/**
+ * Normalize a caller-supplied plan-run token. Persistence and resolution
+ * share this helper so human-readable ids map to one canonical label.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizePlanRunId(id) {
+  const token = String(id ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^plan-run::/, '')
+    .replace(/[^a-z0-9._-]+/g, '-');
+  if (!token) {
+    throw new Error('plan-run id requires a non-empty planRunId');
+  }
+  return token;
+}
+
+/**
+ * Build a `plan-run::<id>` label. When `id` is omitted, generates a short
+ * random hex token (8 chars) suitable for a rare multi-Story plan.
+ *
+ * @param {string} [id]
+ * @returns {string}
+ */
+export function planRunLabel(id) {
+  const token =
+    typeof id === 'string' && id.trim() !== ''
+      ? normalizePlanRunId(id)
+      : randomBytes(4).toString('hex');
+  return `${PLAN_RUN_LABEL_PREFIX}${token}`;
+}
+
+function bodyObjectFromTicket(ticket) {
+  if (typeof ticket.body === 'string') {
+    return parseStoryBody(ticket.body).body;
+  }
+  if (ticket.body && typeof ticket.body === 'object') {
+    return parseStoryBody(ticket.body).body;
+  }
+
+  // Allow top-level structured fields (goal/changes/…) without a `body` key.
+  return parseStoryBody({
+    goal: ticket.goal ?? '',
+    slicing: ticket.slicing ?? '',
+    spec: ticket.spec ?? '',
+    changes: ticket.changes ?? [],
+    acceptance: ticket.acceptance ?? [],
+    verify: ticket.verify ?? [],
+    references: ticket.references ?? [],
+    non_goals: ticket.non_goals ?? [],
+    wide: ticket.wide ?? null,
+    reason_to_exist: ticket.reason_to_exist ?? null,
+    depends_on: ticket.depends_on ?? [],
+    estimated_test_files: ticket.estimated_test_files ?? null,
+  }).body;
+}
+
+function normalizeDependsOn(ticket, bodyObject) {
+  if (Array.isArray(ticket.depends_on)) {
+    return ticket.depends_on.filter((d) => typeof d === 'string');
+  }
+  return Array.isArray(bodyObject.depends_on) ? bodyObject.depends_on : [];
+}
+
+function arraysEqual(a, b) {
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+/**
+ * Top-level `acceptance[]` / `verify[]` are the machine contract (validator
+ * SSOT). Sync them into the body so the persisted GitHub issue is complete.
+ * When the body already lists the same items, keep them; when the body is
+ * empty, fill from top-level; when both disagree, fail closed.
+ *
+ * @param {object} ticket
+ * @param {object} bodyObject
+ * @param {'acceptance'|'verify'} field
+ */
+function syncContractFieldFromTopLevel(ticket, bodyObject, field) {
+  if (!Array.isArray(ticket[field])) return;
+  const topLevel = ticket[field].map(String);
+  const bodyValue = Array.isArray(bodyObject[field])
+    ? bodyObject[field].map(String)
+    : [];
+  if (bodyValue.length > 0 && !arraysEqual(topLevel, bodyValue)) {
+    throw new Error(
+      `[plan-persist] Story "${ticket.slug ?? ticket.title ?? 'unknown'}" has mismatched top-level and body ${field} arrays`,
+    );
+  }
+  bodyObject[field] = topLevel;
+}
+
+/**
+ * Normalize a plan Story ticket into `{ slug, title, bodyObject }`.
+ * Accepts either a serialized markdown `body` string or a structured body.
+ *
+ * @param {object} ticket
+ * @returns {{ slug: string, title: string, bodyObject: object, depends_on: string[] }}
+ */
+export function normalizeStoryTicket(ticket) {
+  if (!ticket || typeof ticket !== 'object') {
+    throw new Error('[plan-persist] each story ticket must be an object');
+  }
+  const slug =
+    typeof ticket.slug === 'string' && ticket.slug.trim() !== ''
+      ? ticket.slug.trim()
+      : null;
+  if (!slug) {
+    throw new Error(
+      '[plan-persist] each story ticket requires a non-empty slug',
+    );
+  }
+  const title =
+    typeof ticket.title === 'string' && ticket.title.trim() !== ''
+      ? ticket.title.trim()
+      : `Story ${slug}`;
+  const bodyObject = bodyObjectFromTicket(ticket);
+  syncContractFieldFromTopLevel(ticket, bodyObject, 'acceptance');
+  syncContractFieldFromTopLevel(ticket, bodyObject, 'verify');
+  const depends_on = normalizeDependsOn(ticket, bodyObject);
+
+  return { slug, title, bodyObject, depends_on };
+}
+
+/**
+ * Fold optional shared Tech Spec prose into a Story body when the Story has
+ * no inline Spec. Specs stay inline; over-budget Specs throw.
+ *
+ * Precedence: per-Story `body.spec` wins; otherwise `sharedSpec` is used
+ * (N===1 convenience only — callers must not share one Spec across N>1).
+ *
+ * @param {object} bodyObject
+ * @param {string} slug
+ * @param {object} [opts]
+ * @param {string|null} [opts.sharedSpec]
+ * @returns {{ bodyObject: object }}
+ */
+export function foldSpecIntoStoryBody(bodyObject, slug, opts = {}) {
+  const { sharedSpec = null } = opts;
+
+  const next = {
+    ...bodyObject,
+    references: Array.isArray(bodyObject.references)
+      ? [...bodyObject.references]
+      : [],
+  };
+
+  const inline =
+    typeof next.spec === 'string' && next.spec.trim() !== ''
+      ? next.spec.trim()
+      : typeof sharedSpec === 'string' && sharedSpec.trim() !== ''
+        ? sharedSpec.trim()
+        : '';
+
+  if (inline === '') {
+    return { bodyObject: next };
+  }
+
+  const { content } = assertSpecWithinBudget({ storyId: slug, spec: inline });
+  next.spec = content;
+  return { bodyObject: next };
+}
+
+function assembleOnePlanStory(ticket, opts) {
+  const { slug, title, bodyObject, depends_on } = normalizeStoryTicket(ticket);
+  const { bodyObject: folded } = foldSpecIntoStoryBody(bodyObject, slug, {
+    sharedSpec: opts.sharedSpec ?? null,
+  });
+  const body = serializeStoryBody({ ...folded, depends_on });
+  return {
+    story: {
+      slug,
+      title,
+      body,
+      bodyObject: { ...folded, depends_on },
+      acceptance: Array.isArray(folded.acceptance) ? folded.acceptance : [],
+      depends_on,
+    },
+  };
+}
+
+/**
+ * Shared techspec.md is an N===1 convenience only — folding one Spec into
+ * every sibling duplicates approach prose and breaks Story-as-SSOT.
+ *
+ * @param {object[]} tickets
+ * @param {string|null|undefined} sharedSpec
+ */
+function assertSharedSpecAllowed(tickets, sharedSpec) {
+  if (tickets.length <= 1) return;
+  if (typeof sharedSpec !== 'string' || sharedSpec.trim() === '') return;
+  throw new Error(
+    '[plan-persist] a shared techspec.md cannot be folded into N>1 Stories — ' +
+      "put each Story's approach in its own ## Spec so every Story stays a " +
+      'complete executable document.',
+  );
+}
+
+/**
+ * Assemble markdown bodies for every Story: normalize → fold spec →
+ * assertAcceptancePartition → serialize.
+ *
+ * @param {object[]} tickets
+ * @param {object} [opts]
+ * @param {string|null} [opts.sharedSpec]
+ * @param {string[]} [opts.planAcceptance]
+ * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[] }> }}
+ */
+export function assemblePlanStories(tickets, opts = {}) {
+  if (!Array.isArray(tickets) || tickets.length === 0) {
+    throw new Error(
+      '[plan-persist] stories payload must be a non-empty array — author at least one Story (default-single).',
+    );
+  }
+
+  assertSharedSpecAllowed(tickets, opts.sharedSpec);
+
+  const stories = tickets.map(
+    (ticket) => assembleOnePlanStory(ticket, opts).story,
+  );
+
+  assertAcceptancePartition(stories, {
+    planAcceptance: opts.planAcceptance,
+  });
+
+  return { stories };
+}
+
+function orderStoriesByDependencies(stories) {
+  const list = Array.isArray(stories) ? stories : [];
+  const known = new Set(list.map((story) => story.slug));
+  for (const story of list) {
+    const unknown = story.depends_on.filter((slug) => !known.has(slug));
+    if (unknown.length > 0) {
+      throw new Error(
+        `[plan-persist] Story "${story.slug}" depends on unknown sibling(s): ${unknown.join(', ')}`,
+      );
+    }
+  }
+  const ordered = [];
+  const scheduled = new Set();
+  const pending = [...list];
+  while (pending.length > 0) {
+    const index = pending.findIndex((story) =>
+      story.depends_on.every((slug) => scheduled.has(slug)),
+    );
+    if (index === -1) {
+      throw new Error(
+        `[plan-persist] dependency cycle prevents Story creation: ${pending.map((story) => story.slug).join(', ')}`,
+      );
+    }
+    const [story] = pending.splice(index, 1);
+    ordered.push(story);
+    scheduled.add(story.slug);
+  }
+  return ordered;
+}
+
+/**
+ * Create Story issues via `provider.createIssue`. Applies `type::story`,
+ * `agent::ready`, and — when N>1 — a shared plan-run label.
+ *
+ * @param {object} args
+ * @param {object} args.provider
+ * @param {ReturnType<typeof assemblePlanStories>['stories']} args.stories
+ * @param {object} [args.opts]
+ * @param {string} [args.opts.planRunId]
+ * @param {boolean} [args.opts.dryRun=false]
+ * @returns {Promise<{ created: Array<{ slug: string, id: number, url?: string, title: string }>, planRunLabel: string|null }>}
+ */
+export async function createStoryIssues({ provider, stories, opts = {} }) {
+  if (typeof provider?.createIssue !== 'function') {
+    throw new Error(
+      '[plan-persist] provider does not expose createIssue; cannot persist Stories.',
+    );
+  }
+
+  const list = Array.isArray(stories) ? stories : [];
+  const planLabel = list.length > 1 ? planRunLabel(opts.planRunId) : null;
+  const labels = [TYPE_LABELS.STORY, AGENT_LABELS.READY];
+  if (planLabel) labels.push(planLabel);
+
+  if (opts.dryRun) {
+    return {
+      created: list.map((s, i) => ({
+        slug: s.slug,
+        id: -(i + 1),
+        title: s.title,
+        url: undefined,
+      })),
+      planRunLabel: planLabel,
+    };
+  }
+
+  const created = [];
+  const createdBySlug = new Map();
+  for (const story of orderStoriesByDependencies(list)) {
+    const dependencyRefs = story.depends_on.map(
+      (slug) => `#${createdBySlug.get(slug)}`,
+    );
+    const body =
+      dependencyRefs.length === 0
+        ? story.body
+        : serializeStoryBody(
+            { ...story.bodyObject, depends_on: dependencyRefs },
+            { includeFooter: true },
+          );
+    const result = await provider.createIssue({
+      title: story.title,
+      body,
+      labels: [...labels],
+    });
+    const id = result?.id ?? result?.number;
+    if (!Number.isInteger(id)) {
+      throw new Error(
+        `[plan-persist] createIssue for slug "${story.slug}" did not return a numeric id`,
+      );
+    }
+    created.push({
+      slug: story.slug,
+      id,
+      title: story.title,
+      url: result.url,
+    });
+    createdBySlug.set(story.slug, id);
+  }
+
+  return { created, planRunLabel: planLabel };
+}

package/.agents/scripts/lib/orchestration/plan-persist/summary.js

@@ -1,21 +1,9 @@
 /**
- * summary.js — plan-persist terminal summary (Epic #4474, PR3).
+ * summary.js — plan-persist terminal summary (v2 Stage 3).
  *
- * Owns the single `plan-summary` structured comment the collapsed persist
- * surface upserts at terminal success, closing with the dry-run wave table.
- * This replaces two retired round-trips of the 12-phase pipeline:
- *
- *   - the Phase 9 plan-time `dispatch-manifest` comment, whose claimed
- *     consumer ("Wave Completeness Gate, /deliver Step 0.5") does not exist
- *     — the live manifest is written at deliver time by `wave-record-io.js`
- *     (#4474 design §3: DROP, keep the wave table as summary text only);
- *   - the Phase 12 notify round-trip ("informational — no webhook for
- *     planning").
- *
- * The wave table is computed from the validated ticket set's `depends_on`
- * slug edges via the same `computeStoryWaves` layering the deliver-time
- * dispatch pipeline uses, so the preview matches what `/deliver` will
- * actually fan out (barring later manual ticket edits).
+ * Upserts a single `plan-summary` structured comment on the primary Story
+ * at terminal success. Carries risk / routing receipts and the dry-run
+ * `depends_on` ordering table for the rare N>1 plan.
  *
  * @module lib/orchestration/plan-persist/summary
  */
@@ -23,23 +11,15 @@
 import { computeStoryWaves } from '../dependency-analyzer.js';
 
 /**
- * Structured-comment type for the persist summary. Registered in
- * `ticketing/reads.js` `STRUCTURED_COMMENT_TYPES`; upsert-idempotent so a
- * `--force`/`--resume` re-persist replaces the prior summary in place.
+ * Structured-comment type for the persist summary.
  */
 export const PLAN_SUMMARY_COMMENT_TYPE = 'plan-summary';
 
 /**
  * Compute the dry-run wave assignment for a validated ticket set.
  *
- * Adapts the slug-keyed ticket shape onto `computeStoryWaves`' storyGroups
- * contract (slug → { storyId, tasks: [] }; explicit deps from `depends_on`).
- * Under the 2-tier hierarchy Stories carry no tasks, so all edges are
- * explicit.
- *
  * @param {Array<{ slug: string, title?: string, depends_on?: string[] }>} tickets
  * @returns {Array<{ wave: number, stories: Array<{ slug: string, title: string }> }>}
- *   Waves in execution order.
  */
 export function buildWaveTable(tickets) {
   const list = Array.isArray(tickets) ? tickets : [];
@@ -66,53 +46,24 @@ export function buildWaveTable(tickets) {
 }
 
 /**
- * Render the dry-run wave table as GitHub-flavoured markdown.
- *
  * @param {ReturnType<typeof buildWaveTable>} waveTable
- * @returns {string[]} markdown lines
+ * @returns {string[]}
  */
 function renderWaveTableLines(waveTable) {
   if (!Array.isArray(waveTable) || waveTable.length === 0) {
-    return ['_No stories to wave (empty plan)._'];
+    return ['_No stories to sequence (empty plan)._'];
   }
   const rows = waveTable.map(
     ({ wave, stories }) =>
       `| ${wave + 1} | ${stories.map((s) => `\`${s.slug}\``).join(', ')} |`,
   );
-  return ['| Wave | Stories |', '| --- | --- |', ...rows];
+  return ['| Order | Stories |', '| --- | --- |', ...rows];
 }
 
 /**
- * Build the `plan-summary` structured-comment body: risk + routing +
- * freshness + healthcheck receipts, closing with the mode-specific tail —
- * the dry-run wave table for fan-out/amend, or the single-delivery routing
- * record `{ deliveryShape, sliceCount, routingReasons }` (Epic #4474 PR4)
- * for the spec-only mode.
- *
- * Every auto-waiver the persist derived is printed WITH its reason
- * (#4496 fix 2) — e.g. the no-BDD-runner acceptance-disposition waiver
- * (`planningRisk.acceptanceWaivedReason`) — so the summary is
- * self-explanatory and a headless reader never has to re-derive a persist
- * outcome from framework source.
+ * Build the `plan-summary` structured-comment body.
  *
- * @param {{
- *   epicId: number,
- *   ticketCount: number,
- *   planningRisk: { overallLevel?: string, gateDecision?: string, acceptanceDisposition?: string, acceptanceWaivedReason?: string },
- *   reviewRouting: { decision?: string },
- *   freshness?: { stale?: number, ambiguous?: number },
- *   healthcheck?: { ok?: boolean, waived?: boolean, skipped?: boolean },
- *   waveTable: ReturnType<typeof buildWaveTable>,
- *   mode?: 'fan-out'|'single'|'amend',
- *   planMetricsLine?: string|null,
- *   single?: { deliveryShape: 'single', sliceCount: number|null, routingReasons: string[] }|null,
- *   amend?: {
- *     closed: Array<{ slug: string, issueNumber: number }>,
- *     recreated: Array<{ slug: string, oldIssueNumber: number, issueNumber: number }>,
- *     created: Array<{ slug: string, issueNumber: number }>,
- *     keptCount: number,
- *   }|null,
- * }} input
+ * @param {object} input
  * @returns {string}
  */
 export function buildPlanSummaryCommentBody({
@@ -123,84 +74,60 @@ export function buildPlanSummaryCommentBody({
   freshness,
   healthcheck,
   waveTable,
-  mode = 'fan-out',
+  mode = 'stories',
   planMetricsLine = null,
+  stories = null,
+  planRunLabel = null,
+  // legacy unused knobs kept so older test call sites don't crash mid-migration
   single = null,
   amend = null,
 }) {
+  void mode;
+  void single;
+  void amend;
+
   const freshnessLine =
     (freshness?.stale ?? 0) > 0 || (freshness?.ambiguous ?? 0) > 0
-      ? `- ⚠️ Spec freshness: ${freshness.stale} stale / ${freshness.ambiguous} ambiguous reference(s) — see the spec-freshness comment.`
+      ? `- ⚠️ Spec freshness: ${freshness.stale} stale / ${freshness.ambiguous} ambiguous reference(s).`
       : '- Spec freshness: clean.';
   const healthcheckLine = healthcheck?.skipped
-    ? '- Healthcheck: skipped (test seam).'
+    ? '- Healthcheck: skipped (v2 flat Story persist — ticket validators are the gate).'
     : healthcheck?.ok
       ? '- Healthcheck: passed.'
       : `- Healthcheck: failed, waived by operator label.`;
 
-  const headLine =
-    mode === 'single'
-      ? `- Single-delivery plan (\`delivery::single\`): no Story tree — the Delivery Slicing table is the audit trail.`
-      : `- ${ticketCount} Story ticket(s) persisted across ${waveTable.length} wave(s).`;
+  const storyList =
+    Array.isArray(stories) && stories.length > 0
+      ? stories.map((s) => `#${s.id} (\`${s.slug}\`)`).join(', ')
+      : `${ticketCount} Story(ies)`;
 
-  // Auto-waivers always ship with their reason (#4496 fix 2): the summary
-  // is authoritative, so the line must be self-explanatory on its own.
   const waiverLines = planningRisk?.acceptanceWaivedReason
     ? [
         `- ⚠️ Acceptance disposition auto-waived to \`not-applicable\` — ${planningRisk.acceptanceWaivedReason}`,
       ]
     : [];
 
-  const amendLines = amend
-    ? [
-        `- Amend delta: ${amend.created.length} added, ${amend.recreated.length} modified (closed + recreated), ${amend.closed.length} closed, ${amend.keptCount} kept untouched.`,
-      ]
-    : [];
-
-  const tail =
-    mode === 'single'
-      ? [
-          '#### Delivery routing record',
-          '',
-          '```json',
-          JSON.stringify(
-            {
-              deliveryShape: 'single',
-              sliceCount: single?.sliceCount ?? null,
-              routingReasons: single?.routingReasons ?? [],
-            },
-            null,
-            2,
-          ),
-          '```',
-          '',
-          '_Marker is inert until #4475 lands the deliver-side reader — `/deliver` still treats this Epic as fan-out until then._',
-        ]
-      : [
-          '#### Dry-run wave table',
-          '',
-          ...renderWaveTableLines(waveTable),
-          '',
-          '_Preview only — the authoritative dispatch manifest is written at deliver time (`wave-record-io.js`)._',
-        ];
+  const runLine = planRunLabel
+    ? `- Plan-run label: \`${planRunLabel}\` (N>1 — deliver with \`/deliver --run <planRunId>\`).`
+    : '- Plan-run: single Story (default).';
 
   return [
-    `### 📋 Plan Summary — Epic #${epicId} is \`agent::ready\``,
+    `### 📋 Plan Summary — Story #${epicId} is \`agent::ready\``,
     '',
-    headLine,
-    ...amendLines,
+    `- ${ticketCount} Story ticket(s) persisted: ${storyList}.`,
+    runLine,
     `- Risk: ${planningRisk?.overallLevel ?? 'unknown'} · ${planningRisk?.gateDecision ?? 'unknown'} (review routing: ${reviewRouting?.decision ?? 'unknown'}).`,
     ...waiverLines,
     freshnessLine,
     healthcheckLine,
-    // G2 measurement receipt (Epic #4474 PR1/PR7): the plan-CLI invocation
-    // ledger roll-up (turns-per-plan proxy, per-mode counts, critic skips)
-    // rides the summary comment so the cohort reader never has to pull the
-    // temp ledger off the runner's disk. Omitted when the ledger is empty.
     ...(typeof planMetricsLine === 'string' && planMetricsLine.length > 0
       ? [`- ${planMetricsLine}`]
       : []),
     '',
-    ...tail,
+    '#### Delivery order (`depends_on`)',
+    '',
+    ...renderWaveTableLines(waveTable),
+    '',
+    '_Deliver with `/deliver <storyId>` (N=1) or `/deliver --run <planRunId>` (N>1)._',
   ].join('\n');
 }

package/.agents/scripts/lib/orchestration/plan-reachability.js

@@ -3,13 +3,11 @@
  * the persist surface (Epic #4474 PR6, design §4: the 8.4 reachability
  * critic demoted from a fresh-context sub-agent to a persist-side scan).
  *
- * Mirrors the mechanics of the existing `--paranoid` F7 healthcheck
- * (`epic-plan-healthcheck.js#checkReachability`) — route-glob scan of the
- * paths a Story declares vs the `planning.navigation.navRegistry` token
- * list — but runs it over the **draft** ticket set inside `plan-persist.js`
- * step 4.5, before any provider call, so an orphaned surface is caught
- * while a one-line targeted amend is still free (nothing has been written
- * to GitHub yet).
+ * Route-glob scan of the paths a Story declares vs the
+ * `planning.navigation.navRegistry` token list, run over the **draft**
+ * ticket set inside `plan-persist.js` step 4.5, before any provider call,
+ * so an orphaned surface is caught while a one-line targeted amend is
+ * still free (nothing has been written to GitHub yet).
  *
  * Plan-level coverage semantics (the convergence contract): a route-adding
  * story that never references the nav registry produces orphan surfaces —
@@ -20,9 +18,8 @@
  * registry) in one targeted amend, and the re-run persist passes.
  *
  * Silent no-op when `planning.navigation` is unconfigured (`routeGlobs`
- * empty) — same opt-in contract as F7 / AC-13 — reported as
- * `status: 'skipped'` so the caller can append the audit record to the
- * plan-metrics ledger.
+ * empty) — reported as `status: 'skipped'` so the caller can append the
+ * audit record to the plan-metrics ledger.
  *
  * Pure over its inputs (tickets + resolved config), no I/O.
  */
@@ -31,12 +28,10 @@ import {
   extractStoryPaths,
   globToRegExp,
   resolveNavConfig,
-} from '../../epic-plan-healthcheck.js';
+} from './plan-navigation.js';
 
 /**
- * Fallback tokens when `navRegistry` is unconfigured but `routeGlobs` is —
- * identical to the F7 healthcheck's fallback, so the two checks agree on
- * what counts as a registry reference.
+ * Fallback tokens when `navRegistry` is unconfigured but `routeGlobs` is.
  */
 const FALLBACK_REGISTRY_TOKENS = ['nav registry', 'navigation'];
 

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -9,7 +9,7 @@
  *
  * The `--force` flag is intentional. By the time a Story is `agent::done`
  * its branch has already been merged into the Epic branch (via
- * `story-close.js`), so any residue left in the worktree — dirty
+ * `single-story-close.js`), so any residue left in the worktree — dirty
  * build artifacts, an interrupted rebase, a stray Windows lock — is noise.
  * The safety rails in `WorktreeManager.reap` exist for the _active_ close
  * path; at plan time we already know the Story is done and want the

package/.agents/scripts/lib/orchestration/{epic-plan-spec/phases → planning}/authoring-context.js

@@ -12,17 +12,17 @@ import path from 'node:path';
 import {
   resolveFeatureRoots,
   verifyBddRunnerPendingTag,
-} from '../../../bdd-runner-detect.js';
-import { scanBddScenarios } from '../../../bdd-scenario-scanner.js';
-import { buildCodebaseSnapshot } from '../../../codebase-snapshot.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 { ensureDocsDigest } from '../../docs-digest.js';
-import { applyBudget } from '../../planning-context-budget.js';
-import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
+} from '../../bdd-runner-detect.js';
+import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
+import { buildCodebaseSnapshot } from '../../codebase-snapshot.js';
+import { getLimits, getPaths, PROJECT_ROOT } from '../../config-resolver.js';
+import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
+import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
+import { Logger } from '../../Logger.js';
+import { hasTicketSection } from '../../ticket-body-sections.js';
+import { ensureDocsDigest } from '../docs-digest.js';
+import { applyBudget } from '../planning-context-budget.js';
+import { collectReferences, hasNewFileCue } from '../spec-freshness.js';
 import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
@@ -41,7 +41,7 @@ import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
  * @param {{ github?: { owner?: string, repo?: string }|null }} opts
  * @returns {string|null}
  */
-export function resolveMemoryDir({ github } = {}) {
+function resolveMemoryDir({ github } = {}) {
   if (
     typeof process.env.MANDREL_MEMORY_DIR === 'string' &&
     process.env.MANDREL_MEMORY_DIR.length > 0
@@ -256,8 +256,8 @@ export async function buildAuthoringContext(
       // 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'),
+        techSpec: hasTicketSection(epic.body ?? '', 'techSpec'),
+        acceptanceTable: hasTicketSection(epic.body ?? '', 'acceptanceTable'),
       },
     },
     docsContext,