mandrel 1.92.0 → 1.94.0

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

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+
+/**
+ * slice-phase.js — single-delivery slice lifecycle + checkpoint writer
+ * (Epic #4475, M4-B). The single-delivery analogue of `story-phase.js`.
+ *
+ * A single-delivery run collapses the whole Epic into one long guarded session
+ * walking the Epic body's `## Delivery Slicing` table on `epic/<id>` (there is
+ * no per-Story fan-out, so no `story.heartbeat`). The `deliver-epic-single.md`
+ * executor calls this CLI at each slice boundary so the run has:
+ *
+ *   1. A ledger signal — one `slice.start` / `slice.end` / `slice.heartbeat`
+ *      record appended to `temp/epic-<epicId>/lifecycle.ndjson` (via the M4-A
+ *      `emit-slice-lifecycle.js` emitters). `slice.heartbeat` is the
+ *      forward-progress signal the `/deliver` §2e Idle Watchdog reads to tell
+ *      the one long session apart from a dead one; `slice.start`/`.end` bracket
+ *      each slice.
+ *   2. A durable checkpoint flip — when `--record <status>` is passed (the
+ *      executor passes `--record done` after a slice commits to `epic/<id>`),
+ *      `slices[sliceId].status` is spliced `pending → done` on the
+ *      `epic-run-state` checkpoint so a resumed run SKIPS the already-landed
+ *      slice (the branch already carries the work — no re-pay).
+ *
+ * The ledger emit is best-effort: a missing/unreachable ledger or a schema
+ * hiccup is logged and swallowed — the checkpoint is the source of truth, the
+ * ledger record is observability (mirrors `story-phase.js`). The checkpoint
+ * flip (when requested) is authoritative and its failure propagates.
+ *
+ * CLI:
+ *   --epic <id>                          Epic ID (required).
+ *   --slice <sliceId>                    Slice-map key, e.g. slice-1 (required).
+ *   --event <start|end|heartbeat>        Lifecycle event to emit (required).
+ *   --outcome <done|blocked|failed|skipped>
+ *                                        Required for --event end.
+ *   --record <pending|done|blocked|failed>
+ *                                        Flip slices[sliceId].status on the
+ *                                        checkpoint. Omit to leave it untouched.
+ *   --slice-index <n>                    Zero-based table position (metadata).
+ *   --title <str>                        Human-readable slice label.
+ *   --phase <init|implementing|closing|blocked|done>
+ *                                        Heartbeat phase (default implementing).
+ *   --duration-ms <n>                    Slice duration for --event end.
+ *   --work-cwd <path>                    Single worktree root for the
+ *                                        active-slice env export (--event
+ *                                        start). Defaults to the process cwd.
+ *   --no-emit                            Suppress the ledger emit (tests).
+ *
+ * Stdout: a single JSON envelope
+ *   { ok, epicId, sliceId, event, emitted, ledgerPath, recorded, status }
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { setActiveSliceEnv } from './lib/observability/active-story-env.js';
+import { recordSliceStatus } from './lib/orchestration/epic-run-state-store.js';
+import {
+  emitSliceEnd,
+  emitSliceHeartbeat,
+  emitSliceStart,
+} from './lib/orchestration/lifecycle/emit-slice-lifecycle.js';
+import { normalizeOperatorHandle } from './lib/orchestration/ticket-lease.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const VALID_EVENTS = new Set(['start', 'end', 'heartbeat']);
+const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
+const VALID_HEARTBEAT_PHASES = new Set([
+  'init',
+  'implementing',
+  'closing',
+  'blocked',
+  'done',
+]);
+
+const HELP = `Usage: node .agents/scripts/slice-phase.js \\
+  --epic <id> --slice <sliceId> --event <start|end|heartbeat> \\
+  [--outcome <done|blocked|failed|skipped>] [--record <pending|done|blocked|failed>] \\
+  [--slice-index <n>] [--title <str>] [--phase <phase>] [--duration-ms <n>] [--no-emit]
+
+Emits one slice.start / slice.end / slice.heartbeat record to the Epic's
+lifecycle ledger and, when --record is supplied, flips slices[sliceId].status
+on the epic-run-state checkpoint (the M4-B single-delivery slice walk uses
+--record done after each slice commits to epic/<id> so resume skips it).
+`;
+
+/**
+ * Best-effort ledger emit for one slice boundary. Dispatches to the matching
+ * `emit-slice-lifecycle.js` emitter and swallows any append failure (logged,
+ * never fatal) — the checkpoint is state, the ledger is observability. A
+ * programming error (bad event / missing outcome) still throws so it surfaces
+ * in tests.
+ *
+ * @param {object} args
+ * @returns {{ emitted: boolean, ledgerPath: string|null }}
+ */
+function emitSliceEventBestEffort({
+  event,
+  epicId,
+  sliceId,
+  sliceIndex,
+  title,
+  outcome,
+  durationMs,
+  phase,
+  operator,
+  config,
+  ledgerPath,
+  timestamp,
+}) {
+  try {
+    let res;
+    if (event === 'start') {
+      res = emitSliceStart({
+        epicId,
+        sliceId,
+        ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+        ...(typeof title === 'string' ? { title } : {}),
+        timestamp,
+        config: config ?? undefined,
+        ledgerPath,
+      });
+    } else if (event === 'end') {
+      res = emitSliceEnd({
+        epicId,
+        sliceId,
+        outcome,
+        ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
+        ...(Number.isInteger(durationMs) ? { durationMs } : {}),
+        timestamp,
+        config: config ?? undefined,
+        ledgerPath,
+      });
+    } else {
+      res = emitSliceHeartbeat({
+        epicId,
+        sliceId,
+        phase,
+        timestamp,
+        ...(operator !== null && operator !== undefined ? { operator } : {}),
+        config: config ?? undefined,
+        ledgerPath,
+      });
+    }
+    return { emitted: true, ledgerPath: res.ledgerPath };
+  } catch (err) {
+    Logger.warn(
+      `[slice-phase] slice.${event} emit failed (continuing): ${err.message}`,
+    );
+    return { emitted: false, ledgerPath: null };
+  }
+}
+
+/**
+ * End-to-end slice-phase writer. DI-friendly: tests pass `provider`, override
+ * the ledger path, and skip the emit as needed.
+ *
+ * @param {{
+ *   epicId: number,
+ *   sliceId: string,
+ *   event: string,
+ *   outcome?: string,
+ *   record?: string,
+ *   sliceIndex?: number,
+ *   title?: string,
+ *   phase?: string,
+ *   durationMs?: number,
+ *   noEmit?: boolean,
+ *   provider?: object,
+ *   config?: object,
+ *   ledgerPath?: string,
+ *   now?: Date,
+ * }} args
+ */
+export async function runSlicePhase(args) {
+  const {
+    epicId,
+    sliceId,
+    event,
+    outcome,
+    record,
+    sliceIndex,
+    title,
+    phase = 'implementing',
+    durationMs,
+    noEmit = false,
+    provider: providerOverride,
+    config: configOverride,
+    ledgerPath: ledgerPathOverride,
+    workCwd: workCwdOverride,
+    now = new Date(),
+  } = args ?? {};
+
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new Error('runSlicePhase: --epic must be a positive integer');
+  }
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new Error('runSlicePhase: --slice must be a non-empty string');
+  }
+  if (!VALID_EVENTS.has(event)) {
+    throw new Error(
+      `runSlicePhase: --event "${event}" must be one of: ${[...VALID_EVENTS].join(', ')}`,
+    );
+  }
+  if (event === 'end' && !VALID_OUTCOMES.has(outcome)) {
+    throw new Error(
+      `runSlicePhase: --event end requires --outcome one of: ${[...VALID_OUTCOMES].join(', ')}`,
+    );
+  }
+  if (event === 'heartbeat' && !VALID_HEARTBEAT_PHASES.has(phase)) {
+    throw new Error(
+      `runSlicePhase: --phase "${phase}" must be one of: ${[...VALID_HEARTBEAT_PHASES].join(', ')}`,
+    );
+  }
+
+  const config = configOverride ?? (providerOverride ? null : resolveConfig());
+  const operator = normalizeOperatorHandle(config?.github?.operatorHandle);
+  const timestamp = now.toISOString();
+
+  // Epic #4476 (M5): at each slice boundary START, export the active-slice
+  // env (`CC_EPIC_ID` / `CC_SLICE_ID` / `CC_OPERATOR`) into the single
+  // worktree's `.env.local` so the PostToolUse hook emits `slice.heartbeat`
+  // off the token stream for the duration of this slice — no per-step
+  // heartbeat CLI turn. Best-effort: a write failure never blocks the slice.
+  // Gated on an explicit `workCwd` (the CLI supplies `process.cwd()`); a bare
+  // `runSlicePhase` call in a unit test passes none and never touches the env
+  // or writes a `.env.local`.
+  let sliceEnvWritten = false;
+  if (
+    event === 'start' &&
+    typeof workCwdOverride === 'string' &&
+    workCwdOverride.length > 0
+  ) {
+    try {
+      const res = setActiveSliceEnv({
+        epicId,
+        sliceId,
+        ...(operator ? { operator } : {}),
+        workCwd: workCwdOverride,
+        logger: Logger,
+      });
+      sliceEnvWritten = res.fileWritten;
+    } catch (err) {
+      Logger.warn(
+        `[slice-phase] active-slice env export failed (continuing): ${err.message}`,
+      );
+    }
+  }
+
+  let emitted = false;
+  let ledgerPath = null;
+  if (!noEmit) {
+    ({ emitted, ledgerPath } = emitSliceEventBestEffort({
+      event,
+      epicId,
+      sliceId,
+      sliceIndex,
+      title,
+      outcome,
+      durationMs,
+      phase,
+      operator,
+      config,
+      ledgerPath: ledgerPathOverride,
+      timestamp,
+    }));
+  }
+
+  // Authoritative checkpoint flip — only when --record is supplied. Unlike the
+  // best-effort emit, a record failure propagates (the slice-map marker is the
+  // resume contract; a silent failure would re-pay the slice on resume).
+  let recorded = false;
+  let status = null;
+  if (typeof record === 'string' && record.length > 0) {
+    const provider =
+      providerOverride ?? createProvider(config ?? resolveConfig());
+    await recordSliceStatus({
+      provider,
+      epicId,
+      sliceId,
+      status: record,
+      ...(typeof title === 'string' && title ? { title } : {}),
+    });
+    recorded = true;
+    status = record;
+  }
+
+  return {
+    ok: true,
+    epicId,
+    sliceId,
+    event,
+    emitted,
+    ledgerPath,
+    recorded,
+    status,
+    sliceEnvWritten,
+  };
+}
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      epic: { type: 'string' },
+      slice: { type: 'string' },
+      event: { type: 'string' },
+      outcome: { type: 'string' },
+      record: { type: 'string' },
+      'slice-index': { type: 'string' },
+      title: { type: 'string' },
+      phase: { type: 'string' },
+      'duration-ms': { type: 'string' },
+      'work-cwd': { type: 'string' },
+      'no-emit': { type: 'boolean' },
+      help: { type: 'boolean' },
+    },
+    strict: false,
+  });
+  const parsed = {
+    help: Boolean(values.help),
+    epicId: Number.parseInt(values.epic ?? '', 10),
+    sliceId: values.slice,
+    event: values.event,
+    noEmit: Boolean(values['no-emit']),
+  };
+  if (typeof values.outcome === 'string') parsed.outcome = values.outcome;
+  if (typeof values.record === 'string') parsed.record = values.record;
+  if (typeof values.title === 'string') parsed.title = values.title;
+  if (typeof values.phase === 'string') parsed.phase = values.phase;
+  if (typeof values['work-cwd'] === 'string' && values['work-cwd']) {
+    parsed.workCwd = values['work-cwd'];
+  }
+  if (values['slice-index'] !== undefined) {
+    parsed.sliceIndex = Number.parseInt(values['slice-index'], 10);
+  }
+  if (values['duration-ms'] !== undefined) {
+    parsed.durationMs = Number.parseInt(values['duration-ms'], 10);
+  }
+  return parsed;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgv(argv);
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  // The CLI runs from inside the single worktree (the executor `cd`s there),
+  // so default the active-slice env target to the process cwd unless an
+  // explicit --work-cwd overrides it. runSlicePhase only writes the
+  // `.env.local` for --event start.
+  const envelope = await runSlicePhase({
+    ...parsed,
+    workCwd: parsed.workCwd ?? process.cwd(),
+  });
+  process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'slice-phase' });

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

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * Projects .agents/agents/ (and .agents/local/agents/ when present) into a flat
+ * `.claude/agents/` tree so Claude Code exposes each role definition as a
+ * role-scoped sub-agent (`subagent_type: <name>`). Exact sibling of
+ * `sync-claude-commands.js` — same header, same local-shadow policy, same
+ * orphan-reap, same prune-exempt handling for the consumer-authored
+ * `.agents/local/agents/` source. Two source directories are enumerated in
+ * order:
+ *
+ *   1. PAYLOAD_SRC  — `.agents/agents/`  (the installed Mandrel payload)
+ *   2. LOCAL_SRC    — `.agents/local/agents/`  (consumer-authored, prune-exempt)
+ *
+ * The payload directory wins on basename collision: if both sources supply
+ * `foo.md`, the payload copy is projected and the local copy is ignored with a
+ * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
+ * agent defs are also protected from the orphan-reap — they survive
+ * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
+ *
+ * Only top-level `.md` files project (`.claude/agents/<name>.md`). Unlike the
+ * commands sync there is no `loops/` namespace and no plugin tree to reap — the
+ * agent surface is flat.
+ *
+ * A `.claude/agents/<name>.md` runs on its **own** system prompt — it does NOT
+ * inherit the `CLAUDE.md` @-import closure — so a spawn routed to a role agent
+ * stops re-paying the always-loaded context (issue #4478). The role defs
+ * @-import `security-baseline.md` so the inviolable security MUSTs stay
+ * single-sourced.
+ *
+ * Usage:  node .agents/scripts/sync-claude-agents.js
+ */
+
+// cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applyHeader } from './lib/command-header.js';
+import { Logger } from './lib/Logger.js';
+
+// Resolve the project root from the invocation cwd — the consumer project where
+// `.agents/` is materialized and where Claude Code loads `.claude/agents/`.
+// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
+// runs from `node_modules/mandrel/.agents/scripts/`, so that climb lands on the
+// package dir and the defs would be written *inside node_modules* rather than
+// the consumer. Every real invocation runs with cwd at the project root
+// (`npm run sync:agents`, the prepare hook). Tests drive fixture trees via the
+// SYNC_CLAUDE_AGENTS_SRC/DEST overrides below.
+const PROJECT_ROOT = process.cwd();
+
+// Env-var overrides exist so the sync logic can be exercised against a fixture
+// agents tree in isolation. When unset, behaviour is unchanged — the script
+// defaults to the real agents / .claude/agents directories. SYNC_CLAUDE_AGENTS_SRC
+// overrides the PAYLOAD source only; LOCAL_SRC is always derived from the project
+// root so fixture tests can isolate the payload source.
+const PAYLOAD_SRC =
+  process.env.SYNC_CLAUDE_AGENTS_SRC ??
+  path.join(PROJECT_ROOT, '.agents', 'agents');
+const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'agents');
+
+const DEST_DIR =
+  process.env.SYNC_CLAUDE_AGENTS_DEST ??
+  path.join(PROJECT_ROOT, '.claude', 'agents');
+
+export const HEADER =
+  '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+export const LOCAL_HEADER =
+  '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
+
+/**
+ * Return true when the given directory path exists and is accessible.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+fs.mkdirSync(DEST_DIR, { recursive: true });
+
+// Top-level .md files project flat. Subdirectories are skipped.
+const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
+
+// Enumerate sources: payload first, then local (if it exists). Payload wins on
+// basename collision — a consumer must not silently shadow a core role def.
+const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
+
+/** @type {Array<{dir: string, name: string}>} */
+const entries = SRC_DIRS.flatMap((dir) =>
+  fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(isTopLevelAgent)
+    .map((e) => ({ dir, name: e.name })),
+);
+
+// Collision policy: payload wins, warn on a shadowed local file.
+const byName = new Map();
+for (const e of entries) {
+  if (byName.has(e.name)) {
+    Logger.warn(`  shadowed  ${e.name} (local copy ignored; payload wins)`);
+    continue;
+  }
+  byName.set(e.name, e);
+}
+
+// sourceSet drives the orphan-reap: any existing agent def not in this set is
+// removed.
+const sourceSet = new Set(byName.keys());
+
+/**
+ * List the `.md` agent defs currently on disk in the destination.
+ *
+ * @returns {string[]}
+ */
+function listExistingAgents() {
+  try {
+    return fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+for (const name of listExistingAgents()) {
+  if (!sourceSet.has(name)) {
+    fs.unlinkSync(path.join(DEST_DIR, name));
+    Logger.info(`  removed  ${name} (no longer in .agents/agents)`);
+  }
+}
+
+// Copy each role def, injecting the auto-generated header after any leading
+// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
+// agent's name/description). Use a distinct header comment for local-origin files.
+let synced = 0;
+const resolvedEntries = Array.from(byName.values());
+await Promise.all(
+  resolvedEntries.map(async ({ dir, name }) => {
+    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 target = applyHeader(content, header);
+
+    // Skip write if content is already identical (avoid noisy git diffs).
+    try {
+      const existingContent = await fs.promises.readFile(dest, 'utf8');
+      if (existingContent === target) return;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    await fs.promises.writeFile(dest, target, 'utf8');
+    synced++;
+    Logger.info(`  synced   ${name}`);
+  }),
+);
+
+Logger.info(
+  `\n✔ ${synced} file(s) synced, ${sourceSet.size} total agents in .claude/agents/`,
+);

package/.agents/scripts/update-ticket-state.js

@@ -13,6 +13,10 @@
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
+import {
+  enqueueLabel,
+  outboxPathFor,
+} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   cascadeCompletion,
   STATE_LABELS,
@@ -33,6 +37,8 @@ if (
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
+      buffer: { type: 'boolean' },
+      epic: { type: 'string' },
     },
     strict: false,
   });
@@ -69,6 +75,31 @@ if (
       return;
     }
 
+    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
+    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
+    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
+    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
+    // immediately and are never buffered. Requires --epic to locate the outbox.
+    if (
+      values.buffer &&
+      state !== STATE_LABELS.BLOCKED &&
+      state !== STATE_LABELS.DONE
+    ) {
+      const epicId = Number.parseInt(values.epic ?? '', 10);
+      if (!Number.isInteger(epicId) || epicId <= 0) {
+        throw new Error('--buffer requires --epic <id>');
+      }
+      enqueueLabel({
+        outboxPath: outboxPathFor(epicId, config),
+        ticketId,
+        state,
+      });
+      Logger.info(
+        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
+      );
+      return;
+    }
+
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );