mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/lifecycle/emit-slice-lifecycle.js

@@ -1,270 +0,0 @@
-/**
- * emit-slice-lifecycle.js — Epic #4475 (M4-A).
- *
- * Programmatic emitters for the three single-delivery slice lifecycle events
- * (`slice.start`, `slice.end`, `slice.heartbeat`) — the single-delivery
- * analogues of the per-Story `story.dispatch.start` / `story.dispatch.end` /
- * `story.heartbeat` events. They append one schema-validated NDJSON record to
- * `temp/epic-<id>/lifecycle.ndjson`, mirroring `emit-story-heartbeat.js`.
- *
- * A single-delivery run collapses the whole Epic into one long guarded
- * session walking the `## Delivery Slicing` table on `epic/<id>`. Without a
- * per-Story heartbeat the `/deliver` idle watchdog cannot tell a live session
- * from a dead one, so these events give the long session an inspectable
- * forward-progress signal (`slice.heartbeat`) plus per-slice boundaries
- * (`slice.start` / `slice.end`) the resume path reads back.
- *
- * Introduced INERT in M4-A: the executor that emits these lands in M4-B
- * (`deliver-epic-single.md`). Shipping the emitters + schemas now keeps that
- * PR the flip-only change.
- *
- * The emit is best-effort at the call site (a failure to append MUST NOT
- * block the slice transition itself); callers catch and log via the script's
- * Logger, exactly as the story-heartbeat callers do. These functions still
- * throw on a programming error (bad argument / schema mismatch) so the bug
- * surfaces in tests.
- */
-
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-import { epicLedgerPath } from '../../config/temp-paths.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_DIR = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'lifecycle',
-);
-
-const VALID_PHASES = new Set([
-  'init',
-  'implementing',
-  'closing',
-  'blocked',
-  'done',
-]);
-
-const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
-
-/** Lazily-compiled AJV validators, one per event schema. */
-const _validators = new Map();
-
-function getValidator(event) {
-  let validator = _validators.get(event);
-  if (!validator) {
-    const schema = JSON.parse(
-      readFileSync(path.join(SCHEMA_DIR, `${event}.schema.json`), 'utf8'),
-    );
-    const ajv = new Ajv2020({ allErrors: true, strict: false });
-    addFormats(ajv);
-    validator = ajv.compile(schema);
-    _validators.set(event, validator);
-  }
-  return validator;
-}
-
-function assertEpicId(epicId) {
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new Error('emit-slice-lifecycle: epicId must be a positive integer');
-  }
-}
-
-function assertSliceId(sliceId) {
-  if (typeof sliceId !== 'string' || sliceId.length === 0) {
-    throw new Error('emit-slice-lifecycle: sliceId must be a non-empty string');
-  }
-}
-
-/**
- * Validate `payload` against `<event>.schema.json`, then append it as a single
- * NDJSON `emitted` record to the Epic ledger. Shared tail of all three
- * emitters.
- *
- * @param {string} event
- * @param {object} payload
- * @param {{ epicId: number, timestamp: string, config?: object, ledgerPath?: string }} ctx
- * @returns {{ ledgerPath: string, record: object }}
- */
-function appendSliceEvent(
-  event,
-  payload,
-  { epicId, timestamp, config, ledgerPath: ledgerPathOverride },
-) {
-  const validator = getValidator(event);
-  if (!validator(payload)) {
-    const detail = (validator.errors ?? [])
-      .map((e) => `${e.instancePath || '/'} ${e.message}`)
-      .join('; ');
-    throw new Error(
-      `emit-slice-lifecycle: ${event} payload failed schema validation: ${detail}`,
-    );
-  }
-
-  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
-  mkdirSync(path.dirname(ledgerPath), { recursive: true });
-  const record = { kind: 'emitted', ts: timestamp, event, payload };
-  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
-  return { ledgerPath, record };
-}
-
-/**
- * Append one `slice.start` record as the executor begins implementing a slice.
- *
- * @param {object} opts
- * @param {number} opts.epicId
- * @param {string} opts.sliceId       Stable slice-map key (e.g. `slice-1`).
- * @param {number} [opts.sliceIndex]  Zero-based position in the Delivery
- *                                    Slicing table.
- * @param {string} [opts.title]       Human-readable slice label.
- * @param {string} [opts.timestamp]   ISO-8601 wall clock. Defaults to now().
- * @param {object} [opts.config]
- * @param {string} [opts.ledgerPath]  Override for tests.
- * @returns {{ ledgerPath: string, record: object }}
- */
-export function emitSliceStart(opts) {
-  const {
-    epicId,
-    sliceId,
-    sliceIndex,
-    title,
-    timestamp = new Date().toISOString(),
-    config,
-    ledgerPath,
-  } = opts ?? {};
-  assertEpicId(epicId);
-  assertSliceId(sliceId);
-
-  const payload = {
-    event: 'slice.start',
-    epicId,
-    sliceId,
-    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
-    ...(typeof title === 'string' ? { title } : {}),
-    timestamp,
-  };
-  return appendSliceEvent('slice.start', payload, {
-    epicId,
-    timestamp,
-    config,
-    ledgerPath,
-  });
-}
-
-/**
- * Append one `slice.end` record when a slice finishes. A `done` outcome is
- * what the slice-map checkpoint flips `slices[id].status` to before the walk
- * advances.
- *
- * @param {object} opts
- * @param {number} opts.epicId
- * @param {string} opts.sliceId
- * @param {'done'|'blocked'|'failed'|'skipped'} opts.outcome
- * @param {number} [opts.sliceIndex]
- * @param {number} [opts.durationMs]
- * @param {string} [opts.timestamp]
- * @param {object} [opts.config]
- * @param {string} [opts.ledgerPath]
- * @returns {{ ledgerPath: string, record: object }}
- */
-export function emitSliceEnd(opts) {
-  const {
-    epicId,
-    sliceId,
-    outcome,
-    sliceIndex,
-    durationMs,
-    timestamp = new Date().toISOString(),
-    config,
-    ledgerPath,
-  } = opts ?? {};
-  assertEpicId(epicId);
-  assertSliceId(sliceId);
-  if (!VALID_OUTCOMES.has(outcome)) {
-    throw new Error(
-      `emit-slice-lifecycle: slice.end outcome "${outcome}" must be one of: ${[...VALID_OUTCOMES].join(', ')}`,
-    );
-  }
-
-  const payload = {
-    event: 'slice.end',
-    epicId,
-    sliceId,
-    ...(Number.isInteger(sliceIndex) ? { sliceIndex } : {}),
-    outcome,
-    ...(Number.isInteger(durationMs) ? { durationMs } : {}),
-    timestamp,
-  };
-  return appendSliceEvent('slice.end', payload, {
-    epicId,
-    timestamp,
-    config,
-    ledgerPath,
-  });
-}
-
-/**
- * Append one `slice.heartbeat` record from inside a slice's implementation
- * loop — the forward-progress signal the idle watchdog reads for the single
- * long session.
- *
- * @param {object} opts
- * @param {number} opts.epicId
- * @param {string} opts.sliceId
- * @param {string} [opts.phase='implementing']  init|implementing|closing|blocked|done.
- * @param {string} [opts.timestamp]
- * @param {string} [opts.operator]  Optional lease-owner handle; included only
- *                                  when a non-empty string is supplied.
- * @param {object} [opts.config]
- * @param {string} [opts.ledgerPath]
- * @returns {{ ledgerPath: string, record: object }}
- */
-export function emitSliceHeartbeat(opts) {
-  const {
-    epicId,
-    sliceId,
-    phase = 'implementing',
-    timestamp = new Date().toISOString(),
-    operator,
-    config,
-    ledgerPath,
-  } = opts ?? {};
-  assertEpicId(epicId);
-  assertSliceId(sliceId);
-  if (!VALID_PHASES.has(phase)) {
-    throw new Error(
-      `emit-slice-lifecycle: slice.heartbeat phase "${phase}" must be one of: ${[...VALID_PHASES].join(', ')}`,
-    );
-  }
-  if (
-    operator !== undefined &&
-    (typeof operator !== 'string' || operator.length === 0)
-  ) {
-    throw new Error(
-      'emit-slice-lifecycle: operator, when supplied, must be a non-empty string',
-    );
-  }
-
-  const payload = {
-    event: 'slice.heartbeat',
-    epicId,
-    sliceId,
-    phase,
-    timestamp,
-    ...(operator !== undefined ? { operator } : {}),
-  };
-  return appendSliceEvent('slice.heartbeat', payload, {
-    epicId,
-    timestamp,
-    config,
-    ledgerPath,
-  });
-}

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-dispatch-end.js

@@ -1,147 +0,0 @@
-/**
- * emit-story-dispatch-end.js — Story #3900.
- *
- * Programmatic helper that appends a single `story.dispatch.end` NDJSON
- * record to `temp/epic-<id>/lifecycle.ndjson` for one recorded Story.
- *
- * Why this exists:
- *   The `wave-tick.js` in-flight reconciler (and the `--check-idle`
- *   watchdog) compute "in-flight" Stories as those carrying a
- *   `story.dispatch.start` record WITHOUT a matching `story.dispatch.end`.
- *   Before this Story the only producer of `story.dispatch.end` was
- *   `lib/orchestration/wave-session.js`, which nothing imports outside
- *   tests — so every dispatched Story stayed "in-flight" forever and the
- *   idle watchdog flagged completed Stories as stalled. The host-LLM driven
- *   `/deliver` path closes a wave through `epic-execute-record-wave.js`,
- *   so that CLI is the correct place to emit the matching dispatch-end per
- *   recorded Story.
- *
- * The emit mirrors the thin direct-append shape of
- * `lifecycle-emit-story-dispatch.js` (start) and `emit-story-heartbeat.js`:
- * one schema-validated `emitted`-kind record, no full listener chain. It is
- * best-effort at the call site — a failed append must not block the wave
- * loop, so callers wrap it and log.
- *
- * Schema contract (story.dispatch.end.schema.json):
- *   { storyId, outcome: done|blocked|failed|skipped, durationMs }
- */
-
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-import { epicLedgerPath } from '../../config/temp-paths.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'lifecycle',
-  'story.dispatch.end.schema.json',
-);
-
-const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
-
-let _validator;
-
-function getValidator() {
-  if (_validator) return _validator;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  _validator = ajv.compile(schema);
-  return _validator;
-}
-
-/**
- * Append exactly one `story.dispatch.end` NDJSON record to the Epic ledger.
- *
- * @param {object} opts
- * @param {number} opts.epicId       Parent Epic — required for the ledger path.
- * @param {number} opts.storyId      Story whose dispatch settled.
- * @param {string} opts.outcome      One of done|blocked|failed|skipped.
- * @param {number} [opts.durationMs=0]  Wall-clock dispatch duration in ms.
- *                                       Defaults to 0 when the host loop does
- *                                       not track per-Story timing.
- * @param {string} [opts.timestamp]  ISO-8601 wall clock. Defaults to now().
- * @param {object} [opts.config]     Optional resolved config for tempRoot.
- * @param {string} [opts.ledgerPath] Override for tests.
- * @returns {{ ledgerPath: string, record: object }}
- */
-export function emitStoryDispatchEnd(opts) {
-  const {
-    epicId,
-    storyId,
-    outcome,
-    durationMs = 0,
-    timestamp = new Date().toISOString(),
-    config,
-    ledgerPath: ledgerPathOverride,
-  } = opts ?? {};
-
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new Error('emitStoryDispatchEnd: epicId must be a positive integer');
-  }
-  if (!Number.isInteger(storyId) || storyId < 1) {
-    throw new Error('emitStoryDispatchEnd: storyId must be a positive integer');
-  }
-  if (!VALID_OUTCOMES.has(outcome)) {
-    throw new Error(
-      `emitStoryDispatchEnd: outcome "${outcome}" must be one of: ${[...VALID_OUTCOMES].join(', ')}`,
-    );
-  }
-  if (!Number.isInteger(durationMs) || durationMs < 0) {
-    throw new Error(
-      'emitStoryDispatchEnd: durationMs must be a non-negative integer',
-    );
-  }
-
-  const payload = { storyId, outcome, durationMs };
-
-  const validator = getValidator();
-  if (!validator(payload)) {
-    const detail = (validator.errors ?? [])
-      .map((e) => `${e.instancePath || '/'} ${e.message}`)
-      .join('; ');
-    throw new Error(
-      `emitStoryDispatchEnd: payload failed schema validation: ${detail}`,
-    );
-  }
-
-  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
-  mkdirSync(path.dirname(ledgerPath), { recursive: true });
-  const record = {
-    kind: 'emitted',
-    ts: timestamp,
-    event: 'story.dispatch.end',
-    payload,
-  };
-  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
-  return { ledgerPath, record };
-}
-
-/**
- * Map a recorded Story status (`done`/`blocked`/`failed`) to the
- * `story.dispatch.end` outcome enum. The status taxonomy is a strict subset
- * of the outcome enum, so the mapping is identity for the three values the
- * record-wave projection produces. Unknown values throw rather than emit a
- * schema-invalid record.
- *
- * @param {string} status
- * @returns {string}
- */
-export function storyStatusToDispatchOutcome(status) {
-  if (!VALID_OUTCOMES.has(status)) {
-    throw new Error(
-      `storyStatusToDispatchOutcome: unknown story status "${status}"`,
-    );
-  }
-  return status;
-}

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-heartbeat.js

@@ -1,155 +0,0 @@
-/**
- * emit-story-heartbeat.js — Story #3057.
- *
- * Programmatic helper that appends a single `story.heartbeat` NDJSON
- * record to `temp/epic-<id>/lifecycle.ndjson` during a Story's
- * implementation loop. Story-implementation phases can run for many
- * minutes between dispatch and merge; `story.heartbeat` is the
- * inspectable in-progress signal the host-loop reconciler reads to
- * confirm forward progress.
- *
- * Distinct from:
- *   - `story.dispatch.start` — one per Story per dispatch attempt
- *     (lifecycle-emit-story-dispatch.js).
- *   - `story.merged` — one per Story per close, post-merge.
- *
- * The emit is best-effort: a failure to append (missing schema,
- * unreachable ledger path, validation error) MUST NOT block the phase
- * transition itself. Callers should catch and log via the script's
- * Logger; the heartbeat is observability, not state.
- *
- * Schema contract (story.heartbeat.schema.json):
- *   { event, storyId, epicId, phase, timestamp, operator? }
- *
- * The schema declares `additionalProperties: false`, so this emitter's
- * signature is deliberately narrow: only the schema-allowed fields are
- * accepted. The earlier per-child Task id and progress counters
- * were dropped under Epic #3078's
- * 2-tier hard cutover — they would fail strict validation and have no
- * meaning now that the Story is the leaf execution unit with no child
- * tickets. The optional `operator` field (Story #3480) records the handle
- * holding the assignee-as-lease claim; it is included only when supplied so
- * pre-lease callers continue to emit the unchanged shape.
- */
-
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-import { epicLedgerPath } from '../../config/temp-paths.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'lifecycle',
-  'story.heartbeat.schema.json',
-);
-
-const VALID_PHASES = new Set([
-  'init',
-  'implementing',
-  'closing',
-  'blocked',
-  'done',
-]);
-
-let _validator;
-
-function getValidator() {
-  if (_validator) return _validator;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  _validator = ajv.compile(schema);
-  return _validator;
-}
-
-/**
- * Append exactly one `story.heartbeat` NDJSON record to the Epic ledger.
- *
- * @param {object} opts
- * @param {number} opts.storyId   Story whose implementation loop is firing.
- * @param {number} opts.epicId    Parent Epic — required for the ledger path.
- * @param {string} [opts.phase='implementing']
- *                                One of init|implementing|closing|blocked|done.
- * @param {string} [opts.timestamp]   ISO-8601 wall clock. Defaults to now().
- * @param {string} [opts.operator]    Optional lease-owner handle (Story #3480).
- *                                    When a non-empty string is supplied it is
- *                                    recorded on the payload so the
- *                                    assignee-as-lease primitive can decide a
- *                                    claim's liveness from the latest heartbeat
- *                                    for a given owner. Omitted when absent so
- *                                    pre-lease callers emit the unchanged shape.
- * @param {object} [opts.config]      Optional resolved config for tempRoot.
- * @param {string} [opts.ledgerPath]  Override for tests.
- * @returns {{ ledgerPath: string, record: object }}
- */
-export function emitStoryHeartbeat(opts) {
-  const {
-    storyId,
-    epicId,
-    phase = 'implementing',
-    timestamp = new Date().toISOString(),
-    operator,
-    config,
-    ledgerPath: ledgerPathOverride,
-  } = opts ?? {};
-
-  if (!Number.isInteger(storyId) || storyId < 1) {
-    throw new Error('emitStoryHeartbeat: storyId must be a positive integer');
-  }
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new Error('emitStoryHeartbeat: epicId must be a positive integer');
-  }
-  if (!VALID_PHASES.has(phase)) {
-    throw new Error(
-      `emitStoryHeartbeat: phase "${phase}" must be one of: ${[...VALID_PHASES].join(', ')}`,
-    );
-  }
-  if (
-    operator !== undefined &&
-    (typeof operator !== 'string' || operator.length === 0)
-  ) {
-    throw new Error(
-      'emitStoryHeartbeat: operator, when supplied, must be a non-empty string',
-    );
-  }
-
-  const payload = {
-    event: 'story.heartbeat',
-    storyId,
-    epicId,
-    phase,
-    timestamp,
-    ...(operator !== undefined ? { operator } : {}),
-  };
-
-  const validator = getValidator();
-  if (!validator(payload)) {
-    const detail = (validator.errors ?? [])
-      .map((e) => `${e.instancePath || '/'} ${e.message}`)
-      .join('; ');
-    throw new Error(
-      `emitStoryHeartbeat: payload failed schema validation: ${detail}`,
-    );
-  }
-
-  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
-  mkdirSync(path.dirname(ledgerPath), { recursive: true });
-  const record = {
-    kind: 'emitted',
-    ts: timestamp,
-    event: 'story.heartbeat',
-    payload,
-  };
-  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
-  return { ledgerPath, record };
-}