mandrel 1.93.0 → 1.94.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/acceptance-reconciler.js

@@ -34,6 +34,47 @@
  */
 
 import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../../../../acceptance-spec-reconciler.js';
+import { DELIVERY_SINGLE_LABEL } from '../../deliver-route.js';
+import { read as readEpicRunState } from '../../epic-run-state-store.js';
+
+/**
+ * Default single-delivery resolver (Epic #4475, M4-B, design §2c). Decides
+ * whether the Epic under reconciliation is the single-delivery shape — the
+ * signal that flips a `waived` reconcile into a hard failure (the back gate
+ * of the non-waivable epic-level acceptance contract). Two sources, primary
+ * first:
+ *
+ *   1. `epic-run-state.deliveryShape === 'single'` — the durable checkpoint
+ *      the single-delivery prepare writes.
+ *   2. The `delivery::single` label on the Epic ticket — the plan-time marker.
+ *
+ * Best-effort + fail-open-to-fan-out: any probe failure (null provider in a
+ * unit fixture, a GitHub read error) degrades to `false` (treat as fan-out),
+ * so the defence-in-depth back gate never *invents* a block — the front gate
+ * (prepare refusing `acceptance::n-a`) is the primary guard. Tests inject
+ * `resolveSingleFn` directly to bypass the probes.
+ *
+ * @param {{ provider?: object|null, epicId: number, config?: object|null }} args
+ * @returns {Promise<boolean>}
+ */
+export async function defaultResolveSingle({ provider, epicId }) {
+  if (!provider) return false;
+  try {
+    const checkpoint = await readEpicRunState({ provider, epicId });
+    if (checkpoint?.deliveryShape === 'single') return true;
+  } catch {
+    // Fall through to the label probe.
+  }
+  try {
+    const epic = await provider.getTicket(epicId);
+    const labels = Array.isArray(epic?.labels) ? epic.labels : [];
+    return labels.some(
+      (l) => (typeof l === 'string' ? l : l?.name) === DELIVERY_SINGLE_LABEL,
+    );
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Classify a `reconcileAcceptanceSpec` result envelope into the typed
@@ -49,6 +90,16 @@ import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../..
  *                       `.waived` and route waived Epics through to PR
  *                       creation, while empty-spec Epics still
  *                       terminate without a PR via `.skipped`.
+ *                       **Non-waivable under single delivery (Epic #4475,
+ *                       M4-B, design §2c):** when `opts.single` is true the
+ *                       epic-level reconcile is the ONLY acceptance gate
+ *                       left, so a `waived` status is treated as a hard
+ *                       `failed` (reason `single-delivery-non-waivable`)
+ *                       instead of passing through — the back gate that
+ *                       forecloses the cohort's dilution (waived reconcile
+ *                       as the sole gate). The front gate (prepare refusing
+ *                       `acceptance::n-a`) already blocks this at seed time;
+ *                       this is defence in depth.
  *   - `'empty-spec'` → the linked spec exists but declares zero AC IDs.
  *                       Treated as "no work to do"; emit `.skipped` with
  *                       reason `'empty-spec'` so operators see the
@@ -61,14 +112,23 @@ import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../..
  *                       the Epic ticket.
  *
  * @param {object|undefined|null} result reconciler envelope.
+ * @param {{ single?: boolean }} [opts] `single: true` flips a `waived` status
+ *   into a hard `failed` (the non-waivable epic reconcile back gate).
  * @returns {{ outcome: 'ok'|'waived'|'skipped'|'failed', reason?: string }}
  */
-export function classifyReconcileResult(result) {
+export function classifyReconcileResult(result, opts = {}) {
+  const single = opts?.single === true;
   if (!result || typeof result !== 'object') {
     return { outcome: 'failed', reason: 'reconciler-no-result' };
   }
   const status = result.status;
   if (status === 'waived') {
+    if (single) {
+      return {
+        outcome: 'failed',
+        reason: 'single-delivery-non-waivable',
+      };
+    }
     return { outcome: 'waived', reason: 'waiver' };
   }
   if (status === 'empty-spec') {
@@ -112,6 +172,9 @@ export class AcceptanceReconciler {
    *   injected for the same reason.
    * @param {Function} [opts.reconcileAcceptanceSpecFn] Override of the
    *   helper for tests; defaults to the production export.
+   * @param {Function} [opts.resolveSingleFn] Override of the single-delivery
+   *   resolver for tests (Epic #4475, M4-B); defaults to `defaultResolveSingle`
+   *   (checkpoint `deliveryShape` → `delivery::single` label).
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -134,6 +197,7 @@ export class AcceptanceReconciler {
     this.config = opts.config ?? null;
     this.reconcileAcceptanceSpecFn =
       opts.reconcileAcceptanceSpecFn ?? defaultReconcileAcceptanceSpec;
+    this.resolveSingleFn = opts.resolveSingleFn ?? defaultResolveSingle;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` keys we've handled. */
     this._seen = new Set();
@@ -256,7 +320,24 @@ export class AcceptanceReconciler {
       return;
     }
 
-    const classification = classifyReconcileResult(result);
+    // Resolve the delivery shape before classifying: under single delivery a
+    // `waived` reconcile is non-waivable (design §2c). Best-effort — a probe
+    // failure degrades to `false` (fan-out pass-through), never inventing a
+    // block.
+    let single = false;
+    try {
+      single = await this.resolveSingleFn({
+        provider: this.provider,
+        epicId,
+        config: this.config,
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AcceptanceReconciler] single-delivery probe failed (treating as fan-out): ${err?.message ?? err}`,
+      );
+    }
+
+    const classification = classifyReconcileResult(result, { single });
     if (classification.outcome === 'ok') {
       await this._emitOk({ event, seqId, baseRead });
       return;

package/.agents/scripts/lib/orchestration/lifecycle/listeners/checkpoint-pointer-writer.js

@@ -81,6 +81,12 @@ export const SUBSCRIBED_END_EVENTS = Object.freeze([
   'epic.snapshot.end',
   'epic.watch.end',
   'retro.end',
+  // Epic #4475 (M4-A) — single-delivery slice boundary. A completed slice is
+  // a resume checkpoint for the one long guarded session (the analogue of
+  // story.dispatch.end for fan-out). Subscribed now so the pointer updates
+  // once the M4-B executor emits slice.end through the bus; inert until then
+  // (nothing emits it in M4-A).
+  'slice.end',
   'story.dispatch.end',
 ]);
 

package/.agents/scripts/lib/orchestration/plan-critic-conditions.js

@@ -28,8 +28,9 @@
  * skip decision this module produces is logged to the plan-metrics ledger
  * (`appendCriticSkip`) by the callers so under-firing is auditable.
  *
- * Pure, synchronous, no I/O — the `plan-critics.js` CLI owns reading the
- * authored artifacts and the resolved config.
+ * Pure, synchronous, no I/O — the folded pre-write phase inside
+ * `plan-persist.js` owns reading the authored artifacts and the resolved
+ * config.
  */
 
 import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -129,6 +129,7 @@ export async function runCloseValidationPhase({
       config,
       epicBranch: baseBranch,
       cwd: worktreePath || cwd,
+      log: (m) => Logger.info(m),
     }),
     log: (m) => Logger.info(m),
     storyId,

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -140,6 +140,7 @@ export async function runPreMergeGates({
     config,
     epicBranch,
     cwd: worktreePath || cwd,
+    log: (m) => logger.info?.(m),
   });
   const gateCount = Array.isArray(gates) ? gates.length : 0;
   // Story #2250 — emit `close-validate.start` only when both an epicId

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -272,7 +272,7 @@ export function validateAcFreshness({
  * Epic #2501 introduced this guard after the legacy `baseline-refresh`
  * leading-token prescription created a wave of commit-msg hook failures
  * across story-deliver sub-agents. See
- * `.agents/skills/core/baseline-refresh/SKILL.md` for the canonical refresh
+ * `.agents/skills/core/gates-and-baselines/SKILL.md` for the canonical refresh
  * shape (Conventional-Commits subject + `baseline-refresh: true` body
  * trailer).
  */

package/.agents/scripts/lib/provider-factory.js

@@ -4,7 +4,7 @@
  * Accepts the canonical resolved config object (the wrapper returned by
  * `resolveConfig()` with `config.github` populated). The legacy
  * `orchestration`-shaped argument is no longer supported as part of the
- * Epic #2880 hard cutover; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ * Epic #2880 hard cutover; see `.agents/rules/git-conventions-reference.md#contract-cutovers-—-no-shim-layer`.
  *
  * @see docs/v5-implementation-plan.md Sprint 1B
  */

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -88,7 +88,7 @@ Your job is to take an Epic (including its inline User Stories) and a Technical
 
 ### LABEL CONVENTIONS:
 - Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
-- Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
+- Every ticket must have a \`persona::[engineer|architect|qa-engineer|security-engineer|etc]\` label indicating WHO should execute it.
 
 ### OUTPUT FORMAT:
 You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.

package/.agents/scripts/post-structured-comment.js

@@ -22,6 +22,10 @@ import fs from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
+import {
+  outboxPathFor,
+  postCommentOrBuffer,
+} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   assertValidStructuredCommentType,
   upsertStructuredComment,
@@ -37,6 +41,11 @@ Flags:
                  retro, epic-run-state, wave-0-start) (required).
   --body-file    Path to a file containing the markdown body (required).
   --provider     Provider name (default: inferred from .agentrc.json github block).
+  --buffer       Headless mode: buffer this upsert to the per-Epic bookkeeping
+                 outbox instead of posting live. Requires --epic. Drained to
+                 GitHub once at finalize by bookkeeping-reconcile.js (Epic
+                 #4476). Omit for attended runs (posts live, unchanged).
+  --epic <id>    Epic id owning the outbox (required with --buffer).
   --help         Show this message.
 `;
 
@@ -64,6 +73,8 @@ export function parseArgv(argv) {
       marker: { type: 'string' },
       'body-file': { type: 'string' },
       provider: { type: 'string' },
+      buffer: { type: 'boolean' },
+      epic: { type: 'string' },
       help: { type: 'boolean' },
     },
     strict: false,
@@ -115,6 +126,33 @@ export async function main(argv = process.argv.slice(2)) {
     : config;
   const provider = createProvider(effectiveConfig);
 
+  // Headless buffering (Epic #4476 M5): route the upsert to the per-Epic
+  // outbox instead of a live GitHub round-trip. Requires --epic to locate the
+  // outbox; finalize's bookkeeping-reconcile.js drains it once. Attended runs
+  // (no --buffer) are unchanged.
+  if (values.buffer) {
+    const epicId = Number.parseInt(values.epic ?? '', 10);
+    if (!Number.isInteger(epicId) || epicId <= 0) {
+      process.stderr.write(
+        '[post-structured-comment] --buffer requires --epic <id>.\n',
+      );
+      process.exit(2);
+    }
+    assertValidStructuredCommentType(values.marker);
+    const { buffered } = await postCommentOrBuffer({
+      provider,
+      ticketId,
+      marker: values.marker,
+      body,
+      headless: true,
+      outboxPath: outboxPathFor(epicId, config),
+    });
+    process.stdout.write(
+      `${JSON.stringify({ success: true, ticketId, type: values.marker, buffered })}\n`,
+    );
+    return;
+  }
+
   const envelope = await runPostStructuredComment({
     ticketId,
     type: values.marker,

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' });