mandrel 1.91.0 → 1.93.0

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * plan-context.js — step 1 of the collapsed `/plan` pipeline (Epic #4474,
+ * M3 PR2): the single emit-context CLI.
+ *
+ * Folds the retired 12-phase pipeline's two emit-context halves plus
+ * the three previously-no-CLI library calls
+ * (`findSimilarOpenEpics`, clarity scoring, re-plan detection) into ONE
+ * stdout-pure JSON envelope. The PR7 cutover retired the delegate CLIs —
+ * this is the only emit-context surface.
+ *
+ * Three entry forms (exactly one is required):
+ *
+ *   --epic <id>          Existing-Epic mode. Envelope carries `epic`,
+ *                        `clarity` (Epic Clarity Gate rubric), `replan`
+ *                        (already-planned signals) and `planState`.
+ *
+ *   --one-pager <path>   Ideation mode — the Epic does not exist yet
+ *                        (creation moves to the persist half). Envelope
+ *                        carries `onePager` and `duplicates[]` (cross-Epic
+ *                        dup search). No clarity score: the ideation path
+ *                        is definitionally clear.
+ *
+ *   --seed "<text>"      Headless ideation entry (#4496 fix 1) — neither
+ *                        the Epic nor the one-pager exists yet. The dup
+ *                        search runs off the raw seed text, and the
+ *                        envelope additively carries `seed`, `scopeTriage`
+ *                        (the scope-triage rubric applied CLI-side — fix 6)
+ *                        and `onePagerSpec`, so the one-pager sections are
+ *                        authored in the same batched write as the spec
+ *                        artifacts.
+ *
+ * Flags:
+ *   --pretty         Pretty-print the JSON envelope.
+ *   --full-context   Bypass the planning-context budget (unbounded body).
+ *
+ * stdout is reserved for the JSON envelope (Story #2278 discipline):
+ * `routeAllOutputToStderr()` runs before any pipeline code so a captured
+ * file is unconditionally parseable by `JSON.parse`.
+ *
+ * Exit codes:
+ *   0 — envelope emitted.
+ *   1 — fatal error (see stderr).
+ */
+
+// 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 { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  resolveConfig,
+  validateOrchestrationConfig,
+} from './lib/config-resolver.js';
+import { routeAllOutputToStderr } from './lib/Logger.js';
+import { buildPlanContext } from './lib/orchestration/plan-context.js';
+import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
+import { createProvider } from './lib/provider-factory.js';
+
+/**
+ * Build the envelope and write it to `stdout` as a single JSON line
+ * (or pretty-printed with --pretty). Exported for tests: the stdout-purity
+ * test injects a fake provider and a capture stream and asserts the
+ * captured output is exactly one `JSON.parse`-able payload.
+ *
+ * @param {{
+ *   mode: 'epic'|'one-pager'|'seed',
+ *   epicId?: number,
+ *   onePagerPath?: string,
+ *   onePagerContent?: string,
+ *   seedText?: string,
+ *   provider: object,
+ *   config: object,
+ *   settings: object,
+ *   fullContext?: boolean,
+ *   pretty?: boolean,
+ *   cwd?: string,
+ *   stdout?: { write: (chunk: string) => void },
+ * }} args
+ * @returns {Promise<object>} the emitted envelope.
+ */
+export async function emitPlanContext({
+  mode,
+  epicId,
+  onePagerPath,
+  onePagerContent,
+  seedText,
+  provider,
+  config,
+  settings,
+  fullContext = false,
+  pretty = false,
+  cwd,
+  stdout = process.stdout,
+}) {
+  const envelope = await buildPlanContext({
+    mode,
+    epicId,
+    onePagerPath,
+    onePagerContent,
+    seedText,
+    provider,
+    config,
+    settings,
+    fullContext,
+    cwd,
+  });
+  const json = pretty
+    ? JSON.stringify(envelope, null, 2)
+    : JSON.stringify(envelope);
+  stdout.write(`${json}\n`);
+  return envelope;
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      epic: { type: 'string' },
+      'one-pager': { type: 'string' },
+      seed: { type: 'string' },
+      pretty: { type: 'boolean', default: false },
+      'full-context': { type: 'boolean', default: false },
+    },
+    strict: true,
+  });
+
+  const hasEpic = typeof values.epic === 'string' && values.epic.length > 0;
+  const hasOnePager =
+    typeof values['one-pager'] === 'string' && values['one-pager'].length > 0;
+  const hasSeed = typeof values.seed === 'string' && values.seed.length > 0;
+  const entryForms = [hasEpic, hasOnePager, hasSeed].filter(Boolean).length;
+  if (entryForms !== 1) {
+    throw new Error(
+      'Pass exactly one of --epic <id>, --one-pager <path> or --seed "<text>". ' +
+        '(--epic: existing-Epic mode; --one-pager: ideation mode; ' +
+        '--seed: headless ideation entry.)',
+    );
+  }
+  const mode = hasEpic ? 'epic' : hasOnePager ? 'one-pager' : 'seed';
+
+  let epicId;
+  if (hasEpic) {
+    epicId = Number.parseInt(values.epic, 10);
+    if (!Number.isInteger(epicId)) {
+      throw new Error(
+        `--epic must be a numeric issue id (got "${values.epic}").`,
+      );
+    }
+  }
+
+  // stdout is reserved for the JSON envelope: flip every Logger sink that
+  // could land on stdout to stderr BEFORE any pipeline code runs
+  // (Story #2278 — the same stdout-purity guarantee the retired pipeline
+  // gives; this CLI is emit-only so the flip is unconditional).
+  routeAllOutputToStderr();
+
+  let config;
+  let settings;
+  try {
+    config = resolveConfig();
+    // `settings` retains the legacy bag shape `buildAuthoringContext` and
+    // friends consume: `{ baseBranch, paths, planning, docsContextFiles }`.
+    settings = {
+      baseBranch: config.project?.baseBranch,
+      paths: config.project?.paths,
+      planning: config.planning,
+      docsContextFiles: config.project?.docsContextFiles,
+    };
+    validateOrchestrationConfig(config);
+  } catch (err) {
+    throw new Error(`Config schema validation failed:\n${err.message}`);
+  }
+  const provider = createProvider(config);
+
+  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode so the folded
+  // emit surface is measured against the 12-phase baseline. One-pager and
+  // seed modes have no Epic yet, so the record routes to the standalone
+  // stream (epicId null) exactly like `story-plan.js`.
+  await recordPlanInvocation(
+    {
+      cli: 'plan-context',
+      mode,
+      epicId: hasEpic ? epicId : null,
+      config,
+    },
+    () =>
+      emitPlanContext({
+        mode,
+        epicId,
+        onePagerPath: hasOnePager ? values['one-pager'] : undefined,
+        seedText: hasSeed ? values.seed : undefined,
+        provider,
+        config,
+        settings,
+        fullContext: values['full-context'],
+        pretty: values.pretty,
+      }),
+  );
+}
+
+runAsCli(import.meta.url, main, { source: 'plan-context' });

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

@@ -0,0 +1,199 @@
+#!/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' });