mandrel 1.93.0 → 2.0.0

package/.agents/scripts/plan-critics.js

@@ -1,199 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * plan-critics.js — deterministic dispatch gate for the conditional
- * author-step critics of the collapsed /plan flow (Epic #4474 PR6,
- * design §4).
- *
- * **Thin shim (#4496 fix 6).** The evaluation itself now lives in
- * `lib/orchestration/plan-critics-evaluate.js` and is folded into
- * `plan-persist.js` as a pre-write phase, so the headless (`--yes`) path
- * never pays a standalone CLI turn for the dispatch decision. This CLI
- * survives one release for the attended pre-gate evaluation (the verdict
- * folds into gate #2's view before the persist runs) and for any external
- * scripting; it delegates to the shared module and keeps its exact output
- * contract.
- *
- * Runs between authoring and gate #2, entirely git-local (zero GitHub
- * calls): reads the authored artifacts, evaluates the risk/size dispatch
- * conditions for the consolidation (8.3) and pre-mortem (8.5) critics via
- * the shared evaluator, and emits one JSON verdict on stdout. The workflow
- * dispatches a fresh-context sub-agent ONLY for critics with
- * `dispatch: true`; every skip decision is appended to the plan-metrics
- * ledger (`kind: "critic-skip"`, with reasons) so under-firing is
- * auditable — the persist validators remain unchanged hard gates
- * regardless of what this gate decides.
- *
- * Conditions (design §4 / §6 PR6):
- *   - Consolidation: the existing deterministic precondition
- *     (`evaluateConsolidationPrecondition`) says dispatch AND (the draft
- *     has > 5 stories OR a confirmed divergence from the Tech Spec's
- *     Delivery Slicing table). Skipped outright in the single-delivery
- *     shape (no tickets exist to consolidate).
- *   - Pre-mortem: risk verdict overall level is high, OR ticket count is
- *     at least half `maxTickets`, OR any `planning.riskHeuristics` phrase
- *     matches the plan text (case-insensitive substring over tech spec +
- *     tickets + risk summary).
- *
- * Modes:
- *   --epic <id>          Artifact paths default to the per-Epic temp tree
- *                        (`temp/epic-<id>/techspec.md`, `risk-verdict.json`,
- *                        `tickets.json`); skip records land on the
- *                        per-Epic plan-metrics ledger.
- *   explicit paths       Ideation mode: pass --tech-spec/--risk-verdict
- *                        (and --tickets when fan-out) explicitly; skip
- *                        records land on the standalone ledger stream.
- *
- * Output (stdout-pure JSON):
- *   { epicId, consolidation: { critic, dispatch, reasons },
- *     premortem: { critic, dispatch, reasons } }
- *
- * Exit codes: 0 — verdict emitted (dispatch decisions are data, not
- * failures); 1 — fatal error (unreadable/invalid artifacts, bad args).
- */
-
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
-import './lib/runtime-deps/ensure-installed.js';
-import { readFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { epicArtifactPath } from './lib/config/temp-paths.js';
-import {
-  resolveConfig,
-  validateOrchestrationConfig,
-} from './lib/config-resolver.js';
-import { routeAllOutputToStderr } from './lib/Logger.js';
-import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
-import {
-  appendCriticSkip,
-  recordPlanInvocation,
-} from './lib/orchestration/plan-metrics.js';
-
-const USAGE =
-  'Usage: plan-critics.js (--epic <EpicId> | --tech-spec <file> ' +
-  '--risk-verdict <file> [--tickets <file>]) [--pretty]';
-
-async function readOptional(filePath, { required }) {
-  try {
-    return await readFile(filePath, 'utf8');
-  } catch (err) {
-    if (!required && err?.code === 'ENOENT') return null;
-    throw new Error(`Cannot read ${filePath}: ${err.message}`);
-  }
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      epic: { type: 'string' },
-      'tech-spec': { type: 'string' },
-      'risk-verdict': { type: 'string' },
-      tickets: { type: 'string' },
-      pretty: { type: 'boolean', default: false },
-    },
-    strict: true,
-  });
-
-  let epicId = null;
-  if (values.epic !== undefined) {
-    epicId = Number.parseInt(values.epic, 10);
-    if (!Number.isInteger(epicId)) {
-      throw new Error(
-        `--epic must be a numeric issue id (got "${values.epic}").\n${USAGE}`,
-      );
-    }
-  }
-
-  // stdout is reserved for the JSON verdict — flip every Logger sink to
-  // stderr before any pipeline code runs (same guarantee plan-context.js
-  // gives its envelope).
-  routeAllOutputToStderr();
-
-  let config;
-  try {
-    config = resolveConfig();
-    validateOrchestrationConfig(config);
-  } catch (err) {
-    throw new Error(`Config schema validation failed:\n${err.message}`);
-  }
-
-  const fallback = (basename) =>
-    epicId === null ? undefined : epicArtifactPath(epicId, basename, config);
-  const techSpecPath = values['tech-spec'] ?? fallback('techspec.md');
-  const riskVerdictPath =
-    values['risk-verdict'] ?? fallback('risk-verdict.json');
-  const ticketsPath = values.tickets ?? fallback('tickets.json');
-  if (!techSpecPath || !riskVerdictPath) {
-    throw new Error(
-      `Missing artifact path(s): without --epic, explicit --tech-spec and --risk-verdict are required.\n${USAGE}`,
-    );
-  }
-
-  const verdict = await recordPlanInvocation(
-    { cli: 'plan-critics', mode: 'evaluate', epicId, config },
-    async () => {
-      const techSpecContent = await readOptional(techSpecPath, {
-        required: true,
-      });
-      const riskVerdict = loadRiskVerdict(riskVerdictPath);
-      // Tickets are shape-dependent: a single-delivery plan authors none.
-      // Required only when passed explicitly.
-      const ticketsRaw = ticketsPath
-        ? await readOptional(ticketsPath, {
-            required: values.tickets !== undefined,
-          })
-        : null;
-      let tickets = null;
-      if (ticketsRaw !== null) {
-        try {
-          tickets = JSON.parse(ticketsRaw);
-        } catch (err) {
-          throw new Error(
-            `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
-          );
-        }
-        if (!Array.isArray(tickets)) {
-          throw new Error(
-            `Tickets file "${ticketsPath}" must contain a JSON array.`,
-          );
-        }
-      }
-
-      const { consolidation, premortem } = evaluatePlanCritics({
-        techSpecContent,
-        riskVerdict,
-        tickets,
-        config,
-      });
-
-      // Skip-audit trail (#4474 PR6): every non-dispatch is a ledger
-      // record. Best-effort — a failed append never fails the gate.
-      for (const decision of [consolidation, premortem]) {
-        if (!decision.dispatch) {
-          await appendCriticSkip(
-            {
-              critic: decision.critic,
-              reasons: decision.reasons,
-              cli: 'plan-critics',
-              epicId,
-            },
-            config,
-          );
-        }
-      }
-
-      return { epicId, consolidation, premortem };
-    },
-  );
-
-  const json = values.pretty
-    ? JSON.stringify(verdict, null, 2)
-    : JSON.stringify(verdict);
-  process.stdout.write(`${json}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'plan-critics' });

package/.agents/scripts/retro-run.js

@@ -1,218 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * retro-run.js — execute the `/deliver` Phase 6 retro from a CLI.
- *
- * Phase 6 of `/deliver` posts the Epic retro by invoking the
- * in-process retro module (`lib/orchestration/retro-runner.js`'s
- * `runRetro`). That module is a library entry point — it has no CLI
- * wrapper and hard-requires both a GitHub `provider` and a lifecycle
- * `bus` (Epic #2646 Story C made `bus` a non-optional input). Without a
- * wrapper the host LLM driving Phase 6 had to hand-improvise a bus, and
- * a bare bus with no `LedgerWriter` registered means `retro.start` /
- * `retro.end` never reach the Epic-scoped `lifecycle.ndjson` ledger.
- *
- * This CLI mirrors `epic-deliver-note-intervention.js`: it resolves the
- * config and provider, constructs a lifecycle bus with a `LedgerWriter`
- * bound to the Epic's temp tree, calls `runRetro`, and prints the result
- * envelope. `--full-retro` forces the six-section retro regardless of
- * manifest cleanliness (maps to `runRetro`'s `forceFull`).
- *
- * Usage:
- *   node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
- *
- * Output: a single JSON envelope
- *   `{ epicId, posted, compact, ledgerPath, commentId? }`.
- */
-
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { tempRootFrom } from './lib/config/temp-paths.js';
-import { resolveConfig } from './lib/config-resolver.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 { runRetro } from './lib/orchestration/retro-runner.js';
-import { createProvider } from './lib/provider-factory.js';
-
-/**
- * Pure: resolve the framework/consumer repo slugs (`"<owner>/<repo>"`)
- * from a resolved config's `github` block, for threading into the retro's
- * routed-proposal composer.
- *
- * - `consumerRepo` is the project's OWN repo (`github.owner/github.repo`).
- *   It has **no** silent fallback: when `github.owner` / `github.repo` are
- *   absent the slug is `''`, which `gatherRetroSignals` treats as "disable
- *   the consumer pane loudly" rather than routing consumer-tagged friction
- *   at the framework mirror (Story #4417).
- * - `frameworkRepo` is the distinct framework mirror
- *   (`github.frameworkRepo.{owner,repo}`) when configured, otherwise `''`
- *   — `gatherRetroSignals` then falls back to its `DEFAULT_FRAMEWORK_REPO`
- *   constant (a stable, known default is legitimate for the framework).
- *
- * Exported for tests.
- *
- * @param {object} [config]
- * @returns {{ frameworkRepo: string, consumerRepo: string }}
- */
-export function resolveRetroRepos(config) {
-  const gh = config?.github ?? {};
-  const consumerRepo =
-    typeof gh.owner === 'string' &&
-    gh.owner.length > 0 &&
-    typeof gh.repo === 'string' &&
-    gh.repo.length > 0
-      ? `${gh.owner}/${gh.repo}`
-      : '';
-  const fw = gh.frameworkRepo ?? {};
-  const frameworkRepo =
-    typeof fw.owner === 'string' &&
-    fw.owner.length > 0 &&
-    typeof fw.repo === 'string' &&
-    fw.repo.length > 0
-      ? `${fw.owner}/${fw.repo}`
-      : '';
-  return { frameworkRepo, consumerRepo };
-}
-
-const HELP = `Usage: node .agents/scripts/retro-run.js --epic <epicId> [--full-retro]
-
-Composes and posts the Epic retro structured comment for Epic #<epicId>,
-wiring a lifecycle bus + LedgerWriter so the run's \`retro.start\` /
-\`retro.end\` boundaries land in temp/epic-<epicId>/lifecycle.ndjson.
-
-  --epic <epicId>   Epic to run the retro for (required, positive integer).
-  --full-retro      Force the full six-section retro regardless of
-                    manifest cleanliness (maps to runRetro forceFull).
-`;
-
-/**
- * Pure: parse argv into the normalized option bag. Exported for tests.
- *
- * @param {string[]} argv
- * @returns {{ epicId: number|null, fullRetro: boolean, help: boolean }}
- */
-export function parseRetroRunArgs(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      epic: { type: 'string' },
-      'full-retro': { type: 'boolean' },
-      help: { type: 'boolean', short: 'h' },
-    },
-    strict: false,
-  });
-  const epicId = Number.parseInt(values.epic ?? '', 10);
-  return {
-    epicId: Number.isNaN(epicId) || epicId <= 0 ? null : epicId,
-    fullRetro: values['full-retro'] === true,
-    help: values.help === true,
-  };
-}
-
-/**
- * Runner-shaped entry point. DI-friendly so tests can stub the provider,
- * the bus, the ledger writer, and `runRetro` without touching disk or the
- * GitHub API.
- *
- * Wires the lifecycle bus and registers a `LedgerWriter` bound to the
- * Epic's temp tree before invoking `runRetro`, so the run's
- * `retro.start` / `retro.end` boundaries persist to
- * `temp/epic-<epicId>/lifecycle.ndjson` rather than evaporating into a
- * bare bus.
- *
- * @param {{
- *   epicId: number,
- *   fullRetro?: boolean,
- *   injectedConfig?: object,
- *   injectedProvider?: object,
- *   busFactory?: () => object,
- *   ledgerFactory?: (deps: { epicId: number, tempRoot: string }) => { register: Function, ledgerPath?: string },
- *   runRetroFn?: typeof runRetro,
- *   logger?: { info?: Function, warn?: Function },
- * }} args
- * @returns {Promise<{
- *   epicId: number,
- *   posted: boolean,
- *   compact: boolean,
- *   ledgerPath: string|null,
- *   commentId?: number,
- * }>}
- */
-export async function runRetroCli({
-  epicId,
-  fullRetro = false,
-  injectedConfig,
-  injectedProvider,
-  busFactory,
-  ledgerFactory,
-  runRetroFn = runRetro,
-  logger,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError('runRetroCli: epicId must be a positive integer');
-  }
-
-  const config = injectedConfig ?? resolveConfig();
-  const provider = injectedProvider ?? createProvider(config);
-  const bus = busFactory ? busFactory() : createBus();
-
-  const tempRoot = tempRootFrom(config);
-  const ledger = ledgerFactory
-    ? ledgerFactory({ epicId, tempRoot })
-    : createLedgerWriter({ epicId, tempRoot });
-  ledger.register(bus);
-
-  // Story #4417 — thread the framework/consumer repo slugs resolved from
-  // `config.github` into the retro so the routed-proposal composer files
-  // consumer-tagged friction at the project's own repo (not the framework
-  // mirror), and disables the consumer pane loudly when unresolved.
-  const { frameworkRepo, consumerRepo } = resolveRetroRepos(config);
-
-  const result = await runRetroFn({
-    epicId,
-    provider,
-    bus,
-    forceFull: fullRetro,
-    frameworkRepo,
-    consumerRepo,
-    // Story #4418 — thread the resolved config so the retro auto-filer can
-    // read the `delivery.feedbackLoop.retroProposals` toggle.
-    config,
-    logger,
-  });
-
-  const envelope = {
-    epicId,
-    posted: result?.posted === true,
-    compact: result?.compact === true,
-    ledgerPath: ledger.ledgerPath ?? null,
-  };
-  if (Number.isInteger(result?.commentId)) {
-    envelope.commentId = result.commentId;
-  }
-  return envelope;
-}
-
-async function main() {
-  const args = parseRetroRunArgs(process.argv.slice(2));
-  if (args.help) {
-    Logger.info(HELP);
-    return;
-  }
-  if (args.epicId === null) {
-    Logger.error('[retro-run] ERROR: --epic <epicId> is required.');
-    Logger.error(HELP);
-    process.exit(2);
-  }
-  const out = await runRetroCli({
-    epicId: args.epicId,
-    fullRetro: args.fullRetro,
-    logger: Logger,
-  });
-  Logger.info(JSON.stringify(out, null, 2));
-}
-
-runAsCli(import.meta.url, main, { source: 'retro-run' });

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