mandrel 2.0.0 → 2.1.0

package/.agents/schemas/lifecycle/epic.watch.end.schema.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.watch.end.schema.json",
-  "title": "epic.watch.end",
-  "description": "Emitted by Watcher when required checks settle. checkOutcomes maps check-name → terminal state (success | failure | timed_out | skipped) or the slow-but-not-failed sentinel `still-running` (Story #4358: the poll cap fired with the check still pending after the resume budget was exhausted — distinct from a genuine `failure`). AutomergePredicate subscribes to this event (test-only Watcher path; the production Phase 8.5 boundary is epic.automerge.start).",
-  "type": "object",
-  "required": ["prUrl", "checkOutcomes"],
-  "properties": {
-    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
-    "checkOutcomes": {
-      "type": "object",
-      "additionalProperties": {
-        "type": "string",
-        "enum": [
-          "success",
-          "failure",
-          "neutral",
-          "cancelled",
-          "timed_out",
-          "still-running",
-          "action_required",
-          "stale",
-          "skipped"
-        ]
-      }
-    }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/epic.watch.start.schema.json

@@ -1,16 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.watch.start.schema.json",
-  "title": "epic.watch.start",
-  "description": "Emitted by Watcher when required-check polling begins. Required-check names are resolved from GitHub at runtime via gh pr checks, not from .agentrc.json.",
-  "type": "object",
-  "required": ["prUrl", "requiredChecks"],
-  "properties": {
-    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
-    "requiredChecks": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/story.heartbeat.schema.json

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.heartbeat.schema.json",
-  "title": "story.heartbeat",
-  "description": "Emitted by story-phase.js inside a Story's implementation loop. Surfaces the in-progress Story as an inspectable ledger event so /deliver's host-loop reconciler can confirm a long Story is still making forward progress between dispatch and merge — distinct from story.dispatch.start (one per Story per attempt) and story.merged (one per Story per close). The 2-tier hierarchy has no child Task tickets, so the heartbeat carries phase info only. The optional operator field (Story #3480) records the handle holding the assignee-as-lease claim on the Story so the ticket-lease primitive can decide claim liveness from the most-recent heartbeat for a given owner.",
-  "type": "object",
-  "required": ["event", "storyId", "epicId", "phase", "timestamp"],
-  "properties": {
-    "event": { "type": "string", "const": "story.heartbeat" },
-    "storyId": { "type": "integer", "minimum": 1 },
-    "epicId": { "type": "integer", "minimum": 1 },
-    "phase": {
-      "type": "string",
-      "enum": ["init", "implementing", "closing", "blocked", "done"]
-    },
-    "timestamp": { "type": "string", "format": "date-time" },
-    "operator": { "type": "string", "minLength": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/risk-verdict.schema.json

@@ -1,53 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "risk-verdict",
-  "title": "Planning Risk Verdict",
-  "description": "Planner-authored risk judgment for an Epic, produced by the epic-plan-spec-author Skill as the fourth planning artifact (risk-verdict.json) alongside the PRD, Tech Spec, and Acceptance Spec (Epic #3865). plan-persist.js validates the verdict against this schema, derives the deterministic planningRisk envelope via deriveRiskEnvelope (lib/orchestration/planning-risk.js), and records the verdict as a risk-verdict structured comment plus the epic-plan-state checkpoint riskVerdict field. The model supplies the judgment input (axes); the harness owns the gate decision. A malformed verdict fails closed to the validation-error path — it is never silently coerced.",
-  "type": "object",
-  "required": ["axes", "summary"],
-  "properties": {
-    "axes": {
-      "type": "array",
-      "description": "Risk axes the planner judges to genuinely apply to the Epic. An empty array asserts no recognized risk axis applies (derives an all-low envelope). Every entry must use the fixed axis vocabulary mirrored from REQUIRED_AXES / NOT_APPLICABLE_AXES in lib/orchestration/planning-risk.js.",
-      "items": {
-        "type": "object",
-        "required": ["axis", "level", "rationale"],
-        "properties": {
-          "axis": {
-            "type": "string",
-            "enum": [
-              "visible-behavior",
-              "public-api",
-              "security",
-              "data-migration",
-              "billing",
-              "destructive-mutation",
-              "critical-workflow",
-              "docs-only",
-              "test-harness",
-              "internal-refactor"
-            ],
-            "description": "Risk axis identifier. The first seven force a required acceptance disposition when present (REQUIRED_AXES); the last three waive the acceptance spec when they are the only signals (NOT_APPLICABLE_AXES)."
-          },
-          "level": {
-            "type": "string",
-            "enum": ["low", "medium", "high"],
-            "description": "Planner-judged severity of this axis for the Epic's actual change, not keyword presence — e.g. a PRD sentence saying 'out of scope: billing' is not a billing change."
-          },
-          "rationale": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Concrete, reviewer-readable justification grounded in the PRD / Tech Spec the planner just authored. Never an empty self-attestation."
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "summary": {
-      "type": "string",
-      "minLength": 1,
-      "description": "One-paragraph overall risk narrative for the audit trail (the rationale the retired regex classifier could never produce)."
-    }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/story-perf-summary.schema.json

@@ -1,73 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-perf-summary.schema.json",
-  "title": "StoryPerfSummary",
-  "description": "Payload of the <!-- structured:story-perf-summary --> comment posted once per Story at close (Epic #1030). Replaces the per-Task friction comment fanout and the standalone phase-timings comment.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "kind",
-    "storyId",
-    "epicId",
-    "closedAt",
-    "frictionByCategory",
-    "phaseTimingsMs",
-    "topSlowPhasesVsBaseline",
-    "reworkScore",
-    "retryDensity"
-  ],
-  "properties": {
-    "kind": { "type": "string", "const": "story-perf-summary" },
-    "storyId": { "type": "integer", "minimum": 1 },
-    "epicId": { "type": "integer", "minimum": 1 },
-    "closedAt": { "type": "string", "format": "date-time" },
-    "frictionByCategory": {
-      "type": "object",
-      "description": "Counts of friction signals bucketed by category for this Story.",
-      "additionalProperties": { "type": "integer", "minimum": 0 }
-    },
-    "phaseTimingsMs": {
-      "type": "object",
-      "description": "Elapsed ms per phase, sourced from phase-timer.js in-process record.",
-      "additionalProperties": { "type": "integer", "minimum": 0 }
-    },
-    "topSlowPhasesVsBaseline": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["phase", "elapsedMs", "baselineP95Ms", "ratio"],
-        "properties": {
-          "phase": { "type": "string", "minLength": 1 },
-          "elapsedMs": { "type": "integer", "minimum": 0 },
-          "baselineP95Ms": { "type": "integer", "minimum": 0 },
-          "ratio": { "type": "number", "minimum": 0 }
-        }
-      }
-    },
-    "reworkScore": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["filesEditedBeyondThreshold"],
-      "properties": {
-        "filesEditedBeyondThreshold": { "type": "integer", "minimum": 0 },
-        "topPath": { "type": ["string", "null"], "minLength": 1 },
-        "topPathEdits": { "type": ["integer", "null"], "minimum": 0 }
-      }
-    },
-    "retryDensity": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["retries", "uniqueCommands"],
-      "properties": {
-        "retries": { "type": "integer", "minimum": 0 },
-        "uniqueCommands": { "type": "integer", "minimum": 0 }
-      }
-    },
-    "ghSpawnCount": {
-      "type": "integer",
-      "minimum": 0,
-      "description": "Throw-away measurement field (Story #1795 / Epic #1788): the in-process `gh` spawn counter snapshot at end of close validation. Used to verify the ≥100 fewer-spawns acceptance criterion against the baseline recorded under `temp/epic-1788/`. Removed in a follow-up cleanup commit before the Story merges to the Epic branch."
-    }
-  }
-}

package/.agents/scripts/analyze-execution.js

@@ -1,444 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * analyze-execution.js — single writer of the structured perf-summary
- * comments (Epic #1030 / Story #1123).
- *
- * Reads NDJSON from `temp/epic-<eid>/stories/story-<sid>/signals.ndjson` and
- * upserts one of two structured comments:
- *
- *   - `--story <sid> --epic <eid>` (Story mode): posts
- *     `<!-- structured:story-perf-summary -->` on the Story ticket. The
- *     payload combines the Story's NDJSON signals with the timing
- *     summary written by `post-merge-close.js` to
- *     `temp/epic-<eid>/stories/story-<sid>/phase-timings.json` (path overridable
- *     via `--phase-timings <path>`).
- *
- *   - `--epic <eid>` (Epic mode): rolls up every Story under the Epic by
- *     fetching each `story-perf-summary` structured comment from the
- *     ticketing provider. Posts the
- *     `<!-- structured:epic-perf-report -->` comment on the Epic ticket.
- *     Run from the retro composer / `/deliver` Phase 6.0.
- *
- * Both modes are idempotent: `upsertStructuredComment` deletes the prior
- * marker before posting the new one.
- *
- * Exit code is `0` on success, `0` on tolerated soft failures (missing
- * NDJSON for a Story, no children for an Epic) so the close pipelines
- * never block on observability output. Hard failures (bad CLI args,
- * provider error, schema-violating payload) exit non-zero — the call
- * sites in `single-story-close.js` / `helpers/deliver-story.md` treat that
- * as a non-fatal warning.
- *
- * This file is a thin CLI: it wires the I/O readers from
- * `lib/observability/perf-report-readers.js` to the pure renderers in
- * `lib/observability/perf-report-render.js` inside `runStoryMode` /
- * `runEpicMode`, then parses argv and dispatches. The report-formatting
- * and signal-reading logic live in those two modules so report formatting
- * is unit-testable without fixtures (Story #3350).
- *
- * Usage:
- *   node .agents/scripts/analyze-execution.js --story <sid> --epic <eid> \
- *       [--phase-timings <path>]
- *   node .agents/scripts/analyze-execution.js --epic <eid>
- *   node .agents/scripts/analyze-execution.js --epic <eid> --plan-metrics-json
- *
- * `--plan-metrics-json` (Epic #4474 PR7 — the G2 extraction surface) is a
- * **local read-only** mode: it reads the per-Epic plan-metrics ledger
- * (`temp/epic-<eid>/plan-metrics.json`), rolls it up with
- * `summarizePlanMetrics`, and prints one compact JSON envelope
- * `{ epicId, planMetrics, summaryLine }` to stdout — no provider call, no
- * comment write, all logs on stderr — so a bench cohort can extract
- * turns-per-plan / per-mode invocation counts / critic skips without
- * scraping GitHub or the human log.
- *
- * @see docs/data-dictionary.md §StoryPerfSummary, §EpicPerfReport
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { signalsFile } from './lib/config/temp-paths.js';
-import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
-import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { computeBaselineRefreshRate } from './lib/observability/baseline-refresh-rate.js';
-import {
-  computeEpicPerfReport,
-  computeStoryPerfSummary,
-} from './lib/observability/perf-aggregator.js';
-import {
-  aggregateBaselineFrictionFromSignals,
-  collectStorySummaries,
-  gatherEpicCommitsFromGit,
-  readEpicLifecycleEvents,
-  readGhSpawnCount,
-  readPhaseTimings,
-  readStorySignals,
-} from './lib/observability/perf-report-readers.js';
-import {
-  EPIC_PERF_TYPE,
-  renderEpicBody,
-  renderStoryBody,
-  STORY_PERF_TYPE,
-} from './lib/observability/perf-report-render.js';
-import {
-  readPlanMetrics,
-  renderPlanMetricsSummaryLine,
-  summarizePlanMetrics,
-} from './lib/orchestration/plan-metrics.js';
-import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
-import { createProvider } from './lib/provider-factory.js';
-
-// Re-exported so existing importers (tests, retro composer) keep a stable
-// entry point after the read/render split (Story #3350).
-export { extractStoryPerfSummaryFromComment } from './lib/observability/perf-report-render.js';
-
-/**
- * Resolve the wave-execution concurrency cap from the resolved config
- * (`delivery.deliverRunner.concurrencyCap`), falling back to the
- * dispatcher's safe default of 2. Story #3025 / Task #3030.
- */
-function resolveConcurrencyCap(config) {
-  const cap = config?.delivery?.deliverRunner?.concurrencyCap;
-  return Number.isInteger(cap) && cap >= 1 ? cap : 2;
-}
-
-/**
- * Resolve the verify-results concurrency cap from the resolved config
- * (`delivery.deliverRunner.verifyConcurrencyCap`), falling back to 4.
- * Story #3025 / Task #3030.
- */
-function resolveVerifyConcurrencyCap(config) {
-  const cap = config?.delivery?.deliverRunner?.verifyConcurrencyCap;
-  return Number.isInteger(cap) && cap >= 1 ? cap : 4;
-}
-
-/**
- * Story mode: read NDJSON + phase-timings, build the payload, upsert.
- *
- * @param {{
- *   storyId: number,
- *   epicId: number,
- *   phaseTimingsPath?: string|null,
- *   provider: object,
- *   config: object,
- *   logger?: object,
- *   now?: () => Date,
- * }} ctx
- * @returns {Promise<{ commentId: number, payload: object }>}
- */
-export async function runStoryMode(ctx) {
-  const { storyId, epicId, provider, config } = ctx;
-  const logger = ctx.logger ?? Logger;
-  const now = ctx.now ?? (() => new Date());
-
-  logger.info?.(
-    `[analyze-execution] story-mode story=#${storyId} epic=#${epicId}`,
-  );
-
-  const events = await readStorySignals(epicId, storyId, config);
-  const phaseTiming = await readPhaseTimings(
-    epicId,
-    storyId,
-    config,
-    ctx.phaseTimingsPath ?? null,
-  );
-  const ghSpawnCount = await readGhSpawnCount(epicId, storyId, config);
-
-  const payload = computeStoryPerfSummary(events, {
-    storyId,
-    epicId,
-    closedAt: now().toISOString(),
-    phaseTiming,
-  });
-  if (ghSpawnCount !== null) {
-    // Throw-away measurement field (Story #1795). Surfaces the in-process
-    // `gh-exec.getSpawnCount()` snapshot captured at the end of close
-    // validation so the Story-close structured comment can be diffed
-    // against the baseline recorded under `temp/epic-1788/` for the
-    // "≥100 fewer spawns" acceptance criterion.
-    payload.ghSpawnCount = ghSpawnCount;
-  }
-
-  const body = renderStoryBody(payload);
-  const result = await upsertStructuredComment(
-    provider,
-    storyId,
-    STORY_PERF_TYPE,
-    body,
-  );
-  logger.info?.(
-    `[analyze-execution] story-perf-summary upserted on Story #${storyId} (commentId=${result.commentId})`,
-  );
-  return { commentId: result.commentId, payload };
-}
-
-/**
- * Epic mode: collect every Story's perf summary, roll them up, upsert
- * the epic-perf-report comment.
- *
- * @param {{
- *   epicId: number,
- *   provider: object,
- *   config?: object,
- *   cwd?: string,
- *   windowDays?: number,
- *   logger?: object,
- *   now?: () => Date,
- *   collectSummariesFn?: typeof collectStorySummaries,
- *   gatherEpicCommitsFn?: typeof gatherEpicCommitsFromGit,
- *   aggregateFrictionFn?: typeof aggregateBaselineFrictionFromSignals,
- * }} ctx
- * @returns {Promise<{ commentId: number, payload: object, baselineRefreshRate: object | null, qualityGateFriction: object | null }>}
- */
-export async function runEpicMode(ctx) {
-  const { epicId, provider } = ctx;
-  const logger = ctx.logger ?? Logger;
-  const now = ctx.now ?? (() => new Date());
-  const windowDays =
-    Number.isFinite(ctx.windowDays) && ctx.windowDays > 0
-      ? Math.floor(ctx.windowDays)
-      : 28;
-  const collectFn = ctx.collectSummariesFn ?? collectStorySummaries;
-  const gatherCommitsFn = ctx.gatherEpicCommitsFn ?? gatherEpicCommitsFromGit;
-  const aggregateFrictionFn =
-    ctx.aggregateFrictionFn ?? aggregateBaselineFrictionFromSignals;
-
-  logger.info?.(`[analyze-execution] epic-mode epic=#${epicId}`);
-
-  const summaries = await collectFn(provider, epicId, logger);
-
-  // Story #3025 / Task #3030 — forward lifecycle events to the
-  // aggregator so the report's `waveParallelism` array is populated
-  // (the analyzer used to omit the field, leaving the report at `[]`).
-  const readLifecycleEventsFn =
-    ctx.readLifecycleEventsFn ?? readEpicLifecycleEvents;
-  const lifecycleEvents = ctx.config
-    ? await readLifecycleEventsFn(epicId, ctx.config, logger)
-    : [];
-  const concurrencyCap = resolveConcurrencyCap(ctx.config);
-  const verifyConcurrencyCap = resolveVerifyConcurrencyCap(ctx.config);
-
-  // Only forward `events` when we actually have something — passing an
-  // empty array suppresses the friction-from-summaries fallback in
-  // `computeEpicPerfReport.buildSignalCounts`, which would zero the
-  // counts for callers that have summaries but no lifecycle stream
-  // (e.g. legacy/test paths without a `config`).
-  const reportOpts = {
-    epicId,
-    generatedAt: now().toISOString(),
-    concurrencyCap,
-    verifyConcurrencyCap,
-  };
-  if (lifecycleEvents.length > 0) {
-    reportOpts.events = lifecycleEvents;
-  }
-
-  const payload = computeEpicPerfReport(summaries, reportOpts);
-
-  // Story #1400 / Task #1427 — baseline-refresh-rate row. Pure reporter
-  // operates on a fixture of git-log records gathered by the injected
-  // `gatherEpicCommitsFn`. A spawn failure surfaces as `[]` and degrades
-  // to the "no Story merges in window" line in the rendered body.
-  let baselineRefreshRate = null;
-  try {
-    const commits = await gatherCommitsFn({
-      epicId,
-      windowDays,
-      cwd: ctx.cwd ?? process.cwd(),
-      logger,
-    });
-    baselineRefreshRate = computeBaselineRefreshRate(commits, {
-      windowDays,
-      now,
-    });
-  } catch (err) {
-    logger.warn?.(
-      `[analyze-execution] baseline-refresh-rate gather failed (non-fatal): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-  }
-
-  // Story #1400 / Task #1429 — Quality gate friction block. Aggregates
-  // `baseline-refresh-regression` records from the existing
-  // signals.ndjson stream (no new file format).
-  let qualityGateFriction = null;
-  if (ctx.config) {
-    try {
-      const storyIds = (summaries ?? [])
-        .map((s) => s?.storyId)
-        .filter((n) => Number.isInteger(n) && n > 0);
-      qualityGateFriction = await aggregateFrictionFn({
-        epicId,
-        storyIds,
-        config: ctx.config,
-        windowDays,
-        now,
-      });
-    } catch (err) {
-      logger.warn?.(
-        `[analyze-execution] quality-gate-friction aggregate failed (non-fatal): ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-  }
-
-  const body = renderEpicBody(payload, {
-    baselineRefreshRate,
-    qualityGateFriction,
-  });
-  const result = await upsertStructuredComment(
-    provider,
-    epicId,
-    EPIC_PERF_TYPE,
-    body,
-  );
-  logger.info?.(
-    `[analyze-execution] epic-perf-report upserted on Epic #${epicId} (commentId=${result.commentId}, stories=${summaries.length})`,
-  );
-
-  // Plan-metrics roll-up (#4474 PR1) — surface the plan-CLI invocation
-  // ledger (`temp/epic-<id>/plan-metrics.json`) alongside the perf report.
-  // Additive and non-fatal: a missing or unreadable ledger yields `null`.
-  let planMetrics = null;
-  try {
-    planMetrics = summarizePlanMetrics(
-      await readPlanMetrics(epicId, ctx.config),
-    );
-    if (planMetrics) {
-      logger.info?.(
-        `[analyze-execution] ${renderPlanMetricsSummaryLine(planMetrics)}`,
-      );
-    }
-  } catch (err) {
-    logger.warn?.(
-      `[analyze-execution] plan-metrics read failed (non-fatal): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-  }
-
-  return {
-    commentId: result.commentId,
-    payload,
-    baselineRefreshRate,
-    qualityGateFriction,
-    planMetrics,
-  };
-}
-
-function parseCli(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      story: { type: 'string' },
-      epic: { type: 'string' },
-      'phase-timings': { type: 'string' },
-      'window-days': { type: 'string' },
-      'plan-metrics-json': { type: 'boolean', default: false },
-      cwd: { type: 'string' },
-    },
-    strict: false,
-  });
-  const story = values.story != null ? Number.parseInt(values.story, 10) : null;
-  const epic = values.epic != null ? Number.parseInt(values.epic, 10) : null;
-  const windowDays =
-    values['window-days'] != null
-      ? Number.parseInt(values['window-days'], 10)
-      : null;
-  return {
-    storyId: Number.isInteger(story) && story > 0 ? story : null,
-    epicId: Number.isInteger(epic) && epic > 0 ? epic : null,
-    phaseTimingsPath: values['phase-timings'] ?? null,
-    windowDays:
-      Number.isInteger(windowDays) && windowDays > 0 ? windowDays : null,
-    planMetricsJson: values['plan-metrics-json'] === true,
-    cwd: values.cwd ?? null,
-  };
-}
-
-/**
- * `--plan-metrics-json` — local, read-only G2 extraction surface (Epic
- * #4474 PR7). Reads the per-Epic plan-metrics ledger and prints one
- * compact JSON envelope to stdout. No provider, no comment write; stdout
- * is reserved for the envelope (all logs on stderr). A missing ledger is
- * not an error — it yields `planMetrics: null` so a cohort script can
- * branch on the field instead of the exit code.
- *
- * @param {{ epicId: number, config: object }} input
- * @returns {Promise<{ epicId: number, planMetrics: object|null, summaryLine: string }>}
- */
-export async function runPlanMetricsJsonMode({ epicId, config }) {
-  const planMetrics = summarizePlanMetrics(
-    await readPlanMetrics(epicId, config),
-  );
-  return {
-    epicId,
-    planMetrics,
-    summaryLine: renderPlanMetricsSummaryLine(planMetrics),
-  };
-}
-
-async function main(argv = process.argv.slice(2)) {
-  const args = parseCli(argv);
-
-  if (!args.epicId) {
-    throw new Error(
-      'Usage: analyze-execution.js --epic <eid> [--story <sid>] [--phase-timings <path>]',
-    );
-  }
-
-  const cwd = path.resolve(args.cwd ?? PROJECT_ROOT);
-  const config = resolveConfig({ cwd });
-
-  if (args.planMetricsJson) {
-    // Stdout is reserved for the compact envelope — flip every log sink to
-    // stderr before any pipeline code runs (Story #2278 discipline).
-    routeAllOutputToStderr();
-    const result = await runPlanMetricsJsonMode({
-      epicId: args.epicId,
-      config,
-    });
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    return;
-  }
-
-  const provider = createProvider(config);
-
-  if (args.storyId) {
-    // Existence guard: surface a clear log when the Story has no signals
-    // yet, but still post the comment with empty arrays so the marker
-    // exists for idempotence checks downstream.
-    const sigPath = signalsFile(args.epicId, args.storyId, config);
-    try {
-      await fs.access(sigPath);
-    } catch {
-      Logger.info?.(
-        `[analyze-execution] no signals.ndjson at ${sigPath} — posting empty story-perf-summary`,
-      );
-    }
-    const result = await runStoryMode({
-      storyId: args.storyId,
-      epicId: args.epicId,
-      phaseTimingsPath: args.phaseTimingsPath,
-      provider,
-      config,
-    });
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    return;
-  }
-
-  const result = await runEpicMode({
-    epicId: args.epicId,
-    provider,
-    config,
-    cwd,
-    windowDays: args.windowDays ?? undefined,
-  });
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'analyze-execution' });