mandrel 1.57.0

package/.agents/scripts/lifecycle-diff.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * lifecycle-diff.js — assertion modes over a lifecycle ledger file for
+ * the repeatability invariants. The structural-`diff` helpers below are
+ * exported for unit tests that pin the diff contract.
+ *
+ * Usage:
+ *   node .agents/scripts/lifecycle-diff.js --assert <mode> <ledger>
+ *       — `mode` is one of:
+ *           merge-gate-ordering   — epic.merge.armed must be preceded
+ *                                   by epic.merge.ready (same seqId
+ *                                   chain; armed.seqId > ready.seqId).
+ *           reconcile-ordering    — pr.created must be preceded by
+ *                                   acceptance.reconcile.ok.
+ *       — exits 0 on pass; exits 1 with a structured message on fail.
+ *
+ * Invariants are derived from Tech Spec #2189 § Repeatability Acceptance
+ * Criteria.
+ */
+
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Parse an NDJSON lifecycle ledger into an array of records. Blank
+ * lines tolerated; malformed JSON throws with line number. Duplicated
+ * from `lib/orchestration/lifecycle/trace-logger.js` to avoid coupling
+ * the CLI to the listener surface.
+ */
+export function parseLedgerText(text) {
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (_err) {
+      throw new Error(
+        `lifecycle-diff: malformed JSON in ledger on line ${i + 1}: ${line.slice(0, 80)}`,
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Project a single record into a comparison key. `ts` and `seqId` are
+ * intentionally elided; the rest of the record is included so that the
+ * structural shape (event order, payload contents, listener attribution
+ * on failed records) is the diff surface.
+ *
+ * Exported for unit tests that pin the diff contract.
+ */
+export function projectRecord(rec) {
+  if (!rec || typeof rec !== 'object') return rec;
+  const { ts: _ts, seqId: _seqId, ...rest } = rec;
+  return rest;
+}
+
+/**
+ * Structural diff of two ledger arrays. Returns an array of mismatch
+ * descriptors (empty when identical modulo `ts`/`seqId`).
+ */
+export function diff(ledgerA, ledgerB) {
+  const a = ledgerA.map(projectRecord);
+  const b = ledgerB.map(projectRecord);
+  const out = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i += 1) {
+    const left = a[i];
+    const right = b[i];
+    const leftJson = JSON.stringify(left);
+    const rightJson = JSON.stringify(right);
+    if (leftJson !== rightJson) {
+      out.push({ index: i, left: left ?? null, right: right ?? null });
+    }
+  }
+  return out;
+}
+
+/**
+ * Assert: epic.merge.armed must be preceded by epic.merge.ready
+ * (same run). Returns `{ ok: true }` or `{ ok: false, reason }`.
+ */
+export function assertMergeGateOrdering(records) {
+  let sawReady = false;
+  let sawReadySeq = null;
+  for (const rec of records) {
+    if (rec.kind !== 'emitted') continue;
+    if (rec.event === 'epic.merge.ready') {
+      sawReady = true;
+      sawReadySeq = rec.seqId;
+    } else if (rec.event === 'epic.merge.armed') {
+      if (!sawReady) {
+        return {
+          ok: false,
+          reason: `epic.merge.armed at seqId=${rec.seqId} without preceding epic.merge.ready`,
+        };
+      }
+      if (sawReadySeq != null && rec.seqId <= sawReadySeq) {
+        return {
+          ok: false,
+          reason: `epic.merge.armed seqId=${rec.seqId} must be > epic.merge.ready seqId=${sawReadySeq}`,
+        };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Assert: pr.created must be preceded by either acceptance.reconcile.ok
+ * or acceptance.reconcile.waived in the same run. Story #2893 split the
+ * waiver path out of `.skipped` so the Finalizer now subscribes to both
+ * `.ok` and `.waived`; either is a valid predecessor for pr.created.
+ * A reconcile.skipped (empty-spec only after #2893) or reconcile.failed
+ * before pr.created remains a violation.
+ */
+export function assertReconcileOrdering(records) {
+  let sawReconcileGate = false;
+  let sawReconcileGateSeq = null;
+  let sawReconcileGateEvent = null;
+  for (const rec of records) {
+    if (rec.kind !== 'emitted') continue;
+    if (
+      rec.event === 'acceptance.reconcile.ok' ||
+      rec.event === 'acceptance.reconcile.waived'
+    ) {
+      sawReconcileGate = true;
+      sawReconcileGateSeq = rec.seqId;
+      sawReconcileGateEvent = rec.event;
+    } else if (rec.event === 'pr.created') {
+      if (!sawReconcileGate) {
+        return {
+          ok: false,
+          reason: `pr.created at seqId=${rec.seqId} without preceding acceptance.reconcile.ok or acceptance.reconcile.waived`,
+        };
+      }
+      if (sawReconcileGateSeq != null && rec.seqId <= sawReconcileGateSeq) {
+        return {
+          ok: false,
+          reason: `pr.created seqId=${rec.seqId} must be > ${sawReconcileGateEvent} seqId=${sawReconcileGateSeq}`,
+        };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+const ASSERTIONS = new Map([
+  ['merge-gate-ordering', assertMergeGateOrdering],
+  ['reconcile-ordering', assertReconcileOrdering],
+]);
+
+function loadLedger(p) {
+  return parseLedgerText(readFileSync(p, 'utf8'));
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    options: {
+      assert: { type: 'string' },
+    },
+    allowPositionals: true,
+    args: process.argv.slice(2),
+  });
+
+  // --assert <mode> <ledger>
+  if (!values.assert) {
+    process.stderr.write('Usage: lifecycle-diff --assert <mode> <ledger>\n');
+    return 2;
+  }
+  if (positionals.length !== 1) {
+    process.stderr.write(
+      'lifecycle-diff --assert <mode> requires exactly one positional ledger path\n',
+    );
+    return 2;
+  }
+  const assertion = ASSERTIONS.get(values.assert);
+  if (!assertion) {
+    process.stderr.write(
+      `lifecycle-diff: unknown --assert mode "${values.assert}". Valid: ${[...ASSERTIONS.keys()].join(', ')}\n`,
+    );
+    return 2;
+  }
+  const records = loadLedger(positionals[0]);
+  const result = assertion(records);
+  if (result.ok) {
+    process.stdout.write(`[lifecycle-diff] PASS ${values.assert}\n`);
+    return 0;
+  }
+  process.stderr.write(
+    `[lifecycle-diff] FAIL ${values.assert}: ${result.reason}\n`,
+  );
+  return 1;
+}
+
+await runAsCli(import.meta.url, main, {
+  source: 'lifecycle-diff',
+  propagateExitCode: true,
+});

package/.agents/scripts/lifecycle-emit-story-dispatch.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+/**
+ * lifecycle-emit-story-dispatch.js — Story #2891 Task #2906.
+ *
+ * Thin host-loop CLI that appends a single `story.dispatch.start`
+ * NDJSON record to `temp/epic-<id>/lifecycle.ndjson`. Invoked by
+ * `/epic-deliver` Phase 2 immediately BEFORE each per-Story Agent
+ * tool call so the lifecycle ledger durably records every dispatch
+ * attempt. The `wave-tick.js` reconciler (Story #2891 Task #2901)
+ * then derives `nextAction['in-flight']` from this ledger to surface
+ * Stories that were dispatched but whose Agent return has not yet
+ * landed.
+ *
+ * Why not the generic `lifecycle-emit.js`?
+ *   - That CLI runs the FULL listener chain (acceptance reconciler,
+ *     finalize, branch cleaner, …) which is wrong for a per-Story
+ *     dispatch tick — those listeners are end-of-Epic concerns.
+ *   - The bus emits TWO records per call (`emitted` + `completed`).
+ *     The host loop wants exactly ONE `emitted`-shaped record per
+ *     dispatch attempt so wave-tick's start/end pairing math stays
+ *     straight.
+ *   - The host loop fires once per Story per attempt; a thin direct
+ *     append keeps that path observably cheap.
+ *
+ * Usage:
+ *   node .agents/scripts/lifecycle-emit-story-dispatch.js \
+ *     --epic <epicId> --story <storyId> --wave <waveIndex> \
+ *     --attempt <attempt> [--dispatched-at <iso8601>]
+ *
+ * `--dispatched-at` is optional; when omitted the current wall-clock
+ * is stamped. The flag exists for tests that need a deterministic
+ * timestamp.
+ *
+ * Output: one JSON object on stdout describing the record that was
+ * appended (`{ ledgerPath, record }`). Exit code 0 on success.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import {
+  parseRequiredNonNegativeInt,
+  parseRequiredPositiveInt,
+} from './lib/cli/parse-numeric.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { epicLedgerPath } from './lib/config/temp-paths.js';
+import { resolveConfig } from './lib/config-resolver.js';
+
+const TOOL = 'lifecycle-emit-story-dispatch';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  'schemas',
+  'lifecycle',
+  'story.dispatch.start.schema.json',
+);
+
+const HELP = `Usage: node .agents/scripts/lifecycle-emit-story-dispatch.js \\
+  --epic <epicId> --story <storyId> --wave <waveIndex> \\
+  --attempt <attempt> [--dispatched-at <iso8601>]
+
+Appends a single \`story.dispatch.start\` NDJSON record to
+\`temp/epic-<epicId>/lifecycle.ndjson\`. Schema-validated against
+\`.agents/schemas/lifecycle/story.dispatch.start.schema.json\`.
+`;
+
+/**
+ * Parse and validate the four required positive integers (or the
+ * sentinel allowing waveIndex >= 0). Throws with a CLI-friendly
+ * message on any failure so `runAsCli` surfaces a clean error line.
+ *
+ * @param {object} parsed Raw argv values from parseArgs.
+ * @returns {{epicId:number, storyId:number, waveIndex:number, attempt:number, dispatchedAt?:string}}
+ */
+export function buildPayloadFromArgs(parsed) {
+  const epicId = parseRequiredPositiveInt(parsed.epic, '--epic', TOOL);
+  const storyId = parseRequiredPositiveInt(parsed.story, '--story', TOOL);
+  const waveIndex = parseRequiredNonNegativeInt(parsed.wave, '--wave', TOOL);
+  const attempt = parseRequiredPositiveInt(parsed.attempt, '--attempt', TOOL);
+  const dispatchedAt =
+    typeof parsed['dispatched-at'] === 'string' &&
+    parsed['dispatched-at'].length > 0
+      ? parsed['dispatched-at']
+      : new Date().toISOString();
+  return { epicId, storyId, waveIndex, attempt, dispatchedAt };
+}
+
+/**
+ * Programmatic entry point. Returns `{ ledgerPath, record }` after
+ * appending exactly one NDJSON line. Tests use this surface to assert
+ * payload shape without spawning a subprocess.
+ *
+ * @param {{epicId:number, storyId:number, waveIndex:number, attempt:number, dispatchedAt?:string, config?:object, ledgerPath?:string}} opts
+ * @returns {{ledgerPath:string, record:object}}
+ */
+export function emitStoryDispatchStart(opts) {
+  const {
+    epicId,
+    storyId,
+    waveIndex,
+    attempt,
+    dispatchedAt = new Date().toISOString(),
+    config,
+    ledgerPath: ledgerPathOverride,
+  } = opts ?? {};
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new Error(
+      'lifecycle-emit-story-dispatch: epicId must be a positive integer',
+    );
+  }
+  const payload = { storyId, waveIndex, dispatchedAt, attempt };
+  validateAgainstSchema(payload);
+
+  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: dispatchedAt,
+    event: 'story.dispatch.start',
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}
+
+let _validator;
+function validateAgainstSchema(payload) {
+  if (!_validator) {
+    const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    _validator = ajv.compile(schema);
+  }
+  if (!_validator(payload)) {
+    const detail = (_validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `lifecycle-emit-story-dispatch: payload failed schema validation: ${detail}`,
+    );
+  }
+}
+
+async function main() {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      epic: { type: 'string' },
+      story: { type: 'string' },
+      wave: { type: 'string' },
+      attempt: { type: 'string' },
+      'dispatched-at': { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+    allowPositionals: true,
+  });
+  if (values.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  const { epicId, storyId, waveIndex, attempt, dispatchedAt } =
+    buildPayloadFromArgs(values);
+
+  let config;
+  try {
+    config = resolveConfig();
+  } catch {
+    // Standalone callers (e.g. fresh worktrees with no `.agentrc.json`
+    // yet) fall back to the default tempRoot. The path resolver
+    // handles the missing-config case gracefully.
+    config = undefined;
+  }
+
+  const out = emitStoryDispatchStart({
+    epicId,
+    storyId,
+    waveIndex,
+    attempt,
+    dispatchedAt,
+    config,
+  });
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'lifecycle-emit-story-dispatch' });