mandrel 1.91.0 → 1.93.0

package/.agents/scripts/loc-delta.js

@@ -1,205 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * loc-delta.js — Epic-level LOC accounting (Epic #1181 / Story #1441 /
- * Task #1457).
- *
- * Verifies the Skills-migration acceptance criterion: across the four
- * SSOT directories
- *   - .agents/scripts/
- *   - .agents/skills/
- *   - .agents/workflows/
- *   - .agents/README.md
- * the signed line delta between `main` and `HEAD` must be < 0 (the
- * migration is meant to *retire* code, not add it). Smoke-test files
- * under `tests/skills/` are intentionally excluded — they exist to pin
- * the migration, not to be counted against the LOC budget.
- *
- * Output: a Markdown-flavoured per-directory breakdown on stdout plus a
- * single signed total line. Exit 0 iff total < 0; exit 1 otherwise.
- *
- * Usage:
- *   node .agents/scripts/loc-delta.js                 # main...HEAD
- *   node .agents/scripts/loc-delta.js --base main     # explicit base
- *   node .agents/scripts/loc-delta.js --json          # machine output
- */
-
-import { spawnSync } from 'node:child_process';
-
-import { runAsCli } from './lib/cli-utils.js';
-
-const SCOPE_PATHS = [
-  '.agents/scripts/',
-  '.agents/skills/',
-  '.agents/workflows/',
-  '.agents/README.md',
-];
-
-const EXCLUDES = ['tests/skills/'];
-
-function parseArgs(argv) {
-  const out = { base: 'main', head: 'HEAD', json: false };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--base') {
-      out.base = argv[++i];
-    } else if (arg === '--head') {
-      out.head = argv[++i];
-    } else if (arg === '--json') {
-      out.json = true;
-    } else if (arg === '--help' || arg === '-h') {
-      out.help = true;
-    }
-  }
-  return out;
-}
-
-/**
- * Compute the (added, removed) line counts between `base` and `head`
- * restricted to the given path. Uses `git diff --numstat` so the parse
- * is unambiguous (tab-separated, additions in column 1, removals in
- * column 2, path in column 3). Binary files surface as `-` and are
- * skipped.
- */
-export function computeDeltaForPath({ base, head, path: scopePath }) {
-  const range = `${base}...${head}`;
-  const result = spawnSync(
-    'git',
-    ['diff', '--numstat', range, '--', scopePath],
-    { encoding: 'utf8' },
-  );
-  if (result.status !== 0) {
-    throw new Error(
-      `git diff failed for ${scopePath}: ${result.stderr || result.stdout}`,
-    );
-  }
-  let added = 0;
-  let removed = 0;
-  for (const rawLine of result.stdout.split('\n')) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    const parts = line.split('\t');
-    if (parts.length < 3) continue;
-    const [a, r, file] = parts;
-    if (a === '-' || r === '-') continue;
-    if (EXCLUDES.some((ex) => file.startsWith(ex))) continue;
-    added += Number.parseInt(a, 10) || 0;
-    removed += Number.parseInt(r, 10) || 0;
-  }
-  return { added, removed, delta: added - removed };
-}
-
-/**
- * Compute the per-directory deltas + signed total. Returns a shape that
- * is friendly both for human rendering and for `--json` consumers.
- */
-export function computeLocDelta({ base, head } = {}) {
-  const effectiveBase = base ?? 'main';
-  const effectiveHead = head ?? 'HEAD';
-  const perPath = SCOPE_PATHS.map((scopePath) => ({
-    path: scopePath,
-    ...computeDeltaForPath({
-      base: effectiveBase,
-      head: effectiveHead,
-      path: scopePath,
-    }),
-  }));
-  const total = perPath.reduce(
-    (acc, row) => ({
-      added: acc.added + row.added,
-      removed: acc.removed + row.removed,
-      delta: acc.delta + row.delta,
-    }),
-    { added: 0, removed: 0, delta: 0 },
-  );
-  return {
-    base: effectiveBase,
-    head: effectiveHead,
-    excludes: EXCLUDES,
-    perPath,
-    total,
-    pass: total.delta < 0,
-  };
-}
-
-function renderHuman(report) {
-  const lines = [];
-  lines.push('--- loc-delta ---');
-  lines.push(`base=${report.base} head=${report.head}`);
-  lines.push(`excluded prefixes: ${report.excludes.join(', ')}`);
-  lines.push('');
-  lines.push('| Directory | Added | Removed | Net delta |');
-  lines.push('| --- | ---: | ---: | ---: |');
-  for (const row of report.perPath) {
-    const sign = row.delta > 0 ? '+' : '';
-    lines.push(
-      `| ${row.path} | ${row.added} | ${row.removed} | ${sign}${row.delta} |`,
-    );
-  }
-  lines.push('');
-  const sign = report.total.delta > 0 ? '+' : '';
-  lines.push(
-    `Totals: added=${report.total.added} · removed=${report.total.removed} · net=${sign}${report.total.delta}`,
-  );
-  lines.push(
-    report.pass
-      ? 'Result: PASS (net LOC delta is negative)'
-      : 'Result: FAIL (net LOC delta is not negative — Epic acceptance not met)',
-  );
-  return lines.join('\n');
-}
-
-function help() {
-  return `Usage: node .agents/scripts/loc-delta.js [--base <ref>] [--head <ref>] [--json]
-
-Verifies that the signed line delta across the four SSOT directories
-(.agents/scripts/, .agents/skills/, .agents/workflows/, .agents/README.md)
-is negative between <base> (default: main) and <head> (default: HEAD).
-Smoke-test files under tests/skills/ are excluded from the count.
-
-Exit code: 0 iff net delta < 0; 1 otherwise.
-`;
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    process.stdout.write(help());
-    return 0;
-  }
-  let report;
-  try {
-    report = computeLocDelta({ base: args.base, head: args.head });
-  } catch (err) {
-    process.stderr.write(`loc-delta: ${err.message}\n`);
-    return 1;
-  }
-  if (args.json) {
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  } else {
-    process.stdout.write(`${renderHuman(report)}\n`);
-  }
-  return report.pass ? 0 : 1;
-}
-
-// Direct-CLI guard: drives `main()` through the framework's `runAsCli`
-// helper so the canonical main-guard shape (enforced by
-// `tests/enforcement/cli-wrapper.test.js`) stays intact. When imported
-// by a test, runAsCli is a no-op and the named exports remain reachable.
-runAsCli(
-  import.meta.url,
-  async () => {
-    const code = await main();
-    if (code !== 0) process.exit(code);
-  },
-  {
-    source: 'loc-delta',
-    onError(err) {
-      process.stderr.write(
-        `loc-delta: unexpected error: ${err?.message ?? err}\n`,
-      );
-      process.exit(1);
-    },
-  },
-);

package/.agents/scripts/render-manifest.js

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * .agents/scripts/render-manifest.js — Derived-view Manifest Renderer
- *
- * Regenerates `temp/epic-<epicId>/manifest.{md,json}` from the
- * `dispatch-manifest` structured comment on the Epic (Epic #1030 Story
- * #1040 / Task #1054 — migrated from the legacy flat
- * `temp/dispatch-manifest-<epicId>.{md,json}` layout). The comment is
- * the single source of truth for which Stories the sprint committed to;
- * the per-Epic files are a convenience view that lets wave-gate runs,
- * local tooling, and CI consumers work offline.
- *
- * Running this script never mutates GitHub state — it only performs a read
- * of the existing comment and writes the derived artefacts under the
- * per-Epic tree.
- *
- * Usage:
- *   node .agents/scripts/render-manifest.js --epic <EPIC_ID>
- *
- * Exit codes:
- *   0 — render succeeded.
- *   1 — no manifest comment (or no parseable JSON) on the Epic.
- *   2 — configuration or provider transport error.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { epicArtifactPath } from './lib/config/temp-paths.js';
-import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
-import { parseFencedJson } from './lib/orchestration/structured-comment-parser.js';
-import { findStructuredComment } from './lib/orchestration/ticketing.js';
-import { atomicWrite } from './lib/presentation/manifest-persistence.js';
-import { createProvider } from './lib/provider-factory.js';
-
-export function extractManifestJson(body) {
-  return parseFencedJson(body);
-}
-
-/**
- * Write the rendered manifest files. Separated from the I/O boundary so
- * tests can exercise the pure contract without touching disk.
- *
- * @param {{ epicId: number, body: string, parsed: object, projectRoot?: string }} opts
- * @returns {{ mdPath: string, jsonPath: string }}
- */
-export function writeRenderedManifest({
-  epicId,
-  body,
-  parsed,
-  projectRoot = PROJECT_ROOT,
-  config,
-}) {
-  // Per-Epic layout (Epic #1030 Story #1040): write under
-  // `<projectRoot>/temp/epic-<eid>/manifest.{md,json}`. Bind the artifact
-  // path to the explicit projectRoot (Story #3900): pre-absolutise the
-  // tempRoot against projectRoot so temp-paths honours it verbatim rather
-  // than anchoring a relative tempRoot to the main checkout (correct for the
-  // lifecycle ledger, wrong for this per-project on-disk manifest write).
-  const relTempRoot =
-    config?.project?.paths?.tempRoot &&
-    !path.isAbsolute(config.project.paths.tempRoot)
-      ? config.project.paths.tempRoot
-      : 'temp';
-  const boundConfig = path.isAbsolute(config?.project?.paths?.tempRoot ?? '')
-    ? config
-    : { project: { paths: { tempRoot: path.join(projectRoot, relTempRoot) } } };
-  const mdPath = epicArtifactPath(epicId, 'manifest.md', boundConfig);
-  const jsonPath = epicArtifactPath(epicId, 'manifest.json', boundConfig);
-  const epicDir = path.dirname(mdPath);
-  if (!fs.existsSync(epicDir)) {
-    fs.mkdirSync(epicDir, { recursive: true });
-  }
-  // Both writes go through the atomic write-then-rename helper so a
-  // crash mid-write (rename throws / process killed) leaves either the
-  // pre-existing artefact intact or no file at all — never a partial
-  // truncation. The `.tmp` residue is best-effort removed on failure
-  // (see `atomicWrite` in manifest-persistence.js).
-  atomicWrite(mdPath, body);
-  atomicWrite(jsonPath, `${JSON.stringify(parsed, null, 2)}\n`);
-  return { mdPath, jsonPath };
-}
-
-export async function renderManifestFromComment({
-  epicId,
-  injectedProvider,
-} = {}) {
-  if (!epicId || Number.isNaN(epicId) || epicId <= 0) {
-    throw new Error('Usage: node render-manifest.js --epic <EPIC_ID>');
-  }
-
-  const config = resolveConfig();
-  const provider = injectedProvider || createProvider(config);
-
-  const comment = await findStructuredComment(
-    provider,
-    epicId,
-    'dispatch-manifest',
-  );
-  if (!comment) {
-    Logger.error(
-      `[render-manifest] No dispatch-manifest comment on Epic #${epicId}. ` +
-        `Run the dispatcher (\`node .agents/scripts/dispatcher.js ${epicId}\`) first.`,
-    );
-    process.exit(1);
-  }
-
-  const parsed = extractManifestJson(comment.body);
-  if (!parsed) {
-    Logger.error(
-      `[render-manifest] dispatch-manifest comment #${comment.id} on Epic #${epicId} did not contain a parseable JSON block.`,
-    );
-    process.exit(1);
-  }
-
-  const { mdPath, jsonPath } = writeRenderedManifest({
-    epicId,
-    body: comment.body,
-    parsed,
-  });
-
-  const storyCount = Array.isArray(parsed.stories) ? parsed.stories.length : 0;
-  Logger.info(
-    `[render-manifest] ✅ Rendered ${storyCount} story(ies) for Epic #${epicId}:\n` +
-      `  - ${mdPath}\n` +
-      `  - ${jsonPath}`,
-  );
-  return { mdPath, jsonPath, stories: storyCount };
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: { epic: { type: 'string' } },
-    strict: false,
-  });
-  const epicId = Number.parseInt(values.epic ?? '', 10);
-  await renderManifestFromComment({ epicId });
-}
-
-runAsCli(import.meta.url, main, { source: 'render-manifest' });

package/.agents/scripts/run-audit-suite.js

@@ -1,97 +0,0 @@
-#!/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/select-audits.js

@@ -1,155 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * select-audits.js — Thin CLI wrapper around the audit-suite `selectAudits`
- * SDK in `lib/audit-suite/`.
- *
- * Successor to the retired mandrel MCP tools. See ADR 20260424-702a
- * in docs/decisions.md for the migration table.
- *
- * Story #1083 (Epic #1072) moved the rule-matching logic
- * (`matchesFilePattern`, `matchesAnyFilePattern`, `selectAudits`) into
- * `lib/audit-suite/selector.js` so the pipeline barrel can re-export
- * the SDK without importing upward from a top-level CLI. This file now
- * contains only argv parsing, provider construction, JSON stdout, and
- * degraded-mode exit-code mapping. Callers that need the rule-matching
- * SDK import it directly from `lib/audit-suite/index.js`.
- *
- * Usage:
- *   node .agents/scripts/select-audits.js \
- *     --ticket <id> --gate <gate> [--base-branch main]
- *
- * Output: a single JSON object on stdout matching the MCP envelope:
- *   { selectedAudits, ticketId, gate, context: { changedFilesCount, ticketTitle } }
- *
- * Exit codes:
- *   0 — selection succeeded
- *   non-zero — validation or provider failure (error on stderr)
- */
-
-import { selectAudits } from './lib/audit-suite/index.js';
-import { defineFlags } from './lib/cli-args.js';
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import { isDegraded } from './lib/degraded-mode.js';
-import { createProvider } from './lib/provider-factory.js';
-
-const HELP = `Usage: node .agents/scripts/select-audits.js \\
-  --ticket <id> --gate <gate> [--base-branch main]
-
-Flags:
-  --ticket       GitHub issue number to evaluate (required).
-  --gate         Audit gate (e.g. gate1, gate2, gate3, gate4) (required).
-  --base-branch  Branch to diff against for changed-file matching (default: main).
-  --help         Show this message.
-`;
-
-export function parseArgv(argv) {
-  const { values } = defineFlags(
-    {
-      ticket: { type: 'integer', alias: 'ticketId' },
-      gate: { type: 'string' },
-      'base-branch': { type: 'string', default: 'main' },
-      'gate-mode': { type: 'boolean' },
-      help: { type: 'boolean' },
-    },
-    argv,
-  );
-  return values;
-}
-
-/**
- * Orchestration body of `main` extracted as a sibling exported function so
- * the parse / validate / dispatch / classify-degraded ladder is unit-testable
- * without spawning a process. `main` becomes a thin shell: parse → call this
- * → render → exit. CLI surface unchanged (same flags, same exit codes, same
- * stdout JSON schema).
- *
- * @param {ReturnType<typeof parseArgv>} values
- * @param {{
- *   resolveConfig?: () => object,
- *   createProvider?: (config: object) => object,
- *   selectAudits?: typeof selectAudits,
- *   env?: Record<string, string|undefined>,
- *   help?: string,
- * }} [deps]
- * @returns {Promise<{ exitCode: number, result: object }>}
- *   `result.kind` is one of: `'help'`, `'validation-error'`, `'envelope'`.
- *   `'envelope'` carries the `selectAudits` JSON the CLI prints verbatim to
- *   stdout. Validation errors and help requests do not print to stdout.
- */
-export async function runSelectAuditsCli(values, deps = {}) {
-  const helpText = deps.help ?? HELP;
-  if (values.help) {
-    return { exitCode: 0, result: { kind: 'help', text: helpText } };
-  }
-
-  const { ticketId, gate, baseBranch, gateMode } = values;
-
-  if (!Number.isFinite(ticketId) || ticketId <= 0) {
-    return {
-      exitCode: 2,
-      result: {
-        kind: 'validation-error',
-        message: '[select-audits] --ticket <id> is required.',
-        help: helpText,
-      },
-    };
-  }
-  if (!gate) {
-    return {
-      exitCode: 2,
-      result: {
-        kind: 'validation-error',
-        message: '[select-audits] --gate <gate> is required.',
-        help: helpText,
-      },
-    };
-  }
-
-  const cfg = deps.resolveConfig ? deps.resolveConfig() : resolveConfig();
-  const provider = deps.createProvider
-    ? deps.createProvider(cfg)
-    : createProvider(cfg);
-  const env = deps.env ?? process.env;
-  const runner = deps.selectAudits ?? selectAudits;
-
-  const gateModeOpts = {
-    argv: gateMode ? ['--gate-mode'] : [],
-    env,
-  };
-  const envelope = await runner({
-    ticketId,
-    gate,
-    provider,
-    baseBranch,
-    gateModeOpts,
-  });
-  return {
-    exitCode: isDegraded(envelope) ? 1 : 0,
-    result: { kind: 'envelope', envelope },
-  };
-}
-
-export async function main(argv = process.argv.slice(2)) {
-  const values = parseArgv(argv);
-  const { exitCode, result } = await runSelectAuditsCli(values);
-
-  if (result.kind === 'help') {
-    process.stdout.write(result.text);
-    return;
-  }
-  if (result.kind === 'validation-error') {
-    process.stderr.write(`${result.message}\n${result.help}`);
-    process.exit(exitCode);
-  }
-  // kind === 'envelope' — degraded envelopes still print to stdout so
-  // callers can parse `degraded: true`, then exit non-zero so shell
-  // pipelines see the soft-fail. Gate-mode throws upstream and runAsCli's
-  // default handler exits 1.
-  process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
-  if (exitCode !== 0) process.exit(exitCode);
-}
-
-runAsCli(import.meta.url, main, { source: 'select-audits' });