@compr/opscontext-mcp 2.1.0 → 2.1.3

package/dist/install-autostart.js

@@ -0,0 +1,356 @@
+// 🔒 LOCKED [AUTOSTART-INSTALL] — 2026-06-23
+// ⛔ NEVER bootstrap into a `system/` domain (would need root + run as root).
+//    Use `gui/$UID` — per-user agent, started at user login, runs as the user.
+// ⛔ NEVER write the plist before checking if a server is already listening on
+//    the port. A pre-existing process means we'd race with the launchd-managed
+//    one for port 7842.
+// ⛔ NEVER ship a plist that calls `npx -y @latest` — every restart would
+//    fetch the registry, eating ~3s and breaking offline. Pin a specific
+//    node path + a specific dist path.
+// WHY: This is the "set it and forget it" entrypoint for non-technical users.
+//    If it fails silently or starts duplicating processes, the entire
+//    auto-capture story collapses and the user has to type `nohup npx ...`
+//    forever — defeating the whole point.
+// FIX: To add platform support beyond macOS, branch on process.platform and
+//    add equivalent systemd / NSSM logic. Keep `gui/$UID` and KeepAlive
+//    discipline in any new platform.
+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");
+const PORT = 7842;
+/** Resolve an absolute node binary path that launchd can find without PATH. */
+function detectNodePath() {
+    // process.execPath is the node that's running THIS script — absolute path.
+    // launchd runs without the user's interactive shell, so we MUST pass an
+    // absolute path (no PATH lookup of "node" works under launchd).
+    return process.execPath;
+}
+/** Find a stable path to the opscontext entrypoint that survives version
+ *  upgrades. Order: (1) globally installed bin → resolve symlink to real path;
+ *  (2) ./dist/index.js next to this module (dev tree). Falls through with
+ *  null if neither is found. */
+function detectOpscontextEntry() {
+    // (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");
+        if (existsSync(candidate))
+            return { kind: "global", path: candidate };
+    }
+    catch {
+        /* no npm root available; fall through */
+    }
+    // (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 {
+        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) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${entryPath}</string>
+    </array>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${nodeBinDir}:/usr/local/bin:/usr/bin:/bin</string>
+        <key>HOME</key>
+        <string>${homedir()}</string>
+        <key>OPSCONTEXT_SKIP_CLAUDE_MEMORY</key>
+        <string>1</string>
+    </dict>
+
+    <key>WorkingDirectory</key>
+    <string>${homedir()}</string>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>${join(LOG_DIR, "mcp-stdout.log")}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${join(LOG_DIR, "mcp-stderr.log")}</string>
+
+    <key>ProcessType</key>
+    <string>Background</string>
+</dict>
+</plist>
+`;
+}
+function isMacOS() {
+    return platform() === "darwin";
+}
+function userId() {
+    return process.getuid?.() ?? 501;
+}
+function portIsOurs() {
+    try {
+        execSync(`lsof -nP -iTCP:${PORT} -sTCP:LISTEN >/dev/null 2>&1`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function waitForPort(timeoutSec = 30) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutSec * 1000) {
+        if (portIsOurs())
+            return true;
+        execSync("sleep 1");
+    }
+    return false;
+}
+export async function cliInstallAutostart(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext install-autostart [--force]
+
+Installs OpsContext as a macOS LaunchAgent so the MCP server starts
+automatically at every login and restarts if it crashes.
+
+After running this once, you never need to start the server manually again.
+Browser extension events + Claude Code hook events + VS Code emitter events
+all flow through the auto-started server.
+
+  --force   Re-create the plist even if one already exists (use after a
+            node version upgrade or after moving the install location).
+
+To stop / uninstall:        opscontext uninstall-autostart
+To check status:            opscontext autostart-status
+To view server logs:        tail -f ~/.contextengine/logs/mcp-stderr.log
+`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.error(`❌ install-autostart currently supports macOS only (this is ${platform()}).`);
+        console.error(`   For Linux: write a systemd --user unit. For Windows: NSSM or Task Scheduler.`);
+        process.exit(1);
+    }
+    const force = args.includes("--force") || args.includes("-f");
+    if (existsSync(PLIST_FILE) && !force) {
+        console.error(`❌ ${PLIST_FILE} already exists.`);
+        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();
+    if (!entry)
+        entry = detectOpscontextEntry();
+    if (!entry) {
+        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
+    mkdirSync(LOG_DIR, { recursive: true });
+    mkdirSync(dirname(PLIST_FILE), { recursive: true });
+    const nodeBinDir = dirname(nodePath);
+    const plist = buildPlist(nodePath, entry.path, nodeBinDir);
+    writeFileSync(PLIST_FILE, plist);
+    console.log(`✅ Wrote ${PLIST_FILE}`);
+    console.log(`   node:  ${nodePath}`);
+    console.log(`   entry: ${entry.path}  (${entry.kind})`);
+    // Stop any currently-running unmanaged opscontext server on the port —
+    // it would race with launchd for port 7842.
+    if (portIsOurs()) {
+        console.log(`   detected existing process on :${PORT} — relying on launchctl bootout to clean it.`);
+    }
+    // Idempotent bootstrap: bootout (ignore failure) → bootstrap
+    const uid = userId();
+    try {
+        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+    }
+    catch {
+        /* not loaded — fine */
+    }
+    try {
+        execSync(`launchctl bootstrap gui/${uid} ${PLIST_FILE}`, { stdio: "inherit" });
+    }
+    catch (err) {
+        console.error(`❌ launchctl bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    console.log(`   waiting for the server to bind port ${PORT}...`);
+    if (waitForPort(30)) {
+        console.log(`✅ OpsContext is now running as a LaunchAgent (started at every login).`);
+        console.log(``);
+        console.log(`Verify:      curl -s http://127.0.0.1:${PORT}/health | jq .`);
+        console.log(`Logs:        tail -f ~/.contextengine/logs/mcp-stderr.log`);
+        console.log(`Stop:        opscontext uninstall-autostart`);
+    }
+    else {
+        console.error(`⚠️ Server didn't bind port ${PORT} within 30s.`);
+        console.error(`   Check the logs: tail -50 ~/.contextengine/logs/mcp-stderr.log`);
+        process.exit(1);
+    }
+}
+export async function cliUninstallAutostart(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext uninstall-autostart
+
+Removes the LaunchAgent and stops the OpsContext MCP server. The audit log
+and extension secret are NOT touched — only the auto-start wiring goes away.
+You can re-install with: opscontext install-autostart`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.error(`❌ Only macOS LaunchAgents supported here.`);
+        process.exit(1);
+    }
+    const uid = userId();
+    let removed = false;
+    try {
+        execSync(`launchctl bootout gui/${uid}/${LABEL}`, { stdio: "ignore" });
+        removed = true;
+    }
+    catch {
+        /* not loaded */
+    }
+    if (existsSync(PLIST_FILE)) {
+        const { unlinkSync } = await import("fs");
+        unlinkSync(PLIST_FILE);
+        console.log(`✅ Removed ${PLIST_FILE}`);
+    }
+    else {
+        console.log(`   (no plist at ${PLIST_FILE})`);
+    }
+    if (removed) {
+        console.log(`✅ Stopped the running ${LABEL} agent.`);
+    }
+    else {
+        console.log(`   (no running ${LABEL} agent found)`);
+    }
+    console.log(``);
+    console.log(`Audit log and extension secret kept at ~/.contextengine/ — re-install any time.`);
+}
+export async function cliAutostartStatus(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(`Usage: opscontext autostart-status
+
+Shows whether OpsContext is configured to auto-start (LaunchAgent present),
+whether it's currently running (port 7842 listening), and the path to the
+running entrypoint.`);
+        return;
+    }
+    if (!isMacOS()) {
+        console.log(`platform:  ${platform()} (LaunchAgent applies to macOS only)`);
+        return;
+    }
+    const plistExists = existsSync(PLIST_FILE);
+    const portUp = portIsOurs();
+    const uid = userId();
+    let launchctlState = "not loaded";
+    try {
+        const out = execSync(`launchctl print gui/${uid}/${LABEL} 2>/dev/null || true`, { encoding: "utf-8" });
+        const match = out.match(/state\s*=\s*(\S+)/);
+        if (match)
+            launchctlState = match[1];
+    }
+    catch {
+        /* ignore */
+    }
+    console.log(`OpsContext auto-start status`);
+    console.log(`─────────────────────────────`);
+    console.log(`  plist:       ${plistExists ? "✅ " + PLIST_FILE : "❌ not installed (run: opscontext install-autostart)"}`);
+    console.log(`  launchctl:   ${launchctlState}`);
+    console.log(`  port ${PORT}:   ${portUp ? "✅ listening" : "❌ not listening"}`);
+    if (portUp) {
+        try {
+            const health = execSync(`curl -sf http://127.0.0.1:${PORT}/health`, { encoding: "utf-8", timeout: 2000 });
+            console.log(`  health:      ${health.trim()}`);
+        }
+        catch {
+            console.log(`  health:      ⚠ port open but /health didn't respond`);
+        }
+    }
+    console.log(``);
+    console.log(`Logs: ~/.contextengine/logs/mcp-stderr.log`);
+}
+//# sourceMappingURL=install-autostart.js.map

package/dist/install-claude-hook.d.ts

@@ -0,0 +1,3 @@
+export declare function cliInstallClaudeHook(args: string[]): Promise<void>;
+export declare function cliUninstallClaudeHook(args: string[]): Promise<void>;
+//# sourceMappingURL=install-claude-hook.d.ts.map

package/dist/install-claude-hook.js

@@ -0,0 +1,180 @@
+// 🔒 LOCKED [CLAUDE-HOOK-INSTALL] — 2026-06-23
+// ⛔ NEVER overwrite existing entries in hooks.PostToolUse — must APPEND.
+//    Users (and CE itself via the dogfood settings) commonly have
+//    matcher-specific PostToolUse entries (e.g. "Read|Edit|Write" gating)
+//    that would be silently destroyed by a replace.
+// ⛔ NEVER write to ~/.claude/settings.json without parsing first. A typo
+//    or non-JSON state means Claude Code refuses to start.
+// ⛔ NEVER emit on PreToolUse — would double-count vs PostToolUse for the
+//    `stuck` heuristic and skew `silent_failure` counts.
+// WHY: Claude Code hook wiring is the ONLY way the user's terminal Claude
+//    Code sessions get into the OpsContext audit log. The installer has to
+//    be safe (idempotent, preserve existing) AND legible (clear error
+//    messages) AND fast (one command). If users have to hand-edit JSON,
+//    they won't.
+// FIX: To add a new hook event, extend EVENT_KINDS + the splice block.
+//    Keep the "preserve existing" discipline in every code path.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
+const HOOKS_DIR = join(CLAUDE_DIR, "hooks");
+const HOOK_SCRIPT = join(HOOKS_DIR, "opscontext-emit.sh");
+const EVENT_KINDS = ["UserPromptSubmit", "PostToolUse", "SessionStart"];
+function readSettings() {
+    if (!existsSync(SETTINGS_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`${SETTINGS_FILE} is not valid JSON — refusing to touch. (${err instanceof Error ? err.message : err})`);
+    }
+}
+function backupSettings() {
+    if (!existsSync(SETTINGS_FILE))
+        return "";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${SETTINGS_FILE}.bak-pre-opscontext-${ts}`;
+    copyFileSync(SETTINGS_FILE, backup);
+    return backup;
+}
+function hookAlreadyWired(entries, hookScript) {
+    if (!entries)
+        return false;
+    return entries.some((e) => e.hooks?.some((h) => h.command?.startsWith(hookScript)));
+}
+/** Path to the reference hook script bundled with this package. */
+function bundledHookSource() {
+    // dist/install-claude-hook.js → ../defaults/claude-code-hook.sh in dev tree,
+    // or .../node_modules/@compr/opscontext-mcp/defaults/claude-code-hook.sh
+    // when globally / locally installed via npm. Both follow the same relative
+    // shape because npm copies defaults/ via the `files` whitelist.
+    const candidates = [
+        join(__dirname || "", "..", "defaults", "claude-code-hook.sh"),
+        join(__dirname || "", "defaults", "claude-code-hook.sh"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+export async function cliInstallClaudeHook(args) {
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: opscontext install-claude-hook
+
+Wires OpsContext into Claude Code's hook system so every terminal Claude
+Code session sends prompts + tool calls to the OpsContext audit log.
+
+Events emitted (all go through the local HTTP endpoint, never the network):
+  • UserPromptSubmit → vscode.prompt_submit  (feeds the loop heuristic)
+  • PostToolUse      → vscode.tool_call      (feeds stuck + silent_failure)
+  • SessionStart     → vscode.session_start
+
+The installer:
+  1. Copies the bundled hook script to ~/.claude/hooks/opscontext-emit.sh
+  2. Splices three entries into ~/.claude/settings.json under "hooks"
+  3. Preserves every existing hook entry (idempotent, safe to re-run)
+
+A timestamped backup is written next to settings.json before any change.
+
+Pre-req: the MCP server must be auto-started or running (otherwise the hook
+silently no-ops, which is the safe default — you won't lose events later).
+Run: opscontext install-autostart
+`);
+        return;
+    }
+    // Step 1: Install / verify the hook script
+    mkdirSync(HOOKS_DIR, { recursive: true });
+    const src = bundledHookSource();
+    if (!src) {
+        console.error(`❌ Could not find bundled hook script defaults/claude-code-hook.sh.`);
+        console.error(`   This means the install is incomplete. Reinstall opscontext:`);
+        console.error(`     npm install -g @compr/opscontext-mcp`);
+        process.exit(1);
+    }
+    copyFileSync(src, HOOK_SCRIPT);
+    chmodSync(HOOK_SCRIPT, 0o755);
+    console.log(`✅ Installed hook script: ${HOOK_SCRIPT}`);
+    // Step 2: Splice into settings.json
+    const settings = readSettings();
+    const backup = backupSettings();
+    if (backup)
+        console.log(`✅ Backed up settings.json → ${backup}`);
+    settings.hooks ??= {};
+    const hookCmdPrefix = `${HOOK_SCRIPT}`; // command string starts with this
+    let added = 0;
+    let skipped = 0;
+    for (const kind of EVENT_KINDS) {
+        settings.hooks[kind] ??= [];
+        if (hookAlreadyWired(settings.hooks[kind], hookCmdPrefix)) {
+            skipped++;
+            continue;
+        }
+        const entry = {
+            hooks: [
+                {
+                    type: "command",
+                    command: `${HOOK_SCRIPT} ${kind}`,
+                    timeout: 5,
+                },
+            ],
+        };
+        // PostToolUse needs a matcher (PreToolUse/PostToolUse are tool-matched);
+        // ".*" matches every tool. Other events are not tool-scoped.
+        if (kind === "PostToolUse")
+            entry.matcher = ".*";
+        settings.hooks[kind].push(entry);
+        added++;
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`✅ ${added} hook entries added, ${skipped} already present.`);
+    console.log(``);
+    console.log(`Test live:`);
+    console.log(`  1. Open a NEW VS Code terminal (settings.json is read at session start).`);
+    console.log(`  2. Run \`claude\` and ask anything — Claude will use tools.`);
+    console.log(`  3. In any other terminal:`);
+    console.log(`     tail -f ~/.contextengine/audit.log | grep --line-buffered '"actor":"claude-code"'`);
+    console.log(``);
+    console.log(`To remove: opscontext uninstall-claude-hook   (or hand-edit ~/.claude/settings.json)`);
+}
+export async function cliUninstallClaudeHook(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(`Usage: opscontext uninstall-claude-hook
+
+Removes OpsContext hook entries from ~/.claude/settings.json. The hook
+script file (~/.claude/hooks/opscontext-emit.sh) is left in place — delete
+manually if you want it gone. The audit log is NOT touched.`);
+        return;
+    }
+    const settings = readSettings();
+    if (!settings.hooks) {
+        console.log(`   (no hooks block in settings.json — nothing to remove)`);
+        return;
+    }
+    const backup = backupSettings();
+    if (backup)
+        console.log(`✅ Backed up settings.json → ${backup}`);
+    let removed = 0;
+    for (const kind of EVENT_KINDS) {
+        const entries = settings.hooks[kind];
+        if (!entries)
+            continue;
+        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh")));
+        removed += entries.length - filtered.length;
+        if (filtered.length === 0) {
+            delete settings.hooks[kind];
+        }
+        else {
+            settings.hooks[kind] = filtered;
+        }
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`✅ Removed ${removed} hook entries.`);
+    console.log(`   Hook script kept at: ${HOOK_SCRIPT}`);
+    console.log(`   Audit log untouched.`);
+}
+//# sourceMappingURL=install-claude-hook.js.map

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`);