mandrel 1.57.0

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -0,0 +1,370 @@
+/**
+ * bootstrap/quality-bootstrap — Story #1401 (Epic #1386)
+ *
+ * Idempotent installer for the stabilized-quality-gates surface area on a
+ * project clone. Performs four additive actions, each safe to re-run:
+ *
+ *   1. Copies the `code-quality-guardrails.md` helper into the project's
+ *      `.agents/workflows/helpers/` (no-op when the helper is already present).
+ *   2. Installs `.husky/pre-commit` carrying the `quality:preview` invocation
+ *      that the framework ships, preserving any custom hook lines already in
+ *      place. When a custom (non-framework) `pre-commit` exists, it is left
+ *      untouched and the caller is told to merge in the snippet manually.
+ *   3. Adds `quality:preview` and `quality:watch` npm scripts when missing.
+ *      Existing scripts are preserved.
+ *   4. Seeds `delivery.quality.codingGuardrails` and
+ *      `delivery.quality.autoRefresh` defaults in `.agentrc.json` when
+ *      the keys are absent. Existing values are preserved.
+ *
+ * Returns a structured summary so the bootstrap and update workflows can
+ * surface exactly which actions ran and which were no-ops.
+ *
+ * Exports are pure-ish (filesystem effects only via the supplied paths) so
+ * the test suite can drive the helper against a tmp directory.
+ *
+ * @module bootstrap/quality-bootstrap
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAgentrcDefaults, lookupPath } from '../config/defaults.js';
+import { deepEqual } from '../json-utils.js';
+
+/**
+ * The exact pre-commit body the framework ships. Kept as a single string so
+ * the hook-installer can detect a verbatim framework hook (overwrite-safe)
+ * vs a custom hook (preserve and warn).
+ */
+export const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
+npx lint-staged
+# Story #1395 / Epic #1386: catch MI/CRAP drift at git-commit time so the
+# agent refactors before the diff is closed. quality:preview wraps both gates
+# with --changed-since HEAD --staged --json and exits non-zero on any
+# threshold violation, blocking the commit and rendering the per-file delta
+# table to stderr (via the gates inherited stdio).
+node .agents/scripts/quality-preview.js --changed-since HEAD --staged
+`;
+
+/**
+ * Minimal pre-commit body for downstream projects that do not carry the
+ * framework's `check-version-sync.js` script. Drops that line and the
+ * `lint-staged` invocation (downstream may or may not have lint-staged
+ * configured); keeps the quality-preview line which is the load-bearing
+ * Epic #1386 addition.
+ */
+export const DOWNSTREAM_PRE_COMMIT = `# Stabilized quality gates (Epic #1386 / Story #1401):
+# catch MI/CRAP drift at git-commit time so the agent refactors before the
+# diff is closed. quality:preview wraps both gates with --changed-since HEAD
+# --staged and exits non-zero on any threshold violation, blocking the
+# commit and rendering the per-file delta table to stderr.
+node .agents/scripts/quality-preview.js --changed-since HEAD --staged
+`;
+
+/**
+ * Marker substring used to detect a framework-installed quality-preview line
+ * inside a pre-commit hook regardless of which body variant is in use.
+ */
+export const PRE_COMMIT_MARKER =
+  'node .agents/scripts/quality-preview.js --changed-since HEAD --staged';
+
+/**
+ * Default values seeded into `delivery.quality.{codingGuardrails,autoRefresh}`
+ * when the keys are absent. Mirrors `.agents/docs/agentrc-reference.json` — keep in
+ * sync when those numbers move.
+ */
+export const QUALITY_CONFIG_DEFAULTS = Object.freeze({
+  codingGuardrails: Object.freeze({
+    cyclomaticFlag: 8,
+    cyclomaticMustFix: 12,
+    miDropMustRefactor: 1.5,
+    requireSiblingTest: false,
+  }),
+  autoRefresh: Object.freeze({
+    enabled: true,
+    miDropCap: 1.5,
+    crapJumpCap: 5,
+    scope: 'diff',
+  }),
+});
+
+/**
+ * NPM scripts seeded by the bootstrap. Existing values are preserved.
+ */
+export const QUALITY_NPM_SCRIPTS = Object.freeze({
+  'quality:preview':
+    'node .agents/scripts/quality-preview.js --changed-since HEAD',
+  'quality:watch': 'node .agents/scripts/quality-watch.js',
+});
+
+/**
+ * Read JSON from a path, returning `null` when the file does not exist.
+ * Surfaces parse errors so callers can fail loudly on a corrupt config.
+ */
+function readJsonIfExists(p) {
+  if (!fs.existsSync(p)) return null;
+  const raw = fs.readFileSync(p, 'utf8');
+  return JSON.parse(raw);
+}
+
+function writeJson(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Step 1 — Ensure the code-quality-guardrails helper is present under
+ * `.agents/workflows/helpers/`. When the helper already exists we report
+ * `already-present`. Otherwise the helper is copied from the framework source
+ * if available, or skipped with a `missing-source` outcome the caller can
+ * surface.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {string} [ctx.frameworkRoot] - Path to the framework checkout
+ *   (defaults to `<projectRoot>/.agents`). Tests pass an explicit path.
+ */
+export function ensureGuardrailsHelper(ctx) {
+  const projectRoot = ctx.projectRoot;
+  const target = path.join(
+    projectRoot,
+    '.agents',
+    'workflows',
+    'helpers',
+    'code-quality-guardrails.md',
+  );
+  if (fs.existsSync(target)) {
+    return { action: 'already-present', path: target };
+  }
+  const sourceRoot = ctx.frameworkRoot ?? path.join(projectRoot, '.agents');
+  const source = path.join(
+    sourceRoot,
+    'workflows',
+    'helpers',
+    'code-quality-guardrails.md',
+  );
+  if (!fs.existsSync(source)) {
+    return { action: 'missing-source', path: target };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+  return { action: 'copied', path: target };
+}
+
+/**
+ * Step 2 — Install the `.husky/pre-commit` hook. Decision tree:
+ *
+ *   - No `.husky/pre-commit` file → write the requested body, action `created`.
+ *   - File exists and already contains the quality-preview marker → no-op,
+ *     action `already-present`.
+ *   - File exists, does NOT contain the marker, and matches the framework
+ *     body byte-for-byte → safe overwrite, action `updated`.
+ *   - File exists, custom content → leave untouched and emit
+ *     `custom-hook-skip` so the workflow can print the operator notice with
+ *     the recommended snippet to merge in.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {'framework'|'downstream'} [ctx.variant='downstream']
+ */
+export function ensurePreCommitHook(ctx) {
+  const variant = ctx.variant ?? 'downstream';
+  const body =
+    variant === 'framework' ? FRAMEWORK_PRE_COMMIT : DOWNSTREAM_PRE_COMMIT;
+  const huskyDir = path.join(ctx.projectRoot, '.husky');
+  const hookPath = path.join(huskyDir, 'pre-commit');
+  if (!fs.existsSync(hookPath)) {
+    fs.mkdirSync(huskyDir, { recursive: true });
+    fs.writeFileSync(hookPath, body, 'utf8');
+    return {
+      action: 'created',
+      path: hookPath,
+      variant,
+      snippet: PRE_COMMIT_MARKER,
+    };
+  }
+  const existing = fs.readFileSync(hookPath, 'utf8');
+  if (existing.includes(PRE_COMMIT_MARKER)) {
+    return {
+      action: 'already-present',
+      path: hookPath,
+      variant,
+      snippet: PRE_COMMIT_MARKER,
+    };
+  }
+  return {
+    action: 'custom-hook-skip',
+    path: hookPath,
+    variant,
+    snippet: body,
+    notice:
+      'Custom .husky/pre-commit detected — leaving untouched. Append the snippet above so quality:preview runs at commit time.',
+  };
+}
+
+/**
+ * Step 3 — Register the `quality:preview` and `quality:watch` npm scripts
+ * in the project's `package.json`. Existing values are preserved
+ * unconditionally; this helper only adds missing keys.
+ *
+ * Returns the per-script outcome so the workflow can surface which scripts
+ * were added vs already present.
+ */
+export function ensureQualityNpmScripts(ctx) {
+  const pkgPath = path.join(ctx.projectRoot, 'package.json');
+  const pkg = readJsonIfExists(pkgPath);
+  if (!pkg) {
+    return { action: 'missing-package-json', path: pkgPath, scripts: {} };
+  }
+  pkg.scripts = pkg.scripts ?? {};
+  const outcomes = {};
+  let mutated = false;
+  for (const [name, cmd] of Object.entries(QUALITY_NPM_SCRIPTS)) {
+    if (typeof pkg.scripts[name] === 'string' && pkg.scripts[name].length > 0) {
+      outcomes[name] = 'already-present';
+    } else {
+      pkg.scripts[name] = cmd;
+      outcomes[name] = 'added';
+      mutated = true;
+    }
+  }
+  if (mutated) writeJson(pkgPath, pkg);
+  return {
+    action: mutated ? 'updated' : 'no-change',
+    path: pkgPath,
+    scripts: outcomes,
+  };
+}
+
+/**
+ * Deep-merge the requested defaults into an object, only setting keys that
+ * are absent AND whose intended value diverges from the framework default
+ * at that dotted path. The runtime layers `getAgentrcDefaults()`
+ * underneath the project config at read time, so a key whose intended
+ * value equals the framework default would be written redundantly — and
+ * would then be flagged `[REDUNDANT]` by the sync-agentrc helper on the
+ * next /agents-update. Default-aware seeding keeps the two helpers from
+ * contradicting each other.
+ *
+ * Returns `{ merged, addedKeys[] }` so the caller can report exactly
+ * which keys were seeded. Pure-default writes are reported under
+ * `skippedKeys[]` so callers can surface why the seed was a no-op.
+ *
+ * @param {object} target
+ * @param {object} defaults — the values the caller would seed if
+ *   default-blindness were the policy.
+ * @param {object} frameworkDefaults — the framework's resolved defaults
+ *   at the seed root. Compared to each intended write.
+ * @param {string} prefix — dotted path under construction.
+ */
+function mergeMissingKeys(
+  target,
+  defaults,
+  frameworkDefaults = {},
+  prefix = '',
+) {
+  const addedKeys = [];
+  const skippedKeys = [];
+  for (const [key, value] of Object.entries(defaults)) {
+    const keyPath = prefix ? `${prefix}.${key}` : key;
+    const frameworkValue =
+      frameworkDefaults && typeof frameworkDefaults === 'object'
+        ? frameworkDefaults[key]
+        : undefined;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      if (!target[key] || typeof target[key] !== 'object') {
+        target[key] = {};
+      }
+      const nested = mergeMissingKeys(
+        target[key],
+        value,
+        frameworkValue ?? {},
+        keyPath,
+      );
+      addedKeys.push(...nested.addedKeys);
+      skippedKeys.push(...nested.skippedKeys);
+      if (
+        Object.keys(target[key]).length === 0 &&
+        target[key] !== frameworkDefaults?.[key]
+      ) {
+        delete target[key];
+      }
+    } else if (target[key] === undefined) {
+      if (deepEqual(value, frameworkValue)) {
+        skippedKeys.push(keyPath);
+      } else {
+        target[key] = value;
+        addedKeys.push(keyPath);
+      }
+    }
+  }
+  return { merged: target, addedKeys, skippedKeys };
+}
+
+/**
+ * Step 4 — Seed the `delivery.quality.codingGuardrails` and
+ * `delivery.quality.autoRefresh` defaults into `.agentrc.json`. Only
+ * missing keys are added; existing values are preserved unconditionally
+ * (including operator overrides that diverge from the framework defaults).
+ *
+ * When `.agentrc.json` does not exist the action is `missing-config` and
+ * nothing is written — the project must complete its base bootstrap first.
+ */
+export function ensureQualityConfigDefaults(ctx) {
+  const cfgPath = path.join(ctx.projectRoot, '.agentrc.json');
+  const cfg = readJsonIfExists(cfgPath);
+  if (!cfg) {
+    return {
+      action: 'missing-config',
+      path: cfgPath,
+      addedKeys: [],
+      skippedKeys: [],
+    };
+  }
+  const frameworkDefaults = getAgentrcDefaults();
+  const frameworkQuality =
+    lookupPath(frameworkDefaults, 'delivery.quality').value ?? {};
+  const hadDelivery = Object.hasOwn(cfg, 'delivery');
+  const hadQuality = hadDelivery && Object.hasOwn(cfg.delivery, 'quality');
+  cfg.delivery = cfg.delivery ?? {};
+  cfg.delivery.quality = cfg.delivery.quality ?? {};
+  const { addedKeys, skippedKeys } = mergeMissingKeys(
+    cfg.delivery.quality,
+    QUALITY_CONFIG_DEFAULTS,
+    frameworkQuality,
+    'delivery.quality',
+  );
+  if (addedKeys.length > 0) {
+    writeJson(cfgPath, cfg);
+  } else {
+    // No-op path — undo the scaffolding we inserted so the on-disk file
+    // and the in-memory snapshot agree (defensive; nothing reads cfg
+    // after this).
+    if (!hadQuality) delete cfg.delivery.quality;
+    if (!hadDelivery) delete cfg.delivery;
+  }
+  return {
+    action: addedKeys.length > 0 ? 'updated' : 'no-change',
+    path: cfgPath,
+    addedKeys,
+    skippedKeys,
+  };
+}
+
+/**
+ * Run all four steps in order. Composable wrapper used by the bootstrap
+ * and update workflows. Each step's outcome is returned under its own key
+ * so callers can render a per-action summary.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {string} [ctx.frameworkRoot]
+ * @param {'framework'|'downstream'} [ctx.variant]
+ */
+export function applyQualityBootstrap(ctx) {
+  return {
+    helper: ensureGuardrailsHelper(ctx),
+    hook: ensurePreCommitHook(ctx),
+    scripts: ensureQualityNpmScripts(ctx),
+    config: ensureQualityConfigDefaults(ctx),
+  };
+}

package/.agents/scripts/lib/bootstrap/summary.js

@@ -0,0 +1,75 @@
+/**
+ * bootstrap/summary — Bootstrap result formatting + summary printing
+ *
+ * Pure formatting helpers (`format*Summary`) and the `printSummary`
+ * presenter extracted from `agents-bootstrap-github.js` (Story #3349).
+ * These render the `runBootstrap` result envelope into operator-facing
+ * lines; they hold no provider coupling and no orchestration logic.
+ */
+
+import { Logger } from '../Logger.js';
+
+export function formatProjectSummary(project) {
+  if (project.scopesMissing) return 'skipped (missing project scope)';
+  if (project.created) return `created #${project.projectNumber}`;
+  if (project.projectNumber) return `adopted #${project.projectNumber}`;
+  return 'skipped';
+}
+
+export function formatBranchProtectionSummary(bp) {
+  if (!bp) return 'not-run';
+  if (bp.status === 'created') return `created (added: ${bp.added.join(', ')})`;
+  if (bp.status === 'merged') {
+    return bp.added.length
+      ? `merged (added: ${bp.added.join(', ')})`
+      : 'merged (no changes)';
+  }
+  if (bp.status === 'skipped') return `skipped (${bp.reason})`;
+  if (bp.status === 'failed') return `failed (${bp.reason})`;
+  return bp.status;
+}
+
+export function formatWorkflowAuditSummary(wa) {
+  if (!wa) return 'not-run';
+  if (wa.skipped) return `skipped (${wa.reason})`;
+  if (wa.action === 'no-conflicts') return 'no conflicting workflows';
+  if (wa.action === 'warn-only')
+    return `warned (${wa.audit.conflicting.length} conflicting; pass --reap-conflicting-workflows to delete)`;
+  if (wa.action === 'reaped') return `reaped ${wa.reaped.length} workflow(s)`;
+  return wa.action ?? 'unknown';
+}
+
+export function formatMergeMethodsSummary(mm) {
+  if (!mm) return 'not-run';
+  if (mm.status === 'unchanged') return 'unchanged (already at target stance)';
+  if (mm.status === 'patched')
+    return `patched (${(mm.patched ?? []).join(', ') || '—'})`;
+  if (mm.status === 'skipped') return `skipped (${mm.reason})`;
+  if (mm.status === 'failed') return `failed (${mm.reason})`;
+  return mm.status;
+}
+
+export function printSummary(result) {
+  Logger.info('\n=== Bootstrap Summary ===');
+  Logger.info(`Labels created: ${result.labels.created.length}`);
+  Logger.info(`Labels skipped: ${result.labels.skipped.length}`);
+  Logger.info(`Fields created: ${result.fields.created.length}`);
+  Logger.info(`Fields skipped: ${result.fields.skipped.length}`);
+  Logger.info(`Project: ${formatProjectSummary(result.project)}`);
+  Logger.info(`Status field: ${result.statusField.status}`);
+  const unavailableSuffix = result.views.unavailable
+    ? ' (mutation unavailable)'
+    : '';
+  Logger.info(
+    `Views — created: ${result.views.created.length}, skipped: ${result.views.skipped.length}${unavailableSuffix}`,
+  );
+  Logger.info(
+    `Workflow audit: ${formatWorkflowAuditSummary(result.workflowAudit)}`,
+  );
+  Logger.info(
+    `Branch protection: ${formatBranchProtectionSummary(result.branchProtection)}`,
+  );
+  Logger.info(
+    `Merge methods: ${formatMergeMethodsSummary(result.mergeMethods)}`,
+  );
+}

package/.agents/scripts/lib/bootstrap/workflow-audit.js

@@ -0,0 +1,256 @@
+/**
+ * bootstrap/workflow-audit — audit the GitHub Projects v2 built-in
+ * workflows for the project board, classifying each enabled workflow
+ * against an allowlist (Story #2845).
+ *
+ * Motivation:
+ *   The orchestrator's `ColumnSync` writes the Status column at every
+ *   `transitionTicketState` call and documents "I own Status" at
+ *   [`column-sync.js:21-27`]. GitHub Projects v2 ships several built-in
+ *   workflows that *also* write the Status column as side-effects of
+ *   issue / PR events. When both are enabled, the bot frequently gets
+ *   the last write on `agent::done` transitions (PR merged ~2 minutes
+ *   after the orchestrator's flip), leaving closed Stories stuck at
+ *   `In Progress` on the board even though the issue is closed and
+ *   labeled `agent::done`. Reproduced on Story #2813.
+ *
+ * Surface:
+ *   - {@link CONFLICTING_WORKFLOWS} / {@link COMPATIBLE_WORKFLOWS} —
+ *     frozen allowlists keyed by GitHub's built-in workflow `name`
+ *     field.
+ *   - {@link auditProjectWorkflows} — pure-ish (one GraphQL read) that
+ *     classifies the project's currently-enabled workflows and returns
+ *     a structured envelope.
+ *   - {@link reapConflictingWorkflows} — opt-in destructive helper
+ *     that issues `deleteProjectV2Workflow` for every entry in the
+ *     audit's `conflicting` set. Fails fast on the first mutation
+ *     error (no partial-reap state).
+ *
+ * GraphQL surface note:
+ *   `ProjectV2Workflow` exposes `enabled` as `NON_NULL` but **read-only**
+ *   — GraphQL ships no `updateProjectV2Workflow` mutation at the time
+ *   of this Story. The only programmatic action is
+ *   `deleteProjectV2Workflow`, which is irreversible from the API
+ *   (the operator must re-create deleted built-ins from the GitHub UI).
+ *   If GitHub later adds a toggle mutation, swap delete for toggle in
+ *   {@link reapConflictingWorkflows}.
+ */
+
+/**
+ * Workflows that **must not** be enabled when the orchestrator owns
+ * the Status column. Each entry writes Status as a side-effect of an
+ * event the orchestrator already handles (close, PR merge, PR link),
+ * and the bot's write typically arrives *after* the orchestrator's
+ * — clobbering the intended terminal state.
+ *
+ * Names match GitHub's built-in `ProjectV2Workflow.name` literals.
+ */
+export const CONFLICTING_WORKFLOWS = Object.freeze([
+  'Pull request merged',
+  'Pull request linked to issue',
+]);
+
+/**
+ * Workflows that are safe to leave on. Either they don't touch the
+ * Status column, or they touch it in a way the orchestrator's writes
+ * agree with (`Item closed` sets Status to `Done`, which matches
+ * `agent::done`).
+ *
+ * Surfaced informationally in the audit envelope so operators can see
+ * what was inspected without re-querying.
+ */
+export const COMPATIBLE_WORKFLOWS = Object.freeze([
+  'Item closed',
+  'Item added to project',
+  'Auto-add to project',
+  'Auto-add sub-issues to project',
+  'Auto-close issue',
+]);
+
+const CONFLICTING_SET = new Set(CONFLICTING_WORKFLOWS);
+const COMPATIBLE_SET = new Set(COMPATIBLE_WORKFLOWS);
+
+const LIST_WORKFLOWS_QUERY = `
+  query($projectId: ID!) {
+    node(id: $projectId) {
+      ... on ProjectV2 {
+        workflows(first: 50) {
+          nodes { id name number enabled }
+        }
+      }
+    }
+  }`;
+
+const DELETE_WORKFLOW_MUTATION = `
+  mutation($workflowId: ID!) {
+    deleteProjectV2Workflow(input: { workflowId: $workflowId }) {
+      projectV2 { id }
+    }
+  }`;
+
+/**
+ * Classify a single workflow row against the allowlists.
+ *
+ * Pure helper — exported for test pinning.
+ *
+ * @param {{ name: string, enabled: boolean }} workflow
+ * @returns {'conflicting'|'compatible'|'unknown'|'disabled-conflicting'|'disabled-other'}
+ */
+export function classifyWorkflow(workflow) {
+  const name = workflow?.name ?? '';
+  const enabled = workflow?.enabled === true;
+  if (CONFLICTING_SET.has(name)) {
+    return enabled ? 'conflicting' : 'disabled-conflicting';
+  }
+  if (COMPATIBLE_SET.has(name)) {
+    return 'compatible';
+  }
+  return enabled ? 'unknown' : 'disabled-other';
+}
+
+/**
+ * Query the project's built-in workflows and classify each one. Returns
+ * a structured envelope the bootstrap step can render and the reap
+ * helper can act on.
+ *
+ * @param {{
+ *   provider: { graphql: Function },
+ *   projectId: string,
+ * }} args
+ * @returns {Promise<{
+ *   projectId: string,
+ *   total: number,
+ *   conflicting: Array<{ id: string, name: string, number: number }>,
+ *   compatible: Array<{ id: string, name: string, number: number }>,
+ *   unknown: Array<{ id: string, name: string, number: number }>,
+ *   disabled: Array<{ id: string, name: string, number: number }>,
+ * }>}
+ */
+export async function auditProjectWorkflows(args) {
+  const { provider, projectId } = args ?? {};
+  if (!provider || typeof provider.graphql !== 'function') {
+    throw new TypeError(
+      'auditProjectWorkflows requires a provider with graphql',
+    );
+  }
+  if (typeof projectId !== 'string' || projectId.length === 0) {
+    throw new TypeError('auditProjectWorkflows requires a non-empty projectId');
+  }
+  const data = await provider.graphql(LIST_WORKFLOWS_QUERY, { projectId });
+  const nodes = data?.node?.workflows?.nodes ?? [];
+  const conflicting = [];
+  const compatible = [];
+  const unknown = [];
+  const disabled = [];
+  for (const node of nodes) {
+    const row = { id: node.id, name: node.name, number: node.number };
+    const klass = classifyWorkflow(node);
+    if (klass === 'conflicting') conflicting.push(row);
+    else if (klass === 'compatible') compatible.push(row);
+    else if (klass === 'unknown') unknown.push(row);
+    else disabled.push(row);
+  }
+  return {
+    projectId,
+    total: nodes.length,
+    conflicting,
+    compatible,
+    unknown,
+    disabled,
+  };
+}
+
+/**
+ * Delete every workflow in the audit's `conflicting` set. Fails fast on
+ * the first mutation error — leaves the remaining workflows untouched
+ * rather than producing a partially-reaped board, because the operator
+ * cannot easily tell which workflows were deleted versus which were
+ * preserved when looking at the post-failure board state.
+ *
+ * Returns the per-workflow outcome so callers can log a deterministic
+ * summary even on partial success (the failure path will throw, but the
+ * happy path returns the full ordered list for printing).
+ *
+ * @param {{
+ *   provider: { graphql: Function },
+ *   audit: ReturnType<typeof auditProjectWorkflows> extends Promise<infer R> ? R : never,
+ * }} args
+ * @returns {Promise<{ reaped: Array<{ id: string, name: string }> }>}
+ */
+export async function reapConflictingWorkflows(args) {
+  const { provider, audit } = args ?? {};
+  if (!provider || typeof provider.graphql !== 'function') {
+    throw new TypeError(
+      'reapConflictingWorkflows requires a provider with graphql',
+    );
+  }
+  if (!audit || !Array.isArray(audit.conflicting)) {
+    throw new TypeError(
+      'reapConflictingWorkflows requires an audit envelope with .conflicting[]',
+    );
+  }
+  const reaped = [];
+  for (const wf of audit.conflicting) {
+    try {
+      await provider.graphql(DELETE_WORKFLOW_MUTATION, { workflowId: wf.id });
+      reaped.push({ id: wf.id, name: wf.name });
+    } catch (err) {
+      throw new Error(
+        `[workflow-audit] Failed to delete workflow "${wf.name}" (id=${wf.id}): ${err?.message ?? err}. ` +
+          `${reaped.length} workflow(s) were already deleted before this failure: ${
+            reaped.map((r) => r.name).join(', ') || '(none)'
+          }.`,
+      );
+    }
+  }
+  return { reaped };
+}
+
+/**
+ * Resolve a Project v2 node id from a project number against the viewer
+ * scope. Used by the bootstrap CLI to convert the resolver's
+ * `projectNumber` into the node id required by
+ * {@link auditProjectWorkflows}. Returns `null` when the viewer cannot
+ * see the project (e.g. missing scope, project not under viewer) so the
+ * caller can degrade gracefully.
+ *
+ * @param {{ provider: { graphql: Function }, projectNumber: number }} args
+ * @returns {Promise<string|null>}
+ */
+export async function resolveProjectIdByNumber(args) {
+  const { provider, projectNumber } = args ?? {};
+  if (!provider || typeof provider.graphql !== 'function') {
+    throw new TypeError(
+      'resolveProjectIdByNumber requires a provider with graphql',
+    );
+  }
+  if (!Number.isInteger(projectNumber) || projectNumber <= 0) {
+    throw new TypeError(
+      'resolveProjectIdByNumber requires a positive integer projectNumber',
+    );
+  }
+  try {
+    const data = await provider.graphql(
+      `query($n: Int!) { viewer { projectV2(number: $n) { id } } }`,
+      { n: projectNumber },
+    );
+    return data?.viewer?.projectV2?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a human-readable summary line for the audit. Pure — exported
+ * so the bootstrap CLI and tests share the same formatting.
+ *
+ * @param {Awaited<ReturnType<typeof auditProjectWorkflows>>} audit
+ * @returns {string}
+ */
+export function formatAuditSummary(audit) {
+  const c = audit.conflicting.length;
+  const ok = audit.compatible.length;
+  const u = audit.unknown.length;
+  const d = audit.disabled.length;
+  return `workflows: ${audit.total} scanned — ${c} conflicting, ${ok} compatible, ${u} unknown, ${d} disabled`;
+}