mandrel 1.57.0

package/.agents/scripts/hierarchy-gate.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * .agents/scripts/hierarchy-gate.js — Hierarchy Completeness Gate
+ *
+ * Walks the Epic's full sub-issue graph (Features → Stories) and verifies
+ * every descendant is closed. Where the wave gate asks "did the sprint
+ * complete what it committed to?" (manifest view), this gate asks "is
+ * anything still open under this Epic?" (live GitHub graph view).
+ *
+ * The two gates catch different problems and are intentionally distinct:
+ *   - The wave gate misses descendants that exist on GitHub but were never
+ *     in the manifest — context::prd / context::tech-spec tickets, mid-sprint
+ *     additions, or recuts that bypassed the dispatcher.
+ *   - The hierarchy gate misses parked follow-ons that live as separate
+ *     top-level Stories outside the Epic's sub-issue graph.
+ *
+ * Per ticket type the rule is:
+ *   - Features  — must be closed.
+ *   - Stories   — must be closed.
+ *   - Auxiliary (context::prd, context::tech-spec) — ignored.
+ *     These are closed by the operator after the Epic PR merges, so
+ *     requiring them closed here would block every Epic.
+ *
+ * **3-tier hierarchy (Epic #3078).** Mandrel ships only Epic / Feature /
+ * Story tickets. `getSubTickets(<storyId>)` returns `[]`; the walk
+ * terminates at the Story. Acceptance criteria live inline on the
+ * Story body.
+ *
+ * Usage:
+ *   node .agents/scripts/hierarchy-gate.js --epic <EPIC_ID>
+ *
+ * Exit codes:
+ *   0 — every descendant ticket is closed.
+ *   1 — one or more descendants are still open.
+ *   2 — configuration or provider error.
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { CONTEXT_LABELS, TYPE_LABELS } from './lib/label-constants.js';
+import { createProvider } from './lib/provider-factory.js';
+
+function classify(ticket) {
+  const labels = ticket.labels ?? [];
+  if (labels.includes(TYPE_LABELS.STORY)) return 'story';
+  if (labels.includes(TYPE_LABELS.FEATURE)) return 'feature';
+  if (
+    labels.includes(CONTEXT_LABELS.PRD) ||
+    labels.includes(CONTEXT_LABELS.TECH_SPEC)
+  ) {
+    return 'auxiliary';
+  }
+  return 'other';
+}
+
+function ticketIsComplete(ticket) {
+  if (ticket.state !== 'closed') {
+    return { ok: false, reason: 'open' };
+  }
+  return { ok: true };
+}
+
+/**
+ * BFS the sub-issue graph from the Epic. Returns one entry per descendant
+ * ticket with full metadata — the caller checks completeness and formats
+ * the failure list.
+ */
+async function collectDescendants(provider, epicId) {
+  const visited = new Set([epicId]);
+  const queue = [epicId];
+  const out = [];
+  while (queue.length > 0) {
+    const parentId = queue.shift();
+    let children;
+    try {
+      children = await provider.getSubTickets(parentId);
+    } catch (err) {
+      throw new Error(`getSubTickets(#${parentId}) failed: ${err.message}`);
+    }
+    for (const child of children) {
+      if (visited.has(child.id)) continue;
+      visited.add(child.id);
+      out.push(child);
+      queue.push(child.id);
+    }
+  }
+  return out;
+}
+
+export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
+  if (!epicId || Number.isNaN(epicId) || epicId <= 0) {
+    throw new Error('Usage: node hierarchy-gate.js --epic <EPIC_ID>');
+  }
+
+  const config = resolveConfig();
+  const provider = injectedProvider || createProvider(config);
+
+  let descendants;
+  try {
+    descendants = await collectDescendants(provider, epicId);
+  } catch (err) {
+    Logger.error(`[hierarchy-gate] ${err.message}`);
+    process.exit(2);
+  }
+
+  const failures = { feature: [], story: [], other: [] };
+  let auxiliaryDeferred = 0;
+  for (const ticket of descendants) {
+    const kind = classify(ticket);
+    if (kind === 'auxiliary') {
+      auxiliaryDeferred += 1;
+      continue;
+    }
+    const verdict = ticketIsComplete(ticket);
+    if (!verdict.ok) {
+      failures[kind].push({
+        id: ticket.id,
+        title: ticket.title,
+        reason: verdict.reason,
+      });
+    }
+  }
+
+  const totalOpen =
+    failures.feature.length + failures.story.length + failures.other.length;
+
+  if (totalOpen > 0) {
+    Logger.error(
+      `[hierarchy-gate] ❌ Hierarchy-completeness gate FAILED for Epic #${epicId}: ${totalOpen} descendant(s) incomplete.`,
+    );
+    const sections = [
+      ['feature', 'Features'],
+      ['story', 'Stories'],
+      ['other', 'Untyped descendants'],
+    ];
+    for (const [key, label] of sections) {
+      if (failures[key].length === 0) continue;
+      Logger.error(`\n  ${label}:`);
+      for (const item of failures[key]) {
+        Logger.error(`    - #${item.id} (${item.reason}) — ${item.title}`);
+      }
+    }
+    Logger.error('\nClose the open descendants and re-run `/epic-deliver`.');
+    process.exit(1);
+  }
+
+  const auxNote =
+    auxiliaryDeferred > 0
+      ? ` (${auxiliaryDeferred} auxiliary ticket${auxiliaryDeferred === 1 ? '' : 's'} deferred to Phase 7)`
+      : '';
+  Logger.info(
+    `[hierarchy-gate] ✅ All ${descendants.length - auxiliaryDeferred} planned descendant(s) under Epic #${epicId} are closed${auxNote}.`,
+  );
+  return {
+    success: true,
+    total: descendants.length,
+    checked: descendants.length - auxiliaryDeferred,
+    auxiliaryDeferred,
+  };
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      epic: { type: 'string' },
+    },
+    strict: false,
+  });
+  const epicId = Number.parseInt(values.epic ?? '', 10);
+  await runHierarchyGate({ epicId });
+}
+
+runAsCli(import.meta.url, main, { source: 'hierarchy-gate' });

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * hydrate-context.js — CLI wrapper for context hydration.
+ *
+ * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
+ *
+ * Delegates to `hydrateContext` from `lib/orchestration/context-hydration-engine.js`
+ * and emits the `{ prompt }` JSON envelope on stdout. Pass `--emit prompt`
+ * to write the raw hydrated prompt (no JSON wrapper) instead — this is the
+ * sole supported hydration entry point.
+ *
+ * Usage:
+ *   node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
+ *   node .agents/scripts/hydrate-context.js --ticket <id> --emit prompt
+ *
+ * If `--epic` is omitted, the epic id is parsed from the ticket body
+ * (`Epic: #N`). Persona / skills are derived from the ticket's labels.
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { getEpicBranch, getStoryBranch } from './lib/git-utils.js';
+import { envelopeToPrompt } from './lib/orchestration/context-envelope.js';
+import {
+  hydrateContext,
+  parseHierarchy,
+} from './lib/orchestration/context-hydration-engine.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `Usage: node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
+
+Flags:
+  --ticket   GitHub issue number to hydrate (required).
+  --epic     Epic id (optional; parsed from the ticket body when omitted).
+  --help     Show this message.
+
+Output: a single JSON object {"prompt": "..."} on stdout by default.
+  --emit envelope  Write {"envelope": {...}} instead (debug / inspection).
+  --emit prompt    Write the raw hydrated prompt (no JSON wrapper) to stdout.
+`;
+
+/**
+ * Build the normalized task object the hydration engine expects from a
+ * full ticket fetched via the provider. Persona and skills come from the
+ * `persona::*` and `skill::*` labels.
+ */
+export function ticketToTask(ticket) {
+  const labels = ticket.labels ?? [];
+  const persona = labels
+    .find((l) => l.startsWith('persona::'))
+    ?.replace('persona::', '');
+  const skills = labels
+    .filter((l) => l.startsWith('skill::'))
+    .map((l) => l.replace('skill::', ''));
+
+  return {
+    id: ticket.id ?? ticket.number,
+    title: ticket.title,
+    body: ticket.body ?? '',
+    labels,
+    persona,
+    skills,
+  };
+}
+
+/**
+ * Core: build the hydrated prompt and return the MCP-compatible envelope.
+ * Exported so tests can pin parity against direct SDK invocation without a
+ * subprocess.
+ */
+export async function runHydrateContext({ ticketId, epicId, provider }) {
+  const ticket = await provider.getTicket(ticketId);
+  const hierarchy = parseHierarchy(ticket.body ?? '');
+
+  const resolvedEpicId = epicId ?? hierarchy.epic ?? null;
+
+  const storyId =
+    hierarchy.story ??
+    hierarchy.parent ??
+    ticket.id ??
+    ticket.number ??
+    ticketId;
+
+  if (!resolvedEpicId) {
+    throw new Error(
+      `[hydrate-context] Could not resolve epic id for ticket #${ticketId}; ` +
+        `pass --epic explicitly or ensure the body contains "Epic: #N".`,
+    );
+  }
+
+  const epicBranch = getEpicBranch(resolvedEpicId);
+  const taskBranch = getStoryBranch(resolvedEpicId, storyId);
+
+  const task = ticketToTask({ ...ticket, id: ticketId });
+  const envelope = await hydrateContext(
+    task,
+    provider,
+    epicBranch,
+    taskBranch,
+    resolvedEpicId,
+  );
+  const prompt = envelopeToPrompt(envelope);
+  return { prompt, envelope };
+}
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      ticket: { type: 'string' },
+      epic: { type: 'string' },
+      emit: { type: 'string' },
+      help: { type: 'boolean' },
+    },
+    strict: false,
+  });
+  return values;
+}
+
+/**
+ * Pure: classify parsed CLI values into a runnable intent. Pulling this
+ * decision out of `main` keeps the side-effecting wrapper at CC ≤ 2 and
+ * lets the unit tests exercise every branch directly.
+ *
+ * Shapes:
+ *   - { kind: 'help' }
+ *   - { kind: 'usage-error', message }
+ *   - { kind: 'run', ticketId, epicId | undefined, emit?: 'envelope' | 'prompt' }
+ */
+export function classifyCliInvocation(values) {
+  if (values?.help) return { kind: 'help' };
+  const ticketId = Number.parseInt(values?.ticket ?? '', 10);
+  if (!Number.isFinite(ticketId) || ticketId <= 0) {
+    return {
+      kind: 'usage-error',
+      message: `[hydrate-context] --ticket <id> is required.\n${HELP}`,
+    };
+  }
+  const epicId = values?.epic ? Number.parseInt(values.epic, 10) : undefined;
+  const intent = { kind: 'run', ticketId, epicId };
+  if (values?.emit === 'envelope' || values?.emit === 'prompt') {
+    intent.emit = values.emit;
+  }
+  return intent;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const intent = classifyCliInvocation(parseArgv(argv));
+  if (intent.kind === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (intent.kind === 'usage-error') {
+    process.stderr.write(intent.message);
+    process.exit(2);
+  }
+
+  const config = resolveConfig();
+  const provider = createProvider(config);
+  const result = await runHydrateContext({
+    ticketId: intent.ticketId,
+    epicId: intent.epicId,
+    provider,
+  });
+  if (intent.emit === 'prompt') {
+    process.stdout.write(result.prompt);
+    return;
+  }
+  const stdoutPayload =
+    intent.emit === 'envelope'
+      ? { envelope: result.envelope }
+      : { prompt: result.prompt };
+  process.stdout.write(`${JSON.stringify(stdoutPayload)}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'hydrate-context' });

package/.agents/scripts/install-matrix-assert.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// .agents/scripts/install-matrix-assert.js
+/**
+ * Golden-path install assertions for the install matrix (Story #3472).
+ *
+ * The `.github/workflows/install-matrix.yml` workflow exercises the published
+ * package contract — install `mandrel`, run `mandrel sync`, run
+ * `mandrel doctor` — across {npm, pnpm, yarn} x {ubuntu-latest,
+ * windows-latest}. Rather than spread the per-leg invariants across
+ * PowerShell-vs-bash shell snippets (which diverge on quoting, `$?`, and
+ * separators per `.agents/rules/shell-conventions.md`), every leg shells out
+ * to this single Node script so the checks run identically on every OS.
+ *
+ * It asserts three invariants against a consumer project directory:
+ *
+ *   1. `materialized` — `<consumer>/.agents/instructions.md` exists, i.e. the
+ *      `.agents/` payload was materialized into the consumer working copy by
+ *      `mandrel sync` (or the best-effort postinstall hook).
+ *
+ *   2. `manifest-clean` — the consumer's `package.json` was NOT mutated with
+ *      the framework's internal runtime dependencies. Installing
+ *      `mandrel` is expected to add exactly that one package to the
+ *      consumer manifest (npm/pnpm/yarn all record the installed dep); what
+ *      MUST NOT happen is the framework's own runtime deps (ajv, js-yaml,
+ *      minimatch, …) leaking into the consumer's declared dependencies. Those
+ *      packages are declared inside `.agents/runtime-deps.json` and the
+ *      framework scripts free-ride on the consumer's node_modules — they are
+ *      never written into the consumer's package.json.
+ *
+ *   3. `doctor-ready` — `mandrel doctor` exited 0 and printed the
+ *      "✅  Ready" verdict line. This is asserted by the workflow step that
+ *      runs doctor and pipes its output here via `--doctor-output <file>`.
+ *
+ * Each invariant can be run independently (`--check <name>`) or all at once
+ * (default). The script exits 0 when every requested check passes and 1 (with
+ * an actionable message on stderr) when any fails — so a CI step that invokes
+ * it fails the leg loudly rather than silently.
+ *
+ * Usage:
+ *   node .agents/scripts/install-matrix-assert.js \
+ *     --consumer <dir> [--check materialized|manifest-clean|doctor-ready] \
+ *     [--doctor-output <file>] [--package-name <name>]
+ *
+ * Security: pure local filesystem reads. No network, no shell, no secrets
+ * logged. The doctor-output file is read as plain text and only scanned for
+ * the verdict marker.
+ *
+ * Injectable seams (used by tests):
+ *   - `fs`     — replaces the node:fs surface
+ *   - `write`  — replaces process.stdout.write
+ *   - `writeErr` — replaces process.stderr.write
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * The framework's internal runtime dependencies. These are declared in
+ * `.agents/runtime-deps.json` and provided by the consumer's install of
+ * `mandrel` (npm hoists them into node_modules), but they MUST NOT
+ * appear in the consumer's *declared* package.json dependencies. Kept in sync
+ * with `.agents/runtime-deps.json` `dependencies` keys.
+ */
+const FRAMEWORK_RUNTIME_DEPS = [
+  'ajv',
+  'ajv-formats',
+  'js-yaml',
+  'minimatch',
+  'picomatch',
+  'string-argv',
+  'typhonjs-escomplex',
+];
+
+/** The verdict marker `mandrel doctor` prints when every check passes. */
+const DOCTOR_READY_MARKER = '✅  Ready';
+
+const ALL_CHECKS = ['materialized', 'manifest-clean', 'doctor-ready'];
+
+/**
+ * Parse `--flag value` / `--flag=value` argv into an options object. Repeated
+ * `--check` flags accumulate into an array.
+ *
+ * @param {string[]} argv
+ * @returns {{ consumer?: string, checks: string[], doctorOutput?: string, packageName: string }}
+ */
+export function parseArgs(argv) {
+  const opts = { checks: [], packageName: 'mandrel' };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    const eq = token.indexOf('=');
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
+    const next = () => inlineValue ?? argv[++i];
+    switch (flag) {
+      case '--consumer':
+        opts.consumer = next();
+        break;
+      case '--check':
+        opts.checks.push(next());
+        break;
+      case '--doctor-output':
+        opts.doctorOutput = next();
+        break;
+      case '--package-name':
+        opts.packageName = next();
+        break;
+      default:
+        // Ignore unknown flags so the script is forward-compatible with
+        // additional workflow plumbing.
+        break;
+    }
+  }
+  if (opts.checks.length === 0) opts.checks = [...ALL_CHECKS];
+  return opts;
+}
+
+/**
+ * Assert the `.agents/` payload was materialized into the consumer project.
+ *
+ * @param {{ consumer: string, fs?: typeof nodeFs }} opts
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function checkMaterialized({ consumer, fs = nodeFs }) {
+  const target = path.join(consumer, '.agents', 'instructions.md');
+  if (fs.existsSync(target)) {
+    return { ok: true, detail: `.agents/ materialized (${target})` };
+  }
+  return {
+    ok: false,
+    detail: `./.agents/instructions.md not found at ${target} — \`mandrel sync\` did not materialize the payload.`,
+  };
+}
+
+/**
+ * Assert the consumer's package.json was not mutated with framework runtime
+ * deps. Installing `mandrel` itself is expected; the framework's
+ * internal runtime packages are not.
+ *
+ * @param {{ consumer: string, packageName: string, fs?: typeof nodeFs }} opts
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function checkManifestClean({ consumer, packageName, fs = nodeFs }) {
+  const manifestPath = path.join(consumer, 'package.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `could not read consumer package.json at ${manifestPath}: ${err.message}`,
+    };
+  }
+
+  const declared = {
+    ...(manifest.dependencies ?? {}),
+    ...(manifest.devDependencies ?? {}),
+    ...(manifest.optionalDependencies ?? {}),
+    ...(manifest.peerDependencies ?? {}),
+  };
+
+  const leaked = FRAMEWORK_RUNTIME_DEPS.filter((dep) => dep in declared);
+  if (leaked.length > 0) {
+    return {
+      ok: false,
+      detail: `consumer package.json was mutated with framework runtime deps: ${leaked.join(', ')}`,
+    };
+  }
+
+  // The framework package itself MAY be present (that is the intended install)
+  // but its absence is also fine — the workflow installs it separately and the
+  // assertion only guards against *unexpected* framework-internal deps.
+  const hasFrameworkPkg = packageName in declared;
+  return {
+    ok: true,
+    detail: hasFrameworkPkg
+      ? `manifest clean: only '${packageName}' added, no framework runtime deps leaked`
+      : 'manifest clean: no framework runtime deps leaked',
+  };
+}
+
+/**
+ * Assert `mandrel doctor` printed the ready verdict. The workflow captures
+ * doctor's stdout to a file and passes it via `--doctor-output`.
+ *
+ * @param {{ doctorOutput?: string, fs?: typeof nodeFs }} opts
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function checkDoctorReady({ doctorOutput, fs = nodeFs }) {
+  if (!doctorOutput) {
+    return {
+      ok: false,
+      detail:
+        '--doctor-output <file> is required for the doctor-ready check (capture `mandrel doctor` stdout to it first).',
+    };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(doctorOutput, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `could not read doctor output at ${doctorOutput}: ${err.message}`,
+    };
+  }
+  if (text.includes(DOCTOR_READY_MARKER)) {
+    return { ok: true, detail: 'mandrel doctor reported a ready verdict' };
+  }
+  return {
+    ok: false,
+    detail:
+      'mandrel doctor did not report a ready verdict (no "✅  Ready" line in captured output).',
+  };
+}
+
+/**
+ * Run the requested checks and report a per-check result. Exits non-zero when
+ * any requested check fails.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   fs?: typeof nodeFs,
+ *   write?: (s: string) => void,
+ *   writeErr?: (s: string) => void,
+ * }} [opts]
+ * @returns {{ ok: boolean, results: Array<{ name: string, ok: boolean, detail: string }> }}
+ */
+export function runAssertions({
+  argv = process.argv.slice(2),
+  fs = nodeFs,
+  write = (s) => process.stdout.write(s),
+  writeErr = (s) => process.stderr.write(s),
+} = {}) {
+  const opts = parseArgs(argv);
+
+  if (!opts.consumer) {
+    writeErr('install-matrix-assert: --consumer <dir> is required.\n');
+    return { ok: false, results: [] };
+  }
+
+  const results = [];
+  for (const name of opts.checks) {
+    let result;
+    switch (name) {
+      case 'materialized':
+        result = checkMaterialized({ consumer: opts.consumer, fs });
+        break;
+      case 'manifest-clean':
+        result = checkManifestClean({
+          consumer: opts.consumer,
+          packageName: opts.packageName,
+          fs,
+        });
+        break;
+      case 'doctor-ready':
+        result = checkDoctorReady({ doctorOutput: opts.doctorOutput, fs });
+        break;
+      default:
+        result = { ok: false, detail: `unknown check '${name}'` };
+        break;
+    }
+    results.push({ name, ...result });
+  }
+
+  for (const r of results) {
+    const icon = r.ok ? 'PASS' : 'FAIL';
+    const sink = r.ok ? write : writeErr;
+    sink(`[${icon}] ${r.name}: ${r.detail}\n`);
+  }
+
+  const ok = results.every((r) => r.ok);
+  return { ok, results };
+}
+
+// cli-opt-out: synchronous CLI whose bespoke main-guard forwards an explicit
+// 0/1 exit code from runAssertions(); runAsCli's async-main signature does not
+// preserve that result code (same rationale as coverage-capture.js).
+// Run when invoked directly (not when imported by tests).
+const invokedDirectly = process.argv[1]?.endsWith('install-matrix-assert.js');
+if (invokedDirectly) {
+  const { ok } = runAssertions();
+  process.exit(ok ? 0 : 1);
+}