@compr/opscontext-mcp 2.1.1 → 2.2.0

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/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired";
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired" | "community.sync_ok" | "community.sync_error";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;

package/dist/audit.js

@@ -6,26 +6,119 @@
 // ⛔ NEVER catch errors inside appendAudit() — silent failures defeat the
 //    entire compliance story. Use safeAppend() at call sites if you need
 //    failure isolation; appendAudit() must surface problems loudly.
-// WHY: This is the SOC2 CC7.2 / ISO 27001 A.12.4.1 compliance bedrock. The
-//    audit log is the foundation that licence-signature verification,
-//    compliance reporting, and enforcement telemetry all build on. Any
-//    silent break here destroys evidence value across years of records.
+// WHY: This is the bedrock for evidence aligned with SOC 2 CC7.2 (change
+//    monitoring) and ISO 27001 A.12.4.1 (event logging). These are
+//    EVIDENCE ARTIFACTS — OpsContext is NOT itself SOC 2– or ISO 27001–
+//    certified; the chain helps a deploying org's auditor satisfy those
+//    controls. See docs/compliance/cc7.2.md + docs/compliance/a.12.4.1.md.
+//    Any silent break here destroys evidence value across years of
+//    records and invalidates the chain integrity property downstream
+//    code (verifyChain, license signatures, enforcement telemetry)
+//    depends on.
 // FIX: If you need to evolve the record format, version the chain
 //    (add a "v":2 field) and keep verifyChain() backward-compatible by
 //    dispatching on the v field. Don't mutate the v=1 contract.
 //
+// 🔒 LOCKED [AUDIT-001-WRITE-RACE-FIX] — 2026-06-24
+// ⛔ NEVER remove the file-lock acquisition in appendAudit(). The chain
+//    was broken at index 2826 (Sessions 11-13) by concurrent writers
+//    (activation server + main MCP) reading the same prev_hash before
+//    either had flushed. The lock serializes the read-then-write
+//    window across processes.
+// ⛔ NEVER trust cachedLastHash without verifying file size hasn't
+//    grown since cachedSize. Another process may have written between
+//    OUR last write and OUR next read.
+// WHY: audit-001-write-race documented in Session 11 SCORE.md. The
+//    in-process chain cache is a perf optimization, NOT a correctness
+//    guarantee — correctness comes from the lock + the size-mismatch
+//    re-read.
+// FIX: To raise throughput further (if profiling proves the stat() per
+//    append is hot), batch appends within a process behind a single
+//    lock acquisition. Don't remove the lock.
+//
 // Tamper-evident audit log — hash-chained JSONL at ~/.contextengine/audit.log.
 //
-// Compliance basis: SOC2 CC7.2 (audit logging), ISO 27001 A.12.4.1 (event logs).
+// Compliance: produces evidence aligned with SOC 2 CC7.2 + ISO 27001 A.12.4.1
+// (evidence artifacts, not certifications — see docs/compliance/).
 //
 // Records every state-changing operation. Each line carries the SHA-256 hash
 // of the previous line's canonical content, so mutation of any historical
 // record breaks chain verification at that index.
-import { existsSync, mkdirSync, readFileSync, appendFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, statSync, writeSync, constants, } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { createHash } from "crypto";
 const GENESIS_HASH = "0".repeat(64);
+// ─── File lock primitives ───────────────────────────────────────────────────
+// O_EXCL + O_CREAT is atomic across processes on POSIX and on Windows NTFS,
+// so creating the lockfile is the synchronization primitive. Stale-lock
+// recovery: if the lockfile is older than STALE_LOCK_MS, treat it as
+// orphaned (process crashed mid-append) and unlink it.
+const LOCK_TIMEOUT_MS = 2000; // total wait before giving up
+const LOCK_RETRY_MS = 5; // poll interval
+const STALE_LOCK_MS = 10_000; // lockfile older than this = orphan
+function lockPath() {
+    return join(auditDir(), "audit.lock");
+}
+/** Synchronous sleep that doesn't burn CPU — uses Atomics.wait on a
+ *  throwaway SharedArrayBuffer. Accurate to ~1ms. */
+function syncSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Acquire an exclusive file lock. Returns a release function. Throws if
+ *  unable to acquire within LOCK_TIMEOUT_MS. */
+function acquireLockSync() {
+    const path = lockPath();
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            // O_EXCL fails atomically if the file already exists.
+            const fd = openSync(path, 
+            // eslint-disable-next-line no-bitwise
+            constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            // Write PID + ts so a debugger can see who's holding the lock.
+            try {
+                writeSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
+            }
+            catch {
+                /* lock file is what matters; the contents are nice-to-have */
+            }
+            closeSync(fd);
+            return () => {
+                try {
+                    unlinkSync(path);
+                }
+                catch {
+                    /* already gone — another cleaner won the race */
+                }
+            };
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            // Lockfile exists. Check if it's stale.
+            try {
+                const st = statSync(path);
+                if (Date.now() - st.mtimeMs > STALE_LOCK_MS) {
+                    // Orphaned — force-unlink and retry.
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch {
+                        /* another process just cleaned it; retry */
+                    }
+                    continue;
+                }
+            }
+            catch {
+                /* lockfile vanished between check and stat; just retry */
+            }
+            syncSleep(LOCK_RETRY_MS);
+        }
+    }
+    throw new Error(`Failed to acquire audit lock at ${path} within ${LOCK_TIMEOUT_MS}ms`);
+}
 function auditDir() {
     // CONTEXTENGINE_HOME lets tests run against a temp dir without touching ~/.contextengine
     return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
@@ -62,16 +155,41 @@ function computeHash(prevHash, ts, event, actor, payload) {
     return createHash("sha256").update(canonical).digest("hex");
 }
 let cachedLastHash = null;
+/** File size at our last successful write. If statSync(path).size differs
+ *  on the next call, another process wrote in between → invalidate cache. */
+let cachedSize = 0;
 export function appendAudit(event, payload, actor = "system") {
     ensureDir();
-    if (cachedLastHash === null)
-        cachedLastHash = readLastHash();
-    const ts = new Date().toISOString();
-    const hash = computeHash(cachedLastHash, ts, event, actor, payload);
-    const record = { ts, event, actor, payload, prev_hash: cachedLastHash, hash };
-    appendFileSync(auditPath(), JSON.stringify(record) + "\n");
-    cachedLastHash = hash;
-    return record;
+    const release = acquireLockSync();
+    try {
+        const path = auditPath();
+        // Cache validity check: if file size grew since OUR last write, another
+        // process appended → re-read prev hash from disk (the cache is stale).
+        // Also handles first-ever call (cachedLastHash === null).
+        const currentSize = existsSync(path) ? statSync(path).size : 0;
+        if (cachedLastHash === null || currentSize !== cachedSize) {
+            cachedLastHash = readLastHash();
+            cachedSize = currentSize;
+        }
+        const ts = new Date().toISOString();
+        const hash = computeHash(cachedLastHash, ts, event, actor, payload);
+        const record = {
+            ts,
+            event,
+            actor,
+            payload,
+            prev_hash: cachedLastHash,
+            hash,
+        };
+        const line = JSON.stringify(record) + "\n";
+        appendFileSync(path, line);
+        cachedLastHash = hash;
+        cachedSize += Buffer.byteLength(line, "utf-8");
+        return record;
+    }
+    finally {
+        release();
+    }
 }
 export function readAuditLog() {
     const path = auditPath();
@@ -147,6 +265,7 @@ export function toCsv(records) {
 // Test-only — flush in-memory chain cache so a fresh path is re-read.
 export function resetCacheForTest() {
     cachedLastHash = null;
+    cachedSize = 0;
 }
 // Safe wrapper that never throws into hot paths. Use this from production
 // call sites so a failed audit append cannot break a learning save or