@compr/opscontext-mcp 2.1.3 → 2.2.0

package/dist/agents.d.ts

@@ -102,9 +102,27 @@ export interface ScoreCheck {
     category: string;
     points: number;
     maxPoints: number;
-    status: "pass" | "partial" | "fail";
+    status: "pass" | "partial" | "fail" | "unknown";
     detail: string;
 }
+/**
+ * 🔒 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 +132,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,6 +1,7 @@
 import { execSync } from "child_process";
-import { readFileSync, existsSync, readdirSync, lstatSync } from "fs";
+import { readFileSync, existsSync, readdirSync, lstatSync, readlinkSync, mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "fs";
 import { resolve, join, dirname } from "path";
+import { tmpdir } from "os";
 import { fileURLToPath } from "url";
 // Read version from package.json at module load
 const __agents_dirname = dirname(fileURLToPath(import.meta.url));
@@ -14,16 +15,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 +56,51 @@ 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 "❌";
+}
+/** 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 +973,80 @@ 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/ — 60 lines, should score the full 10
+        writeFileSync(join(dir, ".github", "copilot-instructions.md"), Array.from({ length: 60 }, (_, i) => `line ${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, 10);
+        expect("SKILLS.md points (repo root)", by("SKILLS.md")?.points, 3);
+        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,27 +1055,28 @@ 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 (10 pts) — .github/ or repo root, see resolveDocPath LOCK
+    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 at = `${lines} lines (${copilot.rel})`;
         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: 4, maxPoints: 10, status: "partial", detail: `⚠ Symlink — ${at} — should be a real file with project-specific context` });
         }
         else if (lines > 50) {
-            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 10, maxPoints: 10, status: "pass", detail: `${lines} lines — comprehensive` });
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 10, maxPoints: 10, status: "pass", detail: `${at} — comprehensive` });
         }
         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` });
+            checks.push({ name: "copilot-instructions.md", category: "Documentation", points: 6, maxPoints: 10, status: "partial", detail: `${at} — could be more detailed` });
         }
         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: 3, maxPoints: 10, status: "partial", detail: `${at} — too sparse, add architecture, rules, key files` });
         }
     }
     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: 10, status: "fail", detail: "Missing from .github/ and repo root — AI agents lack project context" });
     }
     // README.md (8 pts)
     const readmePath = join(p, "README.md");
@@ -975,20 +1114,20 @@ export function scoreProject(dir) {
     else {
         checks.push({ name: "Multi-agent patterns", category: "Documentation", points: 0, maxPoints: 6, 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 > 10 && !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");
@@ -1032,15 +1171,22 @@ export function scoreProject(dir) {
     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" });
+    // 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: 5, maxPoints: 5, 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: 5, 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: 5, 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.
@@ -1263,17 +1409,28 @@ export function scoreProject(dir) {
         checks.push({ name: ".env in .gitignore", category: "Security", points: 0, maxPoints: 8, 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") {
+    // [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: 6, 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: 6, status: "fail", detail: ".env is tracked by git!" });
         }
         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: 6, maxPoints: 6, status: "pass", detail: ".env present and not tracked by git" });
         }
     }
+    else if (!hasEnv) {
+        checks.push({ name: "Secrets exposure", category: "Security", points: 6, maxPoints: 6, 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: 6, 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"];
@@ -1298,8 +1455,37 @@ export function scoreProject(dir) {
         }
     }
     // --- 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)
@@ -1372,7 +1558,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 +1600,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 +1615,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 +1645,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.1.3",
+  "version": "2.2.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",