mandrel 2.59.0 → 2.61.0

package/.agents/scripts/check-workflow-citations.js

@@ -1,332 +0,0 @@
-/**
- * CLI: ratchet-down gate on provenance citations in workflow prose.
- *
- * Workflow documents ride resident in an executing agent's context. A
- * `(Story #1234)` aside costs the same tokens as instruction and teaches
- * the model Mandrel's own history instead of the task in front of it. The
- * citations that survive are the ones a reader must follow to act; the
- * rest belong in the commit trail and `docs/decisions.md`.
- *
- * Nothing stops the tax re-accumulating one well-meaning aside at a time,
- * so this gate holds the line: count every issue-shaped reference across
- * `.agents/workflows/**\/*.md` and fail when the total rises above the
- * committed baseline at `baselines/workflow-citations.json`.
- *
- * The counted token is the bare `#NNNN` form rather than the
- * `(Story|Epic|issue|refs) #NNNN` phrasing, because the same citation is
- * written both ways — `(Story #4593)` and a bare `(#4593)` — and a gate
- * that only saw the prefixed form would wave the other one through.
- *
- * Ratchet semantics mirror `check-arch-cycles.js`:
- *   - Total above the baseline → exit 1, with the files that grew.
- *   - Total below the baseline → printed as shrinkage, exit 0. Refresh the
- *     baseline with `--update` to lock the reduction in.
- *   - Equal → exit 0.
- *
- * Flags:
- *   --baseline <path>  override the baseline path (default
- *                      `baselines/workflow-citations.json`, resolved from cwd)
- *   --root <path>      scan a different workflow root (default
- *                      `.agents/workflows`)
- *   --update           rewrite the baseline from the live count
- *   --json             write the structured envelope to stdout
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { runAsCli } from './lib/cli-utils.js';
-
-/** Default workflow root, relative to the repository root. */
-const DEFAULT_ROOT = path.join('.agents', 'workflows');
-
-/** Default baseline path, relative to the repository root. */
-const DEFAULT_BASELINE = path.join('baselines', 'workflow-citations.json');
-
-/**
- * Issue-shaped reference: a `#` followed by 3–5 digits. Narrow enough to
- * skip markdown headings and anchor links, wide enough to catch both the
- * `(Story #1234)` and bare `(#1234)` spellings of one citation.
- */
-const CITATION_RE = /#\d{3,5}\b/g;
-
-/**
- * Parse argv. Exported so unit tests can pin the parser.
- *
- * @param {string[]} argv
- * @returns {{ baselinePath: string | null, rootPath: string | null, update: boolean, json: boolean }}
- */
-export function parseArgv(argv = []) {
-  const out = {
-    baselinePath: null,
-    rootPath: null,
-    update: false,
-    json: false,
-  };
-  for (let i = 0; i < argv.length; i += 1) {
-    const flag = argv[i];
-    const next = argv[i + 1];
-    const takesValue = next && !next.startsWith('--');
-    if (flag === '--baseline' && takesValue) {
-      out.baselinePath = next;
-      i += 1;
-    } else if (flag === '--root' && takesValue) {
-      out.rootPath = next;
-      i += 1;
-    } else if (flag === '--update') {
-      out.update = true;
-    } else if (flag === '--json') {
-      out.json = true;
-    }
-  }
-  return out;
-}
-
-/**
- * Recursively collect `.md` files under `rootDir`. Returns absolute paths,
- * sorted for determinism.
- *
- * @param {string} rootDir
- * @returns {string[]}
- */
-export function collectMarkdownFiles(rootDir) {
-  const out = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
-    }
-  };
-  walk(rootDir);
-  return out.sort();
-}
-
-/**
- * Pure helper: count citations in source text.
- *
- * @param {string} source
- * @returns {number}
- */
-export function countCitations(source) {
-  return (String(source ?? '').match(CITATION_RE) ?? []).length;
-}
-
-/**
- * Count citations across a file set, relativizing paths against `cwd` so
- * the report serializes identically on every platform. Files with zero
- * citations are omitted — the baseline records where the tax lives.
- *
- * @param {string[]} files absolute paths
- * @param {string} cwd
- * @param {{ readFile?: (p: string) => string }} [opts]
- * @returns {{ total: number, files: Array<{ path: string, count: number }> }}
- */
-export function tallyCitations(files, cwd, { readFile } = {}) {
-  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
-  const rows = [];
-  let total = 0;
-  for (const file of files) {
-    let count;
-    try {
-      count = countCitations(read(file));
-    } catch {
-      continue;
-    }
-    if (count === 0) continue;
-    total += count;
-    rows.push({
-      path: path.relative(cwd, file).split(path.sep).join('/'),
-      count,
-    });
-  }
-  return { total, files: rows.sort((a, b) => a.path.localeCompare(b.path)) };
-}
-
-/**
- * Pure helper: read the baseline envelope. Returns `null` when the file is
- * missing or unparseable — the baseline is not distributed to consumers, so
- * its absence degrades to "no ceiling" rather than a false failure.
- *
- * @param {string} baselinePath
- * @returns {{ total?: number, files?: Array<{ path: string, count: number }> } | null}
- */
-export function loadBaseline(baselinePath) {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Pure helper: diff the live tally against the baseline. `grew` names the
- * files whose per-file count rose, so a failure points at the edit rather
- * than only at the total.
- *
- * @param {{ total?: number, files?: Array<{ path: string, count: number }> } | null} baseline
- * @param {{ total: number, files: Array<{ path: string, count: number }> }} tally
- * @returns {{ baselineTotal: number | null, delta: number | null, grew: Array<{ path: string, from: number, to: number }> }}
- */
-export function diffTally(baseline, tally) {
-  const baselineTotal =
-    typeof baseline?.total === 'number' ? baseline.total : null;
-  const prior = new Map(
-    (baseline?.files ?? []).map((row) => [row.path, row.count]),
-  );
-  const grew = tally.files
-    .map((row) => ({
-      path: row.path,
-      from: prior.get(row.path) ?? 0,
-      to: row.count,
-    }))
-    .filter((row) => row.to > row.from);
-  return {
-    baselineTotal,
-    delta: baselineTotal === null ? null : tally.total - baselineTotal,
-    grew,
-  };
-}
-
-/**
- * Pure helper: render the human-readable diff, mirroring the `+` / `-`
- * vocabulary of the sibling ratchets.
- *
- * @param {{ baselineTotal: number | null, delta: number | null, grew: Array<{ path: string, from: number, to: number }> }} diff
- * @param {{ total: number }} tally
- * @returns {string}
- */
-export function renderDiff(diff, tally) {
-  const lines = [];
-  for (const row of diff.grew) {
-    lines.push(`+ ${row.path}: ${row.from} -> ${row.to}`);
-  }
-  if (diff.delta !== null && diff.delta < 0) {
-    lines.push(
-      `[workflow-citations] ⚠ ${-diff.delta} citation(s) below baseline — refresh with --update to lock the reduction in`,
-    );
-  }
-  const tag = diff.delta !== null && diff.delta > 0 ? '(gate fail)' : '(ok)';
-  lines.push(
-    `[workflow-citations] total=${tally.total} baseline=${diff.baselineTotal ?? 'none'} ${tag}`,
-  );
-  return lines.join('\n');
-}
-
-/**
- * Top-level CLI entry. Exported so tests can drive the pipeline against a
- * tmpdir fixture corpus.
- *
- * @param {{
- *   argv?: string[],
- *   cwd?: string,
- *   stdout?: { write: (s: string) => void },
- *   stderr?: { write: (s: string) => void },
- * }} [opts]
- * @returns {Promise<number>} 0 = at or below baseline; 1 = regression
- */
-export async function runCli({
-  argv = process.argv.slice(2),
-  cwd = process.cwd(),
-  stdout = process.stdout,
-  stderr = process.stderr,
-} = {}) {
-  const { baselinePath, rootPath, update, json } = parseArgv(argv);
-  const root = path.resolve(cwd, rootPath ?? DEFAULT_ROOT);
-  const resolvedBaselinePath = path.resolve(
-    cwd,
-    baselinePath ?? DEFAULT_BASELINE,
-  );
-  if (!fs.existsSync(root)) {
-    throw new Error(`[workflow-citations] workflow root not found: ${root}`);
-  }
-
-  const tally = tallyCitations(collectMarkdownFiles(root), cwd);
-
-  if (update) {
-    const envelope = {
-      $schema: 'https://mandrel.dev/baselines/workflow-citations.schema.json',
-      generatedAt: new Date().toISOString(),
-      total: tally.total,
-      files: tally.files,
-    };
-    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
-    fs.writeFileSync(
-      resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    stdout.write(
-      `[workflow-citations] baseline written: ${resolvedBaselinePath} (total=${tally.total})\n`,
-    );
-    return 0;
-  }
-
-  const baseline = loadBaseline(resolvedBaselinePath);
-  const diff = diffTally(baseline, tally);
-  const exitCode = diff.delta !== null && diff.delta > 0 ? 1 : 0;
-
-  if (json) {
-    stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'workflow-citations-report',
-          root,
-          baselinePath: resolvedBaselinePath,
-          total: tally.total,
-          baselineTotal: diff.baselineTotal,
-          delta: diff.delta,
-          files: tally.files,
-          grew: diff.grew,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
-    );
-    return exitCode;
-  }
-
-  if (!baseline) {
-    stderr.write(
-      `[workflow-citations] ⚠ baseline not found at ${resolvedBaselinePath} — no ceiling enforced\n`,
-    );
-  }
-  stdout.write(`\n--- workflow-citations preview ---\n`);
-  stdout.write(`${renderDiff(diff, tally)}\n`);
-  return exitCode;
-}
-
-async function main() {
-  return runCli();
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'workflow-citations',
-  propagateExitCode: true,
-  errorPrefix: '[workflow-citations] ❌ Fatal error',
-  usage: {
-    invocation:
-      'node .agents/scripts/check-workflow-citations.js [--baseline <path>] [--root <dir>] [--update] [--json]',
-    summary:
-      'Ratchet on provenance citations in workflow prose: count issue-shaped references across .agents/workflows/** and fail when the total rises above the recorded baseline.',
-    flags: [
-      [
-        '--baseline <path>',
-        'Baseline file (default: baselines/workflow-citations.json).',
-      ],
-      ['--root <dir>', 'Workflow root to scan (default: .agents/workflows).'],
-      ['--update', 'Rewrite the baseline from the live count.'],
-      ['--json', 'Emit the comparison envelope as JSON.'],
-    ],
-    notes: [
-      'Exit codes:\n  0  at or below the baseline\n  1  the citation total regressed above the baseline',
-    ],
-  },
-});

package/.agents/scripts/check-workflow-cli-lint.js

@@ -1,299 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * check-workflow-cli-lint.js — enforce the "no workflow instructs a
- * no-CLI library call" rule (Epic #4474 PR5; sibling of
- * check-lifecycle-lint.js).
- *
- * The measured failure mode this rule kills: workflow prose that tells the
- * host LLM to "Call `someExportedFunction({...})` exported from
- * `lib/whatever.js`". There is no runnable form of that instruction, so the
- * model greps the framework source and writes throwaway `.mjs` shims to
- * invoke the export — the mandrel-bench N=2 cohort measured ~12–15 turns of
- * shim-writing per plan for exactly this pattern. Workflows must instruct
- * `node .agents/scripts/<cli>.js …` commands instead.
- *
- * Scope: every `*.md` under `.agents/workflows/`.
- *
- * Heuristic (tuned to zero false positives on the surviving corpus —
- * descriptive mentions like "the automatic paths call `foo()`" are prose
- * about script internals, not instructions, and are NOT flagged):
- *
- *   Rule 1 — imperative library call. A paragraph (fenced code blocks
- *     stripped; lines joined) matching /\b(Call|Invoke)\s+`ident\s*\(/ —
- *     a capitalized imperative directly instructing a function call.
- *
- *   Rule 2 — "exported from" instruction. A paragraph containing both a
- *     backticked call token (`ident(`) and the phrase "exported from" —
- *     the canonical shape of the retired Phase 2/3/4 prose.
- *
- *   Rule 3 — prose-level lib import. `import(` / `require(` naming a
- *     `scripts/lib/` path OUTSIDE a fenced code block. (A complete,
- *     runnable `node -e` one-liner inside a fenced block is exempt: it
- *     costs zero shim-writing turns because it is executable as written.)
- *
- * Exit codes:
- *   0 — clean.
- *   1 — at least one violation; offending file + paragraph line printed
- *       to stderr.
- *
- * Ships as part of `npm run lint` (run-lint.js task list), alongside the
- * lifecycle lint and the label-vocabulary lint.
- */
-
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { runAsCli } from './lib/cli-utils.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-export const DEFAULT_WORKFLOWS_DIR = path.join(
-  REPO_ROOT,
-  '.agents',
-  'workflows',
-);
-
-const IMPERATIVE_CALL_RE = /\b(?:Call|Invoke)\s+`[A-Za-z_$][\w$]*\s*\(/;
-const BACKTICK_CALL_RE = /`[A-Za-z_$][\w$]*\s*\(/;
-const EXPORTED_FROM_RE = /\bexported from\b/;
-const LIB_IMPORT_RE = /\b(?:import|require)\(\s*['"`][^'"`]*scripts\/lib\//;
-
-/** A markdown table row (leading pipe, optionally indented). */
-const TABLE_ROW_RE = /^\s*\|/;
-/** A markdown heading of any level — the lookback boundary for Rule 4. */
-const HEADING_RE = /^\s*#{1,6}\s/;
-/** A backticked `--flag` occupying a table row's first cell. */
-const FLAG_CELL_RE = /^\s*\|\s*`?--[\w-]+/;
-/** A `.js` script filename — bare or path-qualified. */
-const SCRIPT_NAME_RE = /([\w./-]*[\w-]+\.js)\b/;
-/** A markdown table's delimiter row (`| --- | --- |`). */
-const TABLE_DELIMITER_RE = /^\s*\|[\s|:-]+\|?\s*$/;
-/** Minimum `--flag` rows before a table counts as a flag *table*. */
-export const MIN_FLAG_ROWS = 2;
-
-/**
- * Strip fenced code blocks (``` / ~~~), replacing their lines with empty
- * strings so line numbers stay stable. Complete runnable commands live in
- * fences and are exempt by design (see header).
- *
- * @param {string} source
- * @returns {string[]} lines with fenced content blanked.
- */
-export function stripFences(source) {
-  const lines = source.split('\n');
-  let inFence = false;
-  return lines.map((line) => {
-    const fence = /^\s*(```|~~~)/.test(line);
-    if (fence) {
-      inFence = !inFence;
-      return '';
-    }
-    return inFence ? '' : line;
-  });
-}
-
-/**
- * Split blanked lines into paragraphs — runs of consecutive non-empty
- * lines — keeping the 1-based line number of each paragraph's first line.
- *
- * @param {string[]} lines
- * @returns {Array<{ text: string, line: number }>}
- */
-export function toParagraphs(lines) {
-  const paragraphs = [];
-  let buf = [];
-  let start = 0;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trim().length > 0) {
-      if (buf.length === 0) start = i + 1;
-      buf.push(lines[i]);
-    } else if (buf.length > 0) {
-      paragraphs.push({ text: buf.join(' '), line: start });
-      buf = [];
-    }
-  }
-  if (buf.length > 0) paragraphs.push({ text: buf.join(' '), line: start });
-  return paragraphs;
-}
-
-/**
- * Rule 4 — CLI flag table. Find markdown tables that enumerate the `--flags`
- * of a script the repo already owns, and flag them as duplicated surface.
- *
- * The script's own argument parser is the source of truth for its flags, and
- * it prints them itself; a copy in prose is drift waiting to happen (the very
- * drift Story #4546 removed). Prose must point at the command instead.
- *
- * The signal is deliberately narrow, to stay at zero false positives:
- *
- *   1. The table has at least `MIN_FLAG_ROWS` data rows whose **first cell**
- *      is a `--flag`. One flag row among prose rows is a contract/behaviour
- *      table (e.g. "Default | …", "`--dry-run` | …"), not a flag enumeration.
- *   2. A `.js` script is named between the table and the nearest preceding
- *      heading (inclusive) — i.e. the section is *about* that script, so the
- *      table is restating its surface.
- *
- * A slash command's own argument table (`/mandrel-plan`, `/mandrel-deliver`) has no script
- * behind it — nothing owns those flags but the workflow prose itself — so
- * condition 2 leaves it alone by design.
- *
- * @param {string[]} rawLines unstripped source lines (fenced commands are the
- *   usual place a script is named, so this rule reads the original text).
- * @returns {Array<{ rule: string, line: number, hint: string }>}
- */
-export function lintFlagTables(rawLines) {
-  const violations = [];
-  let inFence = false;
-
-  for (let i = 0; i < rawLines.length; i++) {
-    if (/^\s*(```|~~~)/.test(rawLines[i])) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence || !TABLE_ROW_RE.test(rawLines[i])) continue;
-
-    // Collect the contiguous table block starting here.
-    const start = i;
-    let end = i;
-    while (end + 1 < rawLines.length && TABLE_ROW_RE.test(rawLines[end + 1])) {
-      end += 1;
-    }
-    i = end; // continue scanning after this table
-
-    const flagRows = rawLines
-      .slice(start, end + 1)
-      .filter((l) => !TABLE_DELIMITER_RE.test(l) && FLAG_CELL_RE.test(l));
-    if (flagRows.length < MIN_FLAG_ROWS) continue;
-
-    // Look back to the nearest heading (inclusive) for a named script.
-    let script = null;
-    for (let j = start - 1; j >= 0; j--) {
-      const m = SCRIPT_NAME_RE.exec(rawLines[j]);
-      if (m) {
-        script = m[1];
-        break;
-      }
-      if (HEADING_RE.test(rawLines[j])) break;
-    }
-    if (!script) continue;
-
-    const base = script.split('/').pop();
-    violations.push({
-      rule: 'no-cli-flag-table',
-      line: start + 1,
-      hint:
-        `Workflow prose restates the flag surface of \`${base}\` as a table (${flagRows.length} flag rows). ` +
-        "The script's argument parser owns those flags, so a prose copy is drift waiting to happen. " +
-        `Delete the table and point at the command (\`node .agents/scripts/${base} …\`), keeping only the ` +
-        'judgement a reader cannot get from the command itself. If the script has no help output to point ' +
-        'at, add one — do not re-inline the table.',
-    });
-  }
-  return violations;
-}
-
-/**
- * Lint one markdown source. Returns violations
- * `{ rule, line, hint }[]` (empty when clean).
- *
- * @param {string} source markdown content.
- * @returns {Array<{ rule: string, line: number, hint: string }>}
- */
-export function lintWorkflowSource(source) {
-  const violations = [];
-  const rawLines = source.split('\n');
-  const lines = stripFences(source);
-  violations.push(...lintFlagTables(rawLines));
-  for (const para of toParagraphs(lines)) {
-    if (IMPERATIVE_CALL_RE.test(para.text)) {
-      violations.push({
-        rule: 'no-cli-library-call',
-        line: para.line,
-        hint:
-          'Workflow prose instructs calling a function directly ("Call/Invoke `fn(...)`"). ' +
-          'There is no runnable form of that instruction — the model must write a throwaway shim. ' +
-          'Instruct a `node .agents/scripts/<cli>.js …` command instead (add a CLI if none exists).',
-      });
-      continue;
-    }
-    if (EXPORTED_FROM_RE.test(para.text) && BACKTICK_CALL_RE.test(para.text)) {
-      violations.push({
-        rule: 'no-cli-library-call',
-        line: para.line,
-        hint:
-          'Workflow prose points at an exported library function ("`fn(...)` exported from …") ' +
-          'with no CLI entrypoint. Instruct a `node .agents/scripts/<cli>.js …` command instead.',
-      });
-      continue;
-    }
-    if (LIB_IMPORT_RE.test(para.text)) {
-      violations.push({
-        rule: 'no-prose-lib-import',
-        line: para.line,
-        hint:
-          'Workflow prose (outside a fenced code block) instructs importing a scripts/lib module. ' +
-          'Give a complete runnable command in a fenced block, or add a CLI entrypoint.',
-      });
-    }
-  }
-  return violations;
-}
-
-/**
- * Recursively collect `*.md` files under a directory.
- *
- * @param {string} dir
- * @returns {string[]} absolute paths.
- */
-export function collectMarkdown(dir) {
-  const out = [];
-  for (const entry of readdirSync(dir)) {
-    const abs = path.join(dir, entry);
-    const st = statSync(abs);
-    if (st.isDirectory()) out.push(...collectMarkdown(abs));
-    else if (entry.endsWith('.md')) out.push(abs);
-  }
-  return out;
-}
-
-/**
- * Run the check over a workflows directory. Exported for tests (pass a
- * fixture directory).
- *
- * @param {string} [workflowsDir]
- * @returns {Array<{ file: string, rule: string, line: number, hint: string }>}
- */
-export function runCheck(workflowsDir = DEFAULT_WORKFLOWS_DIR) {
-  const violations = [];
-  for (const file of collectMarkdown(workflowsDir)) {
-    const source = readFileSync(file, 'utf8');
-    for (const v of lintWorkflowSource(source)) {
-      violations.push({ file: path.relative(REPO_ROOT, file), ...v });
-    }
-  }
-  return violations;
-}
-
-async function main() {
-  const violations = runCheck();
-  if (violations.length === 0) {
-    process.stdout.write(
-      '[workflow-cli-lint] clean: no workflow instructs a no-CLI library call.\n',
-    );
-    return 0;
-  }
-  for (const v of violations) {
-    process.stderr.write(
-      `[workflow-cli-lint][${v.rule}] ${v.file}:${v.line}\n  ${v.hint}\n`,
-    );
-  }
-  return 1;
-}
-
-await runAsCli(import.meta.url, main, {
-  source: 'check-workflow-cli-lint',
-  propagateExitCode: true,
-});