mandrel 1.76.0 → 1.78.0

package/.agents/scripts/single-story-init.js

@@ -51,6 +51,7 @@ import {
   branchExistsLocally,
   branchExistsViaTrackingRef,
   classifyBranchSeed,
+  seedStoryBranchRef,
 } from './lib/git-branch-lifecycle.js';
 import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
@@ -376,36 +377,28 @@ export async function materializeBaseBranch({
  * @param {Function} opts.progress
  */
 export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
-  const seedAction = decideStoryBranchSeed({
-    localHas: branchExistsLocally(storyBranch, cwd),
-    remoteHas: branchExistsViaTrackingRef(storyBranch, cwd),
+  // Standalone path: no concurrent creator to race, so create failures are
+  // fatal (`swallowCreateRace: false`) and a failed fetch throws. The
+  // seed-action switch shell is single-homed in `seedStoryBranchRef`
+  // (Story #4255); this caller only supplies its `baseRef`, its git seams
+  // bound to `cwd`, and its own log/error vocabulary.
+  seedStoryBranchRef({
+    storyBranch,
+    baseRef: baseBranch,
+    swallowCreateRace: false,
+    spawn: (args) => gitSpawn(cwd, ...args),
+    existsLocally: (b) => branchExistsLocally(b, cwd),
+    existsRemotely: (b) => branchExistsViaTrackingRef(b, cwd),
+    progress,
+    messages: {
+      reuse: (b) => `Reusing existing local story branch: ${b}`,
+      fetch: (b) => `Fetching remote story branch: ${b}`,
+      create: (b, ref) => `Creating story branch ref: ${b} from ${ref}`,
+      createError: (b, _ref, stderr) =>
+        `Failed to create story branch ${b}: ${stderr || '(no stderr)'}`,
+      fetchError: (b, stderr) => `Failed to fetch story branch ${b}: ${stderr}`,
+    },
   });
-  if (seedAction === 'fetch') {
-    progress('GIT', `Fetching remote story branch: ${storyBranch}`);
-    const r = gitSpawn(cwd, 'fetch', 'origin', `${storyBranch}:${storyBranch}`);
-    if (r.status !== 0) {
-      throw new Error(
-        `Failed to fetch story branch ${storyBranch}: ${r.stderr || '(no stderr)'}`,
-      );
-    }
-    return;
-  }
-  if (seedAction === 'create') {
-    progress(
-      'GIT',
-      `Creating story branch ref: ${storyBranch} from ${baseBranch}`,
-    );
-    const r = gitSpawn(cwd, 'branch', storyBranch, baseBranch);
-    if (r.status !== 0) {
-      throw new Error(
-        `Failed to create story branch ${storyBranch}: ${r.stderr || '(no stderr)'}`,
-      );
-    }
-    return;
-  }
-  // seedAction === 'reuse' — the local ref already exists. Do NOT run
-  // `git branch` here; re-creating an existing ref throws. Reuse it.
-  progress('GIT', `Reusing existing local story branch: ${storyBranch}`);
 }
 
 /**

package/.agents/scripts/story-init.js

@@ -38,7 +38,6 @@ import {
 } from './lib/config-resolver.js';
 import { parseBlockedBy } from './lib/dependency-parser.js';
 import { getEpicBranch, getStoryBranch } from './lib/git-utils.js';
-import { runInstallCommand } from './lib/install-cmd-parser.js';
 import { Logger } from './lib/Logger.js';
 import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
 import {
@@ -89,6 +88,8 @@ export async function runStoryInit({
   dryRun: dryRunParam,
   cwd: cwdParam,
   recutOf: recutOfParam,
+  prdId: prdIdParam,
+  techSpecId: techSpecIdParam,
   injectedProvider,
   injectedConfig,
 } = {}) {
@@ -99,10 +100,17 @@ export async function runStoryInit({
           dryRun: !!dryRunParam,
           cwd: cwdParam ?? null,
           recutOf: recutOfParam ?? null,
+          prdId: prdIdParam ?? null,
+          techSpecId: techSpecIdParam ?? null,
         }
       : parseSprintArgs();
   const { storyId, dryRun } = parsed;
   const recutOf = recutOfParam ?? parsed.recutOf ?? null;
+  // Story #4253: pre-resolved Epic linkages (from the /deliver fan-out's
+  // one-time Epic resolution). When both are present, hierarchy-tracer skips
+  // the per-Story getEpic round-trip; when absent it resolves them itself.
+  const threadedPrdId = prdIdParam ?? parsed.prdId ?? null;
+  const threadedTechSpecId = techSpecIdParam ?? parsed.techSpecId ?? null;
   // Worktree-aware cwd resolution: explicit param > --cwd flag > env > PROJECT_ROOT.
   const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
 
@@ -147,11 +155,13 @@ export async function runStoryInit({
     input: { storyId, recutOf, dryRun },
   });
 
-  // Stage 2 — hierarchy.
+  // Stage 2 — hierarchy. When the /deliver fan-out threaded --prd/--tech-spec
+  // (both resolved once by the parent), this short-circuits the per-Story
+  // getEpic. Absent flags fall back to the legacy getEpic resolution.
   const { prdId, techSpecId } = await traceHierarchy({
     provider,
     logger: stageLogger,
-    input: { epicId },
+    input: { epicId, prdId: threadedPrdId, techSpecId: threadedTechSpecId },
   });
 
   progress('CONTEXT', `Epic: #${epicId}, Parent: #${parentId ?? 'none'}`);
@@ -366,9 +376,16 @@ const VALID_INSTALLED_STATES = new Set(['true', 'false', 'skipped']);
 
 /**
  * Apply the dependenciesInstalled tri-state to derive the next install
- * action. Pure helper — exposes the Step 0.5 truth table as data so tests
+ * action. Pure helper — exposes the install truth table as data so tests
  * can pin each branch without spinning up a child process.
  *
+ * Story #4249: this is no longer wired into a post-init re-install. The
+ * in-`ensure` install (with its PM-aware retry budget) is the single install
+ * owner; the formerly-hardcoded `npm ci` retry inside `runStoryInitPrepare`
+ * was deleted. The tri-state still flows onto the `story-init` structured
+ * comment (`dependenciesInstalled`) as the workflow-facing signal, and this
+ * helper remains its canonical classifier.
+ *
  * @param {'true' | 'false' | 'skipped'} dependenciesInstalled
  * @param {{ skipInstall?: boolean }} [options]
  * @returns {'skip' | 'install'}
@@ -384,54 +401,33 @@ export function deriveInstallAction(dependenciesInstalled, options = {}) {
 }
 
 /**
- * Resolve the install command to run when `dependenciesInstalled === 'false'`.
- * `project.commands` does not currently carry a dedicated install key,
- * so this defaults to `npm ci`. Operators can override per-invocation via
- * the `installCmd` option.
+ * Post-init prepare step (Story #4017 — formerly a standalone prepare CLI,
+ * now consuming the in-process init result instead of re-reading the
+ * `story-init` structured comment).
  *
- * @param {{ override?: string }} [options]
- * @returns {string}
- */
-export function resolveInstallCommand(options = {}) {
-  const trimmed = options.override?.trim();
-  if (trimmed) {
-    return trimmed;
-  }
-  return 'npm ci';
-}
-
-/**
- * Post-init prepare step (Story #4017 — formerly a standalone prepare
- * CLI, now consuming the in-process init result
- * instead of re-reading the `story-init` structured comment):
+ * Story #4249: the install branch was deleted. The worktree install is owned
+ * entirely by `WorktreeManager.ensure` (via `installDependencies`), which now
+ * carries a PM-aware retry budget (`installRetryPolicy`) — so a transient
+ * first-attempt failure retries there with the correct package-manager
+ * command, never an unconditional `npm ci` re-run after init. This step is now
+ * purely the snapshot-render half:
  *
- *   1. Apply the `dependenciesInstalled` tri-state truth table — `'false'`
- *      (install attempted and failed) retries the install command in the
- *      worktree; `'true'` / `'skipped'` proceed.
- *   2. Render the initial Story-phase snapshot with every phase pinned to
- *      `pending` and `phase: 'init'` via `upsertStoryRunProgress`
- *      (render-only since Story #3909 — no comment is posted). The
- *      `renderedBody` markdown is relayed to chat by the delivery
- *      workflows so operators see the initial progress block before the
- *      first commit lands.
+ *   - Render the initial Story-phase snapshot with every phase pinned to
+ *     `pending` and `phase: 'init'` via `upsertStoryRunProgress` (render-only
+ *     since Story #3909 — no comment is posted). The `renderedBody` markdown is
+ *     relayed to chat by the delivery workflows so operators see the initial
+ *     progress block before the first commit lands.
  *
- * Install failure throws (init exits non-zero); a snapshot-render failure
- * is non-fatal observability loss and only warns.
+ * A snapshot-render failure is non-fatal observability loss and only warns.
  *
  * @param {{
  *   provider: object,
  *   storyId: number,
- *   result: { workCwd?: string, dependenciesInstalled?: string, storyBranch?: string },
+ *   result: { storyBranch?: string },
  *   notify?: Function | null,
- *   runInstall?: (cmd: string, cwd: string) => { status: number, stderr?: string },
- *   skipInstall?: boolean,
- *   installCmd?: string,
  *   logger?: object,
  * }} args
  * @returns {Promise<{
- *   installAction: 'skip' | 'install',
- *   installCmd: string | null,
- *   installResult: { status: number, stderr?: string } | null,
  *   snapshot: object | null,
  *   renderedBody: string | null,
  * }>}
@@ -441,29 +437,8 @@ export async function runStoryInitPrepare({
   storyId,
   result,
   notify: notifyFn = null,
-  runInstall = runInstallCommand,
-  skipInstall = false,
-  installCmd: installCmdOverride,
   logger = stageLogger,
 }) {
-  const dependenciesInstalled = String(
-    result?.dependenciesInstalled ?? 'skipped',
-  );
-  const installAction = deriveInstallAction(dependenciesInstalled, {
-    skipInstall,
-  });
-  let installCmd = null;
-  let installResult = null;
-  if (installAction === 'install') {
-    installCmd = resolveInstallCommand({ override: installCmdOverride });
-    installResult = runInstall(installCmd, result.workCwd);
-    if (installResult.status !== 0) {
-      throw new Error(
-        `runStoryInitPrepare: install command \`${installCmd}\` failed with status ${installResult.status}: ${installResult.stderr ?? ''}`,
-      );
-    }
-  }
-
   let snapshot = null;
   let renderedBody = null;
   try {
@@ -483,7 +458,7 @@ export async function runStoryInitPrepare({
     );
   }
 
-  return { installAction, installCmd, installResult, snapshot, renderedBody };
+  return { snapshot, renderedBody };
 }
 
 function buildStoryInitResult({

package/.agents/scripts/story-phase.js

@@ -27,6 +27,12 @@
  *   --story <id>                        Story ID (required).
  *   --phase <init|implementing|closing|blocked|done>
  *                                       Phase the Story is entering (required).
+ *   --epic <id>                         Parent Epic id from the Step 0 envelope.
+ *                                       When supplied, skips the readEpicIdFromStory
+ *                                       GitHub read.
+ *   --branch <name>                     Story branch from the Step 0 envelope.
+ *                                       When supplied, skips the resolveStoryBranch
+ *                                       GitHub read.
  *   --no-heartbeat                      Suppress the lifecycle emit (tests).
  *
  * Stdout: a single JSON envelope
@@ -67,12 +73,17 @@ const VALID_PHASES = new Set([
 
 const HELP = `Usage: node .agents/scripts/story-phase.js \\
   --story <id> --phase <init|implementing|closing|blocked|done> \\
-  [--no-heartbeat]
+  [--epic <id>] [--branch <name>] [--no-heartbeat]
 
 Renders the Story-phase snapshot for Story #<id> at the requested phase
 (returned as renderedBody for chat relay; no comment is posted) and
 (unless --no-heartbeat) appends one story.heartbeat record to the parent
 Epic's lifecycle ledger so the Idle Watchdog can confirm the Story is alive.
+
+--epic / --branch let the caller pass the parent Epic id and Story branch
+from story-init.js's Step 0 envelope, skipping the GitHub reads
+(readEpicIdFromStory / resolveStoryBranch) that would otherwise re-fetch
+these immutable values on every phase call. Omit both for interactive use.
 `;
 
 /**
@@ -216,9 +227,17 @@ function emitHeartbeatBestEffort({
  * End-to-end phase writer. DI-friendly: tests pass `provider`, override
  * the ledger path, and skip the heartbeat as needed.
  *
+ * When `epicId` / `branch` are supplied (the `/deliver` worker passes them
+ * from `story-init.js`'s Step 0 envelope), the corresponding GitHub read is
+ * skipped entirely: `epicId` short-circuits `readEpicIdFromStory` and
+ * `branch` short-circuits `resolveStoryBranch`. Omit both for interactive
+ * use to restore the original GitHub-read resolution.
+ *
  * @param {{
  *   storyId: number,
  *   phase: string,
+ *   epicId?: number|null,
+ *   branch?: string,
  *   noHeartbeat?: boolean,
  *   provider?: object,
  *   config?: object,
@@ -230,6 +249,8 @@ export async function runStoryPhase(args) {
   const {
     storyId,
     phase,
+    epicId: epicIdOverride,
+    branch: branchOverride,
     noHeartbeat = false,
     provider: providerOverride,
     config: configOverride,
@@ -253,8 +274,17 @@ export async function runStoryPhase(args) {
     : (ticketId, payload, opts = {}) =>
         notify(ticketId, payload, { config, provider, ...opts });
 
-  const branch = await resolveStoryBranch({ provider, storyId });
-  const epicId = await readEpicIdFromStory({ provider, storyId });
+  // When the Step 0 envelope supplied the branch / epicId (the /deliver
+  // worker passes them via --branch / --epic), skip the GitHub reads that
+  // would otherwise re-fetch these immutable values on every phase call.
+  const branch =
+    typeof branchOverride === 'string' && branchOverride
+      ? branchOverride
+      : await resolveStoryBranch({ provider, storyId });
+  const epicId =
+    epicIdOverride !== undefined
+      ? epicIdOverride
+      : await readEpicIdFromStory({ provider, storyId });
   const phases = phasesForWorkflowPhase(phase, now);
 
   const { body: renderedBody, payload: snapshot } =
@@ -301,17 +331,29 @@ export function parseArgv(argv) {
     options: {
       story: { type: 'string' },
       phase: { type: 'string' },
+      epic: { type: 'string' },
+      branch: { type: 'string' },
       'no-heartbeat': { type: 'boolean' },
       help: { type: 'boolean' },
     },
     strict: false,
   });
-  return {
+  // `--epic` absent → leave `epicId` undefined so runStoryPhase falls back to
+  // the readEpicIdFromStory GitHub read. `--branch` absent → leave `branch`
+  // undefined so it falls back to resolveStoryBranch.
+  const parsed = {
     help: Boolean(values.help),
     storyId: Number.parseInt(values.story ?? '', 10),
     phase: values.phase,
     noHeartbeat: Boolean(values['no-heartbeat']),
   };
+  if (values.epic !== undefined) {
+    parsed.epicId = Number.parseInt(values.epic, 10);
+  }
+  if (typeof values.branch === 'string' && values.branch) {
+    parsed.branch = values.branch;
+  }
+  return parsed;
 }
 
 export async function main(argv = process.argv.slice(2)) {

package/.agents/scripts/sync-claude-commands.js

@@ -23,10 +23,22 @@
  * environment (CLI, IDE, GUI, web, SDK). On a machine that previously synced
  * the plugin tree, this script reaps it on the next run (see reapPluginTree).
  *
- * Only top-level .md files are projected. The `.agents/workflows/helpers/`
- * subdirectory holds path-included modules (e.g. epic-code-review, epic-retro)
- * that parent workflows read by relative path — they are intentionally **not**
- * exposed as commands, so helpers/ is skipped.
+ * Top-level .md files project flat (`/<name>`). The
+ * `.agents/workflows/helpers/` subdirectory holds path-included modules
+ * (e.g. epic-code-review, epic-retro) that parent workflows read by
+ * relative path — they are intentionally **not** exposed as commands, so
+ * helpers/ is skipped.
+ *
+ * The `.agents/workflows/loops/` subdirectory is the **one** exception to
+ * the skip-subdirectories rule (Story #4289, Epic #4284). Each loop unit
+ * there projects to `.claude/commands/loops/<name>.md`, preserving the
+ * subpath so Claude Code namespaces it as `/loops:<name>` (matching Claude
+ * Code's subdirectory-command namespacing). Hosts that flatten
+ * subdirectory commands surface the same file as the flat fallback
+ * `/loops-<name>` (i.e. `loops-<name>` in the command tree) — the
+ * projection writes the namespaced path; the flat form is the documented
+ * host-side fallback, not a second on-disk copy. No subdirectory other
+ * than `loops/` is recursed.
  *
  * Usage:  node .agents/scripts/sync-claude-commands.js
  */
@@ -127,43 +139,111 @@ function reapPluginTree() {
 reapPluginTree();
 fs.mkdirSync(DEST_DIR, { recursive: true });
 
-// Only sync top-level .md files. Subdirectories (notably helpers/) are
-// ignored — they contain path-included modules, not slash commands.
+// The only namespaced subdirectory we recurse. Every other subdirectory
+// (notably helpers/) is skipped — those hold path-included modules, not
+// slash commands. Loop units under workflows/loops/ project into
+// .claude/commands/loops/ so Claude Code namespaces them as /loops:<name>
+// (Story #4289).
+const LOOPS_NS = 'loops';
+
+// Top-level .md files project flat. Subdirectories are skipped here and the
+// only one re-introduced is loops/ (handled by enumerateLoopUnits below).
 const isTopLevelWorkflow = (entry) =>
   entry.isFile() && entry.name.endsWith('.md');
 
+/**
+ * `README.md` (any case) under `loops/` is namespace documentation, not a
+ * loop unit — it carries no `loop:` frontmatter and must not project as a
+ * `/loops:README` command. Exclude it from the loop-unit enumeration (this
+ * mirrors `check-loop-units.js#isLoopUnitFile`, which excludes it from the
+ * lint gate).
+ *
+ * @param {import('node:fs').Dirent} entry
+ * @returns {boolean}
+ */
+const isLoopUnit = (entry) =>
+  isTopLevelWorkflow(entry) && entry.name.toLowerCase() !== 'readme.md';
+
+/**
+ * Enumerate the loop units under a source dir's `loops/` subdirectory.
+ * Returns entries keyed by the namespaced relative path
+ * (`loops/<name>.md`) so they never collide with a flat top-level command
+ * of the same basename and so the reap can track them distinctly. The
+ * directory's `README.md` is skipped — it is documentation, not a command.
+ *
+ * @param {string} dir — a workflows source root (payload or local).
+ * @returns {Array<{dir: string, name: string, rel: string}>}
+ */
+function enumerateLoopUnits(dir) {
+  const loopsDir = path.join(dir, LOOPS_NS);
+  if (!dirExists(loopsDir)) return [];
+  return fs
+    .readdirSync(loopsDir, { withFileTypes: true })
+    .filter(isLoopUnit)
+    .map((e) => ({
+      dir,
+      name: e.name,
+      rel: `${LOOPS_NS}/${e.name}`,
+    }));
+}
+
 // Enumerate sources: payload first, then local (if it exists). Payload wins
-// on basename collision — a consumer must not silently shadow a core command.
+// on relative-path collision — a consumer must not silently shadow a core
+// command. Each entry carries its destination-relative path (`rel`): a bare
+// basename for flat top-level commands, `loops/<name>.md` for loop units.
 const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
 
-/** @type {Array<{dir: string, name: string}>} */
-const entries = SRC_DIRS.flatMap((dir) =>
-  fs
+/** @type {Array<{dir: string, name: string, rel: string}>} */
+const entries = SRC_DIRS.flatMap((dir) => [
+  ...fs
     .readdirSync(dir, { withFileTypes: true })
     .filter(isTopLevelWorkflow)
-    .map((e) => ({ dir, name: e.name })),
-);
+    .map((e) => ({ dir, name: e.name, rel: e.name })),
+  ...enumerateLoopUnits(dir),
+]);
 
-// Collision policy: payload wins, warn on a shadowed local file.
-const byName = new Map();
+// Collision policy: payload wins, warn on a shadowed local file. Keyed by the
+// destination-relative path so a flat `foo.md` and a `loops/foo.md` are
+// distinct entries.
+const byRel = new Map();
 for (const e of entries) {
-  if (byName.has(e.name)) {
-    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+  if (byRel.has(e.rel)) {
+    Logger.warn(`  shadowed  ${e.rel} (local copy ignored; payload wins)`);
     continue;
   }
-  byName.set(e.name, e);
+  byRel.set(e.rel, e);
 }
 
 // sourceSet drives the orphan-reap: any existing command not in this set is
-// removed. Local-projected commands are included, so they survive the reap.
-const sourceSet = new Set(byName.keys());
+// removed. Keyed by destination-relative path so loop units are reaped from
+// the loops/ namespace and flat commands from the root.
+const sourceSet = new Set(byRel.keys());
 
-const existing = fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+/**
+ * List the destination-relative paths of every projected command currently
+ * on disk: flat `*.md` at the root plus `loops/*.md` in the namespace.
+ *
+ * @returns {string[]}
+ */
+function listExistingCommands() {
+  const flat = fs
+    .readdirSync(DEST_DIR)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f);
+  const loopsDest = path.join(DEST_DIR, LOOPS_NS);
+  const loops = dirExists(loopsDest)
+    ? fs
+        .readdirSync(loopsDest)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => `${LOOPS_NS}/${f}`)
+    : [];
+  return [...flat, ...loops];
+}
 
-for (const file of existing) {
-  if (!sourceSet.has(file)) {
-    fs.unlinkSync(path.join(DEST_DIR, file));
-    Logger.info(`  removed  ${file} (no longer in workflows)`);
+for (const rel of listExistingCommands()) {
+  if (!sourceSet.has(rel)) {
+    fs.unlinkSync(path.join(DEST_DIR, rel));
+    Logger.info(`  removed  ${rel} (no longer in workflows)`);
   }
 }
 
@@ -173,15 +253,18 @@ for (const file of existing) {
 // Parallelised so the ~30-file sync doesn't serialise on per-file fs latency
 // (noticeable on Windows where each syscall pays a larger fixed cost).
 let synced = 0;
-const resolvedEntries = Array.from(byName.values());
+const resolvedEntries = Array.from(byRel.values());
 await Promise.all(
-  resolvedEntries.map(async ({ dir, name }) => {
+  resolvedEntries.map(async ({ dir, rel }) => {
     const isLocal = dir === LOCAL_SRC;
     const header = isLocal ? LOCAL_HEADER : HEADER;
-    const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
-    const dest = path.join(DEST_DIR, name);
+    const content = await fs.promises.readFile(path.join(dir, rel), 'utf8');
+    const dest = path.join(DEST_DIR, rel);
     const target = applyHeader(content, header);
 
+    // Ensure the namespace subdirectory exists before writing a loop unit.
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+
     // Skip write if content is already identical (avoid noisy git diffs).
     // Use try/catch over existsSync+readFile so we only pay one syscall.
     try {
@@ -193,7 +276,7 @@ await Promise.all(
 
     await fs.promises.writeFile(dest, target, 'utf8');
     synced++;
-    Logger.info(`  synced   ${name}`);
+    Logger.info(`  synced   ${rel}`);
   }),
 );