@compr/opscontext-mcp 2.1.1 → 2.1.3

package/dist/hooks.js

@@ -16,6 +16,33 @@
 // Inputs are fed by helpers that read the actual git working state.
 // Each runner returns a list of violations + a summary; the CLI maps that
 // onto exit codes + audit events + human/machine output.
+//
+// ---------------------------------------------------------------------------
+// ACCEPTED LIMITS — out-of-scope by design (do NOT classify these as bugs)
+// ---------------------------------------------------------------------------
+//   1. `git commit --no-verify` — documented git escape hatch. Cannot be
+//      caught at the hook layer (git skips ALL hooks under that flag).
+//      Mitigation lives upstream of git (CODEOWNERS / branch protection /
+//      server-side push rules), not here.
+//   2. Workflow ID format (`wf_x`) is NOT verified against actual
+//      audit-log entries — adding that would require a server-side query
+//      against the OpsContext audit-log service. Deferred to a later
+//      iteration. We only enforce the text-shape of the citation, not that
+//      it corresponds to a real workflow.
+//   3. Direct SSH edits, cron edits, Cloudflare UI edits — out of scope
+//      by design. If the change never enters git, no commit hook can
+//      observe it. Defense-in-depth is via sidecar collectors (PM2,
+//      systemd, cron, Cloudflare audit log) feeding the central audit log.
+//   4. Glob case-sensitivity on case-insensitive filesystems (APFS / NTFS)
+//      — git itself does NOT normalize this. A rule scoped to
+//      `server/Deploy.sh` will not match a path `server/deploy.sh` on
+//      Linux but WILL match on macOS-default APFS. Mitigation: author
+//      policy.json with case-sensitive paths that match git's stored
+//      paths exactly.
+//   5. Sibling-project deploy scripts (KONIVE / PLANK / etc.) — each
+//      project gets its own `.contextengine/policy.json`. This rule only
+//      applies to the repo it lives in. Cross-repo enforcement is a
+//      separate concern (org-policy distribution via `extends:`).
 import { execSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { createHash } from "crypto";
@@ -279,6 +306,219 @@ export function formatDocCoverageViolations(violations) {
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
+// Commit-message-required checker (Agent B — Option B consumer)
+// ---------------------------------------------------------------------------
+//
+// Consumes the `commit_message_required` rule type added by Agent A
+// (CommitMessageRequiredSchema in src/policy.ts, sample rule
+// `multi-agent-for-shared-infra` in .contextengine/policy.json).
+//
+// Trigger: any staged file path matches the rule's `paths` globs.
+// Pass:    the commit message matches the rule's `pattern` (ERE regex).
+// Bypass:  the commit body contains `--skip-multi-agent-reason: <reason>`
+//          — the bypass IS recorded as a separate kind (`bypass`) so the
+//          CLI can emit a `policy.skipped` audit event with the reason.
+//
+// We intentionally do NOT swallow the bypass into "no violation":
+// surfacing it as a `bypass` kind lets the CLI keep the audit-log append
+// in the same place as `hook.block` events, preserving symmetry.
+/** Canonical bypass marker. Lives at the top of the checker so editors
+ *  can grep for it when reviewing the audit story. */
+export const COMMIT_BYPASS_PREFIX = "--skip-multi-agent-reason:";
+/** Minimum reason length when bypassing. Hardened 2026-06-26 (verifier
+ *  Bypass #11): the previous 5-char floor passed `12345` as a "valid"
+ *  reason — no semantic content, just a placeholder to defeat the gate.
+ *  Now 20 chars + at least one whitespace character (real reasons are
+ *  prose with words, not concatenated tokens). Matches
+ *  BypassTokenSchema.requires_reason_min_length default of 20. */
+const MIN_BYPASS_REASON_LENGTH = 20;
+/** Extract a bypass reason from the commit message. Returns the
+ *  reason text (trimmed) or null when absent.
+ *
+ *  Hardened 2026-06-26 (verifier Bypass #5 + #11):
+ *    - The bypass-marker MUST appear at the start of its own line
+ *      (only leading whitespace allowed). Mid-line or commented-out
+ *      markers like `# Note: do NOT use --skip-multi-agent-reason: ever`
+ *      are REJECTED — the `#` (or any non-whitespace char) before the
+ *      prefix on the same line disqualifies the line.
+ *    - Reason must be ≥ MIN_BYPASS_REASON_LENGTH chars (20).
+ *    - Reason must contain at least one whitespace character — real
+ *      reasons are prose ("emergency rollback at 03:00 UTC"), not
+ *      alphanumeric placeholders ("12345" / "abc123def456…"). A token
+ *      without spaces is almost certainly a defeat attempt.
+ */
+export function extractBypassReason(commitMessage) {
+    for (const rawLine of commitMessage.split(/\r?\n/)) {
+        // Allow ONLY leading whitespace before the prefix (no `#`, no quote,
+        // no other prose). Verifier Bypass #5 attack vector closed here.
+        const leadingMatch = rawLine.match(/^(\s*)/);
+        const leading = leadingMatch ? leadingMatch[1] : "";
+        const afterLeading = rawLine.slice(leading.length);
+        if (!afterLeading.startsWith(COMMIT_BYPASS_PREFIX))
+            continue;
+        const reason = afterLeading.slice(COMMIT_BYPASS_PREFIX.length).trim();
+        if (reason.length < MIN_BYPASS_REASON_LENGTH)
+            continue;
+        // Real reasons contain at least one space — reject "12345",
+        // "abcdef1234567890ABCDE", and other word-less placeholders.
+        if (!/\s/.test(reason))
+            continue;
+        return reason;
+    }
+    return null;
+}
+/**
+ * Strip any top-level alternation branch from a policy regex pattern
+ * that contains the literal COMMIT_BYPASS_PREFIX. Verifier Bypass #3:
+ * the canonical policy pattern
+ *
+ *   Multi-agent: wf_[a-z0-9-]+|--skip-multi-agent-reason: .+
+ *
+ * had two branches in one pattern; the second branch matched the literal
+ * bypass marker anywhere in the message (including mid-line, commented
+ * out, etc.), short-circuiting the strict line-anchored validation in
+ * extractBypassReason. Fix: the matcher in runCommitMessageRequired
+ * ignores the bypass-marker branch entirely — bypass MUST go through
+ * extractBypassReason's hardened validation.
+ *
+ * Returns the cleaned pattern. If every branch is bypass-related (rare
+ * footgun), returns null — caller treats as "no positive branch to
+ * satisfy", which is the safe default.
+ */
+export function stripBypassBranchFromPattern(pattern) {
+    // Top-level alternation split. This is a SIMPLE split — patterns with
+    // nested grouping that uses `|` inside `(...)` aren't decomposed, but
+    // the canonical policy patterns don't use that shape. If a future
+    // policy needs nested alternation, the safer move is to author the
+    // bypass branch out of the policy entirely (it belongs to
+    // extractBypassReason, not to the pattern).
+    const branches = pattern.split("|");
+    const cleaned = branches.filter((b) => !b.includes(COMMIT_BYPASS_PREFIX));
+    if (cleaned.length === 0)
+        return null;
+    return cleaned.join("|");
+}
+/**
+ * Apply policy.commit_message_required rules to a staged-file list +
+ * commit message. Returns one entry per fired rule (either a
+ * missing-pattern violation OR a bypass acknowledgement).
+ *
+ * Empty list = nothing fired (either no rule's `paths` matched, or every
+ * fired rule was satisfied by the message).
+ *
+ * IMPORTANT: This does NOT itself decide exit codes. The caller (CLI)
+ * decides: missing-pattern + severity=block → exit 1 + hook.block event;
+ * bypass → exit 0 + policy.skipped event with the reason.
+ */
+export function runCommitMessageRequired(policy, files, commitMessage) {
+    const results = [];
+    const bypassReason = extractBypassReason(commitMessage);
+    for (const rule of policy.commit_message_required) {
+        const matchedFiles = files
+            .map((f) => f.path)
+            .filter((p) => matchesAnyGlob(p, rule.paths));
+        if (matchedFiles.length === 0)
+            continue; // rule did not fire
+        // Bypass takes precedence — record it, do not block.
+        if (bypassReason !== null) {
+            results.push({
+                kind: "bypass",
+                severity: rule.severity,
+                ruleId: rule.id,
+                matchedFiles,
+                pattern: rule.pattern,
+                description: rule.description,
+                bypassReason,
+            });
+            continue;
+        }
+        // No bypass — check the pattern. Strip any bypass-marker alternation
+        // branch first (verifier Bypass #3): the bypass path is owned by
+        // extractBypassReason ONLY. Pattern-matching the bypass marker text
+        // is forbidden because the policy regex has no line-anchoring and
+        // therefore cannot distinguish a real bypass from a quoted/commented
+        // mention of the marker.
+        const cleanedPattern = stripBypassBranchFromPattern(rule.pattern);
+        if (cleanedPattern === null) {
+            // Pattern was 100% bypass-branches. Treat as missing-pattern —
+            // the rule has no positive enforcement branch left after
+            // sanitization.
+            results.push({
+                kind: "missing-pattern",
+                severity: rule.severity,
+                ruleId: rule.id,
+                matchedFiles,
+                pattern: rule.pattern,
+                description: rule.description,
+            });
+            continue;
+        }
+        let re;
+        try {
+            re = new RegExp(cleanedPattern);
+        }
+        catch {
+            // Malformed pattern in policy.json — surface as a missing-pattern
+            // violation rather than crashing the hook. The CLI will print the
+            // rule.description, which should explain the contract.
+            results.push({
+                kind: "missing-pattern",
+                severity: rule.severity,
+                ruleId: rule.id,
+                matchedFiles,
+                pattern: rule.pattern,
+                description: rule.description,
+            });
+            continue;
+        }
+        if (!re.test(commitMessage)) {
+            results.push({
+                kind: "missing-pattern",
+                severity: rule.severity,
+                ruleId: rule.id,
+                matchedFiles,
+                pattern: rule.pattern,
+                description: rule.description,
+            });
+        }
+    }
+    return results;
+}
+export function formatCommitMessageViolations(violations) {
+    if (violations.length === 0)
+        return "✅ All commit-message-required rules satisfied.";
+    const lines = [];
+    const blocking = violations.filter((v) => v.kind === "missing-pattern" && v.severity === "block").length;
+    const bypasses = violations.filter((v) => v.kind === "bypass").length;
+    lines.push(`📝 COMMIT MESSAGE POLICY: ${violations.length} rule(s) fired — ${blocking} blocking, ${bypasses} bypassed.`);
+    for (const v of violations) {
+        if (v.kind === "bypass") {
+            lines.push(`  [bypass] ${v.ruleId} on ${v.matchedFiles.join(", ")} — reason: "${v.bypassReason}" (logged to audit)`);
+            continue;
+        }
+        lines.push(`  [${v.severity}] ${v.ruleId} on ${v.matchedFiles.join(", ")} — commit body must match /${v.pattern}/`);
+        if (v.description)
+            lines.push(`           ${v.description}`);
+    }
+    return lines.join("\n");
+}
+export function formatCommitMessageViolationsJson(violations) {
+    return JSON.stringify({
+        check: "commit-message-required",
+        violations_total: violations.length,
+        blocking: violations.filter((v) => v.kind === "missing-pattern" && v.severity === "block").length,
+        bypasses: violations.filter((v) => v.kind === "bypass").length,
+        violations: violations.map((v) => ({
+            kind: v.kind,
+            severity: v.severity,
+            rule_id: v.ruleId,
+            matched_files: v.matchedFiles,
+            pattern: v.pattern,
+            bypass_reason: v.bypassReason,
+        })),
+    });
+}
+// ---------------------------------------------------------------------------
 // Machine-readable output (for CI pipelines)
 // ---------------------------------------------------------------------------
 export function formatSecretViolationsJson(violations) {

package/dist/index.js

@@ -14,11 +14,14 @@ import { verifyChain, readAuditLog, filterByRange } from "./audit.js";
 import { startEventIngestServer } from "./http-server.js";
 import { detect } from "./detector.js";
 import { saveLearning, searchLearnings, listLearnings, deleteLearning, learningsToChunks, learningsStats, formatLearnings, importLearningsFromFile, autoImportFromSources, LEARNING_CATEGORIES, } from "./learnings.js";
-import { readFileSync, existsSync, watch, statSync } from "fs";
+import { communityRulesToChunks, mergeWithDedup, loadCommunityStore, } from "./community-sync.js";
+import { readFileSync, existsSync, watch, statSync, writeFileSync, mkdirSync } from "fs";
 import { basename, join, dirname } from "path";
+import { homedir } from "os";
 import { execSync } from "child_process";
 import { scanCodeDir } from "./code-chunker.js";
 import { fileURLToPath } from "url";
+import { TOOL_COUNT, FREE_TOOL_COUNT, PREMIUM_TOOL_NAMES } from "./tools-manifest.js";
 // Read version from package.json at startup
 let PKG_VERSION = "1.21.3";
 try {
@@ -112,6 +115,19 @@ async function reindex() {
         chunks.push(...learningChunks);
         console.error(`[ContextEngine] 💡 Injected ${learningChunks.length} learning chunks into search index (scoped to ${activeProjectNames.length} projects)`);
     }
+    // Inject community rules from the cached store (best-effort — no network
+    // touched here; the daily `sync-community-rules` CLI keeps the cache fresh).
+    // Deduped against the local learnings so identical content never double-emits.
+    const communityChunks = communityRulesToChunks();
+    if (communityChunks.length > 0) {
+        const before = chunks.length;
+        chunks = mergeWithDedup(chunks, communityChunks);
+        const added = chunks.length - before;
+        const skipped = communityChunks.length - added;
+        const store = loadCommunityStore();
+        console.error(`[ContextEngine] 🌐 Injected ${added} community rule chunks ` +
+            `(${skipped} dedup'd vs local; ${store.rules.length} total in cache)`);
+    }
     // Collect from plugin adapters
     if (config.adapters && config.adapters.length > 0) {
         const adapterChunks = await collectFromAdapters(config.adapters);
@@ -551,7 +567,7 @@ server.tool("delete_session", "Delete a saved session by name. Returns success/n
 // ---------------------------------------------------------------------------
 // Tool: audit_verify (Compliance — tamper-evident audit log)
 // ---------------------------------------------------------------------------
-server.tool("audit_verify", "Verify the integrity of the local audit log chain. Returns OK + record count, or BROKEN + break index when a record has been edited or the chain otherwise diverges. Compliance basis: SOC2 CC7.2, ISO 27001 A.12.4.1. The audit log lives at ~/.contextengine/audit.log and records every state-changing operation (learning save/delete/import, session save/delete, activation activate/deactivate) as a hash-chained JSONL line.", {
+server.tool("audit_verify", "Verify the integrity of the local audit log chain. Returns OK + record count, or BROKEN + break index when a record has been edited or the chain otherwise diverges. Produces evidence aligned with SOC 2 CC7.2 (change monitoring) and ISO 27001 A.12.4.1 (event logging) — evidence artifacts, not a certification (OpsContext is not itself SOC 2– or ISO 27001–certified; see docs/compliance/). The audit log lives at ~/.contextengine/audit.log and records every state-changing operation (learning save/delete/import, session save/delete, activation activate/deactivate) as a hash-chained JSONL line.", {
     since: z.string().optional().describe("ISO date — restrict integrity report counters to records on/after this timestamp (chain still verified end-to-end)"),
     until: z.string().optional().describe("ISO date — restrict counters to records on/before this timestamp"),
 }, async ({ since, until }) => {
@@ -1090,6 +1106,23 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[ContextEngine] 🚀 MCP server running on stdio (keyword search ready)");
+    // 3b. Write server-meta.json so the VS Code extension can read tool count
+    // without needing an active MCP session. Single source of truth =
+    // src/tools-manifest.ts (asserted by tests/tools-manifest.test.ts).
+    try {
+        const metaDir = join(homedir(), ".contextengine");
+        mkdirSync(metaDir, { recursive: true });
+        writeFileSync(join(metaDir, "server-meta.json"), JSON.stringify({
+            toolCount: TOOL_COUNT,
+            freeCount: FREE_TOOL_COUNT,
+            premiumCount: PREMIUM_TOOL_NAMES.length,
+            version: PKG_VERSION,
+            generatedAt: new Date().toISOString(),
+        }, null, 2));
+    }
+    catch (err) {
+        console.error("[ContextEngine] ⚠ Failed to write server-meta.json:", err);
+    }
     // 4. Load embeddings — try cache first, then model (non-blocking)
     const cached = loadCache(chunks);
     if (cached) {

package/dist/install-autostart.js

@@ -18,6 +18,22 @@ import { existsSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { homedir, platform } from "os";
 import { execSync } from "child_process";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+// 🔒 LOCKED [M2-ESM-FILENAME-FIX] — 2026-06-24
+// ⛔ NEVER reference bare `__filename` in this file — the package is
+//    `"type": "module"` so __filename is `undefined` at runtime and
+//    `dirname(__filename || "")` was returning dirname("") = "." which
+//    silently broke the dev-tree fallback. Audit FRESH_USER_AUDIT_
+//    2026-06-23.md finding M2.
+// FIX: Resolve module path via fileURLToPath(import.meta.url). For
+//    cross-package resolution (e.g. when running via npx and the
+//    @compr/opscontext-mcp tarball is in npx's transient cache), also
+//    try createRequire(import.meta.url).resolve("@compr/opscontext-mcp/
+//    dist/index.js") which works inside npx.
+const __filename_esm = fileURLToPath(import.meta.url);
+const __dirname_esm = dirname(__filename_esm);
+const requireFromHere = createRequire(import.meta.url);
 const LABEL = "com.opscontext.mcp";
 const PLIST_FILE = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 const LOG_DIR = join(homedir(), ".contextengine", "logs");
@@ -34,7 +50,7 @@ function detectNodePath() {
  *  (2) ./dist/index.js next to this module (dev tree). Falls through with
  *  null if neither is found. */
 function detectOpscontextEntry() {
-    // Try global install via `npm root -g`
+    // (1) Try global install via `npm root -g`
     try {
         const globalRoot = execSync("npm root -g 2>/dev/null", { encoding: "utf-8" }).trim();
         const candidate = join(globalRoot, "@compr", "opscontext-mcp", "dist", "index.js");
@@ -44,19 +60,31 @@ function detectOpscontextEntry() {
     catch {
         /* no npm root available; fall through */
     }
-    // Try dev tree relative to this module's location (dist/install-autostart.js)
-    // → __dirname/.. would be dist/, then ../ would be repo root, then dist/index.js
+    // (2) Try dev tree relative to this module's location (dist/install-autostart.js)
+    // → __dirname_esm IS dist/, so dist/index.js is a sibling. ESM-safe (uses
+    // fileURLToPath(import.meta.url), not the broken `__filename` reference
+    // that the M2 audit caught).
     try {
-        // import.meta.url style would be nicer but cli.ts is CommonJS-ish; use __dirname
-        // via require.resolve fallback. We're loaded from dist/, so look at sibling.
-        const here = dirname(__filename || "");
-        const candidate = join(here, "index.js");
+        const candidate = join(__dirname_esm, "index.js");
         if (existsSync(candidate))
             return { kind: "devtree", path: candidate };
     }
     catch {
         /* ignore */
     }
+    // (3) NEW: Try resolve via createRequire (works inside npx's transient
+    // install — when the user runs `npx -y @compr/opscontext-mcp
+    // install-autostart` the package is in npx's cache, not npm's global root,
+    // so step (1) misses. createRequire walks Node's resolution algorithm and
+    // finds the cache copy. Audit M2 fix.
+    try {
+        const resolved = requireFromHere.resolve("@compr/opscontext-mcp/dist/index.js");
+        if (existsSync(resolved))
+            return { kind: "npx", path: resolved };
+    }
+    catch {
+        /* not resolvable — caller will print the install-globally hint */
+    }
     return null;
 }
 function buildPlist(nodePath, entryPath, nodeBinDir) {
@@ -163,12 +191,40 @@ To view server logs:        tail -f ~/.contextengine/logs/mcp-stderr.log
         console.error(`   Pass --force to overwrite, or run: opscontext autostart-status`);
         process.exit(1);
     }
+    // Allow operator to pin the entry path explicitly — escape hatch when
+    // detection fails (e.g. monorepo / private registry / unconventional layout).
+    // Audit M2 follow-up: was originally a CLI flag suggestion.
+    const entryFlagIdx = args.findIndex((a) => a === "--entry" || a.startsWith("--entry="));
+    let entry = null;
+    if (entryFlagIdx >= 0) {
+        const raw = args[entryFlagIdx].includes("=")
+            ? args[entryFlagIdx].split("=")[1]
+            : args[entryFlagIdx + 1];
+        if (!raw) {
+            console.error(`❌ --entry requires a path. Usage: --entry=/path/to/dist/index.js`);
+            process.exit(1);
+        }
+        if (!existsSync(raw)) {
+            console.error(`❌ --entry path does not exist: ${raw}`);
+            process.exit(1);
+        }
+        entry = { kind: "manual", path: raw };
+    }
     const nodePath = detectNodePath();
-    const entry = detectOpscontextEntry();
+    if (!entry)
+        entry = detectOpscontextEntry();
     if (!entry) {
-        console.error(`❌ Could not locate opscontext entrypoint.`);
-        console.error(`   Either install globally:  npm install -g @compr/opscontext-mcp`);
+        console.error(`❌ Could not locate opscontext entrypoint. Tried 3 paths:`);
+        console.error(`     (1) npm global root → @compr/opscontext-mcp/dist/index.js`);
+        console.error(`     (2) dev tree sibling (this script's dist/ dir)`);
+        console.error(`     (3) Node resolution of "@compr/opscontext-mcp/dist/index.js" via createRequire (npx cache)`);
+        console.error(``);
+        console.error(`   If you installed with npx, install globally first:`);
+        console.error(`     npm install -g @compr/opscontext-mcp`);
+        console.error(``);
         console.error(`   Or run from a clone:      cd .../ContextEngine && npm run build`);
+        console.error(``);
+        console.error(`   Or pin a path explicitly: opscontext install-autostart --entry=/full/path/to/dist/index.js`);
         process.exit(1);
     }
     // Ensure log dir

package/dist/policy.d.ts

@@ -42,6 +42,38 @@ export declare const DeployVerifyHostSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type DeployVerifyHost = z.infer<typeof DeployVerifyHostSchema>;
+/**
+ * A staged-path → required-commit-message-pattern rule. Fires when a
+ * commit touches any path matching `paths` AND the commit message does
+ * NOT match `pattern`. The canonical case (`multi-agent-for-shared-infra`)
+ * encodes the Session 15 / Sprint 16 lesson: shared production
+ * infrastructure changes (deploy scripts, ecosystem.config, nginx confs)
+ * must cite a multi-agent diagnostic workflow ID (`Multi-agent: wf_…`)
+ * OR carry an explicit bypass reason (`--skip-multi-agent-reason: …`)
+ * that gets recorded in the audit log.
+ *
+ * Rationale: the Sprint 16 multi-agent diagnostic (workflow `wdcraou93`)
+ * caught 5 design errors + 2 structural blockers in an Option B blue/green
+ * rollout that would otherwise have shipped and crashed sibling apps on
+ * the multi-tenant VPS. The rule turns that one-time discipline into a
+ * machine-enforced gate.
+ *
+ * NOTE: processor implementation (parsing staged paths + scanning the
+ * commit message buffer in the prepare-commit-msg or commit-msg hook)
+ * is intentionally left to a follow-up — this file only declares the
+ * shape so policy.json validation accepts the new rule today.
+ */
+export declare const CommitMessageRequiredSchema: z.ZodObject<{
+    id: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    pattern: z.ZodString;
+    severity: z.ZodDefault<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CommitMessageRequired = z.infer<typeof CommitMessageRequiredSchema>;
 /**
  * A documented escape hatch for the hook. Beats undocumented `touch` /
  * `--no-verify` workarounds. Bypass token requires a reason and lives in
@@ -85,6 +117,16 @@ export declare const PolicySchema: z.ZodObject<{
         within_seconds: z.ZodDefault<z.ZodNumber>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    commit_message_required: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        paths: z.ZodArray<z.ZodString>;
+        pattern: z.ZodString;
+        severity: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     bypass_tokens: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         ttl_seconds: z.ZodDefault<z.ZodNumber>;

package/dist/policy.js

@@ -58,6 +58,40 @@ export const DeployVerifyHostSchema = z.object({
     within_seconds: z.number().int().positive().default(60),
     description: z.string().optional(),
 });
+/**
+ * A staged-path → required-commit-message-pattern rule. Fires when a
+ * commit touches any path matching `paths` AND the commit message does
+ * NOT match `pattern`. The canonical case (`multi-agent-for-shared-infra`)
+ * encodes the Session 15 / Sprint 16 lesson: shared production
+ * infrastructure changes (deploy scripts, ecosystem.config, nginx confs)
+ * must cite a multi-agent diagnostic workflow ID (`Multi-agent: wf_…`)
+ * OR carry an explicit bypass reason (`--skip-multi-agent-reason: …`)
+ * that gets recorded in the audit log.
+ *
+ * Rationale: the Sprint 16 multi-agent diagnostic (workflow `wdcraou93`)
+ * caught 5 design errors + 2 structural blockers in an Option B blue/green
+ * rollout that would otherwise have shipped and crashed sibling apps on
+ * the multi-tenant VPS. The rule turns that one-time discipline into a
+ * machine-enforced gate.
+ *
+ * NOTE: processor implementation (parsing staged paths + scanning the
+ * commit message buffer in the prepare-commit-msg or commit-msg hook)
+ * is intentionally left to a follow-up — this file only declares the
+ * shape so policy.json validation accepts the new rule today.
+ */
+export const CommitMessageRequiredSchema = z.object({
+    id: z.string().min(1).describe("Stable identifier for audit-log attribution"),
+    paths: z
+        .array(z.string())
+        .min(1)
+        .describe("Glob patterns of staged files that trigger this rule (e.g. server/deploy.sh)"),
+    pattern: z
+        .string()
+        .min(1)
+        .describe("ERE regex the commit message MUST match for the commit to proceed"),
+    severity: z.enum(["block", "warn"]).default("block"),
+    description: z.string().optional(),
+});
 /**
  * A documented escape hatch for the hook. Beats undocumented `touch` /
  * `--no-verify` workarounds. Bypass token requires a reason and lives in
@@ -82,6 +116,7 @@ export const PolicySchema = z.object({
     secret_patterns: z.array(SecretPatternSchema).default([]),
     doc_coverage: z.array(DocCoverageSchema).default([]),
     deploy_verify_hosts: z.array(DeployVerifyHostSchema).default([]),
+    commit_message_required: z.array(CommitMessageRequiredSchema).default([]),
     bypass_tokens: z.array(BypassTokenSchema).default([]),
 });
 export function validatePolicy(raw) {
@@ -165,6 +200,11 @@ export function formatPolicySummary(policy) {
         lines.push(`  - ${h.host} → probe within ${h.within_seconds}s: ${h.require_probe}`);
     }
     lines.push("");
+    lines.push(`Commit-message-required rules: ${policy.commit_message_required.length}`);
+    for (const r of policy.commit_message_required) {
+        lines.push(`  - [${r.severity}] ${r.id} → paths ${r.paths.join(", ")} must match /${r.pattern}/`);
+    }
+    lines.push("");
     lines.push(`Bypass tokens: ${policy.bypass_tokens.length}`);
     for (const b of policy.bypass_tokens) {
         lines.push(`  - ${b.id} → TTL ${b.ttl_seconds}s, reason ≥ ${b.requires_reason_min_length} chars`);

package/dist/tools-manifest.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tools Manifest — single source of truth for the MCP tool catalog.
+ *
+ * Why: the info panel in the VS Code extension (and the README) historically
+ * hardcoded the tool count ("Active on all 17 MCP tools"). When new tools
+ * shipped (drift_status was the 21st), those displays silently drifted.
+ *
+ * Fix: every tool exposed via `server.tool(...)` in `index.ts` MUST appear
+ * in `ALL_TOOLS` below. A regression test in `tests/tools-manifest.test.ts`
+ * counts `^server.tool(` lines in `index.ts` and asserts the count matches
+ * `ALL_TOOLS.length`. If you add or remove a tool, this list + the test
+ * fail together — no silent drift possible.
+ *
+ * Consumers:
+ *   - `index.ts` writes `~/.contextengine/server-meta.json` on startup with
+ *     `{ toolCount, premiumCount, freeCount, version, generatedAt }` so the
+ *     VS Code extension can read it without needing an active MCP session.
+ *   - `activation.ts` imports `PREMIUM_TOOL_NAMES` (the subset that requires
+ *     a PRO license).
+ *
+ * @module tools-manifest
+ */
+/**
+ * Every tool name registered on the MCP server, in registration order.
+ * Order is not load-bearing — kept stable for easier diffs.
+ */
+export declare const ALL_TOOLS: readonly ["search_context", "list_sources", "read_source", "reindex", "list_projects", "check_ports", "run_audit", "score_project", "save_session", "load_session", "list_sessions", "delete_session", "audit_verify", "drift_status", "end_session", "save_learning", "list_learnings", "delete_learning", "import_learnings", "activate", "activation_status"];
+/**
+ * The 4 tools gated behind PRO activation. Subset of `ALL_TOOLS`.
+ * Must match `PREMIUM_TOOLS` in `src/activation.ts` (asserted by test).
+ */
+export declare const PREMIUM_TOOL_NAMES: readonly ["score_project", "run_audit", "check_ports", "list_projects"];
+/** Total count — what users see as "Active on all N MCP tools". */
+export declare const TOOL_COUNT: 21;
+/** Free-tier tool count — everything except `PREMIUM_TOOL_NAMES`. */
+export declare const FREE_TOOL_COUNT: number;
+//# sourceMappingURL=tools-manifest.d.ts.map

package/dist/tools-manifest.js

@@ -0,0 +1,64 @@
+/**
+ * Tools Manifest — single source of truth for the MCP tool catalog.
+ *
+ * Why: the info panel in the VS Code extension (and the README) historically
+ * hardcoded the tool count ("Active on all 17 MCP tools"). When new tools
+ * shipped (drift_status was the 21st), those displays silently drifted.
+ *
+ * Fix: every tool exposed via `server.tool(...)` in `index.ts` MUST appear
+ * in `ALL_TOOLS` below. A regression test in `tests/tools-manifest.test.ts`
+ * counts `^server.tool(` lines in `index.ts` and asserts the count matches
+ * `ALL_TOOLS.length`. If you add or remove a tool, this list + the test
+ * fail together — no silent drift possible.
+ *
+ * Consumers:
+ *   - `index.ts` writes `~/.contextengine/server-meta.json` on startup with
+ *     `{ toolCount, premiumCount, freeCount, version, generatedAt }` so the
+ *     VS Code extension can read it without needing an active MCP session.
+ *   - `activation.ts` imports `PREMIUM_TOOL_NAMES` (the subset that requires
+ *     a PRO license).
+ *
+ * @module tools-manifest
+ */
+/**
+ * Every tool name registered on the MCP server, in registration order.
+ * Order is not load-bearing — kept stable for easier diffs.
+ */
+export const ALL_TOOLS = [
+    "search_context",
+    "list_sources",
+    "read_source",
+    "reindex",
+    "list_projects",
+    "check_ports",
+    "run_audit",
+    "score_project",
+    "save_session",
+    "load_session",
+    "list_sessions",
+    "delete_session",
+    "audit_verify",
+    "drift_status",
+    "end_session",
+    "save_learning",
+    "list_learnings",
+    "delete_learning",
+    "import_learnings",
+    "activate",
+    "activation_status",
+];
+/**
+ * The 4 tools gated behind PRO activation. Subset of `ALL_TOOLS`.
+ * Must match `PREMIUM_TOOLS` in `src/activation.ts` (asserted by test).
+ */
+export const PREMIUM_TOOL_NAMES = [
+    "score_project",
+    "run_audit",
+    "check_ports",
+    "list_projects",
+];
+/** Total count — what users see as "Active on all N MCP tools". */
+export const TOOL_COUNT = ALL_TOOLS.length;
+/** Free-tier tool count — everything except `PREMIUM_TOOL_NAMES`. */
+export const FREE_TOOL_COUNT = ALL_TOOLS.length - PREMIUM_TOOL_NAMES.length;
+//# sourceMappingURL=tools-manifest.js.map