vigiles 12.7.0 → 12.8.0

package/dist/audit-score.js

@@ -33,6 +33,11 @@ const leaderboard_js_1 = require("./leaderboard.js");
 // category rings and the single health number can never drift. W_UNTESTED is
 // audit-only — untested surfaces are advisory (shown, never scored into overall).
 const W_UNTESTED = 3;
+/** Resolve the terse "thing(s)" plural placeholder against a count:
+ * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools"). */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
 /** Apply deductions to a 100 base, clamped to [0,100], collecting non-zero labels. */
 function scoreFrom(deductions) {
     let penalty = 0;
@@ -41,7 +46,10 @@ function scoreFrom(deductions) {
         if (d.n <= 0)
             continue;
         penalty += d.n * d.weight;
-        findings.push({ n: d.n, text: `${String(d.n)} ${d.label}` });
+        findings.push({
+            n: d.n,
+            text: `${String(d.n)} ${pluralizeLabel(d.n, d.label)}`,
+        });
     }
     findings.sort((a, b) => b.n - a.n);
     return {

package/dist/audit-verdict.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The audit VERDICT engine — a header sentence + per-recommendation `pointsIfFixed`,
+ * both derived by RE-SCORING, never by a hardcoded template with a fake number.
+ *
+ * The audit scorer ({@link auditScore}) is pure and deterministic: `overall` is
+ * `100 − Σ(graded penalties)` (clamped to [0,100]) and the letter grade comes from
+ * fixed thresholds (A ≥90 … F <60). Because it's pure, we can answer two "what if"
+ * questions by RUNNING it again with a single recommendation's finding(s) removed
+ * and diffing the `overall`:
+ *
+ *   1. `pointsIfFixed` per recommendation — the exact number of overall points the
+ *      grade gains if THAT one fix is applied (so a fix card can show `+N pts` and
+ *      sort by it). Computed as `overall(report − thisFinding) − overall(report)`.
+ *   2. A verdict `sentence` for the report header — e.g. "Two one-line fixes away
+ *      from an A." — where the COUNT is the minimal number of fixes whose COMBINED
+ *      removal actually crosses the next grade threshold (a real cumulative
+ *      re-score), and `pointsToNextGrade` is the real threshold gap.
+ *
+ * Every recommendation maps 1:1 to exactly one graded finding (see `optimize` /
+ * `explainScore`): each is a single deduction of a known weight, so removing it
+ * lowers the penalty by that weight (modulo the [0,100] clamp). We remove the
+ * finding by its detector + content (matched against the given recommendation),
+ * NOT by reproducing `explainScore`'s ordering — so this stays aligned with the
+ * `recommendations` array the caller passes, by index.
+ *
+ * Pure over its inputs (the same pieces `buildAuditReport` already has): no fs, no
+ * clock, no model, no mutation of the caller's report.
+ *
+ * LIMITATION (documented, not fabricated): some graded penalties have NO
+ * corresponding recommendation (a hard lethal-trifecta contract, an MCP server
+ * that can't start, a `disallowedTools` typo, an invalid model/color, unresolved
+ * skill resources, an invisible skill, a misplaced plugin dir, an ineffective /
+ * never-firing hook). Those cannot be "fixed" through a recommendation here, so
+ * they never contribute to `pointsIfFixed` and can make `fixesToNextGrade` null
+ * (the gap can't be closed by the deterministic fix list alone) — in which case
+ * the verdict leads with the dominant blocking finding instead. The
+ * fixes-to-next-grade count uses a greedy largest-delta-first ordering; that is
+ * provably minimal when penalties are additive (the common case, away from the
+ * score-0 clamp) and a close upper bound otherwise.
+ */
+import { type AuditScore } from "./audit-score.js";
+import type { Recommendation } from "./optimize.js";
+import { type PluginScore } from "./leaderboard.js";
+import type { ScanReport } from "./scan.js";
+/**
+ * The inputs the verdict needs — exactly the pieces {@link buildAuditReport}
+ * already holds. `score` is the authoritative base (`overall` + `grade`) the
+ * report displays; `report` is re-scored with a finding removed to diff against
+ * it; `recommendations` is the array whose indices `perRecommendation` aligns to.
+ */
+export interface VerdictInput {
+    readonly report: ScanReport;
+    readonly score: AuditScore;
+    readonly recommendations: readonly Recommendation[];
+}
+/** One recommendation's overall-points gain if its single fix is applied. */
+export interface RecommendationPoints {
+    /** Index into the input `recommendations` array. */
+    readonly index: number;
+    /**
+     * `overall(report − thisFinding) − overall(report)` — always ≥ 0 (removing a
+     * penalty can only raise or hold the score). Can be 0 when the score is clamped
+     * at 0 (removing one weight still leaves the penalty ≥ 100).
+     */
+    readonly pointsIfFixed: number;
+}
+export interface Verdict {
+    /** The header sentence — real numbers from the re-score + grade thresholds. */
+    readonly sentence: string;
+    /** The current letter grade (echoed from the base score). */
+    readonly grade: PluginScore["grade"];
+    /** Points to the next-higher grade band, or null when already an A. */
+    readonly pointsToNextGrade: number | null;
+    /**
+     * The minimal number of deterministic fixes whose COMBINED removal crosses the
+     * next grade threshold (real cumulative re-score, greedy largest-delta-first),
+     * or null when the deterministic fix list can't close the gap (non-recommendation
+     * penalties dominate) or the grade is already an A.
+     */
+    readonly fixesToNextGrade: number | null;
+    readonly perRecommendation: readonly RecommendationPoints[];
+}
+/**
+ * Compute the audit verdict + per-recommendation `pointsIfFixed` by re-scoring.
+ * Pure and deterministic over its inputs. `perRecommendation` is index-aligned to
+ * the input `recommendations`.
+ */
+export declare function computeVerdict(input: VerdictInput): Verdict;
+//# sourceMappingURL=audit-verdict.d.ts.map

package/dist/audit-verdict.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * The audit VERDICT engine — a header sentence + per-recommendation `pointsIfFixed`,
+ * both derived by RE-SCORING, never by a hardcoded template with a fake number.
+ *
+ * The audit scorer ({@link auditScore}) is pure and deterministic: `overall` is
+ * `100 − Σ(graded penalties)` (clamped to [0,100]) and the letter grade comes from
+ * fixed thresholds (A ≥90 … F <60). Because it's pure, we can answer two "what if"
+ * questions by RUNNING it again with a single recommendation's finding(s) removed
+ * and diffing the `overall`:
+ *
+ *   1. `pointsIfFixed` per recommendation — the exact number of overall points the
+ *      grade gains if THAT one fix is applied (so a fix card can show `+N pts` and
+ *      sort by it). Computed as `overall(report − thisFinding) − overall(report)`.
+ *   2. A verdict `sentence` for the report header — e.g. "Two one-line fixes away
+ *      from an A." — where the COUNT is the minimal number of fixes whose COMBINED
+ *      removal actually crosses the next grade threshold (a real cumulative
+ *      re-score), and `pointsToNextGrade` is the real threshold gap.
+ *
+ * Every recommendation maps 1:1 to exactly one graded finding (see `optimize` /
+ * `explainScore`): each is a single deduction of a known weight, so removing it
+ * lowers the penalty by that weight (modulo the [0,100] clamp). We remove the
+ * finding by its detector + content (matched against the given recommendation),
+ * NOT by reproducing `explainScore`'s ordering — so this stays aligned with the
+ * `recommendations` array the caller passes, by index.
+ *
+ * Pure over its inputs (the same pieces `buildAuditReport` already has): no fs, no
+ * clock, no model, no mutation of the caller's report.
+ *
+ * LIMITATION (documented, not fabricated): some graded penalties have NO
+ * corresponding recommendation (a hard lethal-trifecta contract, an MCP server
+ * that can't start, a `disallowedTools` typo, an invalid model/color, unresolved
+ * skill resources, an invisible skill, a misplaced plugin dir, an ineffective /
+ * never-firing hook). Those cannot be "fixed" through a recommendation here, so
+ * they never contribute to `pointsIfFixed` and can make `fixesToNextGrade` null
+ * (the gap can't be closed by the deterministic fix list alone) — in which case
+ * the verdict leads with the dominant blocking finding instead. The
+ * fixes-to-next-grade count uses a greedy largest-delta-first ordering; that is
+ * provably minimal when penalties are additive (the common case, away from the
+ * score-0 clamp) and a close upper bound otherwise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeVerdict = computeVerdict;
+const audit_score_js_1 = require("./audit-score.js");
+const leaderboard_js_1 = require("./leaderboard.js");
+// The grade-band FLOORS (A ≥90 … D ≥60; below 60 is F), mirroring gradeFor.
+const GRADE_FLOORS = [60, 70, 80, 90];
+/** The smallest band floor strictly above `overall`, or null when already an A. */
+function nextGradeFloor(overall) {
+    for (const floor of GRADE_FLOORS) {
+        if (overall < floor)
+            return floor;
+    }
+    return null;
+}
+const NUMBER_WORDS = [
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+];
+/** Small counts read as words ("two"); larger ones fall back to digits. */
+function numberWord(n) {
+    return n >= 0 && n < NUMBER_WORDS.length ? NUMBER_WORDS[n] : String(n);
+}
+function capitalize(s) {
+    return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+/** Resolve the scorer's terse "thing(s)" plural placeholder against a count —
+ * mirrors audit-score's `pluralizeLabel` so the verdict sentence reads "1 unit"
+ * / "3 units", never "1 unit(s)". */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
+function fixNoun(n) {
+    return n === 1 ? "fix" : "fixes";
+}
+function article(grade) {
+    return grade === "A" ? "an" : "a";
+}
+/** Remove the FIRST array element matching `pred`; returns a new array (or the
+ * same reference when nothing matches, so unrelated re-scores are byte-identical). */
+function removeFirst(arr, pred) {
+    const i = arr.findIndex(pred);
+    if (i < 0)
+        return arr;
+    return [...arr.slice(0, i), ...arr.slice(i + 1)];
+}
+/**
+ * Remove the first agent-issue the `pick` callback rewrites (it returns the
+ * rewritten agent, or null when this agent has no matching issue). Stops after the
+ * first hit so exactly one graded unit is dropped per call.
+ */
+function removeAgentIssue(report, agentName, pick) {
+    let done = false;
+    const agents = report.agents.map((a) => {
+        if (done || a.name !== agentName)
+            return a;
+        const next = pick(a);
+        if (next !== null) {
+            done = true;
+            return next;
+        }
+        return a;
+    });
+    return done ? { ...report, agents } : report;
+}
+/**
+ * Return a copy of `report` with the SINGLE finding behind `rec` neutralized —
+ * matched by the recommendation's detector + its content (surface / rationale),
+ * so it stays aligned with the caller's recommendation, not with `explainScore`'s
+ * internal ordering. Each removal reduces exactly one graded penalty unit; an
+ * unrecognized detector is a no-op (returns the report unchanged), so its
+ * `pointsIfFixed` is an honest 0 rather than a fabricated number.
+ */
+function withFindingRemoved(report, rec) {
+    switch (rec.detector) {
+        case "description-overlap": {
+            // surface is the "a ↔ b" pair; drop that overlap (feeds the W_OVERLAP count).
+            const descriptionOverlaps = removeFirst(report.descriptionOverlaps, (o) => `${o.a} ↔ ${o.b}` === rec.surface);
+            return { ...report, descriptionOverlaps };
+        }
+        case "skill-frontmatter": {
+            // Flip the matched skill's hasDescription — the only field the noDesc penalty
+            // reads — without dropping the skill (keeps Safety's assessable count intact).
+            let flipped = false;
+            const skills = report.skills.map((s) => {
+                if (!flipped && s.name === rec.surface && !s.hasDescription) {
+                    flipped = true;
+                    return { ...s, hasDescription: true };
+                }
+                return s;
+            });
+            return flipped ? { ...report, skills } : report;
+        }
+        case "subagent-tool-contract":
+            return removeAgentIssue(report, rec.surface, (a) => {
+                const toolIssues = removeFirst(a.toolIssues, (t) => t.message === rec.rationale);
+                return toolIssues !== a.toolIssues ? { ...a, toolIssues } : null;
+            });
+        case "mcp-tool-resolves":
+            return removeAgentIssue(report, rec.surface, (a) => {
+                const mcpToolIssues = removeFirst(a.mcpToolIssues, (m) => m.message === rec.rationale);
+                return mcpToolIssues !== a.mcpToolIssues
+                    ? { ...a, mcpToolIssues }
+                    : null;
+            });
+        case "hook-events": {
+            const hookEventIssues = removeFirst(report.hookEventIssues, (h) => h.message === rec.rationale);
+            return hookEventIssues !== report.hookEventIssues
+                ? { ...report, hookEventIssues }
+                : report;
+        }
+        case "hook-script-exists": {
+            // Flip the matched missing hook to "ok" (the missingHooks penalty reads status).
+            let flipped = false;
+            const hooks = report.hooks.map((h) => {
+                if (!flipped && h.script === rec.surface && h.status === "missing") {
+                    flipped = true;
+                    return { ...h, status: "ok" };
+                }
+                return h;
+            });
+            return flipped ? { ...report, hooks } : report;
+        }
+        case "subagent-frontmatter": {
+            const frontmatterIssues = removeFirst(report.frontmatterIssues, (f) => f.kind === "agent" && f.path === rec.surface);
+            return frontmatterIssues !== report.frontmatterIssues
+                ? { ...report, frontmatterIssues }
+                : report;
+        }
+        default:
+            // Unknown detector — can't map it to a graded finding; no-op (honest 0 delta).
+            return report;
+    }
+}
+/** Re-score `report` with EVERY listed recommendation's finding removed at once. */
+function overallWithout(report, recs) {
+    let cur = report;
+    for (const rec of recs)
+        cur = withFindingRemoved(cur, rec);
+    return (0, audit_score_js_1.auditScore)(cur).overall;
+}
+/**
+ * The single largest blocking deduction (max `n × weight`, `n > 0`), for the
+ * issue-forward verdict when the fix list can't close the grade gap. Tie-break by
+ * heavier per-item weight, then the report's own deduction order.
+ */
+function dominantDeduction(report) {
+    let best = null;
+    for (const d of (0, leaderboard_js_1.reportDeductions)(report)) {
+        if (d.n <= 0)
+            continue;
+        const cost = d.n * d.weight;
+        if (best === null ||
+            cost > best.cost ||
+            (cost === best.cost && d.weight > best.weight)) {
+            best = { n: d.n, label: d.label, cost, weight: d.weight };
+        }
+    }
+    return best ? { n: best.n, label: best.label } : null;
+}
+/**
+ * Minimal number of fixes whose COMBINED removal reaches `targetOverall`, applying
+ * recommendations largest-`pointsIfFixed`-first (index-asc tie-break) and
+ * re-scoring the growing set each step. Provably minimal when penalties are
+ * additive (away from the score-0 clamp); a tight upper bound otherwise. Null when
+ * removing every recommendation still doesn't reach the target.
+ */
+function fixesToReach(report, recommendations, perRec, targetOverall) {
+    const order = [...perRec].sort((a, b) => b.pointsIfFixed - a.pointsIfFixed || a.index - b.index);
+    const chosen = [];
+    for (const p of order) {
+        chosen.push(recommendations[p.index]);
+        if (overallWithout(report, chosen) >= targetOverall)
+            return chosen.length;
+    }
+    return null;
+}
+function buildSentence(input, pointsToNextGrade, fixesToNextGrade) {
+    const { score, recommendations, report } = input;
+    if (score.empty) {
+        return "No loadable harness surface — nothing to grade yet.";
+    }
+    // Already an A: nothing is blocking the grade.
+    if (pointsToNextGrade === null) {
+        if (recommendations.length === 0) {
+            return "A — nothing blocking; the harness is structurally clean.";
+        }
+        const n = recommendations.length;
+        return `A — nothing blocking the grade; ${numberWord(n)} deterministic ${fixNoun(n)} would harden it further.`;
+    }
+    // The next band's grade is gradeFor(its FLOOR); the floor is base + the gap.
+    const nextGrade = (0, leaderboard_js_1.gradeFor)(score.overall + pointsToNextGrade);
+    // Reachable by the deterministic fix list: fix-count-forward (the actionable framing).
+    if (fixesToNextGrade !== null) {
+        return `${capitalize(numberWord(fixesToNextGrade))} one-line ${fixNoun(fixesToNextGrade)} away from ${article(nextGrade)} ${nextGrade}.`;
+    }
+    // Not reachable by recommendations alone — lead with the dominant blocking finding.
+    const dom = dominantDeduction(report);
+    if (dom === null) {
+        return `${score.grade} — ${String(pointsToNextGrade)} points below ${article(nextGrade)} ${nextGrade}.`;
+    }
+    return `${score.grade} — ${String(dom.n)} ${pluralizeLabel(dom.n, dom.label)}; fixing every deterministic finding still lands below ${article(nextGrade)} ${nextGrade}.`;
+}
+/**
+ * Compute the audit verdict + per-recommendation `pointsIfFixed` by re-scoring.
+ * Pure and deterministic over its inputs. `perRecommendation` is index-aligned to
+ * the input `recommendations`.
+ */
+function computeVerdict(input) {
+    const { report, score, recommendations } = input;
+    const base = score.overall;
+    const perRecommendation = recommendations.map((rec, index) => {
+        const after = (0, audit_score_js_1.auditScore)(withFindingRemoved(report, rec)).overall;
+        // Removing a penalty can only raise or hold the score; clamp negatives to 0
+        // to defend against any future non-monotonic scorer change.
+        return { index, pointsIfFixed: Math.max(0, after - base) };
+    });
+    const nextFloor = nextGradeFloor(base);
+    const pointsToNextGrade = nextFloor === null ? null : nextFloor - base;
+    const fixesToNextGrade = nextFloor === null
+        ? null
+        : fixesToReach(report, recommendations, perRecommendation, nextFloor);
+    const sentence = buildSentence(input, pointsToNextGrade, fixesToNextGrade);
+    return {
+        sentence,
+        grade: score.grade,
+        pointsToNextGrade,
+        fixesToNextGrade,
+        perRecommendation,
+    };
+}
+//# sourceMappingURL=audit-verdict.js.map

package/dist/cli.js

@@ -35,6 +35,8 @@ const audit_prompts_js_1 = require("./audit-prompts.js");
 const audit_html_js_1 = require("./audit-html.js");
 const audit_serve_js_1 = require("./audit-serve.js");
 const audit_report_js_1 = require("./audit-report.js");
+const rule_inventory_js_1 = require("./rule-inventory.js");
+const rule_routing_js_1 = require("./rule-routing.js");
 const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
 const proofs_js_1 = require("./core/proofs.js");
@@ -1402,6 +1404,132 @@ function discoverAdoptableForAudit(root, instructionFile) {
     out.push(...discoverAdoptableSurfaces(root));
     return out;
 }
+/** Lint-config file BASENAMES whose CONTENTS (textual, NEVER executed) reveal
+ * which rules a repo has configured — read best-effort for the rule-inventory
+ * teaser. Deliberately not resolved/executed (that would be the RCE path); we
+ * grep the raw text. Includes oxlint + biome (same rule names as ESLint) since
+ * modern TS repos lint with them. */
+const RULE_INVENTORY_CONFIG_FILES = new Set([
+    "eslint.config.js",
+    "eslint.config.mjs",
+    "eslint.config.cjs",
+    "eslint.config.ts",
+    ".eslintrc",
+    ".eslintrc.json",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    ".eslintrc.yml",
+    ".eslintrc.yaml",
+    ".oxlintrc.json",
+    ".oxlintrc.jsonc",
+    "oxlint.json",
+    "biome.json",
+    "biome.jsonc",
+    "ruff.toml",
+    ".ruff.toml",
+    "pyproject.toml",
+    ".pylintrc",
+    "clippy.toml",
+    ".clippy.toml",
+    ".rubocop.yml",
+    ".stylelintrc",
+    ".stylelintrc.json",
+]);
+/** Dirs never worth walking for a config file. */
+const RULE_INVENTORY_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+    ".yarn",
+]);
+/** readdir that returns [] instead of throwing (perms, races). */
+function safeReaddir(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+/** Collect lint-config CONTENTS from the repo root AND nested subdirs (depth ≤ 2)
+ * — textual only, never executed. Nested because monorepos/webapps keep their
+ * eslint/oxlint config under `web/`, `frontend/`, `packages/*`, etc. Bounded
+ * (skips heavy dirs; caps files) so it stays cheap on huge repos. */
+function collectLintConfigText(root) {
+    let text = "";
+    let filesRead = 0;
+    const visit = (dir, depth) => {
+        if (filesRead >= 60)
+            return;
+        for (const e of safeReaddir(dir)) {
+            if (e.isFile() && RULE_INVENTORY_CONFIG_FILES.has(e.name)) {
+                try {
+                    text += (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, e.name), "utf-8") + "\n";
+                    filesRead++;
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            else if (e.isDirectory() &&
+                depth < 2 &&
+                !e.name.startsWith(".") &&
+                !RULE_INVENTORY_SKIP_DIRS.has(e.name)) {
+                visit((0, node_path_1.resolve)(dir, e.name), depth + 1);
+            }
+        }
+    };
+    visit(root, 0);
+    return text;
+}
+/** The deterministic rule-inventory teaser for `audit`: read the instruction
+ * file(s) + lint-config TEXT (never executed) and map documented intents to
+ * off-the-shelf rules + whether they're already configured. Best-effort, fs-only;
+ * NO model, NO config execution — safe on any repo. Composition-root. */
+function computeRuleInventory(root, instructionFile) {
+    try {
+        const instructionText = readInstructionText(root, instructionFile);
+        if (!instructionText.trim())
+            return [];
+        return (0, rule_inventory_js_1.buildRuleInventory)(instructionText, collectLintConfigText(root));
+    }
+    catch {
+        return [];
+    }
+}
+/** Read EVERY agent instruction file present (not just the harness-native one) —
+ * rules are often documented in AGENTS.md even under a claude-code harness. */
+function readInstructionText(root, instructionFile) {
+    let instructionText = "";
+    for (const name of new Set([instructionFile, "CLAUDE.md", "AGENTS.md"])) {
+        const p = (0, node_path_1.resolve)(root, name);
+        if ((0, node_fs_1.existsSync)(p))
+            instructionText += (0, node_fs_1.readFileSync)(p, "utf-8") + "\n";
+    }
+    return instructionText;
+}
+/** The deterministic State-B routing preview for `audit`: segment the instruction
+ * file(s) into atomic rules and route each (reuse / hook / semantic / unrouted) —
+ * NO model, fs-only. `undefined` when there's nothing to segment (kept off the
+ * report). Best-effort; a routing failure never breaks the audit. */
+function computeRuleRouting(root, instructionFile) {
+    try {
+        const instructionText = readInstructionText(root, instructionFile);
+        if (!instructionText.trim())
+            return undefined;
+        const routing = (0, rule_routing_js_1.routeRules)(instructionText, instructionFile);
+        return routing.segmented > 0 ? routing : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
  * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
  * adopt (a fully spec-managed repo says nothing). */
@@ -5109,6 +5237,8 @@ async function main() {
                     vigilesVersion: getVersion(),
                     adoptableSurfaces,
                     observations: (0, observe_js_1.summarizeObservations)(ledgerRecords),
+                    rulesInventory: computeRuleInventory(root, adapter.layout.instructionFile),
+                    ruleRouting: computeRuleRouting(root, adapter.layout.instructionFile),
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);

package/dist/eval-cost.d.ts

@@ -9,7 +9,7 @@
  * the `claude` CLI) + a running session tally. We deliberately do NOT show a
  * "% of your subscription" — Anthropic does not expose a subscription's quota or
  * limit programmatically (and the real limits are rolling rate windows, not a
- * dollar bucket), so any percentage would be fiction. See docs/eval-architecture.md.
+ * dollar bucket), so any percentage would be fiction. See research/eval-architecture.md.
  *
  * Pure + injectable (env + an output sink), so the whole thing is unit-tested
  * without a model or a real key.

package/dist/eval.d.ts

@@ -43,7 +43,7 @@ export interface EvalArm {
      * opus: { model: "claude-opus-4-8" } }` — so model-as-an-arm answers "does my
      * harness still hold on the cheaper tier / after a model upgrade?" through the
      * same significance machinery, with no separate model-matrix runner. Omit to
-     * use the eval-level model. See `docs/eval-architecture.md` (model strategy).
+     * use the eval-level model. See `research/eval-architecture.md` (model strategy).
      */
     readonly model?: string;
 }
@@ -491,7 +491,7 @@ export declare function aggregateUsage(usages: readonly EvalUsage[]): ArmUsage;
  * e.g. `claude-haiku-4-5-20251001`. A floating alias (`haiku`, `sonnet`, or even
  * `claude-sonnet-4-6` with no date) can change underneath you — so a cached or
  * baselined result pinned to it can silently hide model drift. See
- * `docs/eval-architecture.md` (honest model pinning).
+ * `research/eval-architecture.md` (honest model pinning).
  */
 export declare function isDatedModel(model: string): boolean;
 /**

package/dist/eval.js

@@ -665,7 +665,7 @@ function isRecord(v) {
  * e.g. `claude-haiku-4-5-20251001`. A floating alias (`haiku`, `sonnet`, or even
  * `claude-sonnet-4-6` with no date) can change underneath you — so a cached or
  * baselined result pinned to it can silently hide model drift. See
- * `docs/eval-architecture.md` (honest model pinning).
+ * `research/eval-architecture.md` (honest model pinning).
  */
 function isDatedModel(model) {
     return /\d{8}$/.test(model);

package/dist/leaderboard.js

@@ -214,6 +214,12 @@ function computeIntegrityScore(deductions) {
     }
     return { score: Math.max(0, 100 - penalty), penalty };
 }
+/** Resolve the terse "thing(s)" plural placeholder against a count:
+ * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools").
+ * (Kept local — audit-score.ts has its own copy to avoid a circular import.) */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
 /** Deterministic structural-health score for one scanned plugin. */
 function scoreReport(r) {
     // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
@@ -230,7 +236,7 @@ function scoreReport(r) {
     for (const d of deductions) {
         if (d.n === 0)
             continue;
-        issues.push(`${String(d.n)} ${d.label}`);
+        issues.push(`${String(d.n)} ${pluralizeLabel(d.n, d.label)}`);
     }
     // Sort issues by cost (worst first) so the report leads with what matters.
     issues.sort((a, b) => Number(b.split(" ")[0]) - Number(a.split(" ")[0]));
@@ -241,10 +247,10 @@ function scoreReport(r) {
     //   - untested surfaces: a hardening gap, not breakage.
     const noContract = r.agents.filter((a) => a.tools === null).length;
     if (noContract > 0) {
-        issues.push(`${String(noContract)} agent(s) inherit all tools (no contract) (advisory)`);
+        issues.push(`${String(noContract)} ${pluralizeLabel(noContract, "agent(s) inherit all tools (no contract) (advisory)")}`);
     }
     if (r.untested > 0) {
-        issues.push(`${String(r.untested)} untested surface(s) (advisory)`);
+        issues.push(`${String(r.untested)} ${pluralizeLabel(r.untested, "untested surface(s) (advisory)")}`);
     }
     return { score, issues };
 }