mandrel 1.58.0 → 1.59.0

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

@@ -321,7 +321,13 @@ export async function planEpic(
     Logger.warn(
       `[Epic Planner] Epic #${epicId} already has all requested planning artifacts. Aborting to prevent duplicates. Use --force to re-plan.`,
     );
-    return;
+    return {
+      persisted: false,
+      reason: 'already-planned',
+      prdId: existing.prd,
+      techSpecId: existing.techSpec,
+      acceptanceSpecId: existing.acceptanceSpec,
+    };
   }
   // Under --force we now OVERWRITE the canonical context tickets in place
   // (same issue numbers, refreshed bodies) rather than closing + recreating
@@ -388,8 +394,18 @@ export async function planEpic(
   if (acceptanceSpecId !== null) {
     artifactLines.push(`- [ ] Acceptance Spec: #${acceptanceSpecId}`);
   }
+  // Idempotent append (Story #4019): strip any pre-existing
+  // `## Planning Artifacts` section before re-appending. The `--force`
+  // path already stripped it in `healAndCleanupArtifacts`, but the
+  // partial-recovery rerun (e.g. PRD present, Tech Spec missing) reaches
+  // here with a body that may still carry a stale section — without the
+  // strip, every rerun stacked a duplicate section onto the Epic body.
   const appendBody = `\n\n## Planning Artifacts\n${artifactLines.join('\n')}\n`;
-  const newBody = epic.body + appendBody;
+  const strippedBody = epic.body.replace(
+    /\n*## Planning Artifacts[\s\S]*$/,
+    '',
+  );
+  const newBody = strippedBody + appendBody;
 
   /** @type {{ add?: string[], remove?: string[] }} */
   const labelMutations = {};
@@ -411,4 +427,12 @@ export async function planEpic(
 
   Logger.info(`[Epic Planner] Epic #${epicId} updated successfully.`);
   Logger.info(`[Epic Planner] Planning pipeline complete!`);
+
+  return {
+    persisted: true,
+    reason: force ? 'force-replan' : 'persisted',
+    prdId,
+    techSpecId,
+    acceptanceSpecId,
+  };
 }

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

@@ -7,10 +7,10 @@
  */
 
 import path from 'node:path';
-import { PROJECT_ROOT } from '../../../config-resolver.js';
 import { Logger } from '../../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../../label-constants.js';
 import { cleanupPhaseTempFiles } from '../../../plan-phase-cleanup.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 import { acquireEpicPlanLease } from '../../epic-plan-lease-guard.js';
 import {
   initialize as initializePlanState,
@@ -119,7 +119,7 @@ export async function runSpecPhase(
 
   await initializePlanState({ provider, epicId });
 
-  await planEpic(
+  const planResult = await planEpic(
     epicId,
     provider,
     { prdContent, techSpecContent, acceptanceSpecContent },
@@ -129,6 +129,7 @@ export async function runSpecPhase(
       planningRisk,
     },
   );
+  const specChanged = planResult?.persisted !== false;
 
   const afterPlan = await provider.getEpic(epicId);
   const prdId = afterPlan.linkedIssues?.prd ?? null;
@@ -199,10 +200,27 @@ export async function runSpecPhase(
   Logger.info(`[epic-plan-spec] Review routing: ${reviewRouting.decision}.`);
   Logger.info(`[epic-plan-spec] ${reviewRouting.operatorMessage}`);
 
-  Logger.info(
-    `[epic-plan-spec] Flipping Epic #${epicId} to ${AGENT_LABELS.REVIEW_SPEC}...`,
-  );
-  await setEpicLabel(provider, epicId, AGENT_LABELS.REVIEW_SPEC);
+  // Story #4019 (refining #3905): a spec-phase rerun that changed nothing
+  // (planEpic short-circuited on `already-planned`) MUST NOT demote a
+  // fully-decomposed `agent::ready` Epic back to `agent::review-spec` —
+  // there is no new spec content to review. The demotion fires only when
+  // the spec actually persisted/changed, or when the Epic is not at
+  // `agent::ready` (where the flip is the normal forward transition).
+  const epicLabels = afterPlan.labels ?? [];
+  const skipDemotion = !specChanged && epicLabels.includes(AGENT_LABELS.READY);
+  let labelTransition;
+  if (skipDemotion) {
+    labelTransition = 'kept-ready';
+    Logger.info(
+      `[epic-plan-spec] Spec unchanged (${planResult?.reason ?? 'already-planned'}) and Epic #${epicId} is ${AGENT_LABELS.READY} — keeping ${AGENT_LABELS.READY} (no demotion to ${AGENT_LABELS.REVIEW_SPEC}).`,
+    );
+  } else {
+    labelTransition = 'review-spec';
+    Logger.info(
+      `[epic-plan-spec] Flipping Epic #${epicId} to ${AGENT_LABELS.REVIEW_SPEC}...`,
+    );
+    await setEpicLabel(provider, epicId, AGENT_LABELS.REVIEW_SPEC);
+  }
 
   const cleanup = await cleanupPhaseTempFiles({ phase: 'spec', epicId });
 
@@ -231,5 +249,7 @@ export async function runSpecPhase(
     freshness,
     planningRisk,
     reviewRouting,
+    specChanged,
+    labelTransition,
   };
 }

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -19,9 +19,9 @@
  * Throws if no open Stories are found.
  */
 
-import { parseBlockedBy } from '../../../dependency-parser.js';
 import { computeWaves } from '../../../Graph.js';
 import { TYPE_LABELS } from '../../../label-constants.js';
+import { buildStoryAdjacency } from '../../../story-adjacency.js';
 import { WaveScheduler } from '../wave-scheduler.js';
 
 /**
@@ -116,30 +116,17 @@ function normalizeWavesForEmit(waves) {
  * Convert an ordered list of story tickets into the adjacency/taskMap shape
  * that `Graph.computeWaves()` expects.
  *
- * Dependency source order (must match manifest-builder.js so dispatch manifest
- * and runtime wave scheduling never disagree):
- *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the story
- *      ticket body via `parseBlockedBy` (same parser the dispatcher uses).
- *   2. Fallback: explicit `dependencies` array on the provider-returned story
- *      object (present in fixture / test payloads; optional in live GitHub
- *      payloads).
- * Only edges to other stories in this Epic are retained — foreign IDs are
- * dropped so the DAG stays closed over the scheduled set.
+ * The adjacency comes from the shared story-level builder
+ * (`lib/story-adjacency.js#buildStoryAdjacency`), which owns the
+ * dependency-source ordering contract (body `blocked by` references via
+ * `parseBlockedBy`, then explicit `dependencies[]`) and drops foreign
+ * edges so the DAG stays closed over the scheduled set.
  */
 function buildStoryDag(stories) {
-  const adjacency = new Map();
+  const adjacency = buildStoryAdjacency(stories);
   const taskMap = new Map();
-  const storyIds = new Set(stories.map((s) => Number(s.id ?? s.number)));
   for (const s of stories) {
     const id = Number(s.id ?? s.number);
-    const fromBody = parseBlockedBy(s.body ?? '');
-    const fromField = Array.isArray(s.dependencies)
-      ? s.dependencies.map(Number)
-      : [];
-    const merged = [...new Set([...fromBody, ...fromField])]
-      .map(Number)
-      .filter((dep) => dep !== id && storyIds.has(dep));
-    adjacency.set(id, merged);
     taskMap.set(id, { ...s, id });
   }
   return { adjacency, taskMap };

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/composition.js

@@ -24,7 +24,7 @@ import { EPIC_RUN_PROGRESS_TYPE, STATE_EMOJI } from './signals.js';
  * (`…`) when the string was longer. Returns the empty string for any
  * falsy input so table cells never render `undefined`/`null`.
  */
-export function truncate(s, n) {
+function truncate(s, n) {
   if (!s) return '';
   return s.length > n ? `${s.slice(0, n - 1)}…` : s;
 }
@@ -272,7 +272,6 @@ export async function renderProgressBody({
  *     wave: number,
  *     concurrencyCap?: number,
  *     stories?: Array<{ id: number, title?: string, state?: string,
- *                       tasksDone?: number, tasksTotal?: number,
  *                       blockerCommentId?: string }>,
  *   }>,
  *   currentWave: number,

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/signals.js

@@ -100,7 +100,6 @@ export function phaseToState(phase) {
  *     storyId: number,
  *     branch?: string,
  *     phase: 'init'|'implementing'|'closing'|'blocked'|'done',
- *     tasks?: [{ id, title?, state, commitSha? }],
  *     title?: string,
  *     updatedAt?: string,
  *   }
@@ -109,16 +108,11 @@ export function parseStoryRunProgressComment(comment) {
   const payload = parseFencedJsonComment(comment);
   if (!payload || typeof payload !== 'object') return null;
   const phase = typeof payload.phase === 'string' ? payload.phase : undefined;
-  const tasks = Array.isArray(payload.tasks) ? payload.tasks : [];
-  const tasksTotal = tasks.length;
-  const tasksDone = tasks.filter((t) => t && t.state === 'done').length;
   return {
     storyId: Number(payload.storyId),
     title: typeof payload.title === 'string' ? payload.title : '',
     phase,
     state: phaseToState(phase),
-    tasksDone,
-    tasksTotal,
   };
 }
 

package/.agents/scripts/lib/orchestration/epic-runner/progress-signals/component-drift.js

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { resolveComponents } from '../../../baselines/components.js';
+import { componentOrder } from './_bullet-format.js';
+
+/**
+ * Shared component-regression walk for the progress-signal drift detectors
+ * (Story #3984). `crap-drift.js` and `maintainability-drift.js` previously
+ * duplicated this baseline-rollup → per-component compare → bullet-list
+ * shape verbatim; the only divergence was the breach comparator (CRAP is
+ * "lower is better", maintainability is "higher is better") and the bullet
+ * text. Both detectors now parameterize this walk.
+ *
+ * Pure — the caller loads the baseline via `lib/baselines/reader.js#load(...)`
+ * and passes the resulting `{ rollup }` plus the gate config block.
+ *
+ * Only components whose rollup breaches the configured floor surface — a
+ * breach in a component-scoped floor does NOT report against `*` unless
+ * `*` itself breaches. This keeps the rollout narrowly targeted: when an
+ * operator wires up a per-component floor for `api`, regressing `api`
+ * names `api` — not `*`.
+ *
+ * @param {{
+ *   rollup?: Record<string, Record<string, number>>,
+ *   gateConfig?: { floors?: Record<string, Record<string, number>> } & object,
+ * }} params
+ * @param {{
+ *   isBreach: (value: number, floor: number) => boolean,
+ *   formatBullet: (name: string, axis: string, value: number, floor: number) => string,
+ * }} spec
+ * @returns {string[]}
+ */
+export function walkComponentRegressions(params = {}, spec) {
+  const rollup = params.rollup ?? {};
+  const gateConfig = params.gateConfig ?? {};
+  const floors = gateConfig.floors ?? {};
+  const components = resolveComponents(gateConfig);
+  const names = new Set([
+    ...Object.keys(components),
+    ...Object.keys(floors),
+    ...Object.keys(rollup),
+  ]);
+  const bullets = [];
+  for (const name of [...names].sort(componentOrder)) {
+    const aggregate = rollup[name];
+    if (!aggregate || typeof aggregate !== 'object') continue;
+    const floor = floors[name] ?? floors['*'];
+    if (!floor || typeof floor !== 'object') continue;
+    for (const axis of Object.keys(floor).sort()) {
+      const target = floor[axis];
+      const value = aggregate[axis];
+      if (typeof target !== 'number' || !Number.isFinite(target)) continue;
+      if (typeof value !== 'number' || !Number.isFinite(value)) continue;
+      if (!spec.isBreach(value, target)) continue;
+      bullets.push(spec.formatBullet(name, axis, value, target));
+    }
+  }
+  return bullets;
+}
+
+/**
+ * Shared wave-start snapshot persistence for the drift detectors. Both
+ * detectors persist a `{ capturedAt, ...metadata, scores }` JSON document
+ * under `<cwd>/<baselineDir>/<filename>` so a resumed epic run can re-read
+ * the wave-start anchor rather than lose it, and both treat persistence as
+ * best-effort (the in-memory baseline still works when a write fails).
+ *
+ * @param {{
+ *   fs: { readFileSync?: Function, writeFileSync?: Function, mkdirSync?: Function },
+ *   baselinePath: string,
+ *   metadata?: Record<string, unknown>,
+ * }} opts
+ */
+export function createSnapshotStore({ fs, baselinePath, metadata = {} }) {
+  return {
+    persist(scores) {
+      if (!fs.writeFileSync) return;
+      try {
+        fs.mkdirSync?.(path.dirname(baselinePath), { recursive: true });
+        fs.writeFileSync(
+          baselinePath,
+          JSON.stringify(
+            { capturedAt: new Date().toISOString(), ...metadata, scores },
+            null,
+            2,
+          ),
+        );
+      } catch {
+        // persistence is best-effort; the in-memory baseline still works
+      }
+    },
+
+    load() {
+      if (!fs.readFileSync) return null;
+      try {
+        const raw = fs.readFileSync(baselinePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed?.scores ?? null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/.agents/scripts/lib/orchestration/epic-runner/progress-signals/crap-drift.js

@@ -1,9 +1,12 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
-import { resolveComponents } from '../../../baselines/components.js';
 import { loadCoverage as defaultLoadCoverage } from '../../../coverage-utils.js';
 import { calculateCrapForSource } from '../../../crap-engine.js';
-import { componentOrder, formatNumber } from './_bullet-format.js';
+import { formatNumber } from './_bullet-format.js';
+import {
+  createSnapshotStore,
+  walkComponentRegressions,
+} from './component-drift.js';
 
 const DEFAULT_THRESHOLD = 5.0;
 const DEFAULT_CEILING = 30;
@@ -43,11 +46,10 @@ export function coverageKeyMatches(key, suffix) {
  *
  *   🧨 crap: <component> <axis> <value> > floor <floor>
  *
- * Only components whose rollup exceeds the configured floor surface — a
- * breach in a component-scoped floor does NOT report against `*` unless
- * `*` itself breaches. This keeps the rollout narrowly targeted: when an
- * operator wires up a per-component floor for `api`, regressing `api`
- * names `api` — not `*`.
+ * CRAP is a "lower is better" gate — every axis breach reports when
+ * `value > floor`. Component-scoped breaches do NOT trigger a `*` bullet
+ * unless `*` itself breaches. The walk itself is the shared
+ * `component-drift.js` helper (Story #3984).
  *
  * @param {{
  *   rollup?: Record<string, Record<string, number>>,
@@ -56,34 +58,11 @@ export function coverageKeyMatches(key, suffix) {
  * @returns {string[]}
  */
 export function detectComponentRegressions(params = {}) {
-  const rollup = params.rollup ?? {};
-  const gateConfig = params.gateConfig ?? {};
-  const floors = gateConfig.floors ?? {};
-  const components = resolveComponents(gateConfig);
-  const names = new Set([
-    ...Object.keys(components),
-    ...Object.keys(floors),
-    ...Object.keys(rollup),
-  ]);
-  const bullets = [];
-  // CRAP is a "lower is better" gate — every axis under crap is ≤ floor.
-  for (const name of [...names].sort(componentOrder)) {
-    const aggregate = rollup[name];
-    if (!aggregate || typeof aggregate !== 'object') continue;
-    const floor = floors[name] ?? floors['*'];
-    if (!floor || typeof floor !== 'object') continue;
-    for (const axis of Object.keys(floor).sort()) {
-      const cap = floor[axis];
-      const value = aggregate[axis];
-      if (typeof cap !== 'number' || !Number.isFinite(cap)) continue;
-      if (typeof value !== 'number' || !Number.isFinite(value)) continue;
-      if (value <= cap) continue;
-      bullets.push(
-        `🧨 crap: ${name} ${axis} ${formatNumber(value)} > floor ${formatNumber(cap)}`,
-      );
-    }
-  }
-  return bullets;
+  return walkComponentRegressions(params, {
+    isBreach: (value, cap) => value > cap,
+    formatBullet: (name, axis, value, cap) =>
+      `🧨 crap: ${name} ${axis} ${formatNumber(value)} > floor ${formatNumber(cap)}`,
+  });
 }
 
 /**
@@ -141,6 +120,11 @@ export function createCrapDriftDetector(opts = {}) {
   const baselineDir = opts.baselineDir ?? '.agents/state';
   const baselinePath = path.join(cwd, baselineDir, BASELINE_FILENAME);
   const logger = opts.logger ?? null;
+  const store = createSnapshotStore({
+    fs,
+    baselinePath,
+    metadata: { ceiling, threshold },
+  });
 
   let baseline = null;
 
@@ -220,39 +204,13 @@ export function createCrapDriftDetector(opts = {}) {
         }
       }
       baseline = snapshot;
-      if (fs.writeFileSync) {
-        try {
-          fs.mkdirSync?.(path.dirname(baselinePath), { recursive: true });
-          fs.writeFileSync(
-            baselinePath,
-            JSON.stringify(
-              {
-                capturedAt: new Date().toISOString(),
-                ceiling,
-                threshold,
-                scores: snapshot,
-              },
-              null,
-              2,
-            ),
-          );
-        } catch {
-          // persistence is best-effort; the in-memory baseline still works
-        }
-      }
+      store.persist(snapshot);
       return snapshot;
     },
 
     loadBaseline() {
-      if (!fs.readFileSync) return null;
-      try {
-        const raw = fs.readFileSync(baselinePath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        baseline = parsed?.scores ?? null;
-        return baseline;
-      } catch {
-        return null;
-      }
+      baseline = store.load();
+      return baseline;
     },
 
     async detect() {

package/.agents/scripts/lib/orchestration/epic-runner/progress-signals/maintainability-drift.js

@@ -1,9 +1,12 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
-import { resolveComponents } from '../../../baselines/components.js';
 import { calculateForSource } from '../../../maintainability-engine.js';
-import { componentOrder, formatNumber } from './_bullet-format.js';
+import { formatNumber } from './_bullet-format.js';
+import {
+  createSnapshotStore,
+  walkComponentRegressions,
+} from './component-drift.js';
 
 const DEFAULT_THRESHOLD = 2.0;
 // Distinct from the canonical ratchet baseline at `baselines/maintainability.json`
@@ -12,6 +15,35 @@ const DEFAULT_THRESHOLD = 2.0;
 // grep for the canonical baseline no longer hits the snapshot.
 const BASELINE_FILENAME = 'wave-mi-snapshot.json';
 
+/**
+ * Detect per-component maintainability regressions from a baseline rollup
+ * against the gate's configured floors. Pure — the caller loads the
+ * baseline via `lib/baselines/reader.js#load('maintainability')` and passes
+ * the resulting `{ rollup }` plus the gate config block.
+ *
+ * Bullet shape (Task #1919, Epic #1786):
+ *
+ *   📉 maintainability: <component> <axis> <value> < floor <floor>
+ *
+ * Maintainability is "higher is better" — every axis breach reports when
+ * `value < floor`. Component-scoped breaches do NOT trigger a `*` bullet
+ * unless `*` itself breaches. The walk itself is the shared
+ * `component-drift.js` helper (Story #3984).
+ *
+ * @param {{
+ *   rollup?: Record<string, Record<string, number>>,
+ *   gateConfig?: { floors?: Record<string, Record<string, number>> } & object,
+ * }} params
+ * @returns {string[]}
+ */
+export function detectComponentRegressions(params = {}) {
+  return walkComponentRegressions(params, {
+    isBreach: (value, target) => value < target,
+    formatBullet: (name, axis, value, target) =>
+      `📉 maintainability: ${name} ${axis} ${formatNumber(value)} < floor ${formatNumber(target)}`,
+  });
+}
+
 /**
  * Detects per-file maintainability drop versus a wave-start baseline.
  *
@@ -40,56 +72,6 @@ const BASELINE_FILENAME = 'wave-mi-snapshot.json';
  *   baselineDir?: string,           // directory (under cwd) to persist snapshot
  * }} [opts]
  */
-/**
- * Detect per-component maintainability regressions from a baseline rollup
- * against the gate's configured floors. Pure — the caller loads the
- * baseline via `lib/baselines/reader.js#load('maintainability')` and passes
- * the resulting `{ rollup }` plus the gate config block.
- *
- * Bullet shape (Task #1919, Epic #1786):
- *
- *   📉 maintainability: <component> <axis> <value> < floor <floor>
- *
- * Maintainability is "higher is better" — every axis breach reports when
- * `value < floor`. Component-scoped breaches do NOT trigger a `*` bullet
- * unless `*` itself breaches.
- *
- * @param {{
- *   rollup?: Record<string, Record<string, number>>,
- *   gateConfig?: { floors?: Record<string, Record<string, number>> } & object,
- * }} params
- * @returns {string[]}
- */
-export function detectComponentRegressions(params = {}) {
-  const rollup = params.rollup ?? {};
-  const gateConfig = params.gateConfig ?? {};
-  const floors = gateConfig.floors ?? {};
-  const components = resolveComponents(gateConfig);
-  const names = new Set([
-    ...Object.keys(components),
-    ...Object.keys(floors),
-    ...Object.keys(rollup),
-  ]);
-  const bullets = [];
-  for (const name of [...names].sort(componentOrder)) {
-    const aggregate = rollup[name];
-    if (!aggregate || typeof aggregate !== 'object') continue;
-    const floor = floors[name] ?? floors['*'];
-    if (!floor || typeof floor !== 'object') continue;
-    for (const axis of Object.keys(floor).sort()) {
-      const target = floor[axis];
-      const value = aggregate[axis];
-      if (typeof target !== 'number' || !Number.isFinite(target)) continue;
-      if (typeof value !== 'number' || !Number.isFinite(value)) continue;
-      if (value >= target) continue;
-      bullets.push(
-        `📉 maintainability: ${name} ${axis} ${formatNumber(value)} < floor ${formatNumber(target)}`,
-      );
-    }
-  }
-  return bullets;
-}
-
 export function createMaintainabilityDriftDetector(opts = {}) {
   const fs = opts.fs ?? nodeFs;
   const cwd = opts.cwd ?? process.cwd();
@@ -100,6 +82,7 @@ export function createMaintainabilityDriftDetector(opts = {}) {
     : DEFAULT_THRESHOLD;
   const baselineDir = opts.baselineDir ?? '.agents/state';
   const baselinePath = path.join(cwd, baselineDir, BASELINE_FILENAME);
+  const store = createSnapshotStore({ fs, baselinePath });
 
   let baseline = null;
 
@@ -126,34 +109,13 @@ export function createMaintainabilityDriftDetector(opts = {}) {
         if (s != null) snapshot[f] = s;
       }
       baseline = snapshot;
-      if (fs.writeFileSync) {
-        try {
-          fs.mkdirSync?.(path.dirname(baselinePath), { recursive: true });
-          fs.writeFileSync(
-            baselinePath,
-            JSON.stringify(
-              { capturedAt: new Date().toISOString(), scores: snapshot },
-              null,
-              2,
-            ),
-          );
-        } catch {
-          // persistence is best-effort; the in-memory baseline still works
-        }
-      }
+      store.persist(snapshot);
       return snapshot;
     },
 
     loadBaseline() {
-      if (!fs.readFileSync) return null;
-      try {
-        const raw = fs.readFileSync(baselinePath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        baseline = parsed?.scores ?? null;
-        return baseline;
-      } catch {
-        return null;
-      }
+      baseline = store.load();
+      return baseline;
     },
 
     async detect() {

package/.agents/scripts/lib/orchestration/epic-runner/story-run-progress-writer.js

@@ -13,7 +13,7 @@
  *
  * The renderer survives because its `{ body, payload }` output still feeds
  * two non-comment contracts: the `renderedBody` markdown the `/story-deliver`
- * and `single-story-deliver` CLIs (`story-phase.js`, `story-deliver-prepare.js`)
+ * and `single-story-deliver` CLIs (`story-phase.js`, the inline `story-init.js` prepare step)
  * relay to chat so the operator sees the phase table inline, and the snapshot
  * payload returned in those CLIs' JSON envelopes. `upsertStoryRunProgress`
  * therefore renders-only: it computes the body/payload and (optionally) mirrors
@@ -90,7 +90,7 @@ const STORY_PHASE_STATUS_EMOJI = {
 /**
  * Build the canonical default `phases[]` array for a freshly-initialized
  * 3-tier Story snapshot. All entries are `pending`; timestamps are null.
- * Exported so call sites (story-deliver-prepare, story-phase) and
+ * Exported so call sites (the story-init prepare step, story-phase) and
  * tests can build the same shape without re-implementing it.
  *
  * @returns {Array<{ name: string, status: 'pending', startedAt: null, endedAt: null }>}

package/.agents/scripts/lib/orchestration/epic-runner/sub-agent-return.js

@@ -9,8 +9,6 @@
  *     "storyId": <number>,
  *     "status": "done" | "blocked" | "failed",
  *     "phase": "init|implementing|closing|blocked|done",
- *     "tasksDone": <number>,
- *     "tasksTotal": <number>,
  *     "branchDeleted": <boolean>,
  *     "blockerCommentId": <string|null>,
  *     "detail": <string|undefined>,
@@ -119,8 +117,6 @@ function validateStoryReturnShape(obj) {
   }
   const value = { storyId, status };
   if (typeof obj.phase === 'string') value.phase = obj.phase;
-  if (Number.isInteger(obj.tasksDone)) value.tasksDone = obj.tasksDone;
-  if (Number.isInteger(obj.tasksTotal)) value.tasksTotal = obj.tasksTotal;
   if (typeof obj.branchDeleted === 'boolean') {
     value.branchDeleted = obj.branchDeleted;
   }
@@ -143,8 +139,8 @@ function quote(text) {
  * Story ticket's live state when the sub-agent return cannot be trusted.
  *
  * The result is always conservative — `status: 'failed'` unless the live
- * ticket carries `agent::done` (or `state: 'closed'`). The phase / counters
- * are best-effort, sourced from the Story's `story-run-progress` comment;
+ * ticket carries `agent::done` (or `state: 'closed'`). The phase is
+ * best-effort, sourced from the Story's `story-run-progress` comment;
  * absence of the comment is non-fatal.
  *
  * Story #3907 — a Story carrying `agent::blocked` reconciles to
@@ -163,8 +159,6 @@ function quote(text) {
  *   storyId: number,
  *   status: 'done' | 'blocked' | 'failed',
  *   phase?: string,
- *   tasksDone?: number,
- *   tasksTotal?: number,
  *   blockerCommentId?: string,
  *   reconciledFromGitHub: true,
  *   reconcileError?: string,
@@ -223,8 +217,8 @@ export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
     }
   }
 
-  // Cross-look the story-run-progress comment for phase / task counters when
-  // present. Story #3909 retired the per-Story story-run-progress *comment*
+  // Cross-look the story-run-progress comment for the phase when present.
+  // Story #3909 retired the per-Story story-run-progress *comment*
   // (the redundant mid-flight surface), so this read now usually finds nothing
   // and the reconciled row degrades to label-only — which is fine: the labels
   // are the authoritative state. Failure here is non-fatal.
@@ -237,12 +231,6 @@ export async function reconcileStoryFromGitHub({ provider, storyId } = {}) {
     const payload = comment ? parseFencedJsonComment(comment) : null;
     if (payload && typeof payload === 'object') {
       if (typeof payload.phase === 'string') out.phase = payload.phase;
-      if (Array.isArray(payload.tasks)) {
-        out.tasksTotal = payload.tasks.length;
-        out.tasksDone = payload.tasks.filter(
-          (t) => t && t.state === 'done',
-        ).length;
-      }
     }
   } catch (err) {
     out.reconcileError = err?.message ?? String(err);