@gobing-ai/spur 0.3.80 → 0.3.82

package/plugins/sp/scripts/quality-gate.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/quality-gate.ts
+import { spawnSync } from "child_process";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+var MAX_GATE_ATTEMPTS = 5;
+var MAX_FINDINGS = 20;
+var RETRY_DELAY_MS_DEFAULT = 1e4;
+var RETRY_DELAY_MS_ENV = "SPUR_QUALITY_GATE_RETRY_DELAY_MS";
+var LOCKED_PATTERN = /SQLiteError: database is locked|SQLite database .*is busy|SQLITE_BUSY/;
+var FINDINGS_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
+var COVERAGE_ROW_PATTERN = /^\s*(\S+\.[A-Za-z]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*(\S*)/;
+function isTransientLock(attemptOutput) {
+  return LOCKED_PATTERN.test(attemptOutput);
+}
+function extractFindings(logText) {
+  const found = new Set;
+  for (const match of logText.matchAll(FINDINGS_PATTERN))
+    found.add(match[0]);
+  return [...found].sort().slice(0, MAX_FINDINGS).map((anchor) => `${anchor} `).join("");
+}
+function tailLines(text, count) {
+  const lines = text.split(`
+`);
+  if (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  const tail = lines.slice(Math.max(0, lines.length - count));
+  return tail.length === 0 ? "" : `${tail.join(`
+`)}
+`;
+}
+function retryMessage(attempt) {
+  return `quality gate: database is locked; retrying (${attempt}/${MAX_GATE_ATTEMPTS}) in 10s
+`;
+}
+function parseCoverageThreshold(bunfigText) {
+  const block = bunfigText.match(/coverageThreshold\s*=\s*\{([^}]*)\}/);
+  if (!block)
+    return null;
+  const threshold = {};
+  for (const axis of ["functions", "lines"]) {
+    const raw = block[1]?.match(new RegExp(`\\b${axis}\\s*=\\s*([\\d.]+)`))?.[1];
+    const value = raw === undefined ? Number.NaN : Number.parseFloat(raw);
+    if (Number.isFinite(value))
+      threshold[axis] = value;
+  }
+  return threshold.functions === undefined && threshold.lines === undefined ? null : threshold;
+}
+function scanCoverageShortfalls(logText, threshold) {
+  const shortfalls = new Map;
+  for (const line of logText.split(`
+`)) {
+    const row = line.match(COVERAGE_ROW_PATTERN);
+    if (!row)
+      continue;
+    const [, path, funcs, lines, uncovered] = row;
+    if (!path || path === "All files" || shortfalls.has(path))
+      continue;
+    const belowFunctions = threshold.functions !== undefined && Number.parseFloat(funcs ?? "") < threshold.functions * 100;
+    const belowLines = threshold.lines !== undefined && Number.parseFloat(lines ?? "") < threshold.lines * 100;
+    if (!belowFunctions && !belowLines)
+      continue;
+    const firstUncovered = uncovered?.match(/\d+/)?.[0] ?? "1";
+    shortfalls.set(path, `quality gate: coverage shortfall ${path}:${firstUncovered} funcs=${funcs} lines=${lines}`);
+  }
+  return [...shortfalls.values()];
+}
+function retryDelayMs(env) {
+  const raw = Number.parseInt(env[RETRY_DELAY_MS_ENV] ?? "", 10);
+  return Number.isFinite(raw) && raw >= 0 ? raw : RETRY_DELAY_MS_DEFAULT;
+}
+function gateSleep(ms) {
+  if (ms > 0)
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function runShellCommand(cmd, cwd) {
+  const dir = mkdtempSync(join(tmpdir(), "spur-quality-gate-"));
+  const path = join(dir, "output");
+  const fd = openSync(path, "w");
+  try {
+    const result = spawnSync("sh", ["-c", cmd], { cwd, stdio: ["ignore", fd, fd] });
+    if (result.error !== undefined) {
+      return { output: `sh -c failed: ${result.error.message}
+`, code: 1 };
+    }
+    return { output: readFileSync(path, "utf8"), code: result.status ?? 1 };
+  } finally {
+    closeSync(fd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+function runQualityGate(mode, env, options = {}) {
+  const cwd = options.cwd;
+  const runDir = join(".spur", "run");
+  mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+  const rel = (name) => join(runDir, `${env.wbs}${name}`);
+  const logFile = rel("-test-gate.log");
+  const findingsFile = rel("-test-gate.findings");
+  const statusFile = rel("-test-gate.status");
+  const attemptFile = rel("-test-fix-attempt");
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  writeFileSync(abs(logFile), "");
+  if (mode === "run")
+    writeFileSync(abs(attemptFile), `0
+`);
+  let gateRc = 0;
+  let gateAttempt = 0;
+  if (mode === "recheck" && (env.gateProbeCmd ?? "").length > 0) {
+    const probe = runShellCommand(env.gateProbeCmd ?? "", cwd);
+    writeFileSync(abs(`${logFile}.probe`), probe.output);
+    gateRc = probe.code;
+    appendFileSync(abs(logFile), probe.output);
+    rmSync(abs(`${logFile}.probe`), { force: true });
+  }
+  if (gateRc === 0) {
+    const delayMs = retryDelayMs(env);
+    for (gateAttempt = 1;gateAttempt <= MAX_GATE_ATTEMPTS; gateAttempt++) {
+      const attemptLogPath = `${logFile}.attempt-${gateAttempt}`;
+      const attempt = runShellCommand(env.qualityGateCmd ?? "", cwd);
+      writeFileSync(abs(attemptLogPath), attempt.output);
+      const locked = isTransientLock(attempt.output);
+      appendFileSync(abs(logFile), attempt.output);
+      rmSync(abs(attemptLogPath), { force: true });
+      gateRc = attempt.code;
+      if (gateRc === 0 || !locked || gateAttempt >= MAX_GATE_ATTEMPTS)
+        break;
+      const line = retryMessage(gateAttempt);
+      process.stdout.write(line);
+      appendFileSync(abs(logFile), line);
+      gateSleep(delayMs);
+    }
+  }
+  if (gateRc !== 0) {
+    const gateLog = existsSync(abs(logFile)) ? readFileSync(abs(logFile), "utf8") : "";
+    if (/^\s*0 fail\b/m.test(gateLog) && !/^\s*[1-9]\d*\s+fail\b/m.test(gateLog)) {
+      const bunfigPath = cwd ? join(cwd, "bunfig.toml") : "bunfig.toml";
+      const threshold = existsSync(bunfigPath) ? parseCoverageThreshold(readFileSync(bunfigPath, "utf8")) : null;
+      if (threshold) {
+        for (const shortfall of scanCoverageShortfalls(gateLog, threshold)) {
+          process.stdout.write(`${shortfall}
+`);
+          appendFileSync(abs(logFile), `${shortfall}
+`);
+        }
+      }
+    }
+  }
+  if (gateRc === 0) {
+    const bytes = existsSync(abs(logFile)) ? statSync(abs(logFile)).size : 0;
+    const attemptsLabel = gateAttempt > 0 ? String(gateAttempt) : "";
+    process.stdout.write(`quality gate PASS (attempts: ${attemptsLabel}; log: ${logFile}; bytes: ${bytes})
+`);
+  } else {
+    process.stdout.write(`quality gate FAIL \u2014 last 40 lines follow (full log: ${logFile})
+`);
+    process.stdout.write(tailLines(readFileSync(abs(logFile), "utf8"), 40));
+  }
+  writeFileSync(abs(findingsFile), extractFindings(readFileSync(abs(logFile), "utf8")));
+  const status = gateRc === 0 ? "PASS" : "FAIL";
+  writeFileSync(abs(statusFile), `${status}
+`);
+  appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ""}
+`);
+  return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
+}
+var QUALITY_GATE_USAGE = "usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)";
+function main(argv, env = process.env) {
+  const mode = argv[0];
+  if (mode !== "run" && mode !== "recheck") {
+    process.stderr.write(`${QUALITY_GATE_USAGE}
+`);
+    return 2;
+  }
+  if ((env.wbs ?? "").length === 0) {
+    process.stderr.write("quality-gate: env `wbs` is required\n");
+    return 2;
+  }
+  runQualityGate(mode, env);
+  return 0;
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  tailLines,
+  scanCoverageShortfalls,
+  runShellCommand,
+  runQualityGate,
+  retryMessage,
+  parseCoverageThreshold,
+  main,
+  isTransientLock,
+  extractFindings,
+  RETRY_DELAY_MS_ENV,
+  RETRY_DELAY_MS_DEFAULT,
+  QUALITY_GATE_USAGE,
+  MAX_GATE_ATTEMPTS,
+  MAX_FINDINGS,
+  LOCKED_PATTERN,
+  FINDINGS_PATTERN,
+  COVERAGE_ROW_PATTERN
+};

package/plugins/sp/scripts/quality-gate.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env bun
+/**
+ * quality-gate — shared retry/bounded-findings gate behind the task-pipeline test-gate
+ * wrappers (task 0823, feature I21, governance §1.2 composition budgets).
+ *
+ * Reproduces the former task-pipeline `test:onEnter` and `test-recheck:onEnter` shell
+ * programs one-for-one so the workflow stays inside the shell-program caps while
+ * writing the same `.spur/run` artifacts:
+ *   - `<wbs>-test-gate.log`       merged gate attempt output + `proof-digest:` trailer
+ *   - `<wbs>-test-gate.findings`  unique `file.ext:line` anchors, code-unit sorted, capped at 20
+ *   - `<wbs>-test-gate.status`    `PASS`/`FAIL`
+ *   - `<wbs>-test-fix-attempt`    remediation counter, reset to `0` by `run` only
+ *
+ * Modes:
+ *   run     reset the attempt counter, truncate the log, execute the gate loop
+ *   recheck truncate the log, execute the probe first (probe failure is the gate
+ *           failure, the gate loop is skipped), then execute the gate loop
+ *
+ * Retry contract: a failed attempt is retried (up to 5 total attempts) only when its
+ * output matches a SQLite busy/locked error; the delay defaults to 10 seconds and is
+ * overridable via `SPUR_QUALITY_GATE_RETRY_DELAY_MS` (tests).
+ *
+ * Environment: `wbs` (required), `qualityGateCmd`, `gateProbeCmd` (recheck), `proofDigest`.
+ * Soft-fail contract: the process always exits 0; the verdict lives in the status file.
+ *
+ * Node-builtin imports only; pure helpers are exported for unit testing (ADR-065).
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+    appendFileSync,
+    closeSync,
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    openSync,
+    readFileSync,
+    rmSync,
+    statSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export const MAX_GATE_ATTEMPTS = 5;
+export const MAX_FINDINGS = 20;
+export const RETRY_DELAY_MS_DEFAULT = 10_000;
+export const RETRY_DELAY_MS_ENV = 'SPUR_QUALITY_GATE_RETRY_DELAY_MS';
+
+/** Transient SQLite lock/busy markers that justify a gate retry (same as the former grep -Eq). */
+export const LOCKED_PATTERN = /SQLiteError: database is locked|SQLite database .*is busy|SQLITE_BUSY/;
+
+/** `file.ext:line` anchor extraction, mirroring the former grep -oE. */
+export const FINDINGS_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
+
+/**
+ * bun's coverage table row: `File | % Funcs | % Lines | Uncovered Line #s` (0862 R2).
+ * Group 4 (uncovered line numbers) may be empty — a fully covered file has no entry.
+ */
+export const COVERAGE_ROW_PATTERN = /^\s*(\S+\.[A-Za-z]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*(\S*)/;
+
+export interface QualityGateEnv {
+    wbs: string;
+    qualityGateCmd?: string;
+    gateProbeCmd?: string;
+    proofDigest?: string;
+    [key: string]: string | undefined;
+}
+
+export interface QualityGateOptions {
+    /** Base directory for `.spur/run`; defaults to the process cwd (CLI behavior). */
+    cwd?: string;
+}
+
+export interface QualityGateResult {
+    status: 'PASS' | 'FAIL';
+    attempts: number;
+    logFile: string;
+    findingsFile: string;
+    statusFile: string;
+    attemptFile: string;
+}
+
+export function isTransientLock(attemptOutput: string): boolean {
+    return LOCKED_PATTERN.test(attemptOutput);
+}
+
+/** Unique anchors, code-unit sorted, capped at MAX_FINDINGS, each followed by one space. */
+export function extractFindings(logText: string): string {
+    const found = new Set<string>();
+    for (const match of logText.matchAll(FINDINGS_PATTERN)) found.add(match[0]);
+    return [...found]
+        .sort()
+        .slice(0, MAX_FINDINGS)
+        .map((anchor) => `${anchor} `)
+        .join('');
+}
+
+/** `tail -n <count>` on POSIX text: last count lines, newline-terminated. */
+export function tailLines(text: string, count: number): string {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+    const tail = lines.slice(Math.max(0, lines.length - count));
+    return tail.length === 0 ? '' : `${tail.join('\n')}\n`;
+}
+
+export function retryMessage(attempt: number): string {
+    return `quality gate: database is locked; retrying (${attempt}/${MAX_GATE_ATTEMPTS}) in 10s\n`;
+}
+
+/** Per-axis coverage floor from `bunfig.toml`; a missing key leaves that axis unchecked. */
+export interface CoverageThreshold {
+    functions?: number;
+    lines?: number;
+}
+
+/**
+ * Parse `coverageThreshold = { lines = 0.9, functions = 0.9 }` out of bunfig text.
+ * `null` when the setting is absent — the caller then skips the shortfall scan entirely.
+ */
+export function parseCoverageThreshold(bunfigText: string): CoverageThreshold | null {
+    const block = bunfigText.match(/coverageThreshold\s*=\s*\{([^}]*)\}/);
+    if (!block) return null;
+    const threshold: CoverageThreshold = {};
+    for (const axis of ['functions', 'lines'] as const) {
+        const raw = block[1]?.match(new RegExp(`\\b${axis}\\s*=\\s*([\\d.]+)`))?.[1];
+        const value = raw === undefined ? Number.NaN : Number.parseFloat(raw);
+        if (Number.isFinite(value)) threshold[axis] = value;
+    }
+    return threshold.functions === undefined && threshold.lines === undefined ? null : threshold;
+}
+
+/**
+ * One `quality gate: coverage shortfall <path>:<line> funcs=<f> lines=<l>` line per distinct table
+ * row below either axis (thresholds are fractions, table numbers are percentages). `line` is the
+ * first number of the uncovered column, else `1`.
+ */
+export function scanCoverageShortfalls(logText: string, threshold: CoverageThreshold): string[] {
+    const shortfalls = new Map<string, string>();
+    for (const line of logText.split('\n')) {
+        const row = line.match(COVERAGE_ROW_PATTERN);
+        if (!row) continue;
+        const [, path, funcs, lines, uncovered] = row;
+        if (!path || path === 'All files' || shortfalls.has(path)) continue;
+        const belowFunctions =
+            threshold.functions !== undefined && Number.parseFloat(funcs ?? '') < threshold.functions * 100;
+        const belowLines = threshold.lines !== undefined && Number.parseFloat(lines ?? '') < threshold.lines * 100;
+        if (!belowFunctions && !belowLines) continue;
+        const firstUncovered = uncovered?.match(/\d+/)?.[0] ?? '1';
+        shortfalls.set(
+            path,
+            `quality gate: coverage shortfall ${path}:${firstUncovered} funcs=${funcs} lines=${lines}`,
+        );
+    }
+    return [...shortfalls.values()];
+}
+
+function retryDelayMs(env: QualityGateEnv): number {
+    const raw = Number.parseInt(env[RETRY_DELAY_MS_ENV] ?? '', 10);
+    return Number.isFinite(raw) && raw >= 0 ? raw : RETRY_DELAY_MS_DEFAULT;
+}
+
+function gateSleep(ms: number): void {
+    if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** `sh -c <cmd> > <attempt log> 2>&1` equivalent: merged output plus exit code. */
+export function runShellCommand(cmd: string, cwd: string | undefined): { output: string; code: number } {
+    const dir = mkdtempSync(join(tmpdir(), 'spur-quality-gate-'));
+    const path = join(dir, 'output');
+    const fd = openSync(path, 'w');
+    try {
+        // One file descriptor preserves stream order and avoids spawnSync's pipe buffer limit.
+        const result = spawnSync('sh', ['-c', cmd], { cwd, stdio: ['ignore', fd, fd] });
+        if (result.error !== undefined) {
+            return { output: `sh -c failed: ${result.error.message}\n`, code: 1 };
+        }
+        return { output: readFileSync(path, 'utf8'), code: result.status ?? 1 };
+    } finally {
+        closeSync(fd);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+export function runQualityGate(
+    mode: 'run' | 'recheck',
+    env: QualityGateEnv,
+    options: QualityGateOptions = {},
+): QualityGateResult {
+    const cwd = options.cwd;
+    const runDir = join('.spur', 'run');
+    mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+    const rel = (name: string): string => join(runDir, `${env.wbs}${name}`);
+    const logFile = rel('-test-gate.log');
+    const findingsFile = rel('-test-gate.findings');
+    const statusFile = rel('-test-gate.status');
+    const attemptFile = rel('-test-fix-attempt');
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+
+    // run: `echo 0 > "$ATTEMPT_FILE" && : > "$LOG_FILE"`; recheck: truncate only.
+    writeFileSync(abs(logFile), '');
+    if (mode === 'run') writeFileSync(abs(attemptFile), '0\n');
+
+    let gateRc = 0;
+    let gateAttempt = 0;
+
+    // recheck probe: a probe failure is the gate failure; the gate loop is skipped.
+    if (mode === 'recheck' && (env.gateProbeCmd ?? '').length > 0) {
+        const probe = runShellCommand(env.gateProbeCmd ?? '', cwd);
+        writeFileSync(abs(`${logFile}.probe`), probe.output);
+        gateRc = probe.code;
+        appendFileSync(abs(logFile), probe.output);
+        rmSync(abs(`${logFile}.probe`), { force: true });
+    }
+
+    if (gateRc === 0) {
+        const delayMs = retryDelayMs(env);
+        for (gateAttempt = 1; gateAttempt <= MAX_GATE_ATTEMPTS; gateAttempt++) {
+            const attemptLogPath = `${logFile}.attempt-${gateAttempt}`;
+            const attempt = runShellCommand(env.qualityGateCmd ?? '', cwd);
+            writeFileSync(abs(attemptLogPath), attempt.output);
+            const locked = isTransientLock(attempt.output);
+            appendFileSync(abs(logFile), attempt.output);
+            rmSync(abs(attemptLogPath), { force: true });
+            gateRc = attempt.code;
+            if (gateRc === 0 || !locked || gateAttempt >= MAX_GATE_ATTEMPTS) break;
+            const line = retryMessage(gateAttempt);
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(abs(logFile), line);
+            gateSleep(delayMs);
+        }
+    }
+
+    // Coverage-only failures carry no `file.ext:line` anchor, so findings extraction would hand the
+    // fix hop an empty file. Name one shortfall line per under-threshold row instead (0862 R2) —
+    // real test failures, an absent threshold and the exit-0 contract are untouched.
+    if (gateRc !== 0) {
+        const gateLog = existsSync(abs(logFile)) ? readFileSync(abs(logFile), 'utf8') : '';
+        if (/^\s*0 fail\b/m.test(gateLog) && !/^\s*[1-9]\d*\s+fail\b/m.test(gateLog)) {
+            const bunfigPath = cwd ? join(cwd, 'bunfig.toml') : 'bunfig.toml';
+            const threshold = existsSync(bunfigPath) ? parseCoverageThreshold(readFileSync(bunfigPath, 'utf8')) : null;
+            if (threshold) {
+                for (const shortfall of scanCoverageShortfalls(gateLog, threshold)) {
+                    process.stdout.write(`${shortfall}\n`); // tee: stdout and the log
+                    appendFileSync(abs(logFile), `${shortfall}\n`);
+                }
+            }
+        }
+    }
+
+    if (gateRc === 0) {
+        const bytes = existsSync(abs(logFile)) ? statSync(abs(logFile)).size : 0;
+        const attemptsLabel = gateAttempt > 0 ? String(gateAttempt) : '';
+        process.stdout.write(`quality gate PASS (attempts: ${attemptsLabel}; log: ${logFile}; bytes: ${bytes})\n`);
+    } else {
+        process.stdout.write(`quality gate FAIL — last 40 lines follow (full log: ${logFile})\n`);
+        process.stdout.write(tailLines(readFileSync(abs(logFile), 'utf8'), 40));
+    }
+
+    writeFileSync(abs(findingsFile), extractFindings(readFileSync(abs(logFile), 'utf8')));
+    const status: 'PASS' | 'FAIL' = gateRc === 0 ? 'PASS' : 'FAIL';
+    writeFileSync(abs(statusFile), `${status}\n`);
+    appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ''}\n`);
+
+    return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
+}
+
+export const QUALITY_GATE_USAGE =
+    'usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)';
+
+export function main(argv: string[], env: QualityGateEnv = process.env): number {
+    const mode = argv[0];
+    if (mode !== 'run' && mode !== 'recheck') {
+        process.stderr.write(`${QUALITY_GATE_USAGE}\n`);
+        return 2;
+    }
+    if ((env.wbs ?? '').length === 0) {
+        process.stderr.write('quality-gate: env `wbs` is required\n');
+        return 2;
+    }
+    runQualityGate(mode, env);
+    return 0;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/surface-drift-inventory.ts

@@ -235,7 +235,6 @@ export function nounOfReference(file: string): string | null {
         workflows: 'workflow',
         agent: 'agent',
         message: 'message',
-        team: 'team',
         init: 'init',
         serve: 'serve',
     };
@@ -641,7 +640,6 @@ const JSON_PROBES: string[][] = [
     ['workflow', 'list', '--json'],
     ['workflow', 'validate', 'basic.yaml', '--json'],
     ['status', '--json'],
-    ['team', 'status', '--json'],
     ['projects', 'list', '--json'],
 ];
 

package/plugins/sp/scripts/task-size-precheck.ts

@@ -27,13 +27,50 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-// ─── Regex (sync with packages/app/src/services/task-size-precheck.ts) ───────
+// ─── Counting (sync with packages/app/src/services/task-size-precheck.ts) ────
 
-/** Matches `- [ ] **R1.**` or `- [x] R1.` etc. Requires period after digits. */
-const R_ITEM_RE = /^\s*-\s*\[[ xX]\]\s*(\*\*)?R\d+\./m;
+/**
+ * Requirement item: list marker required, then an optional checkbox, then the R-number in the
+ * house `- **R1** — <text>` or legacy `- [ ] R1. <text>` form. A bare `R1 <text>` line is prose.
+ */
+const R_ITEM_RE_SOURCE = '^\\s*[-*]\\s+(?:\\[[ xX]\\]\\s*)?[*_]{0,2}R(\\d+)\\.?[*_]{0,2}(?:\\s|$)';
+
+/** Top-level numbered Plan step (`1. <text>`). */
+const NUMBERED_PLAN_ITEM_RE_SOURCE = '^\\d+\\.\\s';
+
+/** Checklist Plan item (`- [ ] <text>`, `- [x] <text>`). */
+const CHECKLIST_ITEM_RE_SOURCE = '^\\s*[-*]\\s+\\[[ xX]\\]';
+
+/**
+ * Body of a `##`/`###` section (heading line excluded), up to the next `##`/`###` heading.
+ * `null` when the heading is absent — callers decide the fallback.
+ */
+function sectionBody(content: string, headingPattern: string): string | null {
+    const heading = content.match(new RegExp(headingPattern, 'm'));
+    if (!heading) return null;
+    const rest = content.slice((heading.index ?? 0) + heading[0].length);
+    const nextHeading = rest.match(/^#{2,3}\s+/m);
+    return nextHeading ? rest.slice(0, nextHeading.index ?? 0) : rest;
+}
+
+/** Distinct R-items in `## Requirements` (whole content when the heading is absent). */
+function countRItems(taskContent: string): number {
+    const body = sectionBody(taskContent, '^#{2,3}\\s+Requirements\\s*$') ?? taskContent;
+    const numbers = new Set<string>();
+    for (const match of body.matchAll(new RegExp(R_ITEM_RE_SOURCE, 'gm'))) {
+        numbers.add(match[1] ?? '');
+    }
+    return numbers.size;
+}
 
-/** Matches checklist items under the Plan section. */
-const CHECKLIST_ITEM_RE = /^\s*-\s*\[[ xX]\]/m;
+/** Plan items: top-level numbered steps plus checklist items under `## Plan`. */
+function countPlanItems(taskContent: string): number {
+    const body = sectionBody(taskContent, '^#{2,3}\\s+Plan\\s*$');
+    if (body === null) return 0;
+    const numbered = body.match(new RegExp(NUMBERED_PLAN_ITEM_RE_SOURCE, 'gm'))?.length ?? 0;
+    const checklist = body.match(new RegExp(CHECKLIST_ITEM_RE_SOURCE, 'gm'))?.length ?? 0;
+    return numbered + checklist;
+}
 
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
@@ -128,17 +165,8 @@ function main(): void {
         process.exit(0);
     }
 
-    const reqCount = taskContent.match(new RegExp(R_ITEM_RE.source, 'gm'))?.length ?? 0;
-
-    const planMatch = taskContent.match(/^#{2,3}\s+Plan\s*$/m);
-    const planBody = planMatch
-        ? (() => {
-              const rest = taskContent.slice((planMatch.index ?? 0) + planMatch[0].length);
-              const nextSection = rest.match(/^#{2,3}\s+/m);
-              return nextSection ? rest.slice(0, nextSection.index ?? 0) : rest;
-          })()
-        : '';
-    const planItemCount = planBody.match(new RegExp(CHECKLIST_ITEM_RE.source, 'gm'))?.length ?? 0;
+    const reqCount = countRItems(taskContent);
+    const planItemCount = countPlanItems(taskContent);
 
     const reasons: string[] = [];
     if (reqCount > maxReqs) {

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -298,6 +298,11 @@ function normalizeAcTitle(title: string): string {
             // U+02BC stays a meaningful character, never removable punctuation.
             .replace(/[\u0027\u2018\u2019\u201c\u201d]/g, '')
             .replace(/\s+/g, ' ')
+            // A declared bold head keeps its sentence-final period (`- **AC1: … form.**`) while an
+            // answer row normally cites it without one. Both the declared spelling and the queried
+            // row normalize through here, so dropping it is symmetric — it can only merge titles
+            // that already differ by nothing but trailing periods.
+            .replace(/\s*\.+$/, '')
             .trim()
     );
 }
@@ -332,6 +337,16 @@ function buildAcIdentityIndex(taskContent: string, featureContent: string | null
         const leading = label.split(/\s+/)[0] ?? '';
         if (leading && leading !== label) declareIdentity(leading);
     }
+    // Bold head of a single-line criterion bullet (task 0862 R4): the bold span and its
+    // head before the first ` — ` / `:` are declared ids, so `- **AC2 — Title.** Given …`
+    // answers to both `AC2` and the full bold title.
+    for (const m of section.matchAll(/^[-*]\s+(?:\[[ xX]\]\s+)?\*\*(.+?)\*\*/gm)) {
+        const inner = (m[1] ?? '').trim();
+        if (!inner) continue;
+        declareIdentity(inner);
+        const head = inner.split(/\s+[—–]\s+|:/)[0]?.trim() ?? '';
+        if (head && head !== inner) declareIdentity(head);
+    }
     // Bold-trajectory form (task 0817 R3): answers may cite an AC by a bare
     // `**AC id**` paragraph (house style for long/complex ids). Only whole-line
     // bold spans count — the line-anchored lazy regex rejects lines with two
@@ -492,7 +507,8 @@ function main(): void {
             else
                 add(
                     `line ${row.line}: AC ID "${row.id.slice(0, 60)}" matches no task AC checklist label or scenario title ` +
-                        '(accepted forms: exact title, bare title, `Scenario:` prefix, bracket tags, declared AC-N alias)',
+                        "(accepted forms: exact title, bare title, a criterion bullet's bold head or full bold span, " +
+                        '`Scenario:` prefix, bracket tags, declared AC-N alias)',
                 );
         } else if (canonicalKey !== null && seenAc.has(canonicalKey)) {
             const first = seenAc.get(canonicalKey) ?? '';