mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/test-profile/render-report.js

@@ -1,45 +0,0 @@
-import { selectSlowestEntries } from './parse-tap.js';
-
-/**
- * @param {import('./parse-tap.js').TapProfile} profile
- * @param {{ topN?: number, wallDurationMs?: number | null }} [opts]
- * @returns {string}
- */
-export function renderProfileReport(profile, opts = {}) {
-  const topN = opts.topN ?? 20;
-  const slowest = selectSlowestEntries(profile.entries, topN);
-  const totalSec = (opts.wallDurationMs ?? profile.totalDurationMs ?? 0) / 1000;
-  const lines = [
-    'Mandrel test profile summary',
-    '===========================',
-    '',
-    `Total duration: ${totalSec.toFixed(3)}s`,
-    `Tests: ${profile.testCount ?? '—'}`,
-    `Suites: ${profile.suiteCount ?? '—'}`,
-    `Timed entries parsed: ${profile.entries.length}`,
-    '',
-    `Top ${topN} slowest (tests and suites):`,
-    '',
-  ];
-
-  if (slowest.length === 0) {
-    lines.push('  (no timed entries found in TAP output)');
-  } else {
-    for (const [idx, row] of slowest.entries()) {
-      const kindLabel = row.kind === 'suite' ? 'suite' : 'test';
-      const seconds = (row.durationMs / 1000).toFixed(3);
-      lines.push(
-        `${String(idx + 1).padStart(2)}. [${kindLabel.padEnd(5)}] ${seconds}s  ${row.path}`,
-      );
-    }
-  }
-
-  lines.push('');
-  lines.push(
-    'Notes: suite rows are parent describe blocks; test rows are leaf cases.',
-  );
-  lines.push(
-    'Compare before/after optimizations using the same command on the same machine.',
-  );
-  return `${lines.join('\n')}\n`;
-}

package/.agents/scripts/lint-label-vocabulary.js

@@ -1,214 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * lint-label-vocabulary.js — enforce that GitHub label tokens cited in
- * `.agents/docs/SDLC.md` and every `*.md` under `.agents/workflows/` use the
- * canonical
- * `<axis>::<value>` separator established by
- * `.agents/scripts/lib/label-constants.js`.
- *
- * Why this exists (Tech Spec F9, Epic #2880): the framework's label
- * vocabulary is the contract between docs and the runtime. A typo such
- * as `type/epic` (the original F9 finding at epic-plan.md:49) drifts
- * silently because nothing reads doc prose against the constants file.
- * This lint closes that gap by failing CI on any inline code span that
- * cites a known axis with the wrong separator.
- *
- * Scope:
- *   - Files scanned: `.agents/docs/SDLC.md` plus every `*.md` under
- *     `.agents/workflows/`.
- *   - Tokens scanned: inline backtick code spans only (e.g. `type/epic`).
- *     Prose mentions like "planning/audit metadata" are intentionally
- *     ignored — only fenced citations are treated as label references.
- *   - Axes recognized: the union of namespaces exported from
- *     `lib/label-constants.js` (`agent`, `type`, `status`, `context`,
- *     `acceptance`, `meta`, `planning`) plus the persona prefix.
- *   - Violation shape: any axis token using a separator other than `::`
- *     (e.g. `/`, `:`, `-`). False-positive risk is low because the axes
- *     are project-specific identifiers, not common English words.
- *
- * Exit codes:
- *   0 — clean.
- *   1 — at least one violation; offending file + line printed to stderr.
- *
- * Ships as part of `npm run lint` via `.agents/scripts/run-lint.js`.
- */
-
-import { readdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runAsCli } from './lib/cli-utils.js';
-import { walkFilesByExtension } from './lib/fs-walk.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-
-const DEFAULT_SCAN_TARGETS = Object.freeze([
-  path.join(REPO_ROOT, '.agents', 'docs', 'SDLC.md'),
-  path.join(REPO_ROOT, '.agents', 'workflows'),
-]);
-
-/**
- * Known label-axis prefixes. Each entry corresponds to a namespace
- * exported from `.agents/scripts/lib/label-constants.js`. The list is
- * hard-coded rather than introspected so the lint stays a pure file
- * walk with no module import side effects.
- *
- * Maintainers: when a new label axis lands in `label-constants.js`, add
- * its prefix here (without trailing colons). Forgetting to add an axis
- * makes the lint silently lenient for that namespace — the tests in
- * `tests/contract/lint/label-vocabulary.test.js` lock the canonical
- * set against drift.
- */
-export const KNOWN_AXES = Object.freeze([
-  'agent',
-  'type',
-  'status',
-  'persona',
-  'acceptance',
-  'meta',
-  'planning',
-]);
-
-/**
- * Resolve a mixed list of file/directory paths into the flat set of
- * markdown files to scan. Missing paths are silently skipped (the
- * walker handles ENOENT) so the lint is robust under partial trees.
- */
-function* resolveTargets(targets) {
-  for (const target of targets) {
-    let stat;
-    try {
-      stat = readdirSync(target, { withFileTypes: true });
-    } catch (err) {
-      if (err.code === 'ENOTDIR') {
-        // it's a file path — yield directly if it's .md
-        if (target.endsWith('.md')) yield target;
-        continue;
-      }
-      if (err.code === 'ENOENT') continue;
-      throw err;
-    }
-    // directory — walk it
-    for (const entry of stat) {
-      const p = path.join(target, entry.name);
-      if (entry.isDirectory()) {
-        yield* walkFilesByExtension(p, '.md');
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
-        yield p;
-      }
-    }
-  }
-}
-
-/**
- * Scan a single source string for inline backtick code spans containing
- * a label-shaped token that uses a non-`::` separator after a known
- * axis. Returns an array of `{ line, token, axis, separator }`.
- *
- * The matcher operates on inline code spans only (single backtick
- * delimited). Fenced code blocks (```…```) are not stripped because
- * label citations inside them are still drift signals worth flagging.
- *
- * @param {string} src
- * @param {readonly string[]} [axes]
- * @returns {Array<{ line: number, token: string, axis: string, separator: string }>}
- */
-export function findVocabularyViolations(src, axes = KNOWN_AXES) {
-  const violations = [];
-  const lines = src.split('\n');
-  // Match inline code spans: `…` where the content does not include a
-  // newline or another backtick. Greedy enough for label citations,
-  // strict enough to avoid swallowing prose.
-  const codeSpanRe = /`([^`\n]+)`/g;
-  const axisSet = new Set(axes);
-  // Anchored axis-drift check. We only flag a code span when its body,
-  // taken as a whole, has the shape `<axis><sep><value>` where:
-  //   - axis is a known label axis (case-insensitive)
-  //   - sep is one of the non-canonical separators we treat as drift:
-  //     `/` (the original F9 finding) or a single `:` (also wrong).
-  //     Hyphens (`agent-protocol`) are intentionally NOT flagged —
-  //     they collide with legitimate concept slugs and filenames.
-  //   - value is a lowercase identifier (`[a-z][a-z0-9-]*`)
-  //
-  // The whole-body anchor avoids false positives on:
-  //   - `acceptance::n-a` — canonical label, value contains a
-  //     hyphen but is not at axis position.
-  //   - `<type>/<slug>` — template placeholders.
-  //   - `delivery.maxTokenBudget` — config-key paths with `.`.
-  //   - `delivery.{maxTickets}` — JS destructure shapes.
-  //   - `agent-protocol.md` — filenames / concept slugs.
-  //
-  // Real drift like `type/epic` matches because the WHOLE body is
-  // `type/epic` (axis 'type', single '/', value 'epic').
-  const driftRe = new RegExp(
-    `^(${axes.join('|')})([/:])([a-z][a-z0-9-]*)$`,
-    'i',
-  );
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    codeSpanRe.lastIndex = 0;
-    let span = codeSpanRe.exec(line);
-    while (span !== null) {
-      const body = span[1];
-      const m = driftRe.exec(body);
-      if (m) {
-        const axis = m[1].toLowerCase();
-        const separator = m[2];
-        if (separator !== '::' && axisSet.has(axis)) {
-          violations.push({
-            line: i + 1,
-            token: body,
-            axis,
-            separator,
-          });
-        }
-      }
-      span = codeSpanRe.exec(line);
-    }
-  }
-  return violations;
-}
-
-/**
- * Aggregate violations across all target files.
- *
- * @param {readonly string[]} targets
- * @param {{ read?: typeof readFileSync }} [opts]
- * @returns {Array<{ file: string, line: number, token: string, axis: string, separator: string }>}
- */
-export function lintLabelVocabulary(
-  targets = DEFAULT_SCAN_TARGETS,
-  { read = readFileSync } = {},
-) {
-  const out = [];
-  for (const file of resolveTargets(targets)) {
-    const src = read(file, 'utf8');
-    for (const v of findVocabularyViolations(src)) {
-      out.push({ file, ...v });
-    }
-  }
-  return out;
-}
-
-async function main() {
-  const violations = lintLabelVocabulary();
-  if (violations.length === 0) {
-    process.stdout.write(
-      '[label-vocabulary] clean: no drift from canonical `<axis>::<value>` separator in scanned docs.\n',
-    );
-    return 0;
-  }
-  for (const v of violations) {
-    process.stderr.write(
-      `[label-vocabulary] ${v.file}:${v.line}\n  token \`${v.token}\` uses '${v.separator}' but axis '${v.axis}' requires canonical '::' separator (see .agents/scripts/lib/label-constants.js).\n`,
-    );
-  }
-  return 1;
-}
-
-await runAsCli(import.meta.url, main, {
-  source: 'lint-label-vocabulary',
-  propagateExitCode: true,
-});

package/.agents/scripts/post-structured-comment.js

@@ -1,127 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
-/**
- * post-structured-comment.js — CLI wrapper for structured comment upsert.
- *
- * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
- *
- * Delegates to `upsertStructuredComment` from `lib/orchestration/ticketing.js`
- * and emits the `{ success, ticketId, type }` JSON envelope on stdout.
- *
- * Usage:
- *   node .agents/scripts/post-structured-comment.js \
- *     --ticket <id> --marker <type> --body-file <path> [--provider github]
- *
- * Exit codes:
- *   0 — upsert succeeded
- *   non-zero — validation or provider failure (error on stderr)
- */
-
-import fs from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { resolveConfig } from './lib/config-resolver.js';
-import {
-  assertValidStructuredCommentType,
-  upsertStructuredComment,
-} from './lib/orchestration/ticketing.js';
-import { createProvider } from './lib/provider-factory.js';
-
-const HELP = `Usage: node .agents/scripts/post-structured-comment.js \\
-  --ticket <id> --marker <type> --body-file <path> [--provider github]
-
-Flags:
-  --ticket       GitHub issue number to comment on (required).
-  --marker       Structured-comment type (e.g. progress, friction,
-                 retro, epic-run-state, wave-0-start) (required).
-  --body-file    Path to a file containing the markdown body (required).
-  --provider     Provider name (default: inferred from .agentrc.json github block).
-  --help         Show this message.
-`;
-
-/**
- * Core: idempotently upsert the structured comment and return the envelope.
- * Exported so tests can pin input/output parity against direct SDK use
- * without spawning a subprocess.
- */
-export async function runPostStructuredComment({
-  ticketId,
-  type,
-  body,
-  provider,
-}) {
-  assertValidStructuredCommentType(type);
-  await upsertStructuredComment(provider, ticketId, type, body);
-  return { success: true, ticketId, type };
-}
-
-export function parseArgv(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      ticket: { type: 'string' },
-      marker: { type: 'string' },
-      'body-file': { type: 'string' },
-      provider: { type: 'string' },
-      help: { type: 'boolean' },
-    },
-    strict: false,
-  });
-  return values;
-}
-
-/**
- * Pure: validate the required CLI inputs for `post-structured-comment`. The
- * orchestrator is otherwise too dense to score under the CRAP cap, and these
- * rules deserve their own targeted tests.
- *
- * @param {Record<string, unknown>} values parsed CLI values
- * @returns {{ ticketId: number, errors: string[] }} `errors` is empty on success.
- */
-export function validateRequiredArgs(values) {
-  const ticketId = Number.parseInt(values.ticket ?? '', 10);
-  const errors = [];
-  if (!Number.isFinite(ticketId) || ticketId <= 0) {
-    errors.push('--ticket <id> is required.');
-  }
-  if (!values.marker) errors.push('--marker <type> is required.');
-  if (!values['body-file']) errors.push('--body-file <path> is required.');
-  return { ticketId, errors };
-}
-
-export async function main(argv = process.argv.slice(2)) {
-  const values = parseArgv(argv);
-
-  if (values.help) {
-    process.stdout.write(HELP);
-    return;
-  }
-
-  const { ticketId, errors } = validateRequiredArgs(values);
-  if (errors.length) {
-    for (const e of errors) {
-      process.stderr.write(`[post-structured-comment] ${e}\n`);
-    }
-    process.stderr.write(HELP);
-    process.exit(2);
-  }
-
-  const body = await fs.readFile(values['body-file'], 'utf8');
-
-  const config = resolveConfig();
-  const effectiveConfig = values.provider
-    ? { ...config, provider: values.provider }
-    : config;
-  const provider = createProvider(effectiveConfig);
-
-  const envelope = await runPostStructuredComment({
-    ticketId,
-    type: values.marker,
-    body,
-    provider,
-  });
-  process.stdout.write(`${JSON.stringify(envelope)}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'post-structured-comment' });

package/.agents/scripts/provision-git-hooks.js

@@ -1,85 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * provision-git-hooks.js
- *
- * Materialize the repository's git hooks into a linked worktree, so commits
- * made there are subject to the same `commit-msg` / `pre-commit` / `pre-push`
- * gates as commits made in the main checkout.
- *
- * Worktrees created by `single-story-init.js` are provisioned automatically as
- * part of `worktree.bootstrap`. This entry point exists for the worktrees the
- * orchestrator never creates — a harness or hand-made `git worktree add` —
- * which are otherwise unreachable. Run it from inside such a worktree with no
- * arguments.
- */
-
-import path from 'node:path';
-import { runAsCli } from './lib/cli-utils.js';
-import {
-  materializeGitHooks,
-  resolveCommonCheckout,
-} from './lib/worktree/git-hooks.js';
-
-/**
- * @param {object} [opts]
- * @param {string[]} [opts.argv]
- * @param {string} [opts.cwd]
- * @returns {{ action: string, reason?: string, hooksPath: string|null,
- *   target: string|null, hooks: string[], worktree: string, repoRoot: string }}
- */
-export function runProvisionGitHooks({
-  argv = process.argv.slice(2),
-  cwd = process.cwd(),
-} = {}) {
-  const positional = [];
-  let repoRootFlag = null;
-  for (let i = 0; i < argv.length; i += 1) {
-    if (argv[i] === '--repo-root') {
-      repoRootFlag = argv[i + 1];
-      if (!repoRootFlag) {
-        throw new Error('--repo-root requires a path');
-      }
-      i += 1;
-      continue;
-    }
-    positional.push(argv[i]);
-  }
-
-  const worktree = path.resolve(cwd, positional[0] ?? '.');
-  const repoRoot = repoRootFlag
-    ? path.resolve(cwd, repoRootFlag)
-    : resolveCommonCheckout(worktree);
-
-  const result = materializeGitHooks({ repoRoot, worktree });
-  return { ...result, worktree, repoRoot };
-}
-
-runAsCli(
-  import.meta.url,
-  async () => {
-    const result = runProvisionGitHooks();
-    // Compact single-line digest: this is the machine contract, and the
-    // hook file list is bounded by the hooks directory itself.
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-  },
-  {
-    source: 'provision-git-hooks',
-    usage: {
-      invocation:
-        'node .agents/scripts/provision-git-hooks.js [<worktree-path>] [--repo-root <path>]',
-      summary:
-        "Materialize the repository's git hooks into a linked worktree so its commits are gated.",
-      flags: [
-        [
-          '<worktree-path>',
-          'Worktree to provision (default: the current directory).',
-        ],
-        [
-          '--repo-root <path>',
-          'Checkout that owns the hooks (default: derived from --git-common-dir).',
-        ],
-      ],
-    },
-  },
-);

package/.agents/scripts/prune-baseline-orphans.js

@@ -1,181 +0,0 @@
-#!/usr/bin/env node
-
-// .agents/scripts/prune-baseline-orphans.js — Story #5012.
-//
-// Delete the baseline rows that are provably inert, and nothing else.
-//
-// This is the cheap remedy that makes `check-baseline-scope.js` fair. A gate
-// that hard-fails on a stale row is only defensible while clearing one costs a
-// command rather than a full re-score: the honest alternative — re-derive the
-// whole baseline — spends a coverage run or a full-tree MI pass to express a
-// deletion, which is why stale rows accumulate instead.
-//
-// Two row classes qualify, both decidable without measuring anything:
-//
-//   - `absent`       — the row's file is gone from disk.
-//   - `out-of-scope` — the file is still there, but the gate's own
-//                      `targetDirs` / `ignoreGlobs` no longer match it.
-//
-// The pruner never adds a row, never restamps `generatedAt` (a fresh stamp
-// over unmeasured rows is the exact failure an age check exists to catch), and
-// recomputes `rollup` through the kind's own arithmetic so the pruned envelope
-// still validates against its schema. An unreadable scope config degrades to
-// orphan-only pruning rather than treating unknown scope as empty scope.
-//
-// Exit codes:
-//   0  nothing to prune (or, without `--check`, the prune was written)
-//   1  `--check` found rows that would be pruned
-//   2  the pruner could not run
-
-// 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 { PRUNABLE_KINDS, runPrune } from './lib/baselines/orphan-pruner.js';
-import { runAsCli } from './lib/cli-utils.js';
-import { getQuality } from './lib/config/quality.js';
-import { resolveConfig } from './lib/config-resolver.js';
-
-const EXIT_CLEAN = 0;
-const EXIT_WOULD_PRUNE = 1;
-const EXIT_CANNOT_RUN = 2;
-
-const HELP = {
-  invocation:
-    'node .agents/scripts/prune-baseline-orphans.js [--check] [--kind <kind>] [--json]',
-  summary:
-    "Remove baseline rows whose file is gone from disk or has left the gate's scope. Never adds a row, never restamps generatedAt, never re-scores.",
-  flags: [
-    ['--check', 'Report what would be pruned, write nothing, exit 1 if any.'],
-    ['--kind <kind>', 'Prune one kind only (repeatable). Default: all.'],
-    ['--json', 'Emit the report as JSON instead of text.'],
-    ['--cwd <dir>', 'Repository root to prune. Default: process.cwd().'],
-  ],
-  notes: [
-    'Exit codes:\n  0  clean, or pruned\n  1  --check found prunable rows\n  2  the pruner could not run',
-  ],
-};
-
-/**
- * Parse argv into an options bag. An unknown flag is an error, never a silent
- * no-op — a typo'd `--dry-run` must not read as "write the files".
- *
- * @param {string[]} argv
- * @returns {{ kinds: string[], check: boolean, json: boolean, cwd: string }}
- */
-export function parseArgs(argv = []) {
-  const out = { kinds: [], check: false, json: false, cwd: null };
-  let i = 0;
-  while (i < argv.length) {
-    const arg = argv[i];
-    const value = argv[i + 1];
-    i += 1;
-    if (arg === '--check') out.check = true;
-    else if (arg === '--json') out.json = true;
-    else if (arg === '--kind') {
-      out.kinds.push(value);
-      i += 1;
-    } else if (arg === '--cwd') {
-      out.cwd = value;
-      i += 1;
-    } else throw new Error(`unknown flag "${arg}" (try --help)`);
-  }
-  const unknown = out.kinds.filter((k) => !PRUNABLE_KINDS.includes(k));
-  if (unknown.length > 0) {
-    throw new Error(
-      `unknown --kind ${unknown.join(', ')}; expected one of ${PRUNABLE_KINDS.join(', ')}`,
-    );
-  }
-  if (out.kinds.length === 0) out.kinds = [...PRUNABLE_KINDS];
-  out.cwd = out.cwd ?? process.cwd();
-  return out;
-}
-
-/**
- * Render one kind's outcome as indented text lines.
- *
- * @param {object} entry
- * @param {boolean} check
- * @returns {string[]}
- */
-function renderKind(entry, check) {
-  if (!entry.present) return [];
-  if (entry.skipped)
-    return [`  - ${entry.kind}: skipped (${entry.skipReason})`];
-  const suffix = entry.degraded
-    ? ` [orphan-only: ${entry.degradedReason}]`
-    : '';
-  if (entry.removed.length === 0) {
-    return [`  - ${entry.kind}: clean${suffix}`];
-  }
-  const verb = check ? 'would prune' : 'pruned';
-  return [
-    `  - ${entry.kind}: ${verb} ${entry.removed.length} row(s)${suffix}`,
-    ...entry.removed.map((row) => `      · ${row.reason}: ${row.path}`),
-  ];
-}
-
-/**
- * Render the whole report as text.
- *
- * @param {object} report
- * @returns {string}
- */
-export function formatReport(report) {
-  const verb = report.check ? 'would prune' : 'pruned';
-  const lines = [
-    `[prune-baseline-orphans] ${verb} ${report.removedCount} row(s) across ` +
-      `${report.writtenCount} file(s)`,
-    ...report.kinds.flatMap((entry) => renderKind(entry, report.check)),
-  ];
-  if (report.check && report.removedCount > 0) {
-    lines.push(
-      '',
-      'Run without --check to write the prune:',
-      '  node .agents/scripts/prune-baseline-orphans.js',
-    );
-  }
-  return lines.join('\n');
-}
-
-/**
- * CLI entry point. Returns its exit code rather than calling `process.exit()`,
- * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
- * an unbounded report is not truncated at a pipe boundary (Story #4783).
- *
- * @returns {Promise<number>}
- */
-async function main() {
-  let opts;
-  let report;
-  try {
-    opts = parseArgs(process.argv.slice(2));
-    const config = resolveConfig({ cwd: opts.cwd });
-    report = runPrune({
-      cwd: opts.cwd,
-      kinds: opts.kinds,
-      check: opts.check,
-      quality: getQuality(config) ?? { gates: {} },
-    });
-  } catch (err) {
-    const message = err?.message ?? String(err);
-    process.stdout.write(
-      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
-    );
-    return EXIT_CANNOT_RUN;
-  }
-  process.stdout.write(
-    opts.json
-      ? `${JSON.stringify(report, null, 2)}\n`
-      : `${formatReport(report)}\n`,
-  );
-  return report.check && report.removedCount > 0
-    ? EXIT_WOULD_PRUNE
-    : EXIT_CLEAN;
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'prune-baseline-orphans',
-  usage: HELP,
-  propagateExitCode: true,
-});