@compr/opscontext-mcp 2.4.3 → 2.5.1

package/dist/detector.js

@@ -333,4 +333,122 @@ export const _internal = {
     detectLoop, detectStuck, detectContextBloat, detectFabrication,
     detectDrift, detectNoInsight, detectSilentFailure, detectStaleDocSignal,
 };
+import { metricsFor } from "./transcript-collector.js";
+import { DEFAULT_PRICING } from "./default-pricing.js";
+export const DEFAULT_COST_THRESHOLDS = {
+    billing_mode: "subscription",
+    // [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — never [] again.
+    pricing: DEFAULT_PRICING,
+    min_cache_efficiency: 3,
+    max_tool_calls_per_agent: 2,
+    max_cost_per_agent_usd: 3,
+    min_fanout_for_canary: 5,
+    max_failed_share: 0.05,
+};
+function mkRun(kind, severity, reason, payload) {
+    // evidence is AuditRecord[]; transcript signals carry their detail in
+    // payload instead of inventing records that were never written.
+    return { kind, severity, reason, evidence: [], payload, detectedAt: Date.now() };
+}
+/**
+ * context_burn — the run is paying for context it is not reusing.
+ *
+ * Fires on cache INEFFICIENCY, tool-call inflation, or per-agent valued cost.
+ * Deliberately does NOT fire on a low output/volume ratio: see
+ * [BURN-IS-COST-WEIGHTED-NOT-VOLUME] in policy.ts.
+ */
+export function detectContextBurn(run, t, m) {
+    const x = m ?? metricsFor(run, t.pricing);
+    if (x.agents === 0)
+        return null;
+    const reasons = [];
+    let severity = "warn";
+    const cacheWrite = run.totals.cacheWrite5m + run.totals.cacheWrite1h;
+    // Only meaningful once enough was written to judge reuse.
+    if (cacheWrite > 100_000 && x.cacheEfficiency < t.min_cache_efficiency) {
+        const writeShare = x.cost.total > 0 ? x.cost.cacheWrite / x.cost.total : 0;
+        reasons.push(`cache reused ${x.cacheEfficiency.toFixed(1)}x (floor ${t.min_cache_efficiency}x) — ` +
+            `${(cacheWrite / 1e6).toFixed(1)}M written vs ${(run.totals.cacheRead / 1e6).toFixed(1)}M read, ` +
+            `${(writeShare * 100).toFixed(0)}% of valued cost is cache WRITES`);
+        if (writeShare > 0.5)
+            severity = "critical";
+    }
+    if (x.medianToolCalls > t.max_tool_calls_per_agent) {
+        reasons.push(`median ${x.medianToolCalls} tool calls/agent (max ${t.max_tool_calls_per_agent}) — ` +
+            `agents are searching for their inputs instead of being handed them`);
+    }
+    const perAgent = x.cost.total / x.agents;
+    if (perAgent > t.max_cost_per_agent_usd) {
+        reasons.push(`$${perAgent.toFixed(2)}/agent valued (max $${t.max_cost_per_agent_usd.toFixed(2)})`);
+    }
+    if (!reasons.length)
+        return null;
+    return mkRun("context_burn", severity, `${run.runId}: ${reasons.join("; ")}`, {
+        runId: run.runId, project: run.project, sessionId: run.sessionId,
+        agents: x.agents, medianToolCalls: x.medianToolCalls,
+        cacheEfficiency: Number.isFinite(x.cacheEfficiency) ? x.cacheEfficiency : null,
+        cacheWriteTokens: cacheWrite, cacheReadTokens: run.totals.cacheRead,
+        outputShare: x.outputShare, costUsd: x.cost.total, costPerAgentUsd: perAgent,
+        billingMode: t.billing_mode, costIsNotional: t.billing_mode === "subscription",
+    });
+}
+/**
+ * fanout_without_canary — the fleet was launched before any single unit had
+ * reported, so nothing was known about per-agent consumption when the spend
+ * was committed.
+ *
+ * 🔒 LOCKED [CANARY-IS-A-TIME-ORDERING] — 2026-08-19
+ * ⛔ NEVER implement this as "no agent reported". A completed 300-agent run
+ *    has 300 reports and was still un-canaried.
+ * WHY: the rule being enforced is "run ONE unit and read its consumption
+ *    BEFORE scaling". That is a statement about ordering, not about outcomes,
+ *    and it is only checkable by comparing each agent's start time against the
+ *    earliest sibling completion.
+ * FIX: count agents that started before the first report landed. Severity
+ *    rises when agents then died at the usage window — on a subscription that
+ *    is the failure that actually costs something (real case: 15 of 51 agents
+ *    lost in wf_41771d7b, 0 completed).
+ */
+export function detectFanoutWithoutCanary(run, t, m) {
+    const x = m ?? metricsFor(run, t.pricing);
+    if (x.agents < t.min_fanout_for_canary)
+        return null;
+    if (x.launchedBeforeFirstReport < t.min_fanout_for_canary)
+        return null;
+    const failedShare = x.agents ? x.failed / x.agents : 0;
+    let severity = "warn";
+    const parts = [
+        `${x.launchedBeforeFirstReport} of ${x.agents} agents launched before any had reported`,
+    ];
+    if (x.capacityExhausted > 0) {
+        severity = "critical";
+        parts.push(`${x.capacityExhausted} died at the usage window (${(100 * x.capacityExhausted / x.agents).toFixed(0)}%) — ` +
+            `capacity spent for no result`);
+    }
+    else if (failedShare > t.max_failed_share) {
+        severity = "critical";
+        parts.push(`${x.failed}/${x.agents} returned nothing (${(failedShare * 100).toFixed(0)}%)`);
+    }
+    return mkRun("fanout_without_canary", severity, `${run.runId}: ${parts.join("; ")}`, {
+        runId: run.runId, project: run.project, sessionId: run.sessionId,
+        agents: x.agents, launchedBeforeFirstReport: x.launchedBeforeFirstReport,
+        reported: x.reported, failed: x.failed, capacityExhausted: x.capacityExhausted,
+        failedShare, costUsd: x.cost.total,
+        billingMode: t.billing_mode, costIsNotional: t.billing_mode === "subscription",
+    });
+}
+/** Run both transcript heuristics over a set of runs. */
+export function runTranscriptHeuristics(runs, t = DEFAULT_COST_THRESHOLDS) {
+    const out = [];
+    for (const run of runs) {
+        const m = metricsFor(run, t.pricing);
+        const burn = detectContextBurn(run, t, m);
+        if (burn)
+            out.push(burn);
+        const fan = detectFanoutWithoutCanary(run, t, m);
+        if (fan)
+            out.push(fan);
+    }
+    return out;
+}
 //# sourceMappingURL=detector.js.map

package/dist/hooks.d.ts

@@ -137,4 +137,18 @@ export declare function formatCommitMessageViolations(violations: CommitMessageV
 export declare function formatCommitMessageViolationsJson(violations: CommitMessageViolation[]): string;
 export declare function formatSecretViolationsJson(violations: SecretViolation[]): string;
 export declare function formatDocCoverageViolationsJson(violations: DocCoverageViolation[]): string;
+export interface RuleParityViolation {
+    severity: "block" | "warn";
+    ruleId: string;
+    marker: string;
+    presentIn: string[];
+    missingFrom: string[];
+    reason: "marker-missing-from-some-files" | "marker-required-but-absent-everywhere" | "file-not-found";
+    missingFiles?: string[];
+}
+export declare function runRuleParity(policy: Policy, files: StagedFile[], repoRoot: string, opts?: {
+    all?: boolean;
+}): RuleParityViolation[];
+export declare function formatRuleParityViolations(violations: RuleParityViolation[]): string;
+export declare function formatRuleParityViolationsJson(violations: RuleParityViolation[]): string;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.js

@@ -550,4 +550,158 @@ export function formatDocCoverageViolationsJson(violations) {
         })),
     });
 }
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DIFF-AWARE] — 2026-08-19
+ * ⛔ NEVER make this fire on commits that touch none of the rule's files.
+ * WHY: parity is a property of the whole repo, so the naive implementation checks the
+ *      working tree on every commit — which means one pre-existing drift blocks every
+ *      unrelated commit until someone fixes it. That is how a useful gate becomes a gate
+ *      everyone disables. doc_coverage already learned this: it only fires when the commit
+ *      touches the rule's source paths.
+ * FIX: fire only when the commit stages a change to at least one file the rule governs.
+ *      Editing one of the three agent docs is exactly the moment parity can break, and
+ *      exactly the moment the author has the context to fix it. `--all` (see cliHookRuleParity)
+ *      audits the whole repo on demand, for CI or a deliberate sweep.
+ *
+ * 🔒 LOCKED [RULE-PARITY-READS-THE-INDEX] — 2026-08-19
+ * ⛔ NEVER evaluate marker presence from the working tree during a pre-commit check.
+ * WHY: the first cut did, with the rationalisation that "for a normal `git commit` the
+ *      working tree IS the post-commit state". That is false whenever staging is partial,
+ *      which is the normal case for anyone using `git add -p`. Demonstrated: stage the
+ *      REMOVAL of the marker from CLAUDE.md, then restore it in the working tree only —
+ *      the gate passed, and the commit that deleted the rule from the file agents read
+ *      went through clean. The check was measuring a state git was not about to record.
+ *      Same family as [SCORE-CANARY]'s pins and [EXEC-FAILURE-IS-NOT-EMPTY]: the tool
+ *      answered confidently about something it had not actually looked at.
+ * FIX: for staged files read the INDEX blob (`git show :path`) — that is literally what
+ *      the commit will contain. Unstaged files keep their worktree content, because the
+ *      commit leaves them untouched. `--all` audits the worktree by design: it answers
+ *      "is the repo consistent right now", not "is this commit consistent".
+ */
+/**
+ * Content of `rel` as it will exist AFTER the pending commit.
+ * Staged → the index blob. Not staged → the working tree (the commit does not touch it).
+ * Returns null when the path will not exist.
+ */
+function contentAfterCommit(repoRoot, rel, stagedSet, useWorktree) {
+    if (!useWorktree && stagedSet.has(rel)) {
+        try {
+            return execSync(`git show :"${rel}"`, {
+                cwd: repoRoot,
+                encoding: "utf-8",
+                maxBuffer: 32 * 1024 * 1024,
+            });
+        }
+        catch {
+            // [EXEC-FAILURE-IS-NOT-EMPTY] — "git show failed" is not "the file is absent".
+            // Not a git repo, a corrupt index, or a path git cannot resolve all land here.
+            // Fall through to the working tree rather than reporting a file that plainly
+            // exists as missing. A staged DELETION never reaches this branch: getStagedFiles
+            // filters on --diff-filter=ACMR, so deleted paths are not in stagedSet and are
+            // correctly read as absent from the worktree below.
+        }
+    }
+    const abs = join(repoRoot, rel);
+    if (!existsSync(abs))
+        return null;
+    return readFileSync(abs, "utf-8");
+}
+export function runRuleParity(policy, files, repoRoot, opts = {}) {
+    const stagedSet = new Set(files.map((f) => f.path));
+    const violations = [];
+    for (const rule of policy.rule_parity) {
+        // [RULE-PARITY-IS-DIFF-AWARE] — only fire when this commit touches a governed file.
+        if (!opts.all && !rule.required_in.some((p) => stagedSet.has(p)))
+            continue;
+        const presentIn = [];
+        const missingFrom = [];
+        const missingFiles = [];
+        for (const rel of rule.required_in) {
+            // [RULE-PARITY-READS-THE-INDEX] — what the commit records, not what is on disk.
+            const content = contentAfterCommit(repoRoot, rel, stagedSet, opts.all === true);
+            if (content === null) {
+                missingFiles.push(rel);
+                continue;
+            }
+            if (content.includes(rule.marker))
+                presentIn.push(rel);
+            else
+                missingFrom.push(rel);
+        }
+        if (missingFiles.length > 0) {
+            violations.push({
+                severity: rule.severity,
+                ruleId: rule.id,
+                marker: rule.marker,
+                presentIn,
+                missingFrom,
+                missingFiles,
+                reason: "file-not-found",
+            });
+            continue;
+        }
+        // Adopted nowhere. Only a violation when the rule says it is mandatory.
+        if (presentIn.length === 0) {
+            if (rule.always_required) {
+                violations.push({
+                    severity: rule.severity,
+                    ruleId: rule.id,
+                    marker: rule.marker,
+                    presentIn,
+                    missingFrom,
+                    reason: "marker-required-but-absent-everywhere",
+                });
+            }
+            continue;
+        }
+        // Present somewhere but not everywhere — the drift this rule exists to catch.
+        if (missingFrom.length > 0) {
+            violations.push({
+                severity: rule.severity,
+                ruleId: rule.id,
+                marker: rule.marker,
+                presentIn,
+                missingFrom,
+                reason: "marker-missing-from-some-files",
+            });
+        }
+    }
+    return violations;
+}
+export function formatRuleParityViolations(violations) {
+    if (violations.length === 0)
+        return "✅ All rule-parity rules satisfied.";
+    const lines = [];
+    const blocking = violations.filter((v) => v.severity === "block").length;
+    lines.push(`📐 RULE PARITY: ${violations.length} violation(s) — ${blocking} blocking, ${violations.length - blocking} warning(s).`);
+    for (const v of violations) {
+        if (v.reason === "file-not-found") {
+            lines.push(`  [${v.severity}] ${v.ruleId}: listed file(s) do not exist → ${v.missingFiles.join(", ")}`);
+            continue;
+        }
+        if (v.reason === "marker-required-but-absent-everywhere") {
+            lines.push(`  [${v.severity}] ${v.ruleId}: marker "${v.marker}" is required but present in none of ${v.missingFrom.join(", ")}`);
+            continue;
+        }
+        lines.push(`  [${v.severity}] ${v.ruleId}: marker "${v.marker}" is out of sync.`);
+        lines.push(`      present in : ${v.presentIn.join(", ")}`);
+        lines.push(`      MISSING from: ${v.missingFrom.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+export function formatRuleParityViolationsJson(violations) {
+    return JSON.stringify({
+        check: "rule-parity",
+        violations: violations.length,
+        blocking: violations.filter((v) => v.severity === "block").length,
+        details: violations.map((v) => ({
+            rule_id: v.ruleId,
+            severity: v.severity,
+            reason: v.reason,
+            present_in: v.presentIn,
+            missing_from: v.missingFrom,
+            missing_files: v.missingFiles ?? [],
+        })),
+    });
+}
 //# sourceMappingURL=hooks.js.map

package/dist/index.js

@@ -8,7 +8,7 @@ import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { loadCache, saveCache } from "./cache.js";
-import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, } from "./agents.js";
+import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, runScoreCanary, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { verifyChain, readAuditLog, filterByRange } from "./audit.js";
 import { startEventIngestServer } from "./http-server.js";
@@ -479,6 +479,29 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     const gate = gateCheck("score_project");
     if (gate)
         return { content: [{ type: "text", text: gate }] };
+    // 🔒 LOCKED [SCORE-CANARY-COVERS-EVERY-SCORER] — 2026-08-19
+    // ⛔ NEVER let a scoring entry point run without the canary.
+    // WHY: [SCORE-CANARY] was wired on the CLI only. This MCP tool — the path
+    //    Claude Code actually scores through — had zero call sites, so a
+    //    drifting scorer would have been caught when a human typed the
+    //    command and missed entirely when an agent called the tool. Session
+    //    21 §H2 found the same shape in the fleet-write guard: a guard that
+    //    covers one caller reads, from the outside, exactly like one that works.
+    // FIX: canary here too. This tool never writes SCORE.md, so a deviation
+    //    is reported rather than fatal — but it is never silent.
+    const canary = runScoreCanary();
+    if (!canary.ok) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "🚨 Scoring canary FAILED — these scores are NOT trustworthy.\n\n" +
+                        canary.deviations.map((d) => `   • ${d}`).join("\n") +
+                        (canary.inconclusive
+                            ? "\n\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."),
+                }],
+        };
+    }
     const projectDirs = loadProjectDirs();
     let scores;
     if (project) {

package/dist/policy.d.ts

@@ -89,6 +89,89 @@ export type BypassToken = z.infer<typeof BypassTokenSchema>;
 /**
  * The full policy document — schema version 1.
  */
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DOC-TO-DOC] — 2026-08-19
+ * ⛔ NEVER fold this into doc_coverage. They answer different questions.
+ * WHY: doc_coverage maps SOURCE → DOC ("you changed src/audit.ts, update SKILLS.md").
+ *      It cannot see the failure that motivated this: a rule that existed in
+ *      ~/.claude/CLAUDE.md and AGENT_USAGE.md but NOT in .github/copilot-instructions.md
+ *      — so it was invisible to Cursor, Windsurf and Copilot, which read only the latter.
+ *      No source file changed, so no doc_coverage rule could ever fire. The rule was
+ *      written, reviewed, and simply not where the readers look.
+ * FIX: parity between DOCS. If a marker appears in any listed file, it must appear in all
+ *      of them. Deliberately literal-substring, not regex: a marker is a grep-able tag in
+ *      the LOCK tradition, and a regex here would fail open on a typo.
+ */
+export declare const RuleParitySchema: z.ZodObject<{
+    id: z.ZodString;
+    marker: z.ZodString;
+    required_in: z.ZodArray<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+    always_required: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Model pricing, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [PRICING-LIVES-IN-POLICY] — 2026-08-19
+ * ⛔ NEVER hardcode a rate in the collector, the detector or the CLI.
+ * WHY: rates change, and the collector must be able to value runs for models
+ *    it has never heard of. A rate baked into a compiled `dist/` is a rate
+ *    nobody can correct without a release.
+ * FIX: rates live in `.contextengine/policy.json` → `agent_cost.pricing`.
+ *    Lookup is longest-prefix with a `*` catch-all; an unmatched model is
+ *    reported as UNPRICED, never silently valued at zero.
+ */
+export declare const ModelPricingSchema: z.ZodObject<{
+    model: z.ZodString;
+    input_per_mtok: z.ZodNumber;
+    output_per_mtok: z.ZodNumber;
+    cache_read_per_mtok: z.ZodNumber;
+    cache_write_5m_per_mtok: z.ZodNumber;
+    cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ModelPricingRule = z.infer<typeof ModelPricingSchema>;
+/**
+ * Thresholds for the context_burn and fanout_without_canary detectors.
+ *
+ * 🔒 LOCKED [BURN-IS-COST-WEIGHTED-NOT-VOLUME] — 2026-08-19
+ * ⛔ NEVER fire context_burn on a low output/volume ratio alone.
+ * WHY: a healthy 30-agent workflow measures 1.8% output by volume. That looks
+ *    alarming and is not: cache_read is billed at 0.1x input, so those same
+ *    tokens are 28% of cost, and the run cost $35 against $120 without cache.
+ *    Firing on the volume ratio would flag every well-cached run ever done and
+ *    train the user to ignore the alert — the exact failure the
+ *    [DRIFT-HEURISTICS] LOCK in detector.ts exists to prevent.
+ * FIX: fire on cache INEFFICIENCY (cache_read / cache_write below
+ *    min_cache_efficiency — the prefix is being rebuilt, not reused), on tool
+ *    calls per agent, and on valued cost per agent. Real evidence for the
+ *    inefficiency rule: wf_f676d824 spent 68% of $209 on cache WRITES,
+ *    22.7M written against only 8.5M read, across 722 agents.
+ */
+export declare const AgentCostSchema: z.ZodObject<{
+    billing_mode: z.ZodDefault<z.ZodEnum<{
+        api: "api";
+        subscription: "subscription";
+    }>>;
+    pricing: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        input_per_mtok: z.ZodNumber;
+        output_per_mtok: z.ZodNumber;
+        cache_read_per_mtok: z.ZodNumber;
+        cache_write_5m_per_mtok: z.ZodNumber;
+        cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    min_cache_efficiency: z.ZodDefault<z.ZodNumber>;
+    max_tool_calls_per_agent: z.ZodDefault<z.ZodNumber>;
+    max_cost_per_agent_usd: z.ZodDefault<z.ZodNumber>;
+    min_fanout_for_canary: z.ZodDefault<z.ZodNumber>;
+    max_failed_share: z.ZodDefault<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentCost = z.infer<typeof AgentCostSchema>;
 export declare const PolicySchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     extends: z.ZodOptional<z.ZodString>;
@@ -133,6 +216,37 @@ export declare const PolicySchema: z.ZodObject<{
         requires_reason_min_length: z.ZodDefault<z.ZodNumber>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    rule_parity: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        marker: z.ZodString;
+        required_in: z.ZodArray<z.ZodString>;
+        severity: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+        always_required: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    agent_cost: z.ZodOptional<z.ZodObject<{
+        billing_mode: z.ZodDefault<z.ZodEnum<{
+            api: "api";
+            subscription: "subscription";
+        }>>;
+        pricing: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            input_per_mtok: z.ZodNumber;
+            output_per_mtok: z.ZodNumber;
+            cache_read_per_mtok: z.ZodNumber;
+            cache_write_5m_per_mtok: z.ZodNumber;
+            cache_write_1h_per_mtok: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        min_cache_efficiency: z.ZodDefault<z.ZodNumber>;
+        max_tool_calls_per_agent: z.ZodDefault<z.ZodNumber>;
+        max_cost_per_agent_usd: z.ZodDefault<z.ZodNumber>;
+        min_fanout_for_canary: z.ZodDefault<z.ZodNumber>;
+        max_failed_share: z.ZodDefault<z.ZodNumber>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Policy = z.infer<typeof PolicySchema>;
 /**

package/dist/policy.js

@@ -106,6 +106,90 @@ export const BypassTokenSchema = z.object({
 /**
  * The full policy document — schema version 1.
  */
+/**
+ * 🔒 LOCKED [RULE-PARITY-IS-DOC-TO-DOC] — 2026-08-19
+ * ⛔ NEVER fold this into doc_coverage. They answer different questions.
+ * WHY: doc_coverage maps SOURCE → DOC ("you changed src/audit.ts, update SKILLS.md").
+ *      It cannot see the failure that motivated this: a rule that existed in
+ *      ~/.claude/CLAUDE.md and AGENT_USAGE.md but NOT in .github/copilot-instructions.md
+ *      — so it was invisible to Cursor, Windsurf and Copilot, which read only the latter.
+ *      No source file changed, so no doc_coverage rule could ever fire. The rule was
+ *      written, reviewed, and simply not where the readers look.
+ * FIX: parity between DOCS. If a marker appears in any listed file, it must appear in all
+ *      of them. Deliberately literal-substring, not regex: a marker is a grep-able tag in
+ *      the LOCK tradition, and a regex here would fail open on a typo.
+ */
+export const RuleParitySchema = z.object({
+    id: z.string().min(1).describe("Stable identifier for this parity rule"),
+    marker: z
+        .string()
+        .min(3)
+        .describe("Literal substring that marks the rule's presence, e.g. 'MULTI-AGENT COST'"),
+    required_in: z
+        .array(z.string())
+        .min(2)
+        .describe("Repo-relative doc paths that must agree. Fewer than 2 makes parity meaningless."),
+    severity: z.enum(["block", "warn"]).default("block"),
+    /** When true the marker must be present in EVERY file, even if currently in none. */
+    always_required: z.boolean().default(false),
+    description: z.string().optional(),
+});
+/**
+ * Model pricing, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [PRICING-LIVES-IN-POLICY] — 2026-08-19
+ * ⛔ NEVER hardcode a rate in the collector, the detector or the CLI.
+ * WHY: rates change, and the collector must be able to value runs for models
+ *    it has never heard of. A rate baked into a compiled `dist/` is a rate
+ *    nobody can correct without a release.
+ * FIX: rates live in `.contextengine/policy.json` → `agent_cost.pricing`.
+ *    Lookup is longest-prefix with a `*` catch-all; an unmatched model is
+ *    reported as UNPRICED, never silently valued at zero.
+ */
+export const ModelPricingSchema = z.object({
+    model: z.string().min(1).describe("Exact model id, a prefix of one, or '*' as catch-all"),
+    input_per_mtok: z.number().nonnegative(),
+    output_per_mtok: z.number().nonnegative(),
+    cache_read_per_mtok: z.number().nonnegative(),
+    cache_write_5m_per_mtok: z.number().nonnegative(),
+    cache_write_1h_per_mtok: z.number().nonnegative().optional(),
+});
+/**
+ * Thresholds for the context_burn and fanout_without_canary detectors.
+ *
+ * 🔒 LOCKED [BURN-IS-COST-WEIGHTED-NOT-VOLUME] — 2026-08-19
+ * ⛔ NEVER fire context_burn on a low output/volume ratio alone.
+ * WHY: a healthy 30-agent workflow measures 1.8% output by volume. That looks
+ *    alarming and is not: cache_read is billed at 0.1x input, so those same
+ *    tokens are 28% of cost, and the run cost $35 against $120 without cache.
+ *    Firing on the volume ratio would flag every well-cached run ever done and
+ *    train the user to ignore the alert — the exact failure the
+ *    [DRIFT-HEURISTICS] LOCK in detector.ts exists to prevent.
+ * FIX: fire on cache INEFFICIENCY (cache_read / cache_write below
+ *    min_cache_efficiency — the prefix is being rebuilt, not reused), on tool
+ *    calls per agent, and on valued cost per agent. Real evidence for the
+ *    inefficiency rule: wf_f676d824 spent 68% of $209 on cache WRITES,
+ *    22.7M written against only 8.5M read, across 722 agents.
+ */
+export const AgentCostSchema = z.object({
+    /**
+     * `subscription` — no dollar is debited; cost is a valuation and CAPACITY is
+     * the scarce resource. `api` — cost is a real debit.
+     */
+    billing_mode: z.enum(["subscription", "api"]).default("subscription"),
+    pricing: z.array(ModelPricingSchema).default([]),
+    /** cache_read / cache_write below this means the cache is thrashing. */
+    min_cache_efficiency: z.number().nonnegative().default(3),
+    /** Per-agent tool calls above this means the agent is searching, not working. */
+    max_tool_calls_per_agent: z.number().positive().default(2),
+    /** Valued cost of a single agent, in dollars. */
+    max_cost_per_agent_usd: z.number().nonnegative().default(3),
+    /** Below this many agents, a fan-out is too small to need a canary. */
+    min_fanout_for_canary: z.number().int().positive().default(5),
+    /** Share of agents that may die without a result before this is a failure. */
+    max_failed_share: z.number().min(0).max(1).default(0.05),
+    description: z.string().optional(),
+});
 export const PolicySchema = z.object({
     version: z.literal(1).describe("Policy schema version. Pin to 1 — bumps require a migration path."),
     extends: z
@@ -118,6 +202,8 @@ export const PolicySchema = z.object({
     deploy_verify_hosts: z.array(DeployVerifyHostSchema).default([]),
     commit_message_required: z.array(CommitMessageRequiredSchema).default([]),
     bypass_tokens: z.array(BypassTokenSchema).default([]),
+    rule_parity: z.array(RuleParitySchema).default([]),
+    agent_cost: AgentCostSchema.optional(),
 });
 export function validatePolicy(raw) {
     const result = PolicySchema.safeParse(raw);
@@ -209,6 +295,10 @@ export function formatPolicySummary(policy) {
     for (const b of policy.bypass_tokens) {
         lines.push(`  - ${b.id} → TTL ${b.ttl_seconds}s, reason ≥ ${b.requires_reason_min_length} chars`);
     }
+    lines.push(`Rule-parity rules: ${policy.rule_parity.length}`);
+    for (const r of policy.rule_parity) {
+        lines.push(`  - ${r.id} → marker "${r.marker}" must agree across ${r.required_in.length} file(s) [${r.severity}]${r.always_required ? " (always required)" : ""}`);
+    }
     return lines.join("\n");
 }
 export function formatValidationErrors(errors) {