mandrel 1.57.0

package/.agents/scripts/resync-status-column.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * resync-status-column.js — re-assert the GitHub Projects v2 Status
+ * column for a ticket after auto-merge has fired (Story #2845).
+ *
+ * The `/single-story-deliver` and `/story-deliver` workflow docs call
+ * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
+ * wins the race against the GitHub built-in `Pull request merged`
+ * workflow, which would otherwise overwrite Status to whatever value
+ * the bot's rule prescribes (typically `In Progress`) ~minutes after
+ * the merge lands.
+ *
+ * Story #2876 — the helper polls the live Status after the initial
+ * mutation and re-fires on drift. The one-shot mutation routinely
+ * lost the race (reproduced on Story #2871 / PR #2872); the bounded
+ * poll loop hardens the defense-in-depth so consumers who haven't
+ * disabled the conflicting bot workflows still get a deterministic
+ * outcome.
+ *
+ * Idempotent: re-running on a ticket whose Status already matches the
+ * derived target returns the same `synced` envelope and issues the
+ * same single GraphQL mutation.
+ *
+ * Usage:
+ *   node .agents/scripts/resync-status-column.js --ticket <id>
+ *   node .agents/scripts/resync-status-column.js --story <id>   # alias
+ *
+ * Exit codes:
+ *   0 — sync succeeded, drifted-but-exhausted, OR was skipped for a
+ *       documented reason (`no-project`, `no-meta`, `not-on-project`).
+ *   1 — provider error, GraphQL error, or invalid input.
+ *   2 — usage error (missing required args).
+ *
+ * The CLI prints a single-line JSON envelope to stdout:
+ *   `{ ticketId, status, column?, reason?, attempts? }`
+ */
+
+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 { reassertStatusColumn } from './lib/orchestration/reassert-status-column.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `Usage: node .agents/scripts/resync-status-column.js \\
+  --ticket <id> | --story <id> \\
+  [--provider github] [--poll-attempts <n>] [--poll-delay-ms <ms>]
+
+Re-asserts the Projects v2 Status column for the ticket based on its
+current agent::* label set. Intended to run after auto-merge fires, to
+overwrite any post-merge bot-driven Status flip.
+
+Story #2876 — the helper polls the live Status after the initial
+mutation and re-fires on drift (defense against asynchronous bot
+overwrites that land after our initial write). Default budget is
+~15 s (4 attempts × 5 s delay).
+
+Flags:
+  --ticket           GitHub issue number (required, or pass --story).
+  --story            Alias for --ticket.
+  --provider         Provider name (default: value in .agentrc.json).
+  --poll-attempts    Total mutation attempts including the initial sync
+                     (default 4). Pass 1 to disable the poll loop.
+  --poll-delay-ms    Delay between drift checks in ms (default 5000).
+  --help             Show this message.
+`;
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      ticket: { type: 'string' },
+      story: { type: 'string' },
+      provider: { type: 'string' },
+      'poll-attempts': { type: 'string' },
+      'poll-delay-ms': { type: 'string' },
+      help: { type: 'boolean' },
+    },
+    strict: false,
+  });
+  return values;
+}
+
+/**
+ * Pure input-validation extracted so it can be tested without spawning
+ * a subprocess. Returns `{ ticketId, pollAttempts, pollDelayMs, errors }`
+ * — `errors` is empty on success.
+ *
+ * @param {Record<string, unknown>} values
+ */
+export function validateRequiredArgs(values) {
+  const raw = values.ticket ?? values.story ?? '';
+  const ticketId = Number.parseInt(raw, 10);
+  const errors = [];
+  if (!Number.isFinite(ticketId) || ticketId <= 0) {
+    errors.push('--ticket <id> (or --story <id>) is required.');
+  }
+
+  let pollAttempts;
+  if (values['poll-attempts'] !== undefined) {
+    pollAttempts = Number.parseInt(values['poll-attempts'], 10);
+    if (!Number.isInteger(pollAttempts) || pollAttempts <= 0) {
+      errors.push('--poll-attempts must be a positive integer.');
+    }
+  }
+
+  let pollDelayMs;
+  if (values['poll-delay-ms'] !== undefined) {
+    pollDelayMs = Number.parseInt(values['poll-delay-ms'], 10);
+    if (!Number.isInteger(pollDelayMs) || pollDelayMs < 0) {
+      errors.push('--poll-delay-ms must be a non-negative integer.');
+    }
+  }
+
+  return { ticketId, pollAttempts, pollDelayMs, errors };
+}
+
+export function resolveEffectiveConfig(config, providerName) {
+  return providerName ? { ...config, provider: providerName } : config;
+}
+
+export function buildReassertOptions({
+  provider,
+  ticketId,
+  logger,
+  pollAttempts,
+  pollDelayMs,
+}) {
+  const opts = {
+    provider,
+    ticketId,
+    logger,
+  };
+  if (pollAttempts !== undefined) opts.pollAttempts = pollAttempts;
+  if (pollDelayMs !== undefined) opts.pollDelayMs = pollDelayMs;
+  return opts;
+}
+
+export function writeUsageErrors(errors, stderr = process.stderr) {
+  for (const e of errors) {
+    stderr.write(`[resync-status-column] ${e}\n`);
+  }
+  stderr.write(HELP);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const values = parseArgv(argv);
+  if (values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const { ticketId, pollAttempts, pollDelayMs, errors } =
+    validateRequiredArgs(values);
+  if (errors.length) {
+    writeUsageErrors(errors);
+    process.exit(2);
+  }
+
+  const config = resolveConfig();
+  const effectiveConfig = resolveEffectiveConfig(config, values.provider);
+  const provider = createProvider(effectiveConfig);
+  const result = await reassertStatusColumn(
+    buildReassertOptions({
+      provider,
+      ticketId,
+      logger: Logger,
+      pollAttempts,
+      pollDelayMs,
+    }),
+  );
+  process.stdout.write(`${JSON.stringify({ ticketId, ...result })}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'resync-status-column' });

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * retro-run.js — execute the `/epic-deliver` Phase 6 retro from a CLI.
+ *
+ * Phase 6 of `/epic-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';
+
+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);
+
+  const result = await runRetroFn({
+    epicId,
+    provider,
+    bus,
+    forceFull: fullRetro,
+    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/run-audit-suite.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/* node:coverage ignore file */
+
+/**
+ * run-audit-suite.js — CLI + SDK for running a list of audit workflows.
+ *
+ * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in
+ * docs/decisions.md for the migration table.
+ *
+ * Story #963 (Epic #946) decomposed the previous ~445 LOC monolith (MI=0.0)
+ * into focused helpers under `lib/audit-suite/`:
+ *   - frontmatter.js     — `extractFrontmatter` + summary derivation
+ *   - substitutions.js   — `{{key}}` templating + CLI implicit defaults
+ *   - workflow-loader.js — filesystem IO for workflow markdown + artifacts
+ *   - findings.js        — severity histogram aggregation
+ *   - cli.js             — `parseAuditList`, `parseArgv`, HELP banner
+ *   - runner.js          — `runAuditSuite` aggregation core
+ *
+ * This file is the pipeline entry-point: it parses argv, glues the
+ * helpers together, writes the JSON envelope to stdout, and re-exports the
+ * symbols that downstream callers (`audit-orchestrator.js` and the test
+ * suite) already import from this path.
+ *
+ * Usage:
+ *   node .agents/scripts/run-audit-suite.js \
+ *     --audits <comma-list> [--ticket <id>] [--base-branch main] \
+ *     [--substitution key=value]...
+ *
+ * Output: a single JSON object on stdout matching the MCP envelope:
+ *   { metadata: { ... }, findings: [...], workflows: [...] }
+ *
+ * Exit codes:
+ *   0 — suite completed (findings entries are not failures)
+ *   non-zero — argument or substitution validation failure (error on stderr)
+ */
+
+import { HELP, parseArgv, parseAuditList } from './lib/audit-suite/cli.js';
+import { runAuditSuite } from './lib/audit-suite/runner.js';
+import {
+  applyImplicitSubstitutions,
+  parseSubstitutionPairs,
+} from './lib/audit-suite/substitutions.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+export { parseArgv, parseAuditList } from './lib/audit-suite/cli.js';
+export { aggregateSummary } from './lib/audit-suite/findings.js';
+export {
+  extractFrontmatter,
+  summarizeWorkflow,
+} from './lib/audit-suite/frontmatter.js';
+// --- Re-exports preserved for back-compat with existing import sites ---
+// `audit-orchestrator.js` and the test suite import these from
+// `run-audit-suite.js`. Keep them re-exported here so the decomposition
+// is internal-only.
+export { runAuditSuite } from './lib/audit-suite/runner.js';
+export {
+  applyImplicitSubstitutions,
+  applySubstitutions,
+} from './lib/audit-suite/substitutions.js';
+
+function abort(message, code = 2) {
+  process.stderr.write(message);
+  process.exit(code);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const values = parseArgv(argv);
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (!values.audits) {
+    abort(`[run-audit-suite] --audits <comma-list> is required.\n${HELP}`);
+  }
+
+  const auditWorkflows = parseAuditList(values.audits);
+  if (auditWorkflows.length === 0) {
+    abort(
+      `[run-audit-suite] --audits must contain at least one workflow name.\n`,
+    );
+  }
+
+  const substitutions = parseSubstitutionPairs(values.substitution);
+  applyImplicitSubstitutions(values, substitutions);
+
+  const result = await runAuditSuite({
+    auditWorkflows,
+    substitutions,
+    artifactPrefix: values.runId,
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+runAsCli(import.meta.url, main, { source: 'run-audit-suite' });

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// cli-opt-out: top-level CLI driver invoked via npm run test:coverage; spawns child processes rather than parsing argv, so runAsCli() does not apply.
+/**
+ * Cross-platform driver for `npm run test:coverage`.
+ *
+ * Why this exists: setting `NODE_V8_COVERAGE` directly in a package.json
+ * script string (`NODE_V8_COVERAGE=... node ...`) is bash-only — Windows
+ * cmd.exe (npm's default script-shell on Windows) treats it as a literal
+ * argument and node never sees the env var. Wrapping the run in this
+ * Node script keeps the env injection portable.
+ *
+ * Pipeline:
+ *   1. Run the test suite under `NODE_V8_COVERAGE` so each worker writes
+ *      raw V8 dumps under `coverage/tmp/`.
+ *   2. `c8 report` post-processes the dumps into `coverage/coverage-final.json`
+ *      plus the printed text table. Include/exclude scope from `.c8rc.cjs`
+ *      is passed explicitly because `c8 report` does not auto-load the
+ *      config file.
+ *   3. `check-baselines.js --gate coverage` compares the per-file
+ *      lines/branches/functions percentages in `coverage-final.json`
+ *      against the recorded floors in `baselines/coverage.json` and
+ *      fails on any regression. Update the baseline with
+ *      `npm run coverage:update` when you intentionally change scope.
+ *
+ * The previous shape of this script wrapped tests in `c8 <cmd>`. A
+ * one-off A/B benchmark (now retired) showed the NODE_V8_COVERAGE +
+ * `c8 report` path is ~19% faster end-to-end on a Windows dev host
+ * while producing an identical `coverage-final.json` artifact for the
+ * CRAP gate.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
+import { C8_CLI } from './lib/c8-cli-path.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+const COVERAGE_DIR = path.join(ROOT, 'coverage');
+const require = createRequire(import.meta.url);
+const C8_CONFIG = require('../../.c8rc.cjs');
+const V8_TMP = path.join(COVERAGE_DIR, 'tmp');
+
+rmSync(COVERAGE_DIR, { recursive: true, force: true });
+mkdirSync(V8_TMP, { recursive: true });
+
+const testRun = spawnSync(
+  process.execPath,
+  [
+    '--experimental-test-module-mocks',
+    '--test',
+    '--test-concurrency=8',
+    'tests/**/*.test.js',
+  ],
+  {
+    cwd: ROOT,
+    stdio: 'inherit',
+    env: { ...process.env, NODE_V8_COVERAGE: V8_TMP },
+  },
+);
+
+cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
+
+const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => ['--include', p]);
+const excludeArgs = (C8_CONFIG.exclude ?? []).flatMap((p) => ['--exclude', p]);
+
+const reportRun = spawnSync(
+  process.execPath,
+  [
+    C8_CLI,
+    'report',
+    '--reporter=json',
+    '--reporter=text',
+    '--temp-directory',
+    V8_TMP,
+    ...includeArgs,
+    ...excludeArgs,
+  ],
+  { cwd: ROOT, stdio: 'inherit', shell: false },
+);
+
+const checkRun = spawnSync(
+  process.execPath,
+  [
+    path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
+    '--gate',
+    'coverage',
+  ],
+  { cwd: ROOT, stdio: 'inherit' },
+);
+
+const exitCode =
+  testRun.status !== 0
+    ? testRun.status
+    : reportRun.status !== 0
+      ? reportRun.status
+      : checkRun.status;
+
+process.exit(exitCode ?? 1);

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// cli-opt-out: top-level-await driver with no main() function — runAsCli wraps an async main, which doesn't apply here.
+/* node:coverage ignore file */
+
+/**
+ * Cross-platform parallel driver for `npm run lint`.
+ *
+ * Spawns `biome ci .` and `markdownlint-cli2` concurrently. They share
+ * no state, so running them in series (the prior `&&` form) wasted
+ * wall-clock time on every developer save and pre-push. Stdout/stderr
+ * stream through unchanged so error context survives. Exit code is
+ * non-zero if either tool fails.
+ */
+
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+
+// On Windows, npm/npx shims are `.cmd` batch files. Since Node 20,
+// these can only be spawned through a shell (CWE-78 mitigation closing
+// CVE-2024-27980), so `shell: true` is mandatory there. POSIX hosts
+// can spawn directly.
+const useShell = process.platform === 'win32';
+
+const tasks = [
+  {
+    name: 'biome',
+    cmd: 'npx',
+    args: ['biome', 'ci', '.'],
+  },
+  {
+    name: 'markdownlint',
+    cmd: 'npx',
+    args: [
+      'markdownlint-cli2',
+      '.agents/**/*.md',
+      '*.md',
+      '!node_modules/**',
+      '!.worktrees/**',
+    ],
+  },
+  {
+    // Custom Node-based lint for the lifecycle bus surface (Story #2227).
+    // Enforces:
+    //   1. No `Promise.all` over listener arrays under
+    //      `.agents/scripts/lib/orchestration/lifecycle/**`.
+    //   2. Wildcard-observer firewall: no state-mutating imports in
+    //      listener modules that register on `'*'`.
+    // Both rules are mandated by Tech Spec #2189 and have no biome
+    // equivalent.
+    //
+    // Use bare `node` (PATH-resolved) rather than `process.execPath`:
+    // `process.execPath` on Windows often expands to `C:\Program
+    // Files\nodejs\node.exe`, and spawn(..., { shell: true }) does not
+    // quote the executable, so the space breaks invocation.
+    name: 'lifecycle-lint',
+    cmd: 'node',
+    args: ['.agents/scripts/check-lifecycle-lint.js'],
+  },
+  {
+    // Custom Node-based lint for label-vocabulary citations in
+    // `.agents/docs/SDLC.md` and `.agents/workflows/**/*.md` (Story #2892,
+    // Tech Spec F9 under Epic #2880). Greps inline backtick code
+    // spans for axis-shaped tokens (`type/epic`, etc.) and asserts
+    // only the canonical `<axis>::<value>` separator from
+    // `lib/label-constants.js` appears. Closes the drift gap that
+    // let the original `type/epic` typo land at
+    // `.agents/workflows/epic-plan.md:49`.
+    name: 'label-vocabulary',
+    cmd: 'node',
+    args: ['.agents/scripts/lint-label-vocabulary.js'],
+  },
+];
+
+function runTask({ name, cmd, args }) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: useShell });
+    child.on('error', (err) => {
+      process.stderr.write(`[run-lint:${name}] spawn error: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        process.stderr.write(`[run-lint:${name}] killed by ${signal}\n`);
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}
+
+const results = await Promise.all(tasks.map(runTask));
+const failed = results.findIndex((code) => code !== 0);
+process.exit(failed === -1 ? 0 : results[failed]);