mandrel 1.94.0 → 2.1.0

package/.agents/scripts/standalone-feedback-rollup.js

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * standalone-feedback-rollup.js — end-of-run feedback rollup for the
- * `/deliver` standalone multi-Story path (Epic #4406 / Story #4416).
- *
- * The standalone delivery path (`helpers/deliver-stories`) drives one or
- * more Epic-free Stories to green, and each per-Story sub-agent appends
- * `friction` records to its **standalone** signals stream at
- * `temp/standalone/stories/story-<sid>/signals.ndjson` (written via
- * `appendSignal({ epicId: null, storyId })`). Before this rollup that
- * tree was write-only — nothing ever read it back. This CLI closes the
- * gap: it scans the standalone streams for the delivered Story set and
- * emits a per-category friction summary that `deliver-stories.md`
- * surfaces in its Phase 3 run summary.
- *
- * Usage:
- *   node standalone-feedback-rollup.js --stories <id,...>
- *
- * Contract:
- *   - Stream paths resolve **exclusively** through the `temp-paths`
- *     helpers via `forEachLine(null, storyId, cb, config)` — the `null`
- *     Epic sentinel routes to the standalone tree. No hand-built path
- *     strings.
- *   - Aggregates `friction` records by their **top-level** `category`
- *     (Epic #4406 canonical envelope shape); a record with no category
- *     buckets under `Unknown`.
- *   - **Never fails a run.** A missing or empty stream degrades to an
- *     empty contribution; the CLI always prints a JSON summary and
- *     exits 0. Observability MUST NOT take down the delivering flow.
- *
- * Output (stdout, one JSON object):
- *   {
- *     "kind": "standalone-feedback-rollup",
- *     "stories": [<id>, ...],
- *     "totalFriction": <int>,
- *     "byCategory": { "<category>": <count>, ... },
- *     "perStory": { "<id>": { "friction": <int>, "missing": <bool> }, ... }
- *   }
- *
- * @see .agents/scripts/lib/observability/signals-writer.js (forEachLine, appendSignal)
- * @see .agents/scripts/lib/config/temp-paths.js (signalsFile — null Epic sentinel)
- * @see .agents/workflows/helpers/deliver-stories.md (Phase 3 summary wiring)
- */
-
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { forEachLine } from './lib/observability/signals-writer.js';
-
-const FRICTION_KIND = 'friction';
-const UNKNOWN_CATEGORY = 'Unknown';
-
-/**
- * Parse `--stories <id,...>` into an ordered, de-duplicated array of
- * positive-integer Story IDs. Accepts a single comma-separated value or
- * repeated `--stories` flags. Non-integer / non-positive tokens are
- * rejected so a typo surfaces as an input error rather than a silently
- * empty rollup.
- *
- * @param {string[]} args
- * @returns {{ stories: number[] }}
- */
-export function parseArguments(args) {
-  const raw = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--stories') {
-      const value = args[++i];
-      if (typeof value === 'string') {
-        raw.push(...value.split(','));
-      }
-    }
-  }
-
-  const seen = new Set();
-  const stories = [];
-  for (const token of raw) {
-    const trimmed = token.trim();
-    if (trimmed.length === 0) continue;
-    const id = Number(trimmed);
-    if (!Number.isInteger(id) || id <= 0) {
-      throw new Error(
-        `--stories expects comma-separated positive integers; got ${JSON.stringify(trimmed)}`,
-      );
-    }
-    if (seen.has(id)) continue;
-    seen.add(id);
-    stories.push(id);
-  }
-
-  if (stories.length === 0) {
-    throw new Error(
-      'Usage: node standalone-feedback-rollup.js --stories <id,...>',
-    );
-  }
-
-  return { stories };
-}
-
-/**
- * Read one standalone Story's signals stream and aggregate its `friction`
- * records by top-level `category`, mutating the shared `byCategory` tally.
- *
- * Degrades to a zero contribution on a missing / empty / unreadable
- * stream — `forEachLine` already swallows fs + JSON faults and reports a
- * missing file via `{ missing: true }` rather than throwing.
- *
- * @param {number} storyId
- * @param {Record<string, number>} byCategory Mutated in place.
- * @param {object} config
- * @returns {Promise<{ friction: number, missing: boolean }>}
- */
-async function rollupStory(storyId, byCategory, config) {
-  let friction = 0;
-  // `epicId: null` routes forEachLine → signalsFile(null, storyId, config)
-  // → the standalone tree. Never a hand-built path string.
-  const result = await forEachLine(
-    null,
-    storyId,
-    (record) => {
-      if (
-        record === null ||
-        typeof record !== 'object' ||
-        record.kind !== FRICTION_KIND
-      ) {
-        return;
-      }
-      const category =
-        typeof record.category === 'string' && record.category.length > 0
-          ? record.category
-          : UNKNOWN_CATEGORY;
-      byCategory[category] = (byCategory[category] ?? 0) + 1;
-      friction += 1;
-    },
-    config,
-  );
-
-  return { friction, missing: Boolean(result?.missing) };
-}
-
-/**
- * Aggregate friction across every named standalone Story stream.
- *
- * @param {number[]} stories
- * @param {object} [config]
- * @returns {Promise<{
- *   kind: string,
- *   stories: number[],
- *   totalFriction: number,
- *   byCategory: Record<string, number>,
- *   perStory: Record<string, { friction: number, missing: boolean }>,
- * }>}
- */
-export async function buildRollup(stories, config) {
-  const byCategory = {};
-  const perStory = {};
-  let totalFriction = 0;
-
-  for (const storyId of stories) {
-    const { friction, missing } = await rollupStory(
-      storyId,
-      byCategory,
-      config,
-    );
-    perStory[storyId] = { friction, missing };
-    totalFriction += friction;
-  }
-
-  return {
-    kind: 'standalone-feedback-rollup',
-    stories,
-    totalFriction,
-    byCategory,
-    perStory,
-  };
-}
-
-export async function main(args = process.argv.slice(2)) {
-  const { stories } = parseArguments(args);
-  const config = resolveConfig();
-  const summary = await buildRollup(stories, config);
-  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
-  return 0;
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'StandaloneFeedbackRollup',
-  propagateExitCode: true,
-});

package/.agents/scripts/story-close.js

@@ -1,294 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * story-close.js — Story Execution Closure (CLI shell).
- *
- * Thin pipeline that wires the phase modules under
- * `lib/orchestration/story-close/phases/`. Each phase runs as a discrete
- * step and may short-circuit the pipeline with a `{ status: 'blocked' }`
- * envelope. Pipeline shape:
- *
- *   1. parse + resolveCloseInputs (lib/orchestration/story-close/close-inputs.js)
- *   1.5. already-done no-op guard (inline below) — a Story already at
- *      `agent::done` AND closed short-circuits here so no phase below it
- *      ever flips the label away from `agent::done` or reopens the issue.
- *   2. preflight                  (phases/preflight.js)
- *   3. state-flip → closing       (inline helper below)
- *   4. capture starting branch    (phases/branch-restore.js)
- *   5. acquire per-Epic merge lock + run the locked pipeline
- *      (phases/locked-pipeline.js — gates, refresh, close)
- *   6. restore starting branch    (finally; phases/branch-restore.js)
- *
- * Usage: `node story-close.js --story <ID> [--epic <ID>]`. Exit codes:
- *   0  ok
- *   1  error
- *   2  prior-state (pass --resume / --restart) OR preflight refused
- *
- * @see .agents/workflows/helpers/deliver-stories.md
- */
-
-import { runAsCli } from './lib/cli-utils.js';
-import { tempRootFrom } from './lib/config/temp-paths.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 { checkCdOutGuard } from './lib/orchestration/story-close/cd-out-guard.js';
-import { resolveCloseInputs } from './lib/orchestration/story-close/close-inputs.js';
-import { withEpicMergeLock } from './lib/orchestration/story-close/merge-runner.js';
-import {
-  captureStartingBranch,
-  restoreStartingBranch,
-} from './lib/orchestration/story-close/phases/branch-restore.js';
-import { runStoryCloseLocked } from './lib/orchestration/story-close/phases/locked-pipeline.js';
-import {
-  emitPreflightBlockedResult,
-  runStoryClosePreflight,
-} from './lib/orchestration/story-close/phases/preflight.js';
-import { describeAutoRefreshOutcome } from './lib/orchestration/story-close/phases/refresh.js';
-import {
-  renderCoverageTimeoutFrictionBody,
-  renderSpawnTimeoutFrictionBody,
-  resolveSpawnTimeoutReason,
-} from './lib/orchestration/story-close/phases/timeout-blocked.js';
-import {
-  STATE_LABELS,
-  transitionTicketState,
-} from './lib/orchestration/ticketing.js';
-import { PREFLIGHT_REFUSED_EXIT_CODE } from './lib/preflight-runner.js';
-import { notify } from './notify.js';
-
-// Re-exports preserved for historical test imports. Each underlying
-// implementation now lives under `phases/`.
-export {
-  captureStartingBranch,
-  checkCdOutGuard,
-  describeAutoRefreshOutcome,
-  renderCoverageTimeoutFrictionBody,
-  renderSpawnTimeoutFrictionBody,
-  resolveSpawnTimeoutReason,
-  restoreStartingBranch,
-  runStoryClosePreflight,
-};
-
-const progress = Logger.createProgress('story-close', { stderr: true });
-const progressLog = (tag, msg) => progress(tag, msg);
-
-/**
- * Best-effort lifecycle-bus wiring. Story #2241 / Task #2247 — bus emits
- * land in the Epic-scoped NDJSON ledger so a sub-agent's `story.merged` /
- * `story.blocked` records sit alongside the parent runner's `wave.*`.
- * A wiring failure logs and returns `null` — the close result must never
- * depend on lifecycle observability.
- */
-function wireLifecycleBus({ epicId, config }) {
-  try {
-    const lifecycleBus = createBus();
-    const tempRoot = tempRootFrom(config);
-    const ledger = createLedgerWriter({
-      epicId: Number(epicId),
-      tempRoot,
-    });
-    ledger.register(lifecycleBus);
-    return lifecycleBus;
-  } catch (err) {
-    Logger.warn?.(
-      `[story-close] ⚠️ lifecycle bus init failed (continuing without emits): ${err?.message ?? err}`,
-    );
-    return null;
-  }
-}
-
-/**
- * Phase 3 — flip the Story label to `agent::closing` once preflight has
- * passed and before we acquire the per-Epic merge lock. Best-effort.
- */
-async function transitionToClosing({ provider, storyId, notifyFn }) {
-  try {
-    await transitionTicketState(provider, storyId, STATE_LABELS.CLOSING, {
-      cascade: false,
-      notify: notifyFn,
-    });
-    progress('STATE', `Story #${storyId} → ${STATE_LABELS.CLOSING}`);
-  } catch (err) {
-    Logger.warn?.(
-      `[story-close] failed to flip Story #${storyId} → ${STATE_LABELS.CLOSING}: ${err?.message ?? err}`,
-    );
-  }
-}
-
-/** Orchestrate the Story closure. Exported for testing. */
-export async function runStoryClose({
-  storyId: storyIdParam,
-  epicId: epicIdParam,
-  skipDashboard: skipDashboardParam,
-  skipValidation: skipValidationParam,
-  cwd: cwdParam,
-  resume: resumeParam,
-  restart: restartParam,
-  injectedProvider,
-} = {}) {
-  const resolved = await resolveCloseInputs({
-    storyIdParam,
-    epicIdParam,
-    skipDashboardParam,
-    skipValidationParam,
-    cwdParam,
-    resumeParam,
-    restartParam,
-    injectedProvider,
-  });
-  const {
-    storyId,
-    epicId,
-    cwd,
-    worktreePath,
-    skipDashboard,
-    skipValidation: skipValidationResolved,
-    resumeFlag,
-    restartFlag,
-    noEvidenceFlag,
-    config,
-    provider,
-    story,
-    epicBranch,
-    storyBranch,
-  } = resolved;
-
-  // Phase 0 — idempotency guard. A re-run against a Story that is already
-  // fully closed must be a safe no-op. Without this guard, Phase 3 below
-  // (`transitionToClosing`) unconditionally flips the label to
-  // `agent::closing` — and `transitionTicketState`
-  // (lib/orchestration/ticketing/transition.js) unconditionally sends
-  // `state: 'open'` for any non-`agent::done` target — so re-running close
-  // against an already-closed Story reopens the GitHub issue and strips
-  // `agent::done` *before* the post-merge pipeline even starts. If the
-  // pipeline then throws or a phase silently no-ops (the merge is already
-  // fully reaped, so there is nothing left to redo), the Story is left
-  // regressed at `agent::closing`/OPEN instead of a safe no-op.
-  //
-  // The "already fully closed" test mirrors the deepest-level guard in the
-  // post-merge `ticketClosurePhase` (post-merge/phases/ticket-closure.js):
-  // label `agent::done` AND issue `state === 'closed'`, an AND — never a
-  // state-alone check. The `state === 'closed'` disjunct is deliberately
-  // excluded per the hard-won reasoning in
-  // `lib/single-story/confirm-merge.js`: a Story can arrive here closed at
-  // the GitHub layer (a `Closes #<id>` PR footer, or a prior close that set
-  // `state: closed` but was killed before the label flip landed) while its
-  // label is legitimately still `agent::closing`. Treating that as
-  // already-done would skip the very `closing → done` re-assertion the
-  // re-run exists to perform, stranding the label. Requiring BOTH signals
-  // no-ops only a genuinely finished Story.
-  const alreadyDone =
-    Array.isArray(story?.labels) &&
-    story.labels.includes(STATE_LABELS.DONE) &&
-    story?.state === 'closed';
-  if (alreadyDone) {
-    progress(
-      'SKIP',
-      `Story #${storyId} is already ${STATE_LABELS.DONE} and closed — no-op re-run.`,
-    );
-    return {
-      success: true,
-      result: {
-        storyId,
-        epicId,
-        action: 'noop',
-        reason: 'already-done',
-        merged: true,
-      },
-    };
-  }
-
-  const notifyFn = (ticketId, payload, opts = {}) =>
-    notify(ticketId, payload, { config, provider, ...opts });
-
-  const bus = wireLifecycleBus({ epicId, config });
-
-  progress('INIT', `Closing Story #${storyId}...`);
-
-  // Phase 2 — preflight (exit-code 2 reservation when refused).
-  const preflightOutcome = await runStoryClosePreflight({ storyId, cwd });
-  if (!preflightOutcome.ok) {
-    const blockedResult = await emitPreflightBlockedResult({
-      storyId,
-      preflight: preflightOutcome,
-      progress,
-    });
-    return {
-      success: false,
-      result: blockedResult,
-      exitCode: PREFLIGHT_REFUSED_EXIT_CODE,
-    };
-  }
-
-  // Phase 3 — flip Story → `agent::closing`.
-  await transitionToClosing({ provider, storyId, notifyFn });
-
-  // Phase 4 — capture the starting branch so the `finally` block can
-  // restore it on any throw inside the merge-lock-protected region.
-  const startingBranch = captureStartingBranch(cwd);
-  if (!startingBranch.ok) {
-    Logger.warn?.(
-      `[story-close] branch-restore: could not capture starting branch (${startingBranch.reason}); finally-block restore will be skipped.`,
-    );
-  }
-
-  // Phase 5 — acquire per-Epic merge lock for the entire close flow.
-  try {
-    return await withEpicMergeLock(
-      epicId,
-      { repoRoot: cwd, timeoutMs: 60_000, log: progressLog },
-      () =>
-        runStoryCloseLocked({
-          storyId,
-          epicId,
-          cwd,
-          worktreePath,
-          skipDashboard,
-          skipValidationParam: skipValidationResolved,
-          resumeFlag,
-          restartFlag,
-          noEvidenceFlag,
-          config,
-          provider,
-          story,
-          epicBranch,
-          storyBranch,
-          notifyFn,
-          bus,
-          progress,
-          progressLog,
-        }),
-    );
-  } finally {
-    restoreStartingBranch({ cwd, captured: startingBranch });
-  }
-}
-
-runAsCli(
-  import.meta.url,
-  async () => {
-    const envelope = await runStoryClose();
-    if (envelope?.exitCode === PREFLIGHT_REFUSED_EXIT_CODE) {
-      process.exit(PREFLIGHT_REFUSED_EXIT_CODE);
-    }
-    // Story #2840 — a blocked envelope (code-review-critical, etc.) carries
-    // its own exit code so the CLI fails non-zero without losing the
-    // envelope shape that callers serialise.
-    if (Number.isInteger(envelope?.exitCode) && envelope.exitCode !== 0) {
-      process.exit(envelope.exitCode);
-    }
-    return envelope;
-  },
-  {
-    source: 'story-close',
-    onError: (err) => {
-      // exitCode=2 covers two reservations: dispatchRecovery's
-      // prior-state refusal AND Story #1289's preflight refusal.
-      if (err?.exitCode === 2) process.exit(2);
-      Logger.error(`[phase=fatal] [story-close] ${err.stack || err.message}`);
-      process.exit(1);
-    },
-  },
-);