mandrel 1.94.0 → 2.0.0

package/.agents/scripts/lib/orchestration/planning/decomposer-context.js

@@ -0,0 +1,27 @@
+/**
+ * decomposer-context.js — system-prompt builder for the `/plan` authoring
+ * pass (Story #2466; v2 keeps the prompt helper, drops the Epic-fetch
+ * decomposition envelope).
+ *
+ * `buildDecomposerSystemPrompt` is the live surface consumed by
+ * `plan-context.js#buildSystemPrompts`. The retired
+ * `buildDecompositionContext` Epic-fetch path lived here until the
+ * Story-only cutover removed every caller.
+ */
+
+import { renderDecomposerSystemPrompt } from '../../templates/decomposer-prompts.js';
+
+export function buildDecomposerSystemPrompt(
+  heuristics = [],
+  { maxTickets, epicId } = {},
+) {
+  const base = renderDecomposerSystemPrompt({
+    maxTickets,
+    epicId,
+  });
+  const heuristicsStr =
+    heuristics.length > 0
+      ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
+      : '';
+  return `${base}${heuristicsStr ? `\n\n${heuristicsStr}` : ''}`;
+}

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

@@ -24,7 +24,6 @@ export const RISK_VERDICT_SCHEMA_PATH = path.resolve(
   '..',
   '..',
   '..',
-  '..',
   'schemas',
   'risk-verdict.schema.json',
 );
@@ -57,7 +56,7 @@ function getRiskVerdictValidator(schemaPath, io) {
  *
  * @param {unknown} verdict
  * @param {{ schemaPath?: string, io?: { readFileSync: typeof readFileSync } }} [opts]
- * @returns {import('../../planning-risk.js').RiskVerdict} The validated verdict (same reference).
+ * @returns {import('../planning-risk.js').RiskVerdict} The validated verdict (same reference).
  */
 export function validateRiskVerdict(verdict, opts = {}) {
   const validate = getRiskVerdictValidator(
@@ -72,7 +71,7 @@ export function validateRiskVerdict(verdict, opts = {}) {
       `[epic-plan-spec] risk verdict failed schema validation: ${detail}`,
     );
   }
-  return /** @type {import('../../planning-risk.js').RiskVerdict} */ (verdict);
+  return /** @type {import('../planning-risk.js').RiskVerdict} */ (verdict);
 }
 
 /**
@@ -81,7 +80,7 @@ export function validateRiskVerdict(verdict, opts = {}) {
  *
  * @param {string} verdictPath
  * @param {{ schemaPath?: string, io?: { readFileSync: typeof readFileSync } }} [opts]
- * @returns {import('../../planning-risk.js').RiskVerdict}
+ * @returns {import('../planning-risk.js').RiskVerdict}
  */
 export function loadRiskVerdict(verdictPath, opts = {}) {
   const io = opts.io ?? { readFileSync };

package/.agents/scripts/lib/orchestration/post-merge/phases/branch-cleanup.js

@@ -8,7 +8,7 @@
  * while a remote not-found is treated as a no-op.
  */
 
-import { deleteBranchBoth } from '../../../git-branch-cleanup.js';
+import { deleteBranchEverywhere } from '../../../git-branch-cleanup.js';
 
 function reapPhaseLogger(progress) {
   return progress ?? (() => {});
@@ -20,7 +20,7 @@ export async function branchCleanupPhase(ctx, state = {}) {
     repoRoot,
     progress,
     logger,
-    branchCleanup = deleteBranchBoth,
+    branchCleanup = deleteBranchEverywhere,
   } = ctx;
   const log = reapPhaseLogger(progress);
   log('CLEANUP', `Deleting story branch: ${storyBranch}`);

package/.agents/scripts/lib/orchestration/post-merge/phases/dashboard-refresh.js

@@ -1,33 +1,21 @@
 /**
- * phases/dashboard-refresh.js — regenerate the dispatch manifest after
- * a Story merges into its Epic branch. Honors `--skip-dashboard` so
- * operators running an out-of-band close can suppress the I/O.
+ * phases/dashboard-refresh.js — retired dispatch-manifest refresh seam.
+ *
+ * The Stage 5 hard cutover deletes the dispatcher/manifest surface; keep this
+ * phase as a no-op so any still-wired post-merge pipeline can drain safely.
  */
 
-import { generateAndSaveManifest } from '../../../../dispatcher.js';
-
 function reapPhaseLogger(progress) {
   return progress ?? (() => {});
 }
 
 export async function dashboardRefreshPhase(ctx) {
-  const {
-    epicId,
-    provider,
-    skipDashboard,
-    progress,
-    generateManifestFn = generateAndSaveManifest,
-  } = ctx;
+  const { skipDashboard, progress } = ctx;
   const log = reapPhaseLogger(progress);
   if (skipDashboard) {
-    log(
-      'DASHBOARD',
-      '⏭️ Skipping dashboard refresh (--skip-dashboard flag set)',
-    );
+    log('DASHBOARD', 'Skipping dashboard refresh (--skip-dashboard flag set)');
     return false;
   }
-  log('DASHBOARD', 'Regenerating dispatch manifest...');
-  await generateManifestFn(epicId, true, { provider });
-  log('DASHBOARD', '✅ Dashboard manifest updated (temp/)');
-  return true;
+  log('DASHBOARD', 'Dispatch manifest refresh retired; no dashboard updated.');
+  return false;
 }

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -1,7 +1,8 @@
 /**
  * phases/worktree-reap.js — post-merge worktree reap phase.
  *
- * After a Story branch is merged into the Epic branch, this phase removes
+ * After a Story branch is merged (pre-v2: into the Epic branch; v2:
+ * squash-merged to `main` via `single-story-close.js`), this phase removes
  * the per-Story worktree at `.worktrees/story-<id>/`. The reap is split
  * into three concerns:
  *
@@ -376,7 +377,7 @@ function applyStillRegisteredState({
     try {
       manifestEntry = recordPendingCleanupFn(worktreeRoot, {
         storyId: Number(storyId),
-        branch: getStoryBranch(null, storyId),
+        branch: getStoryBranch(storyId),
         path: stillRegistered.path,
         push: false,
       });

package/.agents/scripts/lib/orchestration/pr-base-guard.js

@@ -1,47 +1,37 @@
 // .agents/scripts/lib/orchestration/pr-base-guard.js
 /**
- * pr-base-guard.js — refuse to open a pull request that would route an
- * Epic-attached Story's work directly into `main` instead of into the
- * parent Epic integration branch.
- *
- * Background: Story #2960 — during Epic #2880 wave 5 a sub-agent fell
- * back to `gh pr create --base main` after `story-close.js`
- * short-circuited as a no-op. The orphaned PR forced a manual recovery
- * (`git merge origin/main` back into `epic/2880`). This module is the
- * defence-in-depth call any framework helper that triggers `gh pr create`
- * MUST invoke before shelling out.
- *
- * Scope: the guard fires only when the Story body declares an
- * `Epic: #N` (or `Parent: #N`) reference. Stand-alone Stories — the
- * `/single-story-deliver` surface — are unaffected because they have no
- * parent reference to detect.
+ * pr-base-guard.js — refuse to open a pull request for a Story that still
+ * carries an Epic/parent footer (pre-v2 hierarchy). v2 Stories are
+ * standalone; Epic-attached bodies are a forward-cutover refusal, not a
+ * redirect onto `epic/<N>`.
  */
 
 import { resolveStoryHierarchy } from '../story-lifecycle.js';
 
 /**
- * Inspect a Story's body for an Epic parent reference and refuse a PR
- * whose `baseBranch` is not the matching `epic/<N>` integration branch.
+ * Inspect a Story's body for an Epic/parent reference and refuse any PR
+ * when one is present. Callers must re-plan Epic-attached tickets as v2
+ * Stories before delivering.
  *
  * @param {object} args
  * @param {number} args.storyId — Story ticket id (used in the error
  *   message so the operator can grep the failing surface).
  * @param {string|null|undefined} args.storyBody — raw Story body markdown.
- *   When falsy, the guard short-circuits (no parent → nothing to enforce).
- * @param {string} args.baseBranch — the `--base` value about to be passed
- *   to `gh pr create`.
- * @throws {Error} when the Story is Epic-attached and `baseBranch` is not
- *   the parent Epic's branch. The message matches the AC verbatim so
- *   reviewers can grep it.
+ *   When falsy, the guard short-circuits (no body → nothing to enforce).
+ * @param {string} args.baseBranch — retained for call-site compatibility;
+ *   unused once an Epic/parent footer is detected (any base is refused).
+ * @throws {Error} when the Story body declares an Epic or Parent footer.
  */
-export function assertStoryPrBaseAllowed({ storyId, storyBody, baseBranch }) {
+export function assertStoryPrBaseAllowed({
+  storyId,
+  storyBody,
+  baseBranch: _baseBranch,
+}) {
   if (!storyBody) return;
   const { epicId } = resolveStoryHierarchy(storyBody);
   if (epicId == null) return;
-  const expected = `epic/${epicId}`;
-  if (baseBranch === expected) return;
   throw new Error(
-    `Story #${storyId} is parented by Epic #${epicId} — merge into ${expected}, not ${baseBranch}. ` +
-      'To bypass, use /single-story-deliver explicitly.',
+    `Story #${storyId} still declares Epic/Parent #${epicId}. ` +
+      'v2 delivery is Story-only — re-plan as a standalone Story (no Epic footer) before opening a PR.',
   );
 }

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -1,10 +1,10 @@
 /**
  * preflight-cache.js — Epic #3019 / Story #3027.
  *
- * Cache adapter for the snapshot/DAG envelope produced by
- * `epic-deliver-preflight.js` so `epic-deliver-prepare.js` can skip the
- * second walk of Epic → Story when the underlying Epic ticket
- * has not drifted between the two operator invocations.
+ * Legacy cache adapter for the snapshot/DAG envelope the deleted
+ * `epic-deliver-preflight.js` / `epic-deliver-prepare.js` pair produced
+ * (pre-v2 Epic `/deliver`). Retained so fingerprint helpers and tests stay
+ * stable; no live v2 entry seam reads or writes this cache.
  *
  * Contract:
  *   - Cache file lives at `<cwd>/temp/epic-<epicId>/preflight-snapshot.json`.
@@ -107,7 +107,7 @@ export function computeBaseSha(epic, stories = []) {
  * miss and fall back to a fresh snapshot/DAG pass.
  *
  * The function intentionally swallows `ENOENT` and JSON-parse errors so
- * a stale or partially-written file does not poison `epic-deliver-prepare`.
+ * a stale or partially-written file does not poison legacy Epic prepare callers.
  *
  * @param {{ epicId: number, cwd?: string }} args
  * @returns {Promise<object | null>}

package/.agents/scripts/lib/orchestration/remote-verifier.js

@@ -7,7 +7,7 @@
  * the delivery inline and committing to local `main` without pushing —
  * when the driving agent *perceived* the environment had no live GitHub
  * remote. The judgment was vibes, not fact. This module gives the entry
- * seams (`epic-deliver-preflight.js`, `single-story-init.js`) a verified
+ * seams (`single-story-init.js` for v2 `/deliver`) a verified
  * probe result to record in their envelopes so the workflow can branch on
  * `remoteVerified: true|false` deterministically: use the remote, or
  * transition to `agent::blocked` quoting the probe output — never a

package/.agents/scripts/lib/orchestration/resolve-plan-run.js

@@ -0,0 +1,155 @@
+/**
+ * Pure helpers for resolve-plan-run.js — keep the CLI entry thin so new-file
+ * CRAP stays under the quality-preview ceiling.
+ *
+ * @module lib/orchestration/resolve-plan-run
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
+import {
+  normalizePlanRunId,
+  PLAN_RUN_LABEL_PREFIX,
+} from './plan-persist/story-ops.js';
+
+/**
+ * Normalize a plan-run id into the canonical label `plan-run::<token>`.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizePlanRunLabel(raw) {
+  const token = normalizePlanRunId(raw);
+  return `${PLAN_RUN_LABEL_PREFIX}${token}`;
+}
+
+/**
+ * Extract a bare plan-run id from a label or raw token.
+ *
+ * @param {string} label
+ * @returns {string}
+ */
+export function planRunIdFromLabel(label) {
+  return String(label ?? '')
+    .trim()
+    .replace(new RegExp(`^${PLAN_RUN_LABEL_PREFIX}`), '');
+}
+
+/**
+ * @param {object} issue
+ * @returns {string[]}
+ */
+export function normalizeIssueLabels(issue) {
+  const raw = issue?.labels;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * @param {object} issue
+ * @returns {{ id: number, title: string, body: string, url: string|null, labels: string[], state: string }|null}
+ */
+export function toStoryRecord(issue) {
+  const id = Number(issue?.number ?? issue?.id);
+  if (!Number.isInteger(id) || id <= 0) return null;
+  const labels = normalizeIssueLabels(issue);
+  if (!labels.includes(TYPE_LABELS.STORY)) return null;
+  return {
+    id,
+    title: String(issue?.title ?? ''),
+    body: String(issue?.body ?? ''),
+    url: issue?.html_url ?? issue?.url ?? null,
+    labels,
+    state: String(issue?.state ?? 'open').toLowerCase(),
+  };
+}
+
+/**
+ * @param {object[]} stories
+ * @returns {{ id: number, dependsOn: number[] }[]}
+ */
+export function storiesToDag(stories) {
+  const adjacency = buildStoryAdjacency(stories, { dropForeign: false });
+  return stories.map((s) => ({
+    id: s.id,
+    dependsOn: adjacency.get(s.id) ?? [],
+  }));
+}
+
+/**
+ * Map provider issues into the deliver-router story list + DAG nodes.
+ *
+ * @param {object[]} issues
+ * @param {{ planRunId: string, planRunLabel: string }} meta
+ * @returns {{ kind: string, planRunId: string, planRunLabel: string, stories: object[], dag: object[] }}
+ */
+export function buildPlanRunEnvelope(issues, { planRunId, planRunLabel }) {
+  const stories = (Array.isArray(issues) ? issues : [])
+    .map(toStoryRecord)
+    .filter(Boolean)
+    .sort((a, b) => a.id - b.id);
+
+  return {
+    kind: 'plan-run',
+    planRunId,
+    planRunLabel,
+    stories: stories.map(({ id, title, url, labels, state }) => ({
+      id,
+      title,
+      url,
+      labels,
+      state,
+    })),
+    dag: storiesToDag(stories),
+    done: stories
+      .filter(
+        (story) =>
+          story.state === 'closed' || story.labels.includes('agent::done'),
+      )
+      .map((story) => story.id),
+  };
+}
+
+/**
+ * Pure core used by tests: given issues + meta, build the envelope.
+ *
+ * @param {{ run: string, issues: object[] }} args
+ * @returns {ReturnType<typeof buildPlanRunEnvelope>}
+ */
+export function resolvePlanRunFromIssues({ run, issues }) {
+  const planRunLabel = normalizePlanRunLabel(run);
+  const planRunId = planRunIdFromLabel(planRunLabel);
+  return buildPlanRunEnvelope(issues, { planRunId, planRunLabel });
+}
+
+/**
+ * Fetch issues for a plan-run label via the ticketing provider.
+ *
+ * @param {object} provider
+ * @param {{ planRunLabel: string, state: string }} args
+ * @returns {Promise<object[]>}
+ */
+export async function fetchPlanRunIssues(provider, { planRunLabel, state }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') {
+    throw new Error('resolve-plan-run: provider.listIssuesByLabel is required');
+  }
+  const labels = `${planRunLabel},${TYPE_LABELS.STORY}`;
+  const issues = await provider.listIssuesByLabel({ state, labels });
+  return Array.isArray(issues) ? issues : [];
+}
+
+/**
+ * @param {string|undefined} state
+ * @returns {string}
+ */
+export function assertIssueState(state) {
+  const value = state ?? 'open';
+  if (!['open', 'closed', 'all'].includes(value)) {
+    throw new Error(
+      `resolve-plan-run: --state must be open|closed|all (got ${value})`,
+    );
+  }
+  return value;
+}

package/.agents/scripts/lib/orchestration/resolves-token.js

@@ -2,7 +2,7 @@
  * resolves-token.js — single source of truth for the `(resolves #N)`
  * Story-merge integration marker.
  *
- * Background. `story-close.js` integrates each Story branch into its
+ * Background. The deleted `story-close.js` integrated each Story branch into its
  * parent Epic branch with `git merge --no-ff` and a Conventional-Commit
  * subject that carries a ` (resolves #<storyId>)` trailer. That trailer is
  * the *durable* proof a Story landed on `epic/<id>`: the local/remote

package/.agents/scripts/lib/orchestration/retro-perf-heuristics.js

@@ -26,23 +26,23 @@
  *     the renderer can attribute the run-length back to the deliver-runner
  *     concurrency cap.
  *
- * Threshold contract (`.agentrc.json → delivery.retro.perfThresholds`):
+ * Threshold contract (code constants only — not operator-tunable via
+ * `.agentrc.json`; the former `delivery.retro.perfThresholds` key was
+ * retired):
  *
  *   - `utilisation`: number in [0, 1]. Default 0.6.
  *   - `bootstrapShare`: number in [0, 1]. Default 0.4.
  *   - `capBindingRunLength`: positive integer. Default 2.
  *
  * The function is total: it never throws on malformed input. A missing or
- * malformed `report` returns `[]`. A missing `thresholds` falls back to the
- * documented defaults.
+ * malformed `report` returns `[]`. A missing `thresholds` falls back to
+ * `DEFAULT_RETRO_PERF_THRESHOLDS` below.
  */
 
 /**
- * Defaults mirroring `.agentrc.json → delivery.retro.perfThresholds` so
- * callers (and tests) can omit `thresholds` and get the same behaviour as
- * a resolved config with no overrides. Keep in lockstep with
- * `lib/config/runners.js` (or wherever the resolver default lives) and the
- * `agentrc.schema.json` defaults stanza.
+ * Framework-fixed defaults for `classifyPerfSignals`. Callers (and tests)
+ * can omit `thresholds` and get these values. Not sourced from agentrc —
+ * edit this constant (and keep tests in lockstep) to change the gates.
  */
 export const DEFAULT_RETRO_PERF_THRESHOLDS = Object.freeze({
   utilisation: 0.6,