mandrel 1.90.0 → 1.92.0

package/.agents/scripts/lib/templates/spec-author-prompts.js

@@ -0,0 +1,74 @@
+/**
+ * spec-author-prompts.js — single source of the Tech Spec and Acceptance
+ * Spec authoring system prompts (Epic #4474, M3 PR2).
+ *
+ * **Single source of the prompt bodies.** These two prompts were lifted
+ * VERBATIM from the "(authoritative)" fenced blocks in
+ * `.agents/skills/core/epic-plan-spec-author/SKILL.md` (§ "Tech Spec system
+ * prompt" and § "Acceptance Spec system prompt") as the M3 side of the
+ * M3/M8 boundary handshake: the `plan-context.js` envelope renders them
+ * into `systemPrompts.spec` / `systemPrompts.acceptance` so the envelope
+ * is authoritative from day one, and M8 (#4479) then deletes the
+ * skill-side copies. This mirrors the Story #4162 pattern established by
+ * `decomposer-prompts.js` for the decompose prompt: one rendered carrier,
+ * no second verbatim copy to drift.
+ */
+
+/**
+ * The Tech Spec authoring system prompt (verbatim from the
+ * `epic-plan-spec-author` SKILL's authoritative block).
+ *
+ * @returns {string}
+ */
+export function renderTechSpecSystemPrompt() {
+  return TECH_SPEC_SYSTEM_PROMPT;
+}
+
+/**
+ * The Acceptance Spec authoring system prompt (verbatim from the
+ * `epic-plan-spec-author` SKILL's authoritative block).
+ *
+ * @returns {string}
+ */
+export function renderAcceptanceSpecSystemPrompt() {
+  return ACCEPTANCE_SPEC_SYSTEM_PROMPT;
+}
+
+const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
+Your job is to convert an Epic into a Technical Specification for implementation.
+
+The Tech Spec should outline:
+1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
+2. Architecture & Design
+3. Data Models (if any)
+4. API Changes (if any)
+5. Core Components
+6. Security & Privacy Considerations
+
+CRITICAL REQUIREMENTS:
+- Respond ONLY with valid Markdown.
+- Do not use top-level <h1> (# ) tags. Open the document with the \`## Delivery Slicing\` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
+- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional \`## Technical Overview\` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
+- Format architectural decisions clearly with bullet points.
+- Author the \`## Delivery Slicing\` section as a markdown table with columns \`Slice | What ships | Independent?\`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.`;
+
+const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
+Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+
+The Acceptance Spec should outline:
+1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
+2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
+3. Disposition — tag each row with one of: new | updated | unchanged
+
+The Epic body's \`## Acceptance Criteria\` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
+
+CRITICAL REQUIREMENTS:
+- Respond ONLY with valid Markdown.
+- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
+- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
+- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
+- Each Outcome MUST be a **terse restatement keyed to a specific Epic \`## Acceptance Criteria\` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
+- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
+- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
+- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.
+- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy \`baseline-refresh\` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (\`ticket-validator.js\` → \`validateAcceptanceSubjectPrefix\`) will reject the decompose with \`code: 'forbidden-subject-prefix'\`. Use a Conventional-Commits subject (e.g. \`chore(baselines): refresh ...\`) and a body trailer (e.g. \`baseline-refresh: true\` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.`;

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

@@ -0,0 +1,186 @@
+#!/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.
+ *
+ * Two 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.
+ *
+ * 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',
+ *   epicId?: number,
+ *   onePagerPath?: string,
+ *   onePagerContent?: 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,
+  provider,
+  config,
+  settings,
+  fullContext = false,
+  pretty = false,
+  cwd,
+  stdout = process.stdout,
+}) {
+  const envelope = await buildPlanContext({
+    mode,
+    epicId,
+    onePagerPath,
+    onePagerContent,
+    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' },
+      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;
+  if (hasEpic === hasOnePager) {
+    throw new Error(
+      'Pass exactly one of --epic <id> or --one-pager <path>. ' +
+        '(--epic: existing-Epic mode; --one-pager: ideation mode.)',
+    );
+  }
+
+  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 mode
+  // has no Epic yet, so the record routes to the standalone stream
+  // (epicId null) exactly like `story-plan.js`.
+  await recordPlanInvocation(
+    {
+      cli: 'plan-context',
+      mode: hasEpic ? 'epic' : 'one-pager',
+      epicId: hasEpic ? epicId : null,
+      config,
+    },
+    () =>
+      emitPlanContext({
+        mode: hasEpic ? 'epic' : 'one-pager',
+        epicId,
+        onePagerPath: hasOnePager ? values['one-pager'] : 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,227 @@
+#!/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).
+ *
+ * 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
+ * `lib/orchestration/plan-critic-conditions.js`, 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 {
+  getLimits,
+  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 {
+  evaluateConsolidationDispatch,
+  evaluatePremortemDispatch,
+} from './lib/orchestration/plan-critic-conditions.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]';
+
+/**
+ * Resolve the planning risk heuristics list from the canonical config
+ * block (same resolution `plan-context.js` and the decompose context use).
+ *
+ * @param {object} config
+ * @returns {string[]}
+ */
+function resolveRiskHeuristics(config = {}) {
+  if (Array.isArray(config.planning?.riskHeuristics)) {
+    return config.planning.riskHeuristics;
+  }
+  return config.agentSettings?.planning?.riskHeuristics || [];
+}
+
+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 =
+        tickets === null
+          ? {
+              critic: 'consolidation',
+              dispatch: false,
+              reasons: [
+                'single-delivery shape — no draft tickets exist to consolidate.',
+              ],
+            }
+          : evaluateConsolidationDispatch({
+              draftStories: tickets,
+              specText: techSpecContent,
+            });
+
+      const premortem = evaluatePremortemDispatch({
+        riskVerdict,
+        ticketCount: tickets?.length ?? 0,
+        maxTickets: getLimits(config).maxTickets,
+        riskHeuristics: resolveRiskHeuristics(config),
+        planText: [
+          techSpecContent,
+          ticketsRaw ?? '',
+          riskVerdict.summary ?? '',
+        ].join('\n'),
+      });
+
+      // 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' });