@compr/opscontext-mcp 2.1.3 → 2.3.0

package/dist/agents.d.ts

@@ -102,9 +102,32 @@ export interface ScoreCheck {
     category: string;
     points: number;
     maxPoints: number;
-    status: "pass" | "partial" | "fail";
+    status: "pass" | "partial" | "fail" | "unknown";
     detail: string;
+    /**
+     * A failure here is disqualifying: it caps the overall grade regardless of the other points.
+     * Reserved for actual secret exposure — see [SECURITY-IS-DISQUALIFYING].
+     */
+    disqualifying?: boolean;
 }
+/**
+ * 🔒 LOCKED [ABSENCE-IS-NOT-A-VERDICT] — 2026-08-13
+ * ⛔ NEVER emit "pass" or "fail" for a condition the check could not actually determine,
+ *    and NEVER write a detail string that hides WHICH locations were inspected.
+ * WHY: three live bugs, all the same shape — the scorer wrote *absence of evidence* down as
+ *      a *verdict*, and the verdict pointed at the wrong fix.
+ *      1. `copilot-instructions.md`/`SKILLS.md` looked only in .github/ and reported files that
+ *         existed at the repo root as "Missing" (fixed ffa5914, [DOC-PATH-DUAL]).
+ *      2. `Git hooks` reported "No hooks — consider auto-push" for a hook that WAS installed but
+ *         whose symlink target had been deleted. existsSync() follows symlinks, so dangling and
+ *         absent are indistinguishable. CE's own Drive backup drifted while the row said
+ *         "consider auto-push" — advice for a problem the repo did not have.
+ *      3. `Secrets exposure` awarded a full 6/6 PASS with the detail "No .env or not a git repo" —
+ *         full marks for a state it openly could not distinguish.
+ * FIX: a check that cannot determine its condition emits status "unknown" (0 points, rendered ❔,
+ *      excluded from the remediation list — it is a gap in the CHECK, not in the project). Every
+ *      pass/fail detail must name what was inspected. Absence is a measurement, not a decision.
+ */
 export interface ProjectScore {
     project: string;
     path: string;
@@ -114,6 +137,14 @@ export interface ProjectScore {
     grade: string;
     checks: ScoreCheck[];
 }
+export interface CanaryResult {
+    ok: boolean;
+    /** Human-readable deviations from the pinned expectation. Empty when ok. */
+    deviations: string[];
+    /** True when the canary itself could not be built — an unknown, not a failure. */
+    inconclusive: boolean;
+}
+export declare function runScoreCanary(): CanaryResult;
 /**
  * Score a project's AI-readiness (0-100%).
  * Checks how well-prepared a project is for AI coding agents.

package/dist/agents.js

@@ -1,7 +1,9 @@
 import { execSync } from "child_process";
-import { readFileSync, existsSync, readdirSync, lstatSync } from "fs";
+import { readFileSync, existsSync, readdirSync, statSync, lstatSync, readlinkSync, mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "fs";
 import { resolve, join, dirname } from "path";
+import { tmpdir } from "os";
 import { fileURLToPath } from "url";
+import { RUBRIC } from "./rubric.js";
 // Read version from package.json at module load
 const __agents_dirname = dirname(fileURLToPath(import.meta.url));
 let AGENTS_VERSION = "1.23.0";
@@ -14,16 +16,34 @@ catch { /* fallback */ }
 // Helpers
 // ---------------------------------------------------------------------------
 function exec(cmd, cwd) {
+    return execChecked(cmd, cwd).output;
+}
+/**
+ * exec() that distinguishes "ran, produced nothing" from "did not run".
+ *
+ * 🔒 LOCKED [EXEC-FAILURE-IS-NOT-EMPTY] — 2026-08-13
+ * ⛔ NEVER let a caller treat exec()'s "" as a factual answer for a check that can FAIL SAFE.
+ * WHY: exec() returns "" for every failure mode — command not found, not a git repo, timeout,
+ *      permission denied — indistinguishable from a successful empty result. The `Secrets exposure`
+ *      check read `git ls-files .env` → "" as ".env is not tracked" and awarded a full 6/6 PASS.
+ *      A security check that hands out full marks precisely when it cannot run is worse than one
+ *      that fails: it manufactures reassurance. Found by [SCORE-CANARY] on its first run, against
+ *      a fixture with a .git directory that is not a real repository.
+ * FIX: security- and correctness-relevant callers use execChecked() and emit "unknown" when
+ *      ok === false. Absence of output is a measurement, not a decision.
+ */
+function execChecked(cmd, cwd) {
     try {
-        return execSync(cmd, {
+        const output = execSync(cmd, {
             cwd,
             encoding: "utf-8",
             timeout: 10_000,
             stdio: ["pipe", "pipe", "pipe"],
         }).trim();
+        return { ok: true, output };
     }
     catch {
-        return "";
+        return { ok: false, output: "" };
     }
 }
 /**
@@ -37,6 +57,66 @@ function isSymlink(filePath) {
         return false;
     }
 }
+/**
+ * Status icon for a score check. "unknown" is ❔ — the check could not determine its
+ * condition, which is a gap in the audit, not a verdict on the project.
+ * See [ABSENCE-IS-NOT-A-VERDICT].
+ */
+function statusIcon(status) {
+    if (status === "pass")
+        return "✅";
+    if (status === "partial")
+        return "🟡";
+    if (status === "unknown")
+        return "❔";
+    return "❌";
+}
+/**
+ * Topics an agent doc must cover to be useful. Matched case-insensitively anywhere in the
+ * document, so a project's own heading vocabulary still counts — this rewards covering the
+ * subject, not adopting our wording. See [SCORE-CONTENT-NOT-LENGTH].
+ */
+const AGENT_DOC_TOPICS = [
+    { label: "architecture", patterns: /\b(architecture|structure|layout|stack|components?|modules?)\b/i },
+    { label: "commands", patterns: /\b(commands?|scripts?|npm run|yarn |pnpm |make |getting started|setup|install)\b/i },
+    { label: "rules", patterns: /\b(rules?|conventions?|guidelines?|standards?|policy|policies|do not|never|always)\b/i },
+    { label: "key files", patterns: /\b(key files?|important files?|entry ?point|file (map|tree)|directory)\b/i },
+];
+/** Labels of the topics this document covers. */
+function matchDocTopics(content, topics) {
+    return topics.filter(t => t.patterns.test(content)).map(t => t.label);
+}
+/** Symlink target for diagnostics, or "?" if unreadable. Never throws. */
+function readlinkSafe(filePath) {
+    try {
+        return readlinkSync(filePath);
+    }
+    catch {
+        return "?";
+    }
+}
+/**
+ * Resolve an agent doc that may live in `.github/` or at the repo root.
+ * Returns the first location that exists (`.github/` wins), or null.
+ *
+ * 🔒 LOCKED [DOC-PATH-DUAL] — 2026-08-07
+ * ⛔ NEVER collapse a caller back to a single hardcoded join(p, ".github", file).
+ * WHY: the scorer read `.github/` only, while `contextengine init` writes SKILLS.md
+ *      at the repo root and the generated pre-commit hook accepts both. Every project
+ *      keeping these at root scored 0/10 + 0/3 for files that existed, so SCORE.md
+ *      rows had to be hand-corrected after every run (caught 2026-08-07 on this repo).
+ * FIX: score whichever location exists — `.github/` first (Copilot's official read
+ *      path), repo root second. Presence is what earns the points, not the directory.
+ */
+function resolveDocPath(projectPath, file) {
+    const inGithub = join(projectPath, ".github", file);
+    if (existsSync(inGithub))
+        return { path: inGithub, rel: `.github/${file}` };
+    const atRoot = join(projectPath, file);
+    if (existsSync(atRoot))
+        return { path: atRoot, rel: file };
+    return null;
+}
 /**
  * Check if an ESLint config is actually backed by installed packages.
  * Returns true if at least `eslint` itself is installed in node_modules.
@@ -909,6 +989,91 @@ export function formatPortMap(ports, conflicts) {
     }
     return lines.join("\n");
 }
+/**
+ * 🔒 LOCKED [SCORE-CANARY] — 2026-08-13
+ * ⛔ NEVER weaken this to "test one known bug", and never let a deviation be a warning only.
+ * WHY: every guard in this file was written AFTER the failure it prevents — the doc-path bug, the
+ *      dangling-hook bug, the shrinking-denominator bug. A wall of named guards is a museum of past
+ *      mistakes: valuable, but it does nothing about the next one. The canary is the only check here
+ *      that can catch a failure nobody predicted, because it does not test for a specific defect —
+ *      it demands that EVERY health signal still reads exactly as pinned before the scorer is
+ *      allowed to write a single file.
+ * FIX: build a synthetic project whose every awkward case is represented (doc at repo root, doc in
+ *      .github/, dangling hook symlink, .env with no git, no package manager), score it, and compare
+ *      against the pinned expectation. Any drift blocks the run. If the fixture cannot be built at
+ *      all, that is `inconclusive` — an unknown, per [ABSENCE-IS-NOT-A-VERDICT] — and must not be
+ *      silently treated as a pass.
+ *
+ * Runs in production on every scoring run, not just in CI. Costs a few milliseconds.
+ */
+/**
+ * True while the canary fixture is being scored. The fixture deliberately leaves 9 points
+ * unassessable (no package manager, no .gitignore), so its invariant log line is EXPECTED —
+ * printing it on every run would train the reader to ignore the warning that matters.
+ */
+let canaryRunning = false;
+export function runScoreCanary() {
+    let dir = null;
+    canaryRunning = true;
+    try {
+        dir = mkdtempSync(join(tmpdir(), "ce-canary-"));
+        // Deliberately awkward, all legal, each one a past or plausible failure:
+        mkdirSync(join(dir, ".github"), { recursive: true });
+        // doc in .github/ — covers all required topics, so it must score full marks on CONTENT.
+        // Deliberately short: length must not be what earns it. See [SCORE-CONTENT-NOT-LENGTH].
+        writeFileSync(join(dir, ".github", "copilot-instructions.md"), [
+            "# Canary", "", "## Architecture", "Two modules and a CLI entry point.", "",
+            "## Commands", "`npm run build`, `npm test`.", "",
+            "## Rules", "Never commit secrets.", "",
+            "## Key files", "`src/index.ts` is the entry point.", "",
+            ...Array.from({ length: 20 }, (_, i) => `filler ${i + 1}`),
+        ].join("\n"));
+        // doc at repo ROOT — the [DOC-PATH-DUAL] case, should score the full 3
+        writeFileSync(join(dir, "SKILLS.md"), Array.from({ length: 20 }, (_, i) => `line ${i + 1}`).join("\n"));
+        // hook installed but BROKEN — the 2026-06-10 case, must read as fail-broken not fail-absent
+        mkdirSync(join(dir, ".git", "hooks"), { recursive: true });
+        symlinkSync(join(dir, "hooks", "post-commit"), join(dir, ".git", "hooks", "post-commit"));
+        // .env with no git repo — unverifiable, must be `unknown` and must NOT collect points
+        writeFileSync(join(dir, ".env"), "SECRET=canary\n");
+        const score = scoreProject({ name: "ce-canary", path: dir });
+        const by = (n) => score.checks.find(c => c.name === n);
+        const deviations = [];
+        const expect = (label, actual, wanted) => {
+            if (actual !== wanted)
+                deviations.push(`${label}: expected ${JSON.stringify(wanted)}, got ${JSON.stringify(actual)}`);
+        };
+        expect("copilot-instructions.md points", by("copilot-instructions.md")?.points, 6);
+        expect("copilot scored on topics not length", by("copilot-instructions.md")?.detail.includes("covers"), true);
+        expect("SKILLS.md points (repo root)", by("SKILLS.md")?.points, 3);
+        // No .git worktree here, so freshness is unmeasurable — it must be unknown, never a pass.
+        expect("Doc freshness status", by("Doc freshness")?.status, "unknown");
+        expect("Doc freshness points", by("Doc freshness")?.points, 0);
+        expect("Git hooks status", by("Git hooks")?.status, "fail");
+        expect("Git hooks names the break", by("Git hooks")?.detail.includes("BROKEN"), true);
+        expect("Secrets exposure status", by("Secrets exposure")?.status, "unknown");
+        expect("Secrets exposure points", by("Secrets exposure")?.points, 0);
+        expect("denominator pinned to 100", score.maxScore, 100);
+        expect("maxPoints sum to 100", score.checks.reduce((s, c) => s + c.maxPoints, 0), 100);
+        expect("percentage matches score/100", score.percentage, Math.round(score.score));
+        return { ok: deviations.length === 0, deviations, inconclusive: false };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            inconclusive: true,
+            deviations: [`canary fixture could not be built: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    finally {
+        canaryRunning = false;
+        if (dir) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* temp dir cleanup is best-effort */ }
+        }
+    }
+}
 /**
  * Score a project's AI-readiness (0-100%).
  * Checks how well-prepared a project is for AI coding agents.
@@ -917,101 +1082,157 @@ export function scoreProject(dir) {
     const checks = [];
     const p = dir.path;
     // --- Documentation (30 points max) ---
-    // copilot-instructions.md (10 pts)
-    const copilotPath = join(p, ".github", "copilot-instructions.md");
-    if (existsSync(copilotPath)) {
-        const copilotIsSymlink = isSymlink(copilotPath);
-        const content = readFileSync(copilotPath, "utf-8");
+    // copilot-instructions.md (6 pts) — scored on CONTENT, not length.
+    // 🔒 LOCKED [SCORE-CONTENT-NOT-LENGTH] — 2026-08-14
+    // ⛔ NEVER score an agent doc on line count alone.
+    // WHY: this was 10 points — a tenth of the entire score — awarded for ">50 lines". Fifty lines
+    //      of anything earned full marks, so the largest single check in the rubric was also the
+    //      easiest to satisfy without doing the work. Length is a proxy for effort; it measures
+    //      typing, not usefulness to an agent.
+    // FIX: score the sections an agent actually needs — architecture, commands, rules/conventions,
+    //      key files. Length survives only as a floor to reject stubs. Same approach the
+    //      .env.example check already used (counting real variables, not lines).
+    const copilot = resolveDocPath(p, "copilot-instructions.md");
+    if (copilot) {
+        const copilotIsSymlink = isSymlink(copilot.path);
+        const content = readFileSync(copilot.path, "utf-8");
         const lines = content.split("\n").length;
+        const found = matchDocTopics(content, AGENT_DOC_TOPICS);
+        const at = `${copilot.rel}, ${lines} lines`;
         if (copilotIsSymlink) {
-            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 4, maxPoints: 10, status: "partial", detail: `⚠ Symlink (${lines} lines) — should be a real file with project-specific context` });
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 2, maxPoints: 6, status: "partial", detail: `⚠ Symlink (${at}) — should be a real file with project-specific context` });
+        }
+        else if (found.length >= AGENT_DOC_TOPICS.length) {
+            // Content decides, and it decides FIRST. A short doc that covers everything an agent needs
+            // beats a long one that covers nothing — that inversion is the whole point of this rework,
+            // so the stub floor below must never be allowed to override a complete document.
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 6, maxPoints: 6, status: "pass", detail: `${at} — covers ${found.join(", ")}` });
         }
-        else if (lines > 50) {
-            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 10, maxPoints: 10, status: "pass", detail: `${lines} lines — comprehensive` });
+        else if (lines <= RUBRIC.copilotPartial) {
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 1, maxPoints: 6, status: "partial", detail: `${at} — a stub; add architecture, commands, rules, key files` });
         }
-        else if (lines > 15) {
-            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 6, maxPoints: 10, status: "partial", detail: `${lines} lines — could be more detailed` });
+        else if (found.length > 0) {
+            const missing = AGENT_DOC_TOPICS.filter(t => !found.includes(t.label)).map(t => t.label);
+            const pts = found.length >= AGENT_DOC_TOPICS.length - 1 ? 4 : 2;
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: pts, maxPoints: 6, status: "partial", detail: `${at} — has ${found.join(", ")}; missing ${missing.join(", ")}` });
         }
         else {
-            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 3, maxPoints: 10, status: "partial", detail: `${lines} lines — too sparse, add architecture, rules, key files` });
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 1, maxPoints: 6, status: "partial", detail: `${at} — none of ${AGENT_DOC_TOPICS.map(t => t.label).join("/")} found; length without structure` });
         }
     }
     else {
-        checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 0, maxPoints: 10, status: "fail", detail: "Missing — AI agents lack project context" });
+        checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 0, maxPoints: 6, status: "fail", detail: "Missing from .github/ and repo root — AI agents lack project context" });
+    }
+    // Doc freshness (4 pts) — is the agent doc keeping up with the code?
+    // 🔒 LOCKED [SCORE-DOC-FRESHNESS] — 2026-08-14
+    // ⛔ NEVER treat a doc's existence as evidence that it is current.
+    // WHY: a 500-line copilot-instructions.md last touched a year ago scored identically to one
+    //      updated yesterday. Stale agent docs are worse than missing ones — an agent trusts them.
+    // FIX: count commits that touched the repo since the doc was last modified, excluding the doc
+    //      itself. The same signal firewall.ts already computes for its staleness nudges.
+    // [EXEC-FAILURE-IS-NOT-EMPTY]: if git cannot answer, this is "unknown", never a pass.
+    if (copilot && existsSync(join(p, ".git"))) {
+        const since = new Date(statSync(copilot.path).mtimeMs).toISOString();
+        // NEVER pipe this through `| wc -l`: a shell pipeline reports the LAST command's exit status,
+        // so a failed `git log` still exits 0 with output "0" — which reads as "0 commits since the
+        // doc changed → fully current". Caught by [SCORE-CANARY]. Count in JS where failure is visible.
+        const { ok, output } = execChecked(`git --no-pager log --oneline --since="${since}" -- . ":!${copilot.rel}"`, p);
+        const drift = ok ? (output ? output.split("\n").length : 0) : NaN;
+        if (!ok || Number.isNaN(drift)) {
+            checks.push({ name: "Doc freshness", category: "Documentation", points: 0, maxPoints: 4, status: "unknown", detail: "❔ git log failed here — cannot tell whether the agent doc is current" });
+        }
+        else if (drift === 0) {
+            checks.push({ name: "Doc freshness", category: "Documentation", points: 4, maxPoints: 4, status: "pass", detail: "Agent doc is the most recent change — fully current" });
+        }
+        else if (drift <= RUBRIC.freshnessGood) {
+            checks.push({ name: "Doc freshness", category: "Documentation", points: 4, maxPoints: 4, status: "pass", detail: `${drift} commit(s) since the agent doc was updated` });
+        }
+        else if (drift <= RUBRIC.freshnessStale) {
+            checks.push({ name: "Doc freshness", category: "Documentation", points: 2, maxPoints: 4, status: "partial", detail: `${drift} commits since the agent doc was updated — drifting` });
+        }
+        else {
+            checks.push({ name: "Doc freshness", category: "Documentation", points: 0, maxPoints: 4, status: "fail", detail: `${drift} commits since the agent doc was updated — agents are reading stale context` });
+        }
+    }
+    else if (copilot) {
+        checks.push({ name: "Doc freshness", category: "Documentation", points: 0, maxPoints: 4, status: "unknown", detail: "❔ Not a git repo — cannot measure doc drift" });
+    }
+    else {
+        checks.push({ name: "Doc freshness", category: "Documentation", points: 0, maxPoints: 4, status: "fail", detail: "No agent doc to keep fresh" });
     }
     // README.md (8 pts)
     const readmePath = join(p, "README.md");
     if (existsSync(readmePath)) {
         const content = readFileSync(readmePath, "utf-8");
         const readmeLines = content.split("\n").length;
-        if (readmeLines > 30) {
-            checks.push({ name: "README.md", category: "Documentation", points: 8, maxPoints: 8, status: "pass", detail: `${readmeLines} lines` });
+        if (readmeLines > RUBRIC.readmeFull) {
+            checks.push({ name: "README.md", category: "Documentation", points: 6, maxPoints: 6, status: "pass", detail: `${readmeLines} lines` });
         }
         else {
-            checks.push({ name: "README.md", category: "Documentation", points: 4, maxPoints: 8, status: "partial", detail: `${readmeLines} lines — sparse` });
+            checks.push({ name: "README.md", category: "Documentation", points: 3, maxPoints: 6, status: "partial", detail: `${readmeLines} lines — sparse` });
         }
     }
     else {
-        checks.push({ name: "README.md", category: "Documentation", points: 0, maxPoints: 8, status: "fail", detail: "Missing" });
+        checks.push({ name: "README.md", category: "Documentation", points: 0, maxPoints: 6, status: "fail", detail: "Missing" });
     }
     // CLAUDE.md / .cursorrules / AGENTS.md (6 pts)
     const altPatterns = ["CLAUDE.md", ".cursorrules", ".cursor/rules", "AGENTS.md"];
     const foundAlt = altPatterns.filter(pat => existsSync(join(p, pat)));
     const realAlt = foundAlt.filter(pat => !isSymlink(join(p, pat)));
     const symlinkAlt = foundAlt.filter(pat => isSymlink(join(p, pat)));
-    if (realAlt.length >= 2) {
-        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 6, maxPoints: 6, status: "pass", detail: `Found: ${realAlt.join(", ")}` });
+    if (realAlt.length >= RUBRIC.multiAgentFull) {
+        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 4, maxPoints: 4, status: "pass", detail: `Found: ${realAlt.join(", ")}` });
     }
     else if (realAlt.length === 1 && symlinkAlt.length >= 1) {
-        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 4, maxPoints: 6, status: "partial", detail: `${realAlt[0]} + ${symlinkAlt.length} symlink(s) — symlinks count as partial` });
+        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 3, maxPoints: 4, status: "partial", detail: `${realAlt[0]} + ${symlinkAlt.length} symlink(s) — symlinks count as partial` });
     }
-    else if (foundAlt.length >= 2 && realAlt.length === 0) {
-        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 2, maxPoints: 6, status: "partial", detail: `${foundAlt.join(", ")} — all symlinks, create real per-agent files` });
+    else if (foundAlt.length >= RUBRIC.multiAgentFull && realAlt.length === 0) {
+        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 1, maxPoints: 4, status: "partial", detail: `${foundAlt.join(", ")} — all symlinks, create real per-agent files` });
     }
     else if (foundAlt.length === 1) {
         const pts = isSymlink(join(p, foundAlt[0])) ? 1 : 3;
         checks.push({ name: "Multi-agent patterns", category: "Documentation", points: pts, maxPoints: 6, status: "partial", detail: `Found: ${foundAlt[0]}${isSymlink(join(p, foundAlt[0])) ? " (symlink)" : ""} only` });
     }
     else {
-        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 0, maxPoints: 6, status: "fail", detail: "No CLAUDE.md, .cursorrules, or AGENTS.md" });
+        checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 0, maxPoints: 4, status: "fail", detail: "No CLAUDE.md, .cursorrules, or AGENTS.md" });
     }
-    // .github/SKILLS.md (3 pts)
-    const skillsPath = join(p, ".github", "SKILLS.md");
-    if (existsSync(skillsPath)) {
-        const skillsContent = readFileSync(skillsPath, "utf-8");
+    // SKILLS.md (3 pts) — .github/ or repo root, see resolveDocPath LOCK
+    const skills = resolveDocPath(p, "SKILLS.md");
+    if (skills) {
+        const skillsContent = readFileSync(skills.path, "utf-8");
         const skillsLines = skillsContent.split("\n").length;
-        if (skillsLines > 10 && !isSymlink(skillsPath)) {
-            checks.push({ name: "SKILLS.md", category: "Documentation", points: 3, maxPoints: 3, status: "pass", detail: `${skillsLines} lines` });
+        if (skillsLines > RUBRIC.skillsFull && !isSymlink(skills.path)) {
+            checks.push({ name: "SKILLS.md", category: "Documentation", points: 3, maxPoints: 3, status: "pass", detail: `${skillsLines} lines (${skills.rel})` });
         }
         else {
-            checks.push({ name: "SKILLS.md", category: "Documentation", points: 1, maxPoints: 3, status: "partial", detail: `${skillsLines} lines${isSymlink(skillsPath) ? " (symlink)" : ""} — add real skill descriptions` });
+            checks.push({ name: "SKILLS.md", category: "Documentation", points: 1, maxPoints: 3, status: "partial", detail: `${skillsLines} lines (${skills.rel})${isSymlink(skills.path) ? " — symlink" : ""} — add real skill descriptions` });
         }
     }
     else {
-        checks.push({ name: "SKILLS.md", category: "Documentation", points: 0, maxPoints: 3, status: "fail", detail: "Missing — agents can't discover capabilities" });
+        checks.push({ name: "SKILLS.md", category: "Documentation", points: 0, maxPoints: 3, status: "fail", detail: "Missing from .github/ and repo root — agents can't discover capabilities" });
     }
     // .env.example (3 pts) — validates actual content, not just existence
     const envExamplePath = join(p, ".env.example");
     if (existsSync(envExamplePath)) {
         const envContent = readFileSync(envExamplePath, "utf-8");
         const envVarLines = envContent.split("\n").filter(l => /^[A-Z_]+=/.test(l.trim())).length;
-        if (envVarLines >= 3) {
-            checks.push({ name: ".env.example", category: "Documentation", points: 3, maxPoints: 3, status: "pass", detail: `${envVarLines} env vars documented` });
+        if (envVarLines >= RUBRIC.envExampleVars) {
+            checks.push({ name: ".env.example", category: "Documentation", points: 2, maxPoints: 2, status: "pass", detail: `${envVarLines} env vars documented` });
         }
         else {
-            checks.push({ name: ".env.example", category: "Documentation", points: 1, maxPoints: 3, status: "partial", detail: `Only ${envVarLines} env var(s) — add all required vars` });
+            checks.push({ name: ".env.example", category: "Documentation", points: 1, maxPoints: 2, status: "partial", detail: `Only ${envVarLines} env var(s) — add all required vars` });
         }
     }
     else {
-        checks.push({ name: ".env.example", category: "Documentation", points: 0, maxPoints: 3, status: "fail", detail: "Missing — agents can't set up env" });
+        checks.push({ name: ".env.example", category: "Documentation", points: 0, maxPoints: 2, status: "fail", detail: "Missing — agents can't set up env" });
     }
     // --- Infrastructure (30 points max) ---
     // Git repo (5 pts)
     if (existsSync(join(p, ".git"))) {
-        checks.push({ name: "Git repository", category: "Infrastructure", points: 5, maxPoints: 5, status: "pass", detail: "Initialized" });
+        checks.push({ name: "Git repository", category: "Infrastructure", points: 4, maxPoints: 4, status: "pass", detail: "Initialized" });
     }
     else {
-        checks.push({ name: "Git repository", category: "Infrastructure", points: 0, maxPoints: 5, status: "fail", detail: "Not a git repo" });
+        checks.push({ name: "Git repository", category: "Infrastructure", points: 0, maxPoints: 4, status: "fail", detail: "Not a git repo" });
     }
     // .gitignore (3 pts) — validates essential patterns, not just existence
     const gitignoreScorePath = join(p, ".gitignore");
@@ -1019,28 +1240,35 @@ export function scoreProject(dir) {
         const giContent = readFileSync(gitignoreScorePath, "utf-8");
         const essentialPatterns = [".env", "node_modules", "dist", "vendor", ".DS_Store", "*.log"];
         const foundPatterns = essentialPatterns.filter(pat => giContent.includes(pat));
-        if (foundPatterns.length >= 3) {
-            checks.push({ name: ".gitignore", category: "Infrastructure", points: 3, maxPoints: 3, status: "pass", detail: `${foundPatterns.length} essential patterns` });
+        if (foundPatterns.length >= RUBRIC.gitignoreFull) {
+            checks.push({ name: ".gitignore", category: "Infrastructure", points: 2, maxPoints: 2, status: "pass", detail: `${foundPatterns.length} essential patterns` });
         }
-        else if (foundPatterns.length >= 1) {
-            checks.push({ name: ".gitignore", category: "Infrastructure", points: 2, maxPoints: 3, status: "partial", detail: `Only ${foundPatterns.length} essential pattern(s) — add .env, node_modules, dist` });
+        else if (foundPatterns.length >= RUBRIC.gitignorePartial) {
+            checks.push({ name: ".gitignore", category: "Infrastructure", points: 1, maxPoints: 2, status: "partial", detail: `Only ${foundPatterns.length} essential pattern(s) — add .env, node_modules, dist` });
         }
         else {
-            checks.push({ name: ".gitignore", category: "Infrastructure", points: 1, maxPoints: 3, status: "partial", detail: "Exists but missing essential patterns (.env, node_modules)" });
+            checks.push({ name: ".gitignore", category: "Infrastructure", points: 1, maxPoints: 2, status: "partial", detail: "Exists but missing essential patterns (.env, node_modules)" });
         }
     }
     else {
-        checks.push({ name: ".gitignore", category: "Infrastructure", points: 0, maxPoints: 3, status: "fail", detail: "Missing" });
-    }
-    // Git hooks (5 pts)
-    const hookDir = join(p, "hooks");
-    const gitHookDir = join(p, ".git", "hooks");
-    const hasPostCommit = existsSync(join(hookDir, "post-commit")) || existsSync(join(gitHookDir, "post-commit"));
-    if (hasPostCommit) {
-        checks.push({ name: "Git hooks", category: "Infrastructure", points: 5, maxPoints: 5, status: "pass", detail: "post-commit hook configured" });
+        checks.push({ name: ".gitignore", category: "Infrastructure", points: 0, maxPoints: 2, status: "fail", detail: "Missing" });
+    }
+    // Git hooks (5 pts) — see [ABSENCE-IS-NOT-A-VERDICT]: "installed but broken" is not "not installed"
+    const repoHook = join(p, "hooks", "post-commit");
+    const gitHook = join(p, ".git", "hooks", "post-commit");
+    // existsSync() follows symlinks — a dangling link reads as absent. Check the link itself first.
+    const dangling = [repoHook, gitHook].filter(h => isSymlink(h) && !existsSync(h));
+    const live = [repoHook, gitHook].filter(h => existsSync(h));
+    if (live.length > 0) {
+        const where = live.map(h => h === gitHook ? ".git/hooks/post-commit" : "hooks/post-commit").join(" + ");
+        checks.push({ name: "Git hooks", category: "Infrastructure", points: 4, maxPoints: 4, status: "pass", detail: `post-commit hook configured (${where})` });
+    }
+    else if (dangling.length > 0) {
+        const broken = dangling.map(h => `${h === gitHook ? ".git/hooks" : "hooks"}/post-commit → ${readlinkSafe(h)}`).join(", ");
+        checks.push({ name: "Git hooks", category: "Infrastructure", points: 0, maxPoints: 4, status: "fail", detail: `⚠ Hook installed but BROKEN — dangling symlink: ${broken}. Auto-push is silently dead; restore the target, don't re-install` });
     }
     else {
-        checks.push({ name: "Git hooks", category: "Infrastructure", points: 0, maxPoints: 5, status: "fail", detail: "No hooks — consider auto-push" });
+        checks.push({ name: "Git hooks", category: "Infrastructure", points: 0, maxPoints: 4, status: "fail", detail: "No post-commit hook at hooks/ or .git/hooks/ — consider auto-push" });
     }
     // Docker / containerization (5 pts)
     // Context-aware: only award points if Docker is actually used for deployment.
@@ -1081,21 +1309,21 @@ export function scoreProject(dir) {
         existsSync(join(p, "fly.toml")) ||
         existsSync(join(p, "railway.json"));
     if (usesDockerForReal && hasDockerfile && hasCompose) {
-        checks.push({ name: "Docker", category: "Infrastructure", points: 5, maxPoints: 5, status: "pass", detail: "Dockerfile + compose (active deployment)" });
+        checks.push({ name: "Docker", category: "Infrastructure", points: 4, maxPoints: 4, status: "pass", detail: "Dockerfile + compose (active deployment)" });
     }
     else if (usesDockerForReal && (hasDockerfile || hasCompose)) {
-        checks.push({ name: "Docker", category: "Infrastructure", points: 3, maxPoints: 5, status: "partial", detail: hasDockerfile ? "Dockerfile only" : "Compose only" });
+        checks.push({ name: "Docker", category: "Infrastructure", points: 2, maxPoints: 4, status: "partial", detail: hasDockerfile ? "Dockerfile only" : "Compose only" });
     }
     else if ((hasDockerfile || hasCompose) && !usesDockerForReal) {
         // Files exist but look like stubs/placeholders — minimal credit
-        checks.push({ name: "Docker", category: "Infrastructure", points: 1, maxPoints: 5, status: "partial", detail: "Docker files exist but appear to be placeholders — not used in deployment" });
+        checks.push({ name: "Docker", category: "Infrastructure", points: 1, maxPoints: 4, status: "partial", detail: "Docker files exist but appear to be placeholders — not used in deployment" });
     }
     else if (hasAltDeploy) {
         // Project uses a different deploy platform — Docker is N/A, award full points
-        checks.push({ name: "Containerization", category: "Infrastructure", points: 5, maxPoints: 5, status: "pass", detail: "Uses managed platform (Vercel/Netlify/Render/Fly)" });
+        checks.push({ name: "Containerization", category: "Infrastructure", points: 4, maxPoints: 4, status: "pass", detail: "Uses managed platform (Vercel/Netlify/Render/Fly)" });
     }
     else {
-        checks.push({ name: "Docker", category: "Infrastructure", points: 0, maxPoints: 5, status: "fail", detail: "Not containerized" });
+        checks.push({ name: "Docker", category: "Infrastructure", points: 0, maxPoints: 4, status: "fail", detail: "Not containerized" });
     }
     // CI config (5 pts) — validates workflows have real actions, not empty stubs
     const ciPaths = [".github/workflows", ".gitlab-ci.yml", "Jenkinsfile", ".circleci", ".travis.yml"];
@@ -1138,14 +1366,14 @@ export function scoreProject(dir) {
         const deployContent = readFileSync(deployFile, "utf-8");
         const deployLines = deployContent.split("\n").filter(l => l.trim() && !l.trim().startsWith("#")).length;
         if (deployLines >= 3) {
-            checks.push({ name: "Deploy script", category: "Infrastructure", points: 4, maxPoints: 4, status: "pass", detail: `${foundDeploy[0]} (${deployLines} effective lines)` });
+            checks.push({ name: "Deploy script", category: "Infrastructure", points: 3, maxPoints: 3, status: "pass", detail: `${foundDeploy[0]} (${deployLines} effective lines)` });
         }
         else {
-            checks.push({ name: "Deploy script", category: "Infrastructure", points: 1, maxPoints: 4, status: "partial", detail: `${foundDeploy[0]} — only ${deployLines} effective lines, looks like a placeholder` });
+            checks.push({ name: "Deploy script", category: "Infrastructure", points: 1, maxPoints: 3, status: "partial", detail: `${foundDeploy[0]} — only ${deployLines} effective lines, looks like a placeholder` });
         }
     }
     else {
-        checks.push({ name: "Deploy script", category: "Infrastructure", points: 0, maxPoints: 4, status: "fail", detail: "No deploy automation" });
+        checks.push({ name: "Deploy script", category: "Infrastructure", points: 0, maxPoints: 3, status: "fail", detail: "No deploy automation" });
     }
     // PM2 / process manager (3 pts)
     if (existsSync(join(p, "ecosystem.config.js")) || existsSync(join(p, "ecosystem.config.cjs"))) {
@@ -1165,10 +1393,10 @@ export function scoreProject(dir) {
         if (testIsSymlink) {
             checks.push({ name: "Tests", category: "Code Quality", points: 3, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ is a symlink (${testFileCount} test files) — should be real test directory` });
         }
-        else if (testFileCount >= 5) {
+        else if (testFileCount >= RUBRIC.testsFull) {
             checks.push({ name: "Tests", category: "Code Quality", points: 8, maxPoints: 8, status: "pass", detail: `${foundTests[0]}/ — ${testFileCount} test files` });
         }
-        else if (testFileCount > 0) {
+        else if (testFileCount > RUBRIC.testsPartial) {
             checks.push({ name: "Tests", category: "Code Quality", points: 5, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ — only ${testFileCount} test files` });
         }
         else {
@@ -1195,7 +1423,7 @@ export function scoreProject(dir) {
         const tsconfigContent = readFileSync(tsconfigPath, "utf-8").trim();
         const tsconfigIsSymlink = isSymlink(tsconfigPath);
         // Detect minimal/reference-only tsconfigs (just project references with no real config)
-        const isSubstantive = tsconfigContent.length > 50 && (tsconfigContent.includes('"compilerOptions"') || tsconfigContent.includes('"extends"'));
+        const isSubstantive = tsconfigContent.length > RUBRIC.tsconfigSubstantive && (tsconfigContent.includes('"compilerOptions"') || tsconfigContent.includes('"extends"'));
         if (tsconfigIsSymlink) {
             checks.push({ name: "TypeScript", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "tsconfig.json is a symlink — create root config" });
         }
@@ -1253,53 +1481,93 @@ export function scoreProject(dir) {
     if (existsSync(gitignorePath)) {
         const gitignore = readFileSync(gitignorePath, "utf-8");
         if (gitignore.includes(".env")) {
-            checks.push({ name: ".env in .gitignore", category: "Security", points: 8, maxPoints: 8, status: "pass", detail: ".env is gitignored" });
+            checks.push({ name: ".env in .gitignore", category: "Security", points: 10, maxPoints: 10, status: "pass", detail: ".env is gitignored" });
         }
         else {
-            checks.push({ name: ".env in .gitignore", category: "Security", points: 0, maxPoints: 8, status: "fail", detail: ".env NOT in .gitignore — secrets at risk!" });
+            checks.push({ name: ".env in .gitignore", category: "Security", points: 0, maxPoints: 10, status: "fail", disqualifying: true, detail: ".env NOT in .gitignore — secrets at risk! Caps this project's grade at C" });
         }
     }
     else {
-        checks.push({ name: ".env in .gitignore", category: "Security", points: 0, maxPoints: 8, status: "fail", detail: "No .gitignore at all" });
+        checks.push({ name: ".env in .gitignore", category: "Security", points: 0, maxPoints: 10, status: "fail", detail: "No .gitignore at all" });
     }
     // No secrets in tracked files (6 pts)
-    if (existsSync(join(p, ".env")) && existsSync(join(p, ".git"))) {
-        const tracked = exec("git ls-files .env", p);
-        if (tracked === ".env") {
-            checks.push({ name: "Secrets exposure", category: "Security", points: 0, maxPoints: 6, status: "fail", detail: ".env is tracked by git!" });
+    // [ABSENCE-IS-NOT-A-VERDICT]: "no .env" and "can't run git here" are different states.
+    // The second is unverifiable and must NOT collect a 6/6 pass.
+    const hasEnv = existsSync(join(p, ".env"));
+    const hasGit = existsSync(join(p, ".git"));
+    if (hasEnv && hasGit) {
+        // [EXEC-FAILURE-IS-NOT-EMPTY]: a failed `git ls-files` must never read as "not tracked".
+        const { ok, output: tracked } = execChecked("git ls-files .env", p);
+        if (!ok) {
+            checks.push({ name: "Secrets exposure", category: "Security", points: 0, maxPoints: 10, status: "unknown", detail: "❔ .env present but `git ls-files` failed here — cannot verify whether it is tracked" });
+        }
+        else if (tracked === ".env") {
+            checks.push({ name: "Secrets exposure", category: "Security", points: 0, maxPoints: 10, status: "fail", disqualifying: true, detail: ".env is tracked by git! Caps this project's grade at C" });
         }
         else {
-            checks.push({ name: "Secrets exposure", category: "Security", points: 6, maxPoints: 6, status: "pass", detail: ".env not tracked" });
+            checks.push({ name: "Secrets exposure", category: "Security", points: 10, maxPoints: 10, status: "pass", detail: ".env present and not tracked by git" });
         }
     }
+    else if (!hasEnv) {
+        checks.push({ name: "Secrets exposure", category: "Security", points: 10, maxPoints: 10, status: "pass", detail: "No .env at repo root — nothing to leak" });
+    }
     else {
-        checks.push({ name: "Secrets exposure", category: "Security", points: 6, maxPoints: 6, status: "pass", detail: "No .env or not a git repo" });
+        checks.push({ name: "Secrets exposure", category: "Security", points: 0, maxPoints: 10, status: "unknown", detail: "❔ .env exists but this is not a git repo — cannot verify whether it is tracked" });
     }
     // Lockfile present (3 pts)
     const lockfiles = ["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "composer.lock"];
     const foundLock = lockfiles.filter(l => existsSync(join(p, l)));
     if (foundLock.length > 0) {
-        checks.push({ name: "Lockfile", category: "Security", points: 3, maxPoints: 3, status: "pass", detail: foundLock.join(", ") });
+        checks.push({ name: "Lockfile", category: "Security", points: 5, maxPoints: 5, status: "pass", detail: foundLock.join(", ") });
     }
     else if (existsSync(pkgPath) || existsSync(join(p, "composer.json"))) {
-        checks.push({ name: "Lockfile", category: "Security", points: 0, maxPoints: 3, status: "fail", detail: "No lockfile — deps not pinned" });
+        checks.push({ name: "Lockfile", category: "Security", points: 0, maxPoints: 5, status: "fail", detail: "No lockfile — deps not pinned" });
     }
     // node_modules in .gitignore (3 pts)
     if (existsSync(gitignorePath)) {
         const gitignore = readFileSync(gitignorePath, "utf-8");
         if (gitignore.includes("node_modules") || gitignore.includes("vendor")) {
-            checks.push({ name: "Deps gitignored", category: "Security", points: 3, maxPoints: 3, status: "pass", detail: "node_modules/vendor gitignored" });
+            checks.push({ name: "Deps gitignored", category: "Security", points: 5, maxPoints: 5, status: "pass", detail: "node_modules/vendor gitignored" });
         }
         else if (!existsSync(join(p, "package.json")) && !existsSync(join(p, "composer.json"))) {
-            checks.push({ name: "Deps gitignored", category: "Security", points: 3, maxPoints: 3, status: "pass", detail: "N/A — no package manager" });
+            checks.push({ name: "Deps gitignored", category: "Security", points: 5, maxPoints: 5, status: "pass", detail: "N/A — no package manager" });
         }
         else {
-            checks.push({ name: "Deps gitignored", category: "Security", points: 0, maxPoints: 3, status: "fail", detail: "node_modules/vendor not in .gitignore" });
+            checks.push({ name: "Deps gitignored", category: "Security", points: 0, maxPoints: 5, status: "fail", detail: "node_modules/vendor not in .gitignore" });
         }
     }
     // --- Calculate totals ---
+    // 🔒 LOCKED [SCORE-ARITHMETIC-INVARIANT] — 2026-08-13
+    // ⛔ NEVER compute the percentage against a summed maxScore without checking it equals 100 first.
+    // WHY: several checks only push a result inside an `if` (e.g. "Deps gitignored" is skipped
+    //      entirely when a project has no .gitignore). A skipped check silently SHRANK the
+    //      denominator, so a project got a percentage out of 97 while every report — and every
+    //      cross-project comparison — presented it as if it were out of 100. Nothing was wrong on
+    //      screen; the number was just quietly measuring something else. A missing check is an
+    //      unknown, not a smaller exam.
+    // FIX: the denominator is pinned to EXPECTED_MAX_SCORE. Any shortfall becomes a visible
+    //      "Scoring completeness" unknown row worth the missing points, and is logged to stderr
+    //      (never stdout — MCP protocol stream). Exact, free, unarguable, runs every time.
+    const EXPECTED_MAX_SCORE = 100;
     const totalScore = checks.reduce((sum, c) => sum + c.points, 0);
-    const maxScore = checks.reduce((sum, c) => sum + c.maxPoints, 0);
+    const emittedMax = checks.reduce((sum, c) => sum + c.maxPoints, 0);
+    if (emittedMax !== EXPECTED_MAX_SCORE) {
+        const gap = EXPECTED_MAX_SCORE - emittedMax;
+        if (!canaryRunning) {
+            console.error(`[contextengine] ⚠ scoring invariant: ${dir.name} emitted ${emittedMax}/${EXPECTED_MAX_SCORE} max points (${gap > 0 ? "missing" : "excess"} ${Math.abs(gap)}) — see the "Could Not Be Verified" section`);
+        }
+        if (gap > 0) {
+            checks.push({
+                name: "Scoring completeness",
+                category: "Meta",
+                points: 0,
+                maxPoints: gap,
+                status: "unknown",
+                detail: `❔ ${gap} point(s) never assessed — a check did not run for this project. Scored against the full ${EXPECTED_MAX_SCORE}, so this is a gap in the audit, not a penalty you can fix`,
+            });
+        }
+    }
+    const maxScore = Math.max(EXPECTED_MAX_SCORE, emittedMax);
     const percentage = Math.round((totalScore / maxScore) * 100);
     let grade;
     if (percentage >= 90)
@@ -1314,6 +1582,21 @@ export function scoreProject(dir) {
         grade = "D";
     else
         grade = "F";
+    // 🔒 LOCKED [SECURITY-IS-DISQUALIFYING] — 2026-08-14
+    // ⛔ NEVER let exposed secrets be averaged away into a good grade.
+    // WHY: security was 20 of 100, so a project could commit its .env and still score 80% on the
+    //      strength of good docs. Weighting alone cannot express "this one thing is not a rounding
+    //      error" — at any weight below ~50 the arithmetic still lets other categories outvote it.
+    // FIX: a failed secret-exposure check CAPS the grade at C no matter the point total. The
+    //      percentage stays honest (it still reports what was earned); only the grade is capped, and
+    //      the report says why. Reserved for actual secret exposure — a missing lockfile is hygiene,
+    //      not a disqualification, and must never set this flag.
+    const disqualified = checks.filter(c => c.disqualifying && c.status === "fail");
+    const GRADE_CAP = "C";
+    const gradeOrder = ["F", "D", "C", "B", "A", "A+"];
+    if (disqualified.length > 0 && gradeOrder.indexOf(grade) > gradeOrder.indexOf(GRADE_CAP)) {
+        grade = GRADE_CAP;
+    }
     return {
         project: dir.name,
         path: dir.path,
@@ -1372,7 +1655,7 @@ export function formatScoreReport(scores) {
         lines.push("| Check | Category | Score | Status | Detail |");
         lines.push("|-------|----------|-------|--------|--------|");
         for (const c of s.checks) {
-            const icon = c.status === "pass" ? "✅" : c.status === "partial" ? "🟡" : "❌";
+            const icon = statusIcon(c.status);
             lines.push(`| ${c.name} | ${c.category} | ${c.points}/${c.maxPoints} | ${icon} | ${c.detail} |`);
         }
         lines.push("");
@@ -1414,7 +1697,7 @@ export function generateProjectScoreMD(score) {
     lines.push("| Check | Category | Score | Max | Status | Detail |");
     lines.push("|---|---|---|---|---|---|");
     for (const c of score.checks) {
-        const icon = c.status === "pass" ? "✅" : c.status === "partial" ? "🟡" : "❌";
+        const icon = statusIcon(c.status);
         lines.push(`| ${c.name} | ${c.category} | ${c.points} | ${c.maxPoints} | ${icon} | ${c.detail} |`);
     }
     // Failures and improvements
@@ -1429,6 +1712,16 @@ export function generateProjectScoreMD(score) {
             lines.push(`- 🟡 **${p.name}**: ${p.detail}`);
         }
     }
+    // Unverifiable — kept OUT of "Improvements Needed" on purpose. These are checks that could not
+    // reach a verdict; listing them as project failures is what [ABSENCE-IS-NOT-A-VERDICT] forbids.
+    const unknowns = score.checks.filter(c => c.status === "unknown");
+    if (unknowns.length > 0) {
+        lines.push("\n## Could Not Be Verified\n");
+        lines.push("_Gaps in the audit, not defects in the project — the scorer could not determine these._\n");
+        for (const u of unknowns) {
+            lines.push(`- ❔ **${u.name}**: ${u.detail}`);
+        }
+    }
     lines.push(`\n---\n*Generated by [ContextEngine](https://www.npmjs.com/package/@compr/contextengine-mcp) on ${date}*\n`);
     return lines.join("\n");
 }
@@ -1449,13 +1742,8 @@ export function generateScoreHTML(scores) {
             return "#f97316";
         return "#ef4444";
     }
-    function statusIcon(status) {
-        if (status === "pass")
-            return "✅";
-        if (status === "partial")
-            return "🟡";
-        return "❌";
-    }
+    // statusIcon is module-level — see [ABSENCE-IS-NOT-A-VERDICT]. A local copy here previously
+    // rendered "unknown" as ❌, which is the exact conflation this work removed.
     function categoryByScore(checks) {
         const m = new Map();
         for (const c of checks) {

package/dist/cli.js

@@ -522,7 +522,7 @@ import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { scanCodeDir } from "./code-chunker.js";
-import { listProjects, runComplianceAudit, formatProjectList, formatPlan, scoreProject, formatScoreReport, generateScoreHTML, generateProjectScoreMD, } from "./agents.js";
+import { listProjects, runComplianceAudit, formatProjectList, formatPlan, scoreProject, runScoreCanary, formatScoreReport, generateScoreHTML, generateProjectScoreMD, } from "./agents.js";
 import { listLearnings, learningsToChunks, learningsStats, formatLearnings, saveLearning, deleteLearning, importLearningsFromFile, autoImportFromSources, LEARNING_CATEGORIES, } from "./learnings.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { activate, deactivate, getActivationStatus, gateCheck, } from "./activation.js";
@@ -703,6 +703,19 @@ async function cliScore(project, html = false, save = true) {
         console.error(gate);
         process.exit(1);
     }
+    // [SCORE-CANARY] — every health signal must read exactly as pinned before we are allowed to
+    // write a single SCORE.md. A drifting scorer that silently rewrites 37 reports is the failure
+    // this blocks; it does not test for one known bug, it refuses to proceed on ANY deviation.
+    const canary = runScoreCanary();
+    if (!canary.ok) {
+        console.error("\n🚨 Scoring canary FAILED — refusing to write any SCORE.md.\n");
+        for (const d of canary.deviations)
+            console.error(`   • ${d}`);
+        console.error(canary.inconclusive
+            ? "\nThe canary fixture could not be built, so the scorer is unverified. This is an unknown, not a pass.\n"
+            : "\nThe scorer no longer behaves as pinned. Fix the deviation or update the pin deliberately.\n");
+        process.exit(1);
+    }
     const projectDirs = loadProjectDirs();
     let scores;
     if (project) {

package/dist/config.js

@@ -7,6 +7,7 @@ const DEFAULT_PATTERNS = [
     ".github/copilot-instructions.md",
     ".github/instructions/copilot-instructions.md",
     ".github/SKILLS.md",
+    "SKILLS.md", // `contextengine init` writes SKILLS.md at the repo root — index both
     // Claude Code
     "CLAUDE.md",
     // Cursor

package/dist/rubric.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Scoring thresholds — the numbers that decide what earns what.
+ *
+ * 🔒 LOCKED [RUBRIC-SINGLE-TABLE] — 2026-08-14
+ * ⛔ NEVER inline a scoring threshold back into src/agents.ts.
+ * WHY: these values are what makes a score gameable — knowing ">50 lines earns the full 10"
+ *      lets anyone pad a file to a number instead of writing the content. They were scattered
+ *      as bare literals across ~10 call sites in agents.ts, so they shipped readable in
+ *      dist/agents.js and could not be obscured without rewriting the whole scorer.
+ * FIX: one table, one module. `scripts/obfuscate-rubric.mjs` rewrites dist/rubric.js at build
+ *      time into an encoded blob, so the published package carries no readable thresholds.
+ *      Adding a literal back into agents.ts silently re-exposes it — the obfuscator only
+ *      touches this file.
+ *
+ * NOTE ON STRENGTH: this stops casual reading, not determined analysis. The surrounding
+ * comparison logic still ships, and 2.1.3 remains on npm forever as a plaintext reference.
+ * It is a speed bump for score-gaming, deliberately, and must never be described as more.
+ * The real protections are the activation gate and BSL-1.1. See CLAUDE.md rules 1-3.
+ */
+export interface Rubric {
+    /** copilot-instructions.md line counts for the 10 / 6 point tiers */
+    copilotFull: number;
+    copilotPartial: number;
+    /** README.md line count for the full 8 points */
+    readmeFull: number;
+    /** SKILLS.md line count for the full 3 points */
+    skillsFull: number;
+    /** .env.example — documented variables needed for full marks */
+    envExampleVars: number;
+    /** .gitignore — essential patterns matched for full / partial credit */
+    gitignoreFull: number;
+    gitignorePartial: number;
+    /** Test files present for the 8 / 5 point tiers */
+    testsFull: number;
+    testsPartial: number;
+    /** tsconfig.json byte length below which it is treated as a stub */
+    tsconfigSubstantive: number;
+    /** Real (non-symlink) agent-pattern files for full credit */
+    multiAgentFull: number;
+    /** Commits since the agent doc was updated: at or below = current, above `freshnessStale` = stale */
+    freshnessGood: number;
+    freshnessStale: number;
+}
+export declare const RUBRIC: Rubric;
+//# sourceMappingURL=rubric.d.ts.map

package/dist/rubric.js

@@ -0,0 +1,9 @@
+/*__RUBRIC_ENCODED__*/
+const _k = "ce-rubric-v1";
+const _d = (b) => {
+  const raw = Buffer.from(b, "base64").toString("binary");
+  let s = "";
+  for (let i = 0; i < raw.length; i++) s += String.fromCharCode(raw.charCodeAt(i) ^ _k.charCodeAt(i % _k.length));
+  return JSON.parse(s);
+};
+export const RUBRIC = Object.freeze(_d("GEdOHQULHgYXawNdD0cXR0VOUAoMXR9dDBF9EwcWGwgPD0wAVkkPABADFgQGawNdD0cXQUVOUBoIRBpdECNYHhlASFhTAVRUDRNoChQPAgUGexdDEEcXQVlAFQAXRBFfDBdINAAOHktZHloTBAxZGxIMHRsGfRdDFwxMHldYQ0VBWRNCFxZrBxkOUFNWAVRFBhZZASUDAB0KTBoTWVUBUAEREQYNSx9WMBBPAQEDHB0KWxMTWVAdXlcPBwUXRDdWBgtZNAAOHktZH1oTBRdIAR0MFxoQahleB0cXQ0VOUA8RSAVZDQBeASYWEwUGD0wFUxg="));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/",
-    "prepublishOnly": "node scripts/check-npm-token-expiry.mjs && npm run build",
+    "prepublishOnly": "node scripts/check-npm-token-expiry.mjs && npm run build && node scripts/obfuscate-rubric.mjs",
     "check-token": "node scripts/check-npm-token-expiry.mjs"
   },
   "keywords": [