mandrel 1.94.0 → 2.1.0

package/.agents/scripts/retro-run.js

@@ -1,218 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * retro-run.js — execute the `/deliver` Phase 6 retro from a CLI.
- *
- * Phase 6 of `/deliver` posts the Epic retro by invoking the
- * in-process retro module (`lib/orchestration/retro-runner.js`'s
- * `runRetro`). That module is a library entry point — it has no CLI
- * wrapper and hard-requires both a GitHub `provider` and a lifecycle
- * `bus` (Epic #2646 Story C made `bus` a non-optional input). Without a
- * wrapper the host LLM driving Phase 6 had to hand-improvise a bus, and
- * a bare bus with no `LedgerWriter` registered means `retro.start` /
- * `retro.end` never reach the Epic-scoped `lifecycle.ndjson` ledger.
- *
- * This CLI mirrors `epic-deliver-note-intervention.js`: it resolves the
- * config and provider, constructs a lifecycle bus with a `LedgerWriter`
- * bound to the Epic's temp tree, calls `runRetro`, and prints the result
- * envelope. `--full-retro` forces the six-section retro regardless of
- * manifest cleanliness (maps to `runRetro`'s `forceFull`).
- *
- * Usage:
- *   node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
- *
- * Output: a single JSON envelope
- *   `{ epicId, posted, compact, ledgerPath, commentId? }`.
- */
-
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { tempRootFrom } from './lib/config/temp-paths.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
-import { createBus } from './lib/orchestration/lifecycle/bus.js';
-import { createLedgerWriter } from './lib/orchestration/lifecycle/ledger-writer.js';
-import { runRetro } from './lib/orchestration/retro-runner.js';
-import { createProvider } from './lib/provider-factory.js';
-
-/**
- * Pure: resolve the framework/consumer repo slugs (`"<owner>/<repo>"`)
- * from a resolved config's `github` block, for threading into the retro's
- * routed-proposal composer.
- *
- * - `consumerRepo` is the project's OWN repo (`github.owner/github.repo`).
- *   It has **no** silent fallback: when `github.owner` / `github.repo` are
- *   absent the slug is `''`, which `gatherRetroSignals` treats as "disable
- *   the consumer pane loudly" rather than routing consumer-tagged friction
- *   at the framework mirror (Story #4417).
- * - `frameworkRepo` is the distinct framework mirror
- *   (`github.frameworkRepo.{owner,repo}`) when configured, otherwise `''`
- *   — `gatherRetroSignals` then falls back to its `DEFAULT_FRAMEWORK_REPO`
- *   constant (a stable, known default is legitimate for the framework).
- *
- * Exported for tests.
- *
- * @param {object} [config]
- * @returns {{ frameworkRepo: string, consumerRepo: string }}
- */
-export function resolveRetroRepos(config) {
-  const gh = config?.github ?? {};
-  const consumerRepo =
-    typeof gh.owner === 'string' &&
-    gh.owner.length > 0 &&
-    typeof gh.repo === 'string' &&
-    gh.repo.length > 0
-      ? `${gh.owner}/${gh.repo}`
-      : '';
-  const fw = gh.frameworkRepo ?? {};
-  const frameworkRepo =
-    typeof fw.owner === 'string' &&
-    fw.owner.length > 0 &&
-    typeof fw.repo === 'string' &&
-    fw.repo.length > 0
-      ? `${fw.owner}/${fw.repo}`
-      : '';
-  return { frameworkRepo, consumerRepo };
-}
-
-const HELP = `Usage: node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
-
-Composes and posts the Epic retro structured comment for Epic #<epicId>,
-wiring a lifecycle bus + LedgerWriter so the run's \`retro.start\` /
-\`retro.end\` boundaries land in temp/epic-<epicId>/lifecycle.ndjson.
-
-  --epic <epicId>   Epic to run the retro for (required, positive integer).
-  --full-retro      Force the full six-section retro regardless of
-                    manifest cleanliness (maps to runRetro forceFull).
-`;
-
-/**
- * Pure: parse argv into the normalized option bag. Exported for tests.
- *
- * @param {string[]} argv
- * @returns {{ epicId: number|null, fullRetro: boolean, help: boolean }}
- */
-export function parseRetroRunArgs(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      epic: { type: 'string' },
-      'full-retro': { type: 'boolean' },
-      help: { type: 'boolean', short: 'h' },
-    },
-    strict: false,
-  });
-  const epicId = Number.parseInt(values.epic ?? '', 10);
-  return {
-    epicId: Number.isNaN(epicId) || epicId <= 0 ? null : epicId,
-    fullRetro: values['full-retro'] === true,
-    help: values.help === true,
-  };
-}
-
-/**
- * Runner-shaped entry point. DI-friendly so tests can stub the provider,
- * the bus, the ledger writer, and `runRetro` without touching disk or the
- * GitHub API.
- *
- * Wires the lifecycle bus and registers a `LedgerWriter` bound to the
- * Epic's temp tree before invoking `runRetro`, so the run's
- * `retro.start` / `retro.end` boundaries persist to
- * `temp/epic-<epicId>/lifecycle.ndjson` rather than evaporating into a
- * bare bus.
- *
- * @param {{
- *   epicId: number,
- *   fullRetro?: boolean,
- *   injectedConfig?: object,
- *   injectedProvider?: object,
- *   busFactory?: () => object,
- *   ledgerFactory?: (deps: { epicId: number, tempRoot: string }) => { register: Function, ledgerPath?: string },
- *   runRetroFn?: typeof runRetro,
- *   logger?: { info?: Function, warn?: Function },
- * }} args
- * @returns {Promise<{
- *   epicId: number,
- *   posted: boolean,
- *   compact: boolean,
- *   ledgerPath: string|null,
- *   commentId?: number,
- * }>}
- */
-export async function runRetroCli({
-  epicId,
-  fullRetro = false,
-  injectedConfig,
-  injectedProvider,
-  busFactory,
-  ledgerFactory,
-  runRetroFn = runRetro,
-  logger,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError('runRetroCli: epicId must be a positive integer');
-  }
-
-  const config = injectedConfig ?? resolveConfig();
-  const provider = injectedProvider ?? createProvider(config);
-  const bus = busFactory ? busFactory() : createBus();
-
-  const tempRoot = tempRootFrom(config);
-  const ledger = ledgerFactory
-    ? ledgerFactory({ epicId, tempRoot })
-    : createLedgerWriter({ epicId, tempRoot });
-  ledger.register(bus);
-
-  // Story #4417 — thread the framework/consumer repo slugs resolved from
-  // `config.github` into the retro so the routed-proposal composer files
-  // consumer-tagged friction at the project's own repo (not the framework
-  // mirror), and disables the consumer pane loudly when unresolved.
-  const { frameworkRepo, consumerRepo } = resolveRetroRepos(config);
-
-  const result = await runRetroFn({
-    epicId,
-    provider,
-    bus,
-    forceFull: fullRetro,
-    frameworkRepo,
-    consumerRepo,
-    // Story #4418 — thread the resolved config so the retro auto-filer can
-    // read the `delivery.feedbackLoop.retroProposals` toggle.
-    config,
-    logger,
-  });
-
-  const envelope = {
-    epicId,
-    posted: result?.posted === true,
-    compact: result?.compact === true,
-    ledgerPath: ledger.ledgerPath ?? null,
-  };
-  if (Number.isInteger(result?.commentId)) {
-    envelope.commentId = result.commentId;
-  }
-  return envelope;
-}
-
-async function main() {
-  const args = parseRetroRunArgs(process.argv.slice(2));
-  if (args.help) {
-    Logger.info(HELP);
-    return;
-  }
-  if (args.epicId === null) {
-    Logger.error('[retro-run] ERROR: --epic <epicId> is required.');
-    Logger.error(HELP);
-    process.exit(2);
-  }
-  const out = await runRetroCli({
-    epicId: args.epicId,
-    fullRetro: args.fullRetro,
-    logger: Logger,
-  });
-  Logger.info(JSON.stringify(out, null, 2));
-}
-
-runAsCli(import.meta.url, main, { source: 'retro-run' });

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

@@ -1,361 +0,0 @@
-#!/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' });