mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/epic-plan-lease-guard.js

@@ -1,31 +1,30 @@
 /**
- * epic-plan-lease-guard.js — `/epic-plan` workflow guards (Story #3481,
+ * epic-plan-lease-guard.js — `/plan` workflow guards (Story #3481,
  * Epic #3457).
  *
  * Wires the assignee-as-lease primitive (`ticket-lease.js`, Story #3480) and a
  * decompose-idempotency guard into the split planning flow so two concurrent
- * `/epic-plan` runs cannot both drive the same Epic, and so a re-run does not
+ * `/plan` runs cannot both drive the same Epic, and so a re-run does not
  * silently duplicate the Feature/Story tree:
  *
  *   - `acquireEpicPlanLease`   — claim the Epic before Phase 7 (spec). Refuses
- *                                (throws, exit non-zero) when a foreign claim
- *                                already holds the Epic, naming the current
- *                                owner. **Fail-closed (audit #3513):**
- *                                `/epic-plan` emits no `story.heartbeat` during
- *                                its run (heartbeats are a delivery-time
- *                                signal), so there is no live-heartbeat source
- *                                to judge a concurrent plan's liveness from.
- *                                Defaulting liveness to "stale" made every
- *                                foreign claim look reclaimable, leaving the
- *                                guard inert. We therefore treat ANY foreign
- *                                assignee as a live claim and refuse the take
- *                                unless `--steal` forcibly transfers it. An
- *                                unassigned or self-held Epic still proceeds.
+ *                                (throws, exit non-zero) when a live foreign
+ *                                claim already holds the Epic, naming the
+ *                                current owner. **Claim-time liveness
+ *                                (Story #4019):** `/plan` emits no
+ *                                `story.heartbeat`, so the lease records its
+ *                                own claim-time in a `plan-lease` structured
+ *                                comment on the Epic at acquire time. A
+ *                                foreign claim fresher than the lease TTL
+ *                                refuses (unless `--steal`); a stale or
+ *                                record-less claim is reclaimed
+ *                                automatically. An unassigned or self-held
+ *                                Epic still proceeds.
  *   - `releaseEpicPlanLease`   — release the claim after Phase 8 (decompose).
  *                                Best-effort and self-scoped: a no-op once the
  *                                Epic was reassigned elsewhere.
  *   - `assertNoOpenPlanChildren` — refuse Phase 8 persist when the Epic already
- *                                has open Feature/Story children, unless the
+ *                                has open Story children, unless the
  *                                operator passed `--force` (a deliberate
  *                                re-decompose that closes the old tree).
  *
@@ -35,16 +34,18 @@
  */
 
 import { getGitHub } from '../config/github.js';
+import { resolveLeaseTtlMs } from '../config/limits.js';
 import { Logger } from '../Logger.js';
 import { TYPE_LABELS } from '../label-constants.js';
 import {
-  acquireLease,
-  normalizeOperatorHandle,
-  releaseLease,
-} from './ticket-lease.js';
+  acquireLeaseFailClosed,
+  resolveOperatorFromCandidates,
+} from './lease-guard-shared.js';
+import { currentOwner, releaseLease } from './ticket-lease.js';
+import { findStructuredComment, upsertStructuredComment } from './ticketing.js';
 
 /**
- * Resolve the operator handle that owns this `/epic-plan` run from
+ * Resolve the operator handle that owns this `/plan` run from
  * `github.operatorHandle`. The assignee-as-lease primitive is single-holder
  * keyed on a non-empty string; when no operator is configured (unset, or the
  * shipped `@[USERNAME]` placeholder, both of which `normalizeOperatorHandle`
@@ -52,32 +53,115 @@ import {
  * (`acquireEpicPlanLease`) then fails closed by throwing rather than running an
  * ownerless, unguarded plan.
  *
- * The `@`-prefix some operators carry on `operatorHandle` is stripped so the
- * value matches the bare login GitHub writes to (and returns from) a ticket's
- * `assignees` — otherwise the assignee PATCH is rejected (HTTP 422, invalid
- * assignee) and the self-held-claim comparison (`owner === operator`) never
- * matches. This mirrors the sibling lease guards
- * (`single-story-lease-guard.js`, `epic-deliver-lease-guard.js`).
+ * The `@`-prefix some operators carry on `operatorHandle` is stripped (via
+ * the shared lease-guard kernel) so the value matches the bare login GitHub
+ * writes to (and returns from) a ticket's `assignees` — otherwise the
+ * assignee PATCH is rejected (HTTP 422, invalid assignee) and the
+ * self-held-claim comparison (`owner === operator`) never matches.
+ *
+ * The plan surface's missing-handle policy is `'null'` (intentional
+ * divergence from the standalone path's `'throw'`): `releaseEpicPlanLease`
+ * is best-effort and must degrade to a `no-operator` no-op rather than
+ * throw, so the throw-on-missing decision lives in `acquireEpicPlanLease`.
  *
  * @param {object} config Resolved config bag.
  * @returns {string|null}
  */
 export function resolveOperator(config) {
-  return normalizeOperatorHandle(getGitHub(config).operatorHandle);
+  return resolveOperatorFromCandidates({
+    candidates: [getGitHub(config).operatorHandle],
+  });
+}
+
+/**
+ * Structured-comment type carrying the plan-lease claim-time record.
+ * Registered in `ticketing/reads.js` `STRUCTURED_COMMENT_TYPES`.
+ */
+export const PLAN_LEASE_COMMENT_TYPE = 'plan-lease';
+
+/**
+ * Render the `plan-lease` structured-comment body: a one-line human
+ * summary plus the canonical fenced-JSON record `parsePlanLeaseClaim`
+ * reads back.
+ *
+ * @param {{ epicId: number, owner: string, claimedAt: string }} input
+ *   `claimedAt` is an ISO-8601 timestamp.
+ * @returns {string}
+ */
+export function buildPlanLeaseCommentBody({ epicId, owner, claimedAt }) {
+  const record = {
+    kind: PLAN_LEASE_COMMENT_TYPE,
+    epicId,
+    owner,
+    claimedAt,
+  };
+  return [
+    `### 🔒 Plan Lease — claimed by \`${owner}\``,
+    '',
+    `This Epic is being planned by \`${owner}\` (claimed ${claimedAt}). A`,
+    'concurrent `/plan` run refuses while this claim is fresher than the',
+    'lease TTL, and reclaims automatically once it goes stale.',
+    '',
+    '```json',
+    JSON.stringify(record, null, 2),
+    '```',
+  ].join('\n');
+}
+
+/**
+ * Parse the claim record out of a `plan-lease` comment body. Returns
+ * `{ owner, claimedAtMs }` or `null` when the body carries no readable
+ * record — which callers treat as "no claim-time recorded" (stale,
+ * reclaimable).
+ *
+ * @param {string|undefined|null} body
+ * @returns {{ owner: string, claimedAtMs: number } | null}
+ */
+export function parsePlanLeaseClaim(body) {
+  if (typeof body !== 'string') return null;
+  const match = body.match(/```json\s*\n([\s\S]*?)\n\s*```/);
+  if (!match) return null;
+  let record;
+  try {
+    record = JSON.parse(match[1]);
+  } catch (_err) {
+    return null;
+  }
+  if (!record || record.kind !== PLAN_LEASE_COMMENT_TYPE) return null;
+  const owner =
+    typeof record.owner === 'string' && record.owner.length > 0
+      ? record.owner
+      : null;
+  const claimedAtMs = Date.parse(record.claimedAt ?? '');
+  if (owner === null || !Number.isFinite(claimedAtMs)) return null;
+  return { owner, claimedAtMs };
 }
 
 /**
  * Acquire the Epic-lease before Phase 7.
  *
- * **Fail-closed (audit #3513).** `/epic-plan` emits no `story.heartbeat`
- * during its run, so there is no live-heartbeat source to judge a concurrent
- * plan's liveness from. Rather than default liveness to "stale" (which made
- * every foreign claim look reclaimable and left this guard inert), we anchor
- * `heartbeatAt` to the same `now` the lease primitive evaluates against. That
- * makes `isClaimLive` return true for ANY foreign owner, so `acquireLease`
- * refuses a foreign assignee unless `steal` is set — naming the current owner.
- * An unassigned Epic (`unclaimed`) or a self-held claim (`already-held`) still
- * proceeds without a write. This mirrors `single-story-lease-guard.js`.
+ * **Claim-time liveness (Story #4019, superseding the audit-#3513
+ * fail-closed anchor).** `/plan` emits no `story.heartbeat`, so the
+ * old guard treated EVERY foreign assignee as live — which made the
+ * documented "`--steal` once you have confirmed the other run is dead"
+ * contract undecidable (there was no in-band liveness signal to confirm
+ * against). The lease now records its own claim-time: on every successful
+ * acquire the guard upserts a `plan-lease` structured comment on the Epic
+ * carrying `{ owner, claimedAt }`. A subsequent run judges a foreign
+ * claim's liveness from that claim-time against the lease TTL
+ * (`resolveLeaseTtlMs`):
+ *
+ *   - **Fresh foreign claim** (claim-time within TTL) → refuse, naming the
+ *     owner and the claim age; `--steal` force-transfers.
+ *   - **Stale foreign claim** (claim-time older than TTL) → reclaim
+ *     automatically.
+ *   - **No claim-time record** (foreign assignee but no readable
+ *     `plan-lease` comment, or the comment names a different owner) →
+ *     treated as stale and reclaimed — the assignee predates this
+ *     mechanism or was set out-of-band, so there is nothing to wait on.
+ *
+ * An unassigned Epic (`unclaimed`) or a self-held claim (`already-held`)
+ * proceeds; both refresh the claim-time record.
  *
  * A refused claim throws (caught at the CLI boundary → exit non-zero).
  *
@@ -85,7 +169,7 @@ export function resolveOperator(config) {
  * @param {import('../ITicketingProvider.js').ITicketingProvider} args.provider
  * @param {number} args.epicId
  * @param {object} [args.config]
- * @param {boolean} [args.steal=false]   Force-transfer a foreign claim.
+ * @param {boolean} [args.steal=false]   Force-transfer a live foreign claim.
  * @param {number} [args.now]            Injectable clock (epoch ms; tests).
  * @returns {Promise<{ acquired: boolean, owner: string|null, previousOwner: string|null, reason: string }>}
  */
@@ -102,37 +186,88 @@ export async function acquireEpicPlanLease({
       `[epic-plan] Refusing to plan Epic #${epicId}: no operator identity is ` +
         'configured. github.operatorHandle is unset or still the shipped ' +
         '`@[USERNAME]` placeholder, so the Epic-lease has no owner and ' +
-        'concurrent /epic-plan runs cannot be serialised. Set your own handle ' +
+        'concurrent /plan runs cannot be serialised. Set your own handle ' +
         'in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
         '"@your-login" } }) and re-run.',
     );
   }
 
-  // Fail closed: with no live-heartbeat source on the plan path, treat any
-  // foreign assignee as a live claim by anchoring `heartbeatAt` to the same
-  // `now` the primitive evaluates against (`isClaimLive` → true for any owner).
-  // `acquireLease` then refuses a foreign claim unless `steal` is set; an
-  // unassigned or self-held Epic proceeds without a write.
   const resolvedNow =
     typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-  const result = await acquireLease({
+  const ttlMs = resolveLeaseTtlMs(config);
+
+  // Resolve the current assignee and the recorded claim-time. The
+  // claim-time only counts when the `plan-lease` record names the same
+  // owner as the assignee — a mismatched or missing record means the claim
+  // has no liveness signal and is treated as stale (reclaimable).
+  const ticket = await provider.getTicket(epicId);
+  const owner = currentOwner(ticket?.assignees);
+  let heartbeatAt = null;
+  if (owner !== null && owner !== operator) {
+    let claim = null;
+    try {
+      const comment = await findStructuredComment(
+        provider,
+        epicId,
+        PLAN_LEASE_COMMENT_TYPE,
+      );
+      claim = comment ? parsePlanLeaseClaim(comment.body) : null;
+    } catch (err) {
+      Logger.warn(
+        `[epic-plan] Could not read plan-lease claim record on #${epicId} ` +
+          `(treating foreign claim as stale): ${err.message}`,
+      );
+    }
+    if (claim && claim.owner === owner) {
+      heartbeatAt = claim.claimedAtMs;
+    }
+  }
+
+  const result = await acquireLeaseFailClosed({
     provider,
     ticketId: epicId,
     operator,
-    heartbeatAt: resolvedNow,
+    heartbeatAt,
     steal,
     config,
     now: resolvedNow,
+    renderRefusal: (refused) => {
+      const ageMinutes =
+        heartbeatAt !== null
+          ? Math.round((resolvedNow - heartbeatAt) / 60000)
+          : null;
+      const ageNote =
+        ageMinutes !== null
+          ? `Its plan-lease claim is ~${ageMinutes} minute(s) old (TTL ${Math.round(ttlMs / 60000)} minute(s)), so the run is presumed live. `
+          : '';
+      return (
+        `[epic-plan] Epic #${epicId} is currently claimed by '${refused.owner}'. ` +
+        `Refusing to plan concurrently — another /plan run owns this Epic. ` +
+        `${ageNote}Wait for that run to finish (the claim auto-expires at the ` +
+        `lease TTL), or re-run with --steal to forcibly transfer the claim.`
+      );
+    },
   });
 
-  if (!result.acquired) {
-    throw new Error(
-      `[epic-plan] Epic #${epicId} is currently claimed by '${result.owner}'. ` +
-        `Refusing to plan concurrently — another /epic-plan run owns this Epic ` +
-        `(the plan path has no heartbeat ledger, so a foreign assignee always ` +
-        `blocks unless stolen). Wait for that run to finish, or re-run with ` +
-        `--steal to forcibly transfer the claim once you have confirmed the ` +
-        `other run is dead.`,
+  // Record (or refresh) the claim-time so the next run can judge this
+  // claim's liveness. Best-effort: a comment failure degrades to a
+  // record-less claim (which a later run treats as stale) — it never
+  // fails the plan.
+  try {
+    await upsertStructuredComment(
+      provider,
+      epicId,
+      PLAN_LEASE_COMMENT_TYPE,
+      buildPlanLeaseCommentBody({
+        epicId,
+        owner: operator,
+        claimedAt: new Date(resolvedNow).toISOString(),
+      }),
+    );
+  } catch (err) {
+    Logger.warn(
+      `[epic-plan] Failed to record plan-lease claim-time on #${epicId} ` +
+        `(non-fatal; a later run will treat this claim as stale): ${err.message}`,
     );
   }
 
@@ -206,10 +341,14 @@ export async function assertNoOpenPlanChildren({
   const openChildren = (children ?? []).filter((t) => {
     const labels = Array.isArray(t.labels) ? t.labels : [];
     const isOpen = t.state === undefined || t.state === 'open';
+    // Any open typed plan ticket counts — `type::story` plus pre-v4
+    // `type::feature` leftovers. The prefix check is legacy-data
+    // detection, not compat support: the guard only refuses, it never
+    // processes the legacy tier. Context tickets (`context::*`) are
+    // untouched.
     return (
       isOpen &&
-      (labels.includes(TYPE_LABELS.FEATURE) ||
-        labels.includes(TYPE_LABELS.STORY))
+      labels.some((l) => typeof l === 'string' && l.startsWith('type::'))
     );
   });
 
@@ -222,12 +361,21 @@ export async function assertNoOpenPlanChildren({
       openChildren.length > 10
         ? `\n  …and ${openChildren.length - 10} more`
         : '';
+    const legacyCount = openChildren.filter(
+      (t) => !(t.labels ?? []).includes(TYPE_LABELS.STORY),
+    ).length;
+    const legacyHint =
+      legacyCount > 0
+        ? `\n${legacyCount} of these are not type::story — they look like ` +
+          `legacy pre-v4 Feature tickets; migrate or close them per the ` +
+          `v1.60.0 migration notes before re-planning.`
+        : '';
     throw new Error(
       `[epic-plan-decompose] Epic #${epicId} already has ` +
-        `${openChildren.length} open Feature/Story child ticket(s):\n${summary}${more}\n\n` +
+        `${openChildren.length} open plan child ticket(s):\n${summary}${more}\n\n` +
         `Persisting now would duplicate the breakdown. Re-run with --force to ` +
         `close the existing tree and re-decompose, or close the stale children ` +
-        `by hand first.`,
+        `by hand first.${legacyHint}`,
     );
   }
 

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

@@ -8,8 +8,8 @@
  */
 
 import path from 'node:path';
-import { PROJECT_ROOT } from '../../../config-resolver.js';
 import * as gitUtils from '../../../git-utils.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 import { forceDrainPendingCleanup } from '../../../worktree/lifecycle/force-drain.js';
 import { readManifest } from '../../../worktree/lifecycle/pending-cleanup.js';
 import { sweepStaleStoryWorktrees } from '../../plan-runner/worktree-sweep.js';

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

@@ -78,7 +78,7 @@ export async function overwriteContextTicket(
   try {
     await provider.postComment(ticketId, {
       type: 'notification',
-      body: `♻️ **Regeneration Audit**: This ${artifact} body was regenerated in place by a \`/epic-plan --force\` re-plan. The issue number and prior discussion history are preserved.`,
+      body: `♻️ **Regeneration Audit**: This ${artifact} body was regenerated in place by a \`/plan --force\` re-plan. The issue number and prior discussion history are preserved.`,
     });
   } catch (_err) {
     // Audit comment is best-effort — never fail the overwrite on a comment
@@ -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/prompts.js

@@ -1,6 +1,6 @@
 /**
  * phases/prompts.js — Canonical PRD / Tech Spec / Acceptance Spec system
- * prompts for the spec phase of `/epic-plan`.
+ * prompts for the spec phase of `/plan`.
  *
  * These ride along on the `--emit-context` envelope as a backstop. The
  * `epic-plan-spec-author` Skill

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,
@@ -112,14 +112,14 @@ export async function runSpecPhase(
   }
 
   // Workflow-guards (Story #3481): acquire the Epic-lease before any Phase 7
-  // mutation so two concurrent /epic-plan runs cannot both drive this Epic. The
+  // mutation so two concurrent /plan runs cannot both drive this Epic. The
   // guard fails closed (audit #3513) — any foreign assignee refuses here and
   // the CLI exits non-zero naming the owner, unless `--steal` transfers it.
   await acquireEpicPlanLease({ provider, epicId, config, steal });
 
   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;
@@ -157,7 +158,7 @@ export async function runSpecPhase(
   // Story #1585 (Epic #1471): the baseline-snapshot fork was previously
   // performed here at plan-time. It now runs at first-story-init time
   // inside `lib/story-init/branch-initializer.js#bootstrapWorktree` so
-  // `/epic-plan` remains git-state-free. `forkAndCommitEpicSnapshot` and
+  // `/plan` remains git-state-free. `forkAndCommitEpicSnapshot` and
   // `forkMainToEpic` remain exported for that caller.
 
   const reviewRouting = resolveReviewRouting({ planningRisk, forceReview });
@@ -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-plan-state-store.js

@@ -30,7 +30,7 @@
  * the lifecycle phase is already authoritative on the Epic's `agent::*` labels,
  * so the duplicate `phase` telemetry (and its `setPhase` round-trips) was
  * deleted. The fields that survive — `spec`, `decompose`, `planningRisk`,
- * `reviewRouting`, `manifestCommentId` — are the ones `/epic-plan --resume`
+ * `reviewRouting`, `manifestCommentId` — are the ones `/plan --resume`
  * reads to skip already-completed work.
  */
 

package/.agents/scripts/lib/orchestration/epic-run-state-store.js

@@ -1,6 +1,6 @@
 /**
  * epic-run-state-store — stateless functions for reading and writing the
- * `epic-run-state` structured comment used by `/epic-deliver`.
+ * `epic-run-state` structured comment used by `/deliver`.
  *
  * This module is the function-based replacement for the legacy
  * `Checkpointer` class that previously lived at
@@ -133,7 +133,7 @@ export async function initialize({
  * Reconcile the resume pointer (`currentWave` + `waves[]` history) against
  * a freshly-recomputed wave plan.
  *
- * Story #3358 — when `/epic-deliver` is resumed on a partially-complete
+ * Story #3358 — when `/deliver` is resumed on a partially-complete
  * Epic, `epic-deliver-prepare.js` recomputes the wave DAG over only the
  * **not-done** Stories (`build-wave-dag.js#discoverOpenStories` drops the
  * closed/merged Stories). The recomputed plan is therefore *shorter* and
@@ -270,7 +270,7 @@ export async function appendIntervention({ provider, epicId, entry } = {}) {
 }
 
 /**
- * Advance the checkpoint's `phase` field to the next `/epic-deliver`
+ * Advance the checkpoint's `phase` field to the next `/deliver`
  * phase. Reads the current state first so the caller does not need to
  * keep an in-memory copy. Other state fields are preserved verbatim.
  *

package/.agents/scripts/lib/orchestration/epic-runner/concurrency-gate.js

@@ -1,10 +1,10 @@
 /**
  * Cross-Story conflict-finding gate for `epic-deliver-prepare.js`.
  *
- * Story #2297 — when the bounded `/epic-plan` flow emitted concurrency
+ * Story #2297 — when the bounded `/plan` flow emitted concurrency
  * findings (Story #2296's validator pass), the operator may have shipped
- * them through to `/epic-deliver` without resolving the underlying
- * `depends_on` gaps. This gate runs at Phase 1 of `/epic-deliver` and
+ * them through to `/deliver` without resolving the underlying
+ * `depends_on` gaps. This gate runs at Phase 1 of `/deliver` and
  * refuses to flip the Epic to `agent::executing` when the upcoming
  * waves still contain unresolved conflicts — surfacing the exact
  * remediation commands the operator should run before retrying.
@@ -138,7 +138,7 @@ export function renderGateErrorMessage(findings, ownerRepo) {
     lines.push('');
   }
   lines.push(
-    'Resolve the listed conflicts and re-run `/epic-deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
+    'Resolve the listed conflicts and re-run `/deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
   );
   return lines.join('\n');
 }

package/.agents/scripts/lib/orchestration/epic-runner/deliver-phases.js

@@ -1,5 +1,5 @@
 /**
- * deliver-phases.js — phase enum and ordering utility for `/epic-deliver`.
+ * deliver-phases.js — phase enum and ordering utility for `/deliver`.
  *
  * Story #1155 (Epic #1142, 5.40.0). Originally extracted from the
  * legacy class-based checkpoint module so the phase enum and close-tail
@@ -11,7 +11,7 @@
  */
 
 /**
- * Ordered list of `/epic-deliver` phases. The checkpoint's `phase` field
+ * Ordered list of `/deliver` phases. The checkpoint's `phase` field
  * stores the **next phase to run**, so a mid-flight crash during
  * `code-review` resumes by reading `phase === 'code-review'` and re-
  * entering Phase D from the start.
@@ -44,7 +44,7 @@ export function assertValidDeliverPhase(nextPhase) {
   if (nextPhase === 'done') return;
   if (phaseIndex(nextPhase) >= 0) return;
   throw new Error(
-    `Invalid /epic-deliver phase ${JSON.stringify(nextPhase)}. ` +
+    `Invalid /deliver phase ${JSON.stringify(nextPhase)}. ` +
       `Expected one of ${DELIVER_PHASES.join(', ')} or 'done'.`,
   );
 }