pi-aia-asf 0.13.5 → 0.14.1

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-11-04
+
+### Added
+
+- (describe changes for 0.14.1)
+
+## [0.14.0] - 2026-11-02
+
+### Added
+
+- **Zero-context reviewer pass** (Phase 4 and Phase 7, large work): six read-only reviewer
+  personas in `skills/aia-asf/agents/` (`design-critic`, `codebase-fitness`, `zoom-out`,
+  `comprehension`, `implementation-readiness`, `structural`) plus a `synthesizer`, each
+  invoked separately, each answering in a fixed finding format (`Blocker | Major | Nit`,
+  scope, rationale, recommendation), critique-first and cite-or-abstain. Reviewers are
+  given the artifact and the acceptance criteria only — never the conversation that
+  produced it.
+- `lib/review.mjs` — the review guards as code rather than as prose: citation verification
+  (a report whose cited file or line range does not resolve is recorded `not run`, **never**
+  "zero findings"), the per-reviewer status table, the finding schema with dedup and
+  severity ordering, and A/B duplication permitted only at the blocker boundary. The
+  citation guard exists because a read-only subagent was observed reporting a confident
+  reading of a file that was never asked for, and exiting 0.
+- `lib/parallel-estimate.mjs` — the serial/parallel decision computed from file ownership,
+  interface ownership, dependency cycles, serial cost and a bounded schedule. Parallel
+  requires no conflicts, at least 3 fully independent packages and a speed-up of 1.3×; a
+  job under 30 serial minutes is refused outright, and a refusal is a recorded decision
+  rather than an omission. Also carries the P47 switch (`readParallelSwitch`: default OFF,
+  `ASF_PARALLEL=1` for one run that does not persist) and the join contract: one lane, the
+  full suite after the rebase, no merge conflict resolved by a model, no thread resolving
+  its own ticket.
+- `lib/gates/drift.mjs` — task-scoped drift: the claims this task's own artifacts make
+  about files and symbols are resolved against the code. `no-claims` and `no-artifacts`
+  are reported as examined-nothing, never as clean, and only a stale claim blocks.
+- `scripts/audit-docs.mjs` — ASF audits its own normative content: relative links, anchors,
+  index/directory agreement, routing ("Read when" or an index row) and frontmatter.
+- `lib/skill-budget.mjs` + `test/test-skill-budget.mjs` — an always-read byte ceiling with a
+  rule-preservation check: procedure, tables and examples may move out of the always-read
+  files; a rule statement may not, and a split that drops one fails the suite.
+- `references/06m-antipatterns.md` (the complete forbidden list, with a short always-read
+  floor left in `SKILL.md`) and `references/06b-appendix.md` (the Rule 9 browser procedure
+  and Rule 15 enforcement-class detail).
+- `references/05-plan.md` — a work-package table (files owned, interfaces needed and
+  provided, depends on, estimated minutes) and a required parallel verdict with its reason,
+  recorded even when the answer is serial.
+- Rebuilt `test/test-antipatterns.mjs`, `test/test-parallel-switch.mjs` and
+  `test/test-operator-surface.mjs` — these had been in the working tree, were never
+  committed, and are gone; they are rewritten against the modules they guard. Added
+  `test/test-review-guards.mjs`, `test/test-docs-integrity.mjs`,
+  `test/test-skill-budget.mjs`, and task-scoped drift coverage in
+  `test/test-improvements.mjs`. Every new guard ships with a control that must fail.
+
+### Changed
+
+- The always-read set is 74,777 bytes across `SKILL.md` and the three mandatory references,
+  down from 88,515 (−15.5%), with the per-file ceilings and their reasons recorded in
+  `lib/skill-budget.mjs` rather than as a bare number. `SKILL.md` itself went 36,931 →
+  25,689 bytes; the reduction is duplicated procedure and the forbidden list, not rules.
+- Phase 5 presents `PLAN.md` as an artifact (path plus decision summary) instead of pasting
+  the plan into chat; Phase 4 now states a reviewer budget (6 reviewers, 2 re-audits, 3
+  concurrent, stop and report at 6× the serial token estimate) so thoroughness is bounded
+  without being thin.
+
+### Fixed
+
+- `references/06k-performance.md` linked to a research document that is not in the package —
+  a dangling link that no test could see until the doc audit was added.
+
 ## [0.13.5] - 2026-10-18
 
 ### Added

package/index.ts

@@ -827,8 +827,18 @@ export default function register(pi: ExtensionAPI): void {
   // as final and notification-only, while `agent_before_settle` is the final
   // actionable boundary. And nothing here awaits a resumed run: the loop guard
   // documents a production hang caused by exactly that.
-  pi.on("agent_before_settle", () => {
+  pi.on("agent_before_settle", async () => {
     try {
+      // The completion gate belongs to an ASF run. Without this check it judged
+      // every session that happened to load ASF — a plain question in a scratch
+      // directory was held to the same evidence bar as a delivered feature.
+      // While pi refused a contentless continuation the gate was inert and
+      // nobody noticed; once the continuation actually resumed the run, the
+      // gate began interrupting work that never asked for ASF. An ASF run is
+      // active when /asf has set a phase for this project and it has not ended.
+      const state = await loadState(projectName());
+      if (!state.current || state.current.phase === "none") return undefined;
+
       const decision = decideSettlement(ledger, {
         scale: currentScale(),
         webTouched,
@@ -845,7 +855,31 @@ export default function register(pi: ExtensionAPI): void {
         continuationsRequested++;
         // One bounded continuation naming exactly what is missing. No UI prompt:
         // this sends the agent back to work, it does not ask anyone anything.
-        return { continue: true };
+        //
+        // The continuation MUST carry content. pi commits `entries` and only
+        // then re-checks whether the context can run another provider request;
+        // at settle time the context ends with the assistant's own message, so
+        // a bare `{ continue: true }` is refused with
+        // "agent_before_settle requested continuation without runnable model
+        // context" and the agent is never told what was missing. A
+        // `custom_message` entry projects to a user-role message, which is what
+        // makes the next request runnable — and it is the only thing that can
+        // deliver the missing list to the model.
+        const list = decision.missing.map((item: string) => `- ${item}`).join("\n");
+        return {
+          entries: [
+            {
+              type: "custom_message",
+              customType: "asf-completion-gate",
+              content:
+                `ASF completion gate: this run cannot settle yet. Missing:\n${list}\n\n` +
+                `Close these now, then let the run settle. Bounded: continuation ${continuationsRequested} of ${MAX_CONTINUATIONS}.`,
+              display: true,
+              details: { missing: decision.missing, continuation: continuationsRequested },
+            },
+          ],
+          continue: true,
+        };
       }
       return undefined;
     } catch {

package/lib/gates/drift.mjs

@@ -0,0 +1,159 @@
+/**
+ * Task-scoped drift (W2.1).
+ *
+ * Repo-wide documentation drift was considered and rejected: it presumes the
+ * documentation exists and is maintained, and products legitimately evolve, so a
+ * repo-wide check produces permanent noise that gets switched off — which is worse
+ * than never having it. What is checked instead is narrower and always available:
+ * the claims THIS task wrote about itself (its PLAN.md, its captured specs, its
+ * design document) against the code as it stands now.
+ *
+ * That is the same claim/evidence split as everywhere else in ASF: an artifact that
+ * names `lib/gates/ledger.mjs` or `deriveSuiteRun()` is making a checkable assertion.
+ * If the file is gone or the symbol no longer exists, the artifact is stale and the
+ * delivery report is describing something that is not there.
+ *
+ * A scan that extracts no claims is reported as such. "Nothing found" and "nothing
+ * looked at" are different results, and conflating them is how a guard goes green
+ * while doing nothing.
+ */
+
+const SOURCE_EXT = /\.(ts|mts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|swift|c|cc|cpp|h|hpp|rb|php|sh|sql|json|yaml|yml)$/i;
+const BACKTICK = /`([^`\n]{2,140})`/g;
+
+/**
+ * Pull the checkable assertions out of an artifact.
+ * Kinds:
+ *   file   — a backticked path (contains "/" or carries a source/document extension)
+ *   symbol — a backticked identifier, optionally call-shaped `foo()` or `Foo#bar`
+ */
+export function extractClaims(text) {
+  const claims = [];
+  const seen = new Set();
+  let m;
+  let line = 1;
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    BACKTICK.lastIndex = 0;
+    let mm;
+    while ((mm = BACKTICK.exec(lines[i]))) {
+      const raw = mm[1].trim();
+      if (!raw || /\s/.test(raw) && !/^\w+#\w+$/.test(raw)) continue;
+      const cleaned = raw.replace(/^\.\//, "").replace(/:[0-9]+(-[0-9]+)?$/, "");
+      const isPath = cleaned.includes("/") || /\.[a-z0-9]{1,6}$/i.test(cleaned);
+      const isSymbol = /^[A-Za-z_$][\w$]*(\([^)]*\))?$/.test(cleaned) || /^\w+#\w+$/.test(cleaned);
+      if (!isPath && !isSymbol) continue;
+      const kind = isPath && !cleaned.endsWith("()") ? "file" : "symbol";
+      const value = cleaned.replace(/\(\)$/, "");
+      const key = `${kind}:${value}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      claims.push({ kind, value, line: i + 1, raw });
+    }
+  }
+  return claims;
+}
+
+function walk(dir, fs, out = [], depth = 0) {
+  if (depth > 8) return out;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name === ".git" || e.name === "node_modules" || e.name === "dist" || e.name === "coverage") continue;
+    const p = `${dir}/${e.name}`;
+    if (e.isDirectory()) walk(p, fs, out, depth + 1);
+    else if (SOURCE_EXT.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * @param {object} input
+ * @param {Array<{path:string, text:string}>} input.artifacts  the task's own artifacts
+ * @param {string} input.repoRoot
+ * @param {object} input.fs                                     injectable for tests
+ * @param {string[]} [input.ignore]                             claim values to skip (documented exceptions)
+ */
+export function checkDrift({ artifacts = [], repoRoot, fs, ignore = [] }) {
+  const ignored = new Set(ignore);
+  const sources = walk(repoRoot, fs);
+  const sourceSet = new Set(sources.map((p) => p.replace(`${repoRoot}/`, "")));
+  const symbolCache = new Map();
+  const hasSymbol = (name) => {
+    if (symbolCache.has(name)) return symbolCache.get(name);
+    const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+    for (const f of sources) {
+      let body = "";
+      try {
+        body = fs.readFileSync(f, "utf8");
+      } catch {
+        continue;
+      }
+      if (re.test(body)) {
+        symbolCache.set(name, true);
+        return true;
+      }
+    }
+    symbolCache.set(name, false);
+    return false;
+  };
+
+  const claims = [];
+  const unresolved = [];
+  const unread = [];
+  for (const artifact of artifacts) {
+    // An artifact may be handed over with its text, or named by path — and an artifact
+    // that could not be read is examined-nothing, never a clean result.
+    let text = artifact.text;
+    if (text === undefined && artifact.path) {
+      try {
+        text = fs.readFileSync(`${repoRoot}/${artifact.path}`.replace("//", "/"), "utf8");
+      } catch {
+        text = undefined;
+      }
+    }
+    if (text === undefined) {
+      unread.push(artifact.path || "(unnamed artifact)");
+      continue;
+    }
+    for (const c of extractClaims(text)) {
+      if (ignored.has(c.value)) continue;
+      claims.push({ ...c, artifact: artifact.path });
+      const ok = c.kind === "file" ? sourceSet.has(c.value) : hasSymbol(c.value);
+      if (!ok) unresolved.push({ ...c, artifact: artifact.path });
+    }
+  }
+
+  const checked = claims.length;
+  return {
+    checked,
+    unresolved,
+    // A scan that looked at nothing is not a clean scan. Reported separately so a
+    // caller cannot mistake "0 unresolved" for "the artifact still matches the code".
+    unread,
+    status: checked === 0 ? (unread.length ? "no-artifacts" : "no-claims") : unresolved.length ? "drift" : "clean",
+    // Only a stale claim blocks the document-accuracy tick. "no-claims" and
+    // "no-artifacts" are examined-nothing: they never block, and they never tick.
+    blocking: unresolved.length > 0,
+    sourcesScanned: sources.length,
+  };
+}
+
+/**
+ * Render the finding the way the delivery report wants it: name the artifact and the
+ * stale claim, so the operator can act without re-reading the document.
+ */
+export function renderDrift(result) {
+  if (result.status === "no-claims") {
+    return "drift: no checkable claims were found in the task artifacts — this is not a pass, the artifact names no files or symbols";
+  }
+  if (!result.unresolved.length) return `drift: clean — ${result.checked} claim(s) in the task artifacts all resolve against the source`;
+  return [
+    `drift: ${result.unresolved.length} of ${result.checked} claim(s) in the task artifacts no longer resolve:`,
+    ...result.unresolved.map((u) => `  ${u.artifact}:${u.line} — ${u.kind} ${u.value}`),
+  ].join("\n");
+}

package/lib/parallel-estimate.mjs

@@ -0,0 +1,241 @@
+/**
+ * Parallel-execution estimator (W3.1).
+ *
+ * ASF's rule is that parallel implementation is a decision, not an enthusiasm. The
+ * decision needs numbers, so this computes them: the serial cost, the critical path
+ * under a concurrency cap, the speed-up that cap actually yields, and the conflicts
+ * that forbid parallelism in the first place.
+ *
+ * Two kinds of conflict are checked, because file disjointness alone is not
+ * independence. Agents working on disjoint files still break each other when they
+ * both touch a shared interface — the silent semantic drift a merge queue cannot see.
+ * So a shared interface that neither package declares as provided counts as a
+ * dependency, and the answer is serial.
+ *
+ * Nothing here spawns anything. It answers "is this worth parallelising" and returns
+ * the reasons either way, so a refusal is recorded rather than silently omitted.
+ */
+
+const MIN_SPEEDUP = 1.3;
+const MIN_INDEPENDENT = 3;
+
+/**
+ * @param {object} input
+ * @param {Array<{id:string, files:string[], interfacesNeeded?:string[], interfacesProvided?:string[], dependsOn?:string[], minutes:number}>} input.packages
+ * @param {number} [input.maxConcurrent]
+ */
+export function estimateParallelism({ packages = [], maxConcurrent = 3 }) {
+  const reasons = [];
+  const errors = [];
+
+  if (!Array.isArray(packages) || packages.length === 0) {
+    return { verdict: "serial", speedup: 1, reasons: ["no work packages declared"], conflicts: [], errors: ["packages is empty"] };
+  }
+
+  const byId = new Map();
+  for (const p of packages) {
+    if (!p.id) errors.push("a package has no id");
+    if (byId.has(p.id)) errors.push(`duplicate package id "${p.id}"`);
+    if (!Number.isFinite(p.minutes) || p.minutes <= 0) errors.push(`package "${p.id}" has no positive minutes`);
+    if (!Array.isArray(p.files) || p.files.length === 0) errors.push(`package "${p.id}" declares no files — independence cannot be verified`);
+    byId.set(p.id, p);
+  }
+  for (const p of packages) {
+    for (const d of p.dependsOn || []) {
+      if (!byId.has(d)) errors.push(`package "${p.id}" depends on unknown package "${d}"`);
+    }
+  }
+  if (errors.length) return { verdict: "serial", speedup: 1, reasons: ["work packages are not well formed"], conflicts: [], errors };
+
+  // A short job is not worth three context windows. The floor is deliberately plain:
+  // parallelism is bought with tokens, and a 15-minute task finished in 5 costs the same
+  // in money and more in risk.
+  const MIN_SERIAL_MINUTES = 30;
+  if (packages.reduce((s, p) => s + p.minutes, 0) < MIN_SERIAL_MINUTES) {
+    return {
+      verdict: "serial",
+      serial: packages.reduce((s, p) => s + p.minutes, 0),
+      criticalPath: 0,
+      criticalPathIds: [],
+      parallel: false,
+      speedup: 1,
+      maxConcurrent: Math.max(1, Math.floor(maxConcurrent)),
+      independentCount: 0,
+      conflicts: [],
+      reasons: [`serial cost is under ${MIN_SERIAL_MINUTES} minutes — the threads would cost more than they save`],
+      errors: [],
+    };
+  }
+
+  // --- conflicts -------------------------------------------------------------
+  const conflicts = [];
+  for (let i = 0; i < packages.length; i++) {
+    for (let j = i + 1; j < packages.length; j++) {
+      const a = packages[i], b = packages[j];
+      const sharedFiles = (a.files || []).filter((f) => (b.files || []).includes(f));
+      if (sharedFiles.length) {
+        conflicts.push({ kind: "file", packages: [a.id, b.id], items: sharedFiles });
+      }
+      // A shared interface is only safe when exactly one side owns it.
+      const aProv = new Set(a.interfacesProvided || []);
+      const bProv = new Set(b.interfacesProvided || []);
+      const aNeed = new Set(a.interfacesNeeded || []);
+      const bNeed = new Set(b.interfacesNeeded || []);
+      const bothTouch = new Set([...aNeed, ...aProv].filter((x) => bNeed.has(x) || bProv.has(x)));
+      const unowned = [...bothTouch].filter((x) => !(aProv.has(x) && bNeed.has(x)) && !(bProv.has(x) && aNeed.has(x)));
+      if (unowned.length) {
+        conflicts.push({ kind: "interface", packages: [a.id, b.id], items: unowned });
+      }
+    }
+  }
+
+  // --- cycle check -----------------------------------------------------------
+  const state = new Map();
+  const hasCycle = (id, stack) => {
+    if (state.get(id) === "done") return false;
+    if (stack.has(id)) return true;
+    stack.add(id);
+    state.set(id, "visiting");
+    for (const d of byId.get(id).dependsOn || []) {
+      if (hasCycle(d, stack)) return true;
+    }
+    stack.delete(id);
+    state.set(id, "done");
+    return false;
+  };
+  for (const p of packages) {
+    state.clear();
+    if (hasCycle(p.id, new Set())) {
+      return { verdict: "serial", speedup: 1, reasons: ["dependency cycle among work packages"], conflicts, errors: ["cycle"] };
+    }
+  }
+
+  // --- serial and critical path ---------------------------------------------
+  const serial = packages.reduce((s, p) => s + p.minutes, 0);
+  const finish = new Map();
+  const earliestFinish = (id) => {
+    if (finish.has(id)) return finish.get(id);
+    const p = byId.get(id);
+    const start = Math.max(0, ...(p.dependsOn || []).map(earliestFinish));
+    const f = start + p.minutes;
+    finish.set(id, f);
+    return f;
+  };
+  const criticalPath = Math.max(...packages.map((p) => earliestFinish(p.id)));
+  const criticalPathIds = packages
+    .filter((p) => earliestFinish(p.id) === criticalPath)
+    .map((p) => p.id);
+
+  // --- bounded list schedule (what the cap really yields) --------------------
+  const cap = Math.max(1, Math.floor(maxConcurrent));
+  const remaining = packages.map((p) => ({ ...p, done: false }));
+  const doneAt = new Map();
+  let clock = 0;
+  let guard = 0;
+  while (remaining.some((p) => !p.done) && guard++ < 1000) {
+    const ready = remaining
+      .filter((p) => !p.done && (p.dependsOn || []).every((d) => doneAt.has(d)))
+      .sort((a, b) => b.minutes - a.minutes);
+    if (!ready.length) break;
+    const batch = ready.slice(0, cap);
+    const start = Math.max(0, ...(batch.flatMap((p) => (p.dependsOn || []).map((d) => doneAt.get(d) || 0))));
+    const end = start + Math.max(...batch.map((p) => p.minutes));
+    for (const p of batch) {
+      p.done = true;
+      doneAt.set(p.id, end);
+    }
+    clock = Math.max(clock, end);
+  }
+  const parallel = clock;
+  const speedup = parallel > 0 ? serial / parallel : 1;
+
+  // --- verdict ---------------------------------------------------------------
+  const independentCount = packages.filter(
+    (p) => !(p.dependsOn || []).length && !conflicts.some((c) => c.packages.includes(p.id)),
+  ).length;
+
+  if (conflicts.length) {
+    const kinds = [...new Set(conflicts.map((c) => c.kind))].join(", ");
+    reasons.push(`conflicts of kind ${kinds} — packages are not independent (06d: if two tasks might touch the same file, they are dependent)`);
+  }
+  if (independentCount < MIN_INDEPENDENT) {
+    reasons.push(`only ${independentCount} fully independent package(s); ${MIN_INDEPENDENT} are needed to pay for the fan-out`);
+  }
+  if (speedup < MIN_SPEEDUP) {
+    reasons.push(`critical path ${criticalPath}m vs serial ${serial}m — speed-up ${speedup.toFixed(2)}x is below the ${MIN_SPEEDUP}x floor, so parallelism would cost more than it saves`);
+  }
+
+  const verdict = conflicts.length === 0 && independentCount >= MIN_INDEPENDENT && speedup >= MIN_SPEEDUP ? "parallel" : "serial";
+  if (verdict === "parallel") {
+    reasons.push(`${independentCount} independent packages, speed-up ${speedup.toFixed(2)}x at concurrency ${cap}; join through the serialised queue and run the full suite after rebase`);
+  }
+
+  return {
+    verdict,
+    serial,
+    criticalPath,
+    criticalPathIds,
+    parallel,
+    speedup: Number(speedup.toFixed(2)),
+    maxConcurrent: cap,
+    independentCount,
+    conflicts,
+    reasons,
+    errors: [],
+  };
+}
+
+/**
+ * The join contract (W3.2). Kept as data so a test can assert the queue is
+ * single-lane and the suite is not skippable, rather than trusting prose.
+ */
+export const JOIN_STEPS = Object.freeze([
+  "fetch every branch and the current main",
+  "rebase the branch onto the updated main",
+  "read each diff against its package's DoD — the orchestrator, never a thread",
+  "run the FULL suite in the rebased state (unit + integration + E2E)",
+  "fast-forward merge only if every check passed",
+  "resolve each ticket with its own summary — only after the suite is green",
+]);
+
+export const JOIN_FORBIDDEN = Object.freeze([
+  "an LLM resolving a merge conflict — re-read the two intents by hand, or stop and ask",
+  "merging without the full suite in the rebased state",
+  "two joins in flight at once",
+  "a thread resolving its own ticket or writing its own summary",
+  "a thread editing outside its declared file partition",
+]);
+
+/**
+ * The parallelism switch (P47). Default OFF, and staying off is the safe reading:
+ * parallelism buys elapsed time and costs tokens, and a wrong "yes" costs both. It is
+ * a config value, not a dependency — ASF must keep working with no orchestration
+ * plugin installed, so nothing here imports one.
+ */
+export const PARALLEL_DEFAULT = false;
+export const MAX_CONCURRENT_CAP = 4; // this box has 4 cores — more threads than cores is just a slower queue
+
+export function readParallelSwitch({ config = {}, env = {} } = {}) {
+  const configured = config?.parallel?.enabled === true;
+  const oneRun = /^(1|true|yes)$/i.test(String(env.ASF_PARALLEL ?? ""));
+  const enabled = configured || oneRun;
+  const requested = Number(config?.parallel?.maxConcurrent ?? 3);
+  const maxConcurrent = Math.max(1, Math.min(MAX_CONCURRENT_CAP, Number.isFinite(requested) ? requested : 3));
+  return {
+    enabled,
+    maxConcurrent,
+    reason: enabled
+      ? oneRun && !configured
+        ? "enabled for this run only by ASF_PARALLEL — the override does not persist"
+        : `enabled by config parallel.enabled, capped at ${maxConcurrent} concurrent`
+      : "default OFF — single-agent is the default; enable with parallel.enabled, or ASF_PARALLEL=1 for one run",
+  };
+}
+
+export function planJoin({ branches = [] }) {
+  return {
+    order: branches.map((b, i) => ({ branch: b, lane: 0, step: i + 1, steps: JOIN_STEPS })),
+    singleLane: true,
+    forbidden: JOIN_FORBIDDEN,
+  };
+}

package/lib/review.mjs

@@ -0,0 +1,148 @@
+/**
+ * Review guards (W1.2, W1.3, W1.6, W3.3).
+ *
+ * These are the rules that decide whether a review actually happened, so they are
+ * code and not prose: a rule about trustworthiness that lives only in markdown is a
+ * rule an agent can satisfy by nodding (06b Rule 20's argument, applied to review).
+ *
+ * The failure this exists for is observed, not hypothetical: a read-only subagent
+ * asked to report from a file that did not exist returned a confident reading of a
+ * *different* file and exited 0. Exit status and confidence are both cheap. A citation
+ * that resolves is not.
+ */
+
+export const REVIEW_DEFAULTS = Object.freeze({
+  maxReviewers: 6,
+  abForBlockers: true,
+  maxReaudits: 2,
+  maxConcurrent: 3,
+  tokenCeilingMultiple: 6,
+});
+
+export const LENSES = Object.freeze([
+  "asf-design-critic",
+  "asf-codebase-fitness",
+  "asf-zoom-out",
+  "asf-comprehension",
+  "asf-implementation-readiness",
+  "asf-structural",
+]);
+
+export const SEVERITIES = Object.freeze(["Blocker", "Major", "Nit"]);
+
+const FINDING = /^###\s+(.+?)\s+—\s+(Blocker|Major|Nit)\s*$/im;
+const SCOPE = /\*\*Scope:\*\*\s*`?([^`\n]+?)`?\s*$/m;
+
+/**
+ * Resolve every `path` or `path:lines` a reviewer cited.
+ * A citation that does not exist, or a line range outside the file, means the
+ * reviewer cannot have read it: the report is rejected and recorded `not run`.
+ */
+export function verifyCitations({ findings = [], repoRoot, fs, minCoverage = 1 }) {
+  const accepted = [];
+  const rejected = [];
+  const existsCache = new Map();
+  const readCache = new Map();
+
+  const fileOf = (scope) => {
+    const m = /^\s*(?:`?)([^\s:`]+)((?::\d+(?:-\d+)?)?)`?/.exec(scope || "");
+    if (!m) return null;
+    return { file: m[1], from: m[2] ? Number(m[2].slice(1).split("-")[0]) : null, to: m[2] && m[2].includes("-") ? Number(m[2].split("-")[1]) : null };
+  };
+
+  for (const f of findings) {
+    const cite = fileOf(f.scope);
+    if (!cite || !cite.file) {
+      rejected.push({ ...f, reason: "no resolvable citation in the scope" });
+      continue;
+    }
+    const abs = `${repoRoot}/${cite.file.replace(/^\.\//, "")}`;
+    let ok = existsCache.get(abs);
+    if (ok === undefined) {
+      ok = fs.existsSync(abs);
+      existsCache.set(abs, ok);
+    }
+    if (!ok) {
+      rejected.push({ ...f, reason: `cited file does not exist: ${cite.file}` });
+      continue;
+    }
+    if (cite.from) {
+      let lines = readCache.get(abs);
+      if (!lines) {
+        lines = fs.readFileSync(abs, "utf8").split("\n").length;
+        readCache.set(abs, lines);
+      }
+      if (cite.from > lines || (cite.to && cite.to > lines)) {
+        rejected.push({ ...f, reason: `cited range ${cite.file}:${cite.from}-${cite.to ?? cite.from} is outside the file (${lines} lines)` });
+        continue;
+      }
+    }
+    accepted.push(f);
+  }
+
+  const coverage = findings.length ? accepted.length / findings.length : 0;
+  return {
+    accepted,
+    rejected,
+    coverage: Number(coverage.toFixed(2)),
+    // A report where nothing resolves is not a clean review — it is an absent one.
+    status: findings.length === 0 ? "no-findings-submitted" : accepted.length === 0 ? "not run" : coverage < minCoverage ? "partial" : "completed",
+  };
+}
+
+/**
+ * Per-reviewer status. A lens that timed out, crashed, returned nothing, or had every
+ * citation rejected is `not run` — never "zero findings".
+ */
+export function reviewerStatus({ results = [] }) {
+  const rows = [];
+  for (const r of results) {
+    let status;
+    if (r.error || r.timedOut) status = "not run";
+    else if (!r.output || !String(r.output).trim()) status = "not run";
+    else if (r.citationCheck && r.citationCheck.status === "not run") status = "not run";
+    else status = "completed";
+    rows.push({ lens: r.lens, status, findings: status === "completed" ? (r.citationCheck?.accepted.length ?? 0) : 0 });
+  }
+  return {
+    rows,
+    completed: rows.filter((r) => r.status === "completed").length,
+    notRun: rows.filter((r) => r.status === "not run").map((r) => r.lens),
+    render() {
+      return ["| Reviewer | Status |", "| --- | --- |", ...rows.map((r) => `| \`${r.lens}\` | ${r.status} |`)].join("\n");
+    },
+  };
+}
+
+/** Findings must carry severity, scope and a recommendation — and merge across lenses. */
+export function normalizeFindings(list = []) {
+  const out = [];
+  const seen = new Set();
+  const invalid = [];
+  for (const f of list) {
+    if (!SEVERITIES.includes(f.severity) || !f.scope || !f.recommendation) {
+      invalid.push(f);
+      continue;
+    }
+    const key = `${f.severity}|${String(f.scope).replace(/\s+/g, " ")}|${String(f.finding).toLowerCase().replace(/\W+/g, " ").trim()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(f);
+  }
+  const rank = { Blocker: 0, Major: 1, Nit: 2 };
+  out.sort((a, b) => rank[a.severity] - rank[b.severity]);
+  return { findings: out, rejected: invalid };
+}
+
+/**
+ * A/B duplication lifts recall, and recall is the expensive property — it is bought at
+ * the blocker boundary, nowhere else.
+ */
+export function abAllowed({ phase, severities = [], config = REVIEW_DEFAULTS }) {
+  if (!config.abForBlockers) return { allowed: false, reason: "review.abForBlockers is off" };
+  if (phase !== "blocker-rereview") return { allowed: false, reason: `A/B is only for a blocker re-review, not "${phase}"` };
+  if (!severities.includes("Blocker")) return { allowed: false, reason: "no blocker was reported, so there is nothing to re-review" };
+  return { allowed: true, reason: "blocker boundary — two instances of the lens to lift recall" };
+}
+
+export { FINDING, SCOPE };