@mmnto/cli 2.1.0 → 2.2.1

package/dist/commands/gate-install.test.js

@@ -3,10 +3,10 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { knownGateEvents, TotemError } from '@mmnto/totem';
+import { knownGates, TotemError } from '@mmnto/totem';
 import { ejectCommand } from './eject.js';
-import { gateInstallCommand, resolveGateEvents } from './gate.js';
-import { commandInstallsGate, GATE_WRAPPER_REL, installGates } from './gate-install.js';
+import { gateInstallCommand } from './gate.js';
+import { commandInstallsGate, GATE_WRAPPER_REL, installGates, } from './gate-install.js';
 import { initCommand } from './init.js';
 import { CLAUDE_GATE_WRAPPER, TOTEM_FILE_END, TOTEM_FILE_MARKER } from './init-templates.js';
 import { resolveGitRootForHookPath, resolveHooksDir } from './install-hooks.js';
@@ -51,6 +51,26 @@ function makeTmpDir() {
     // `.native` expands Windows 8.3 short names so process.cwd()/realpath agree.
     return fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'totem-gate-install-')));
 }
+/**
+ * The parent env with EVERY case-variant of PATH dropped and exactly one
+ * `PATH` set (win32 stores it as `Path`; a plain spread would leave both keys
+ * in the child's block). Everything else is inherited so node still boots under
+ * an empty PATH.
+ *
+ * Load-bearing since the wrapper grew a PATH fallback arm (mmnto-ai/totem#2822):
+ * a wrapper test that means "no CLI is resolvable" must say so explicitly, or it
+ * silently reads the developer's global `@mmnto/cli` and passes/fails by machine.
+ */
+function envWithPath(value) {
+    const env = {};
+    for (const [key, val] of Object.entries(process.env)) {
+        if (key.toUpperCase() === 'PATH')
+            continue;
+        env[key] = val;
+    }
+    env.PATH = value;
+    return env;
+}
 function readSettings(cwd) {
     const raw = fs.readFileSync(path.join(cwd, '.claude', 'settings.json'), 'utf-8');
     return JSON.parse(raw);
@@ -60,13 +80,41 @@ function preToolUseEntries(cwd) {
     const hooks = (parsed.hooks ?? {});
     return (hooks.PreToolUse ?? []);
 }
-/** Count Write|Edit PreToolUse entries whose command references a given gate. */
+/**
+ * The `{event, matcher}` pairs the caller resolves from the core registry and
+ * hands `installGates` (mmnto-ai/totem#2799). Spelled literally here rather than
+ * read from `knownGates()` so a registry change that silently moved a gate to a
+ * different matcher would FAIL these tests instead of following them.
+ */
+const FREEZE_CHECK = { event: 'freeze-check', matcher: 'Write|Edit' };
+const TRANSPORT_SHIELD = {
+    event: 'transport-shield',
+    matcher: 'Bash|PowerShell',
+};
+/**
+ * Every PreToolUse matcher an entry installing `event` currently appears under.
+ * Matcher-AGNOSTIC by construction: a gate that leaked into a second matcher
+ * shows up here as two members, which is the invariant the #2799 tests assert.
+ */
+function matchersFor(cwd, event) {
+    const found = [];
+    for (const e of preToolUseEntries(cwd)) {
+        if (!Array.isArray(e.hooks))
+            continue;
+        for (const h of e.hooks) {
+            const cmd = typeof h === 'string' ? h : (h?.command ?? '');
+            // Collision-safe exact --event match (tier-independent).
+            if (commandInstallsGate(cmd, event))
+                found.push(e.matcher ?? '');
+        }
+    }
+    return found;
+}
+/** Count PreToolUse entries (under ANY matcher) whose command references a given gate. */
 function gateEntryCount(cwd, event) {
-    return preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit' &&
-        Array.isArray(e.hooks) &&
+    return preToolUseEntries(cwd).filter((e) => Array.isArray(e.hooks) &&
         e.hooks.some((h) => {
             const cmd = typeof h === 'string' ? h : (h?.command ?? '');
-            // Collision-safe exact --event match (tier-independent).
             return commandInstallsGate(cmd, event);
         })).length;
 }
@@ -74,7 +122,7 @@ function gateEntryCount(cwd, event) {
 function gateCommandFor(cwd, event) {
     const cmds = [];
     for (const e of preToolUseEntries(cwd)) {
-        if (e.matcher !== 'Write|Edit' || !Array.isArray(e.hooks))
+        if (!Array.isArray(e.hooks))
             continue;
         for (const h of e.hooks) {
             const cmd = typeof h === 'string' ? h : (h?.command ?? '');
@@ -97,7 +145,7 @@ describe('installGates / gate install (settings merge)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('scaffolds the wrapper and merges one PreToolUse entry per gate', () => {
-        const results = installGates(cwd, ['freeze-check']);
+        const results = installGates(cwd, [FREEZE_CHECK]);
         // wrapper scaffold + one entry merge
         expect(results.some((r) => r.file === GATE_WRAPPER_REL && r.action === 'created')).toBe(true);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
@@ -108,7 +156,7 @@ describe('installGates / gate install (settings merge)', () => {
         const wrapperPath = path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs');
         fs.mkdirSync(path.dirname(wrapperPath), { recursive: true });
         fs.writeFileSync(wrapperPath, `${TOTEM_FILE_MARKER}\nstale\n${TOTEM_FILE_END}\n`, 'utf-8');
-        const results = installGates(cwd, ['freeze-check']);
+        const results = installGates(cwd, [FREEZE_CHECK]);
         // gate install now threads the end marker, so scaffoldFile drift-repairs the bounded
         // wrapper (`refreshed`) and gate-install maps that to `merged` (a write happened).
         expect(results.find((r) => r.file === GATE_WRAPPER_REL).action).toBe('merged');
@@ -116,9 +164,9 @@ describe('installGates / gate install (settings merge)', () => {
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
     });
     it('is idempotent: a second install of the same gate is a no-op', () => {
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         const before = JSON.stringify(readSettings(cwd));
-        const second = installGates(cwd, ['freeze-check']);
+        const second = installGates(cwd, [FREEZE_CHECK]);
         const entryResult = second.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('skipped');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
@@ -127,8 +175,8 @@ describe('installGates / gate install (settings merge)', () => {
     it('keys idempotency on the per-gate command substring (distinct gates → distinct entries)', () => {
         // freeze-check installed; a hypothetical future gate keyed on a different
         // --event substring produces a SECOND entry rather than colliding.
-        installGates(cwd, ['freeze-check']);
-        installGates(cwd, ['some-future-gate']);
+        installGates(cwd, [FREEZE_CHECK]);
+        installGates(cwd, [{ event: 'some-future-gate', matcher: 'Write|Edit' }]);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateEntryCount(cwd, 'some-future-gate')).toBe(1);
         // Two distinct Write|Edit gate entries under one matcher.
@@ -147,16 +195,110 @@ describe('installGates / gate install (settings merge)', () => {
                 PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'my-hook' }] }],
             },
         }));
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         const entries = preToolUseEntries(cwd);
         expect(entries.some((e) => e.matcher === 'Bash')).toBe(true);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
     });
-    it('gateInstallCommand --all installs every known gate', async () => {
+    it('gateInstallCommand --all installs every known gate under ITS registry matcher', async () => {
         await gateInstallCommand({ all: true });
-        for (const event of knownGateEvents()) {
+        for (const { event, matcher } of knownGates()) {
+            expect(gateEntryCount(cwd, event)).toBe(1);
+            // The installed matcher is the registry's, not a shared default.
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
+        }
+    });
+});
+// ─── Per-gate matchers (mmnto-ai/totem#2799) ───────────────────────────
+//
+// Before #2799 every gate entry was written under one hardcoded `Write|Edit`
+// matcher. The registry now carries each gate's own matcher, the caller
+// resolves it (`knownGates()`), and `installGates` writes THAT — so
+// `transport-shield` lands on `Bash|PowerShell` while `freeze-check` keeps the
+// byte-identical `Write|Edit` entry it has always written.
+describe('installGates per-gate matcher (mmnto-ai/totem#2799)', () => {
+    let cwd;
+    let originalCwd;
+    const STRICT_FREEZE_ENTRY = {
+        matcher: 'Write|Edit',
+        hooks: [
+            {
+                type: 'command',
+                command: 'node .claude/hooks/gate-wrapper.cjs --event freeze-check --strict',
+            },
+        ],
+    };
+    const STRICT_TRANSPORT_ENTRY = {
+        matcher: 'Bash|PowerShell',
+        hooks: [
+            {
+                type: 'command',
+                command: 'node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict',
+            },
+        ],
+    };
+    beforeEach(() => {
+        cwd = makeTmpDir();
+        originalCwd = process.cwd();
+        process.chdir(cwd);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    });
+    it('transport-shield writes exactly ONE entry under Bash|PowerShell with the baked command', () => {
+        installGates(cwd, [TRANSPORT_SHIELD]);
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'transport-shield')).toBe('node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict');
+        // The whole emitted entry, byte for byte.
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_TRANSPORT_ENTRY]);
+    });
+    it('freeze-check writes the SAME Write|Edit entry it wrote before #2799, byte for byte', () => {
+        installGates(cwd, [FREEZE_CHECK]);
+        // The full emitted JSON entry — the regression guard on the gate whose
+        // matcher did NOT change.
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY]);
+    });
+    it('both gates together write both entries, each under its own matcher', () => {
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY, STRICT_TRANSPORT_ENTRY]);
+        expect(matchersFor(cwd, 'freeze-check')).toEqual(['Write|Edit']);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+    });
+    it('re-running both gates at the same tier is a byte-level no-op', () => {
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        const settingsPath = path.join(cwd, '.claude', 'settings.json');
+        const before = fs.readFileSync(settingsPath, 'utf-8');
+        const second = installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD]);
+        expect(second.find((r) => r.event === 'freeze-check')?.action).toBe('skipped');
+        expect(second.find((r) => r.event === 'transport-shield')?.action).toBe('skipped');
+        expect(fs.readFileSync(settingsPath, 'utf-8')).toBe(before);
+    });
+    it('a tier switch updates the transport-shield entry IN PLACE under its own matcher', () => {
+        installGates(cwd, [TRANSPORT_SHIELD], 'pilot');
+        expect(gateCommandFor(cwd, 'transport-shield')).toContain('--pilot');
+        const switched = installGates(cwd, [TRANSPORT_SHIELD], 'strict');
+        expect(switched.find((r) => r.event === 'transport-shield')?.action).toBe('updated');
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        const cmd = gateCommandFor(cwd, 'transport-shield');
+        expect(cmd).toContain('--strict');
+        expect(cmd).not.toContain('--pilot');
+    });
+    it('after any sequence of INSTALLER writes, no gate appears under two matchers (hand edits are not enforced)', () => {
+        // Interleave tiers and selections — the upsert must converge on exactly one
+        // entry per gate, always under that gate's registry matcher.
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
+        installGates(cwd, [TRANSPORT_SHIELD]);
+        installGates(cwd, [TRANSPORT_SHIELD], 'pilot');
+        installGates(cwd, [FREEZE_CHECK, TRANSPORT_SHIELD], 'strict');
+        installGates(cwd, [TRANSPORT_SHIELD], 'strict');
+        for (const { event, matcher } of [FREEZE_CHECK, TRANSPORT_SHIELD]) {
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
             expect(gateEntryCount(cwd, event)).toBe(1);
         }
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_FREEZE_ENTRY, STRICT_TRANSPORT_ENTRY]);
     });
 });
 // ─── FIX A: tier-AWARE upsert (update in place, never silent no-op/dup) ──
@@ -179,17 +321,17 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('default(strict) then re-install --strict → skipped, one entry, command keeps --strict', () => {
-        installGates(cwd, ['freeze-check']); // default tier === strict
-        const second = installGates(cwd, ['freeze-check'], 'strict');
+        installGates(cwd, [FREEZE_CHECK]); // default tier === strict
+        const second = installGates(cwd, [FREEZE_CHECK], 'strict');
         const entryResult = second.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('skipped');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--strict');
     });
     it('--pilot then --strict → updated, ONE entry, command flips to --strict (not --pilot)', () => {
-        installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--pilot');
-        const switched = installGates(cwd, ['freeze-check'], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'strict');
         const entryResult = switched.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('updated');
         // Exactly one entry — no duplicate created by the tier switch.
@@ -199,8 +341,8 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         expect(cmd).not.toContain('--pilot');
     });
     it('--strict then --pilot → updated back to --pilot, one entry', () => {
-        installGates(cwd, ['freeze-check'], 'strict');
-        const switched = installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'pilot');
         const entryResult = switched.find((r) => r.event === 'freeze-check');
         expect(entryResult?.action).toBe('updated');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
@@ -242,13 +384,13 @@ describe('installGates tier-aware upsert (FIX A)', () => {
                 return c === shieldCommand;
             }));
         // Install the gate at pilot → a distinct second Write|Edit entry.
-        installGates(cwd, ['freeze-check'], 'pilot');
+        installGates(cwd, [FREEZE_CHECK], 'pilot');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(gateCommandFor(cwd, 'freeze-check')).toContain('--pilot');
         expect(hasShield()).toBe(true);
         expect(preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit').length).toBe(2);
         // Tier switch → updates ONLY the gate entry in place; PreWriteShield stays.
-        const switched = installGates(cwd, ['freeze-check'], 'strict');
+        const switched = installGates(cwd, [FREEZE_CHECK], 'strict');
         expect(switched.find((r) => r.event === 'freeze-check')?.action).toBe('updated');
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         const cmd2 = gateCommandFor(cwd, 'freeze-check');
@@ -258,21 +400,9 @@ describe('installGates tier-aware upsert (FIX A)', () => {
         expect(preToolUseEntries(cwd).filter((e) => e.matcher === 'Write|Edit').length).toBe(2);
     });
 });
-describe('resolveGateEvents (registry-driven validation)', () => {
-    it('--all enumerates knownGateEvents()', async () => {
-        expect(await resolveGateEvents({ all: true })).toEqual(knownGateEvents());
-    });
-    it('a known --<name> resolves to itself', async () => {
-        expect(await resolveGateEvents({ name: 'freeze-check' })).toEqual(['freeze-check']);
-    });
-    it('an unknown --<name> fails loud (never default-install)', async () => {
-        await expect(resolveGateEvents({ name: 'made-up-gate' })).rejects.toBeInstanceOf(TotemError);
-        await expect(resolveGateEvents({ name: 'made-up-gate' })).rejects.toThrow(/unknown gate/i);
-    });
-    it('no --all and no --<name> fails loud (no default-install)', async () => {
-        await expect(resolveGateEvents({})).rejects.toThrow(/no gate selected/i);
-    });
-});
+// `resolveGates` (the registry-driven `{event, matcher}` resolver that replaced
+// `resolveGateEvents` in mmnto-ai/totem#2799) is covered in gate.test.ts, beside
+// the other `./gate.js` command-seam tests.
 // ─── The parameterized wrapper's disposition → exit-code map ───────────
 //
 // We render the wrapper template to a temp dir and drive it via stdin with
@@ -291,36 +421,76 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
     afterEach(() => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
-    /** Install a stub local CLI that emits a controlled verdict / exit code. */
+    /** Where the stub CLI records the argv and stdin it was spawned with (absent ⇒ never spawned). */
+    const stubRecordPath = () => path.join(cwd, 'stub-record.json');
+    /** Install a stub local CLI that records its argv + stdin and emits a controlled verdict / exit code. */
     function writeStubCli(opts) {
         const distDir = path.join(cwd, 'node_modules', '@mmnto', 'cli', 'dist');
         fs.mkdirSync(distDir, { recursive: true });
         const verdictJson = opts.verdict === undefined ? '' : JSON.stringify(opts.verdict);
         const exitCode = opts.exit ?? 0;
         // CommonJS stub (the wrapper invokes via `node <path>`); .js is fine here
-        // because there is no package.json type:module in the temp dir.
+        // because there is no package.json type:module in the temp dir. The record
+        // is what lets a test assert BOTH that a spawn happened and exactly which
+        // `gate check --event … --payload -` the wrapper projected, argv AND the
+        // stdin the payload rides on (mmnto-ai/totem#2799); `JSON.stringify` on
+        // the path handles Windows separators without a hand-written escape.
         const stub = [
             '"use strict";',
+            'const fs = require("fs");',
             `const out = ${JSON.stringify(verdictJson)};`,
+            'let stdin = "";',
+            'try { stdin = fs.readFileSync(0, "utf-8"); } catch { stdin = ""; }',
+            `fs.writeFileSync(${JSON.stringify(stubRecordPath())}, JSON.stringify({ argv: process.argv.slice(2), stdin }));`,
             'if (out) process.stdout.write(out + "\\n");',
             `process.exit(${exitCode});`,
             '',
         ].join('\n');
         fs.writeFileSync(path.join(distDir, 'index.js'), stub);
     }
-    /** Run the rendered wrapper with the given envelope + baked extra args. */
-    function runWrapper(envelope, extraArgs = []) {
+    /** What the stub CLI was spawned with, or null when the wrapper never spawned it. */
+    function stubRecord() {
+        if (!fs.existsSync(stubRecordPath()))
+            return null;
+        return JSON.parse(fs.readFileSync(stubRecordPath(), 'utf-8'));
+    }
+    /** The argv the stub CLI was spawned with, or null when the wrapper never spawned it. */
+    function stubArgv() {
+        return stubRecord()?.argv ?? null;
+    }
+    /**
+     * The payload JSON the wrapper projected, parsed (throws if it never
+     * spawned). The payload rides on the child's stdin under `--payload -` —
+     * never argv, whose win32 limit a long Bash command would exceed.
+     */
+    function spawnedPayload() {
+        const record = stubRecord();
+        expect(record, 'the wrapper never spawned the CLI').not.toBeNull();
+        const at = record.argv.indexOf('--payload');
+        expect(at).toBeGreaterThan(-1);
+        expect(record.argv[at + 1]).toBe('-');
+        return JSON.parse(record.stdin);
+    }
+    /**
+     * Run the rendered wrapper with the given envelope + baked extra args.
+     * `env` defaults to the parent's (every test here writes a repo-local stub,
+     * which the wrapper resolves FIRST, so the ambient PATH is inert for them);
+     * the no-CLI test passes an empty PATH explicitly.
+     */
+    function runWrapper(envelope, extraArgs = [], event = 'freeze-check', env = undefined) {
         const wrapperPath = path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs');
-        const res = spawnSync(process.execPath, [wrapperPath, '--event', 'freeze-check', ...extraArgs], {
+        const res = spawnSync(process.execPath, [wrapperPath, '--event', event, ...extraArgs], {
             cwd,
             input: JSON.stringify(envelope),
             encoding: 'utf-8',
             timeout: 30000,
+            ...(env ? { env } : {}),
         });
         return { status: res.status, stderr: res.stderr ?? '' };
     }
     const EDIT_NO_SUBSYSTEM = { tool_name: 'Edit', tool_input: { file_path: 'src/foo.ts' } };
     const DECLARED = { tool_name: 'Edit', tool_input: { subsystem: 'rule-compilation' } };
+    const ALLOW_VERDICT = { disposition: 'allow', reason: 'ok', provenance: {} };
     it('allow → exit 0 (silent)', () => {
         writeStubCli({ verdict: { disposition: 'allow', reason: 'ok', provenance: {} }, exit: 0 });
         const { status } = runWrapper(DECLARED);
@@ -382,14 +552,17 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         expect(res.status).toBe(0);
     });
     // ─── FIX 2: applicable gate but no local CLI dist → fail-closed ────────
-    it('applicable gate but the local CLI dist is missing → exit 2 fail-closed (FIX 2)', () => {
-        // Deliberately do NOT write the stub CLI. A declared subsystem makes the
-        // gate APPLY, but @mmnto/cli is not resolvable. freeze-check has no
-        // commit-time hard floor, so an applicable-but-unevaluable gate must fail
-        // closed (exit 2) rather than silently allow (exit 0).
-        const { status, stderr } = runWrapper(DECLARED);
+    it('applicable gate but NO CLI is resolvable (local absent, PATH empty) → exit 2 fail-closed (FIX 2)', () => {
+        // Deliberately do NOT write the stub CLI, and hand the wrapper an EMPTY
+        // PATH so neither resolution arm can answer (mmnto-ai/totem#2822 added the
+        // PATH fallback; without this the test would silently read a developer's
+        // global @mmnto/cli and stop testing fail-closed). A declared subsystem
+        // makes the gate APPLY; freeze-check has no commit-time hard floor, so an
+        // applicable-but-unevaluable gate must fail closed (exit 2), never silently
+        // allow (exit 0).
+        const { status, stderr } = runWrapper(DECLARED, [], 'freeze-check', envWithPath(''));
         expect(status).toBe(2);
-        expect(stderr).toMatch(/not resolvable|not installed|failing closed/i);
+        expect(stderr).toMatch(/failing closed/i);
     });
     it('gate check exits 0 with unparseable stdout → exit 2 fail-closed', () => {
         // verdict undefined → stub emits nothing; the wrapper cannot parse a
@@ -417,6 +590,258 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         });
         expect(res.status).toBe(0);
     });
+    // ─── Per-event payload projection (mmnto-ai/totem#2799) ────────────────
+    //
+    // The wrapper is --event-parameterized but used to build ONE freeze-check-
+    // shaped payload for every event. It now branches on the baked --event AFTER
+    // the envelope parse and the non-object guard: each gate owns its own
+    // NOT-APPLICABLE test and its own payload, and an event it cannot project
+    // fails CLOSED. The stub CLI records its argv, so "did not spawn" is an
+    // assertion about the filesystem, not an inference from the exit code.
+    const BASH_CMD = { tool_name: 'Bash', tool_input: { command: 'git status' } };
+    const PWSH_CMD = { tool_name: 'PowerShell', tool_input: { command: 'Get-ChildItem' } };
+    it('transport-shield on a Write envelope → exit 0, never spawns', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Write', tool_input: { file_path: 'src/foo.ts' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Write envelope that DECLARES a subsystem still never spawns', () => {
+        // The falsifier for the projection swap: pre-#2799 the wrapper keyed
+        // applicability on `tool_input.subsystem` for EVERY event, so this envelope
+        // shelled out with a freeze-check-shaped `{subsystem}` payload under
+        // `--event transport-shield`. Applicability is now the gate's own.
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Write', tool_input: { subsystem: 'rule-compilation' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Bash envelope with no string command → exit 0, never spawns', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper({ tool_name: 'Bash', tool_input: { description: 'no command field' } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('transport-shield on a Bash envelope with a command spawns {tool, command, platform}', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(BASH_CMD, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stubArgv()).toEqual(['gate', 'check', '--event', 'transport-shield', '--payload', '-']);
+        expect(spawnedPayload()).toEqual({
+            tool: 'Bash',
+            command: 'git status',
+            platform: process.platform,
+        });
+    });
+    it('a Bash command past the win32 command-line limit still reaches the gate on stdin (P3-F6)', () => {
+        // 40,000 characters: past win32's 32,767-character argv cap, where an argv
+        // payload failed the spawn with ENAMETOOLONG and fell into the fail-closed
+        // arm with nothing broken. On stdin the verdict comes back and maps to exit 0.
+        // Discriminates the fold on the windows-latest CI leg only: linux (128 KB per
+        // argument) and darwin admit a 40 KB argv, so there the pre-fold wrapper also
+        // exits 0; the stdin record assertion below is what holds on every platform.
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        /** One command-line past win32's 32,767-character cap (CreateProcess), where argv transport fails. */
+        const PAST_WIN32_ARGV_CAP = 40_000;
+        const long = 'x'.repeat(PAST_WIN32_ARGV_CAP);
+        const { status, stderr } = runWrapper({ tool_name: 'Bash', tool_input: { command: long } }, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(stderr).not.toContain('fail-closed');
+        expect(spawnedPayload()).toEqual({ tool: 'Bash', command: long, platform: process.platform });
+    });
+    it('transport-shield on a PowerShell envelope spawns the same shape with tool PowerShell', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(PWSH_CMD, [], 'transport-shield');
+        expect(status).toBe(0);
+        expect(spawnedPayload()).toEqual({
+            tool: 'PowerShell',
+            command: 'Get-ChildItem',
+            platform: process.platform,
+        });
+    });
+    it('freeze-check is UNCHANGED: no subsystem → exit 0 without spawning', () => {
+        writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+        const { status } = runWrapper(EDIT_NO_SUBSYSTEM);
+        expect(status).toBe(0);
+        expect(stubArgv()).toBeNull();
+    });
+    it('freeze-check is UNCHANGED: a declared subsystem spawns the {subsystem} payload', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(DECLARED);
+        expect(status).toBe(0);
+        expect(stubArgv()).toEqual(['gate', 'check', '--event', 'freeze-check', '--payload', '-']);
+        expect(spawnedPayload()).toEqual({ subsystem: 'rule-compilation' });
+    });
+    it('an --event the wrapper cannot project → exit 2 fail-closed, never spawns', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status, stderr } = runWrapper(BASH_CMD, [], 'nope');
+        expect(status).toBe(2);
+        expect(stderr).toContain('no payload projection for event "nope"; failing closed.');
+        expect(stubArgv()).toBeNull();
+    });
+    it('an unprojectable --event fails closed even under --pilot (tier maps dispositions only)', () => {
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        const { status } = runWrapper(BASH_CMD, ['--pilot'], 'nope');
+        expect(status).toBe(2);
+        expect(stubArgv()).toBeNull();
+    });
+});
+// ─── The PATH fallback arm (mmnto-ai/totem#2822) ───────────────────────
+//
+// A `Bash|PowerShell`-matched gate applies to `pnpm install` / `pnpm build` —
+// the very commands that CREATE the repo-local CLI — so a repo-local-ONLY
+// resolution made the gate block its own bootstrap on a fresh clone, and block
+// the cure its message named (`totem eject`, a Bash command). The wrapper now
+// falls back to a `totem` on PATH (repo-local still FIRST) and fails closed
+// only when NEITHER arm resolves — the #2799 ruling is kept, the self-block is
+// not. Each test below drives the rendered wrapper with a CONTROLLED PATH and
+// discriminates the fold: pre-fix, the first two exited through the no-CLI arm
+// (there was no PATH probe at all) and the third's message named `totem eject`.
+describe('gate-wrapper.cjs PATH fallback (mmnto-ai/totem#2822)', () => {
+    let cwd;
+    let pathDir;
+    /** The self-block case: a bootstrap command under the shell-matched gate. */
+    const BOOTSTRAP = { tool_name: 'Bash', tool_input: { command: 'pnpm install' } };
+    const ALLOW = { disposition: 'allow', reason: 'ok', provenance: {} };
+    beforeEach(() => {
+        cwd = makeTmpDir();
+        fs.mkdirSync(path.join(cwd, '.claude', 'hooks'), { recursive: true });
+        fs.writeFileSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'), CLAUDE_GATE_WRAPPER);
+        // A PATH entry shaped like an npm global prefix on win32: the `totem.cmd`
+        // shim's sibling `node_modules/@mmnto/cli/dist/index.js`. Deliberately NOT
+        // under `cwd/node_modules`, so the repo-local arm cannot resolve it.
+        pathDir = path.join(cwd, 'global-bin');
+        fs.mkdirSync(pathDir, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    });
+    /**
+     * A CLI stub at `<dir>/node_modules/@mmnto/cli/dist/index.js` emitting the
+     * given verdict and exit code; returns the entry path the wrapper should
+     * resolve. It drains stdin (the `--payload -` channel) before exiting so the
+     * parent's `input` write never races an EPIPE into `result.error`.
+     */
+    function writeCliUnder(dir, opts) {
+        const distDir = path.join(dir, 'node_modules', '@mmnto', 'cli', 'dist');
+        fs.mkdirSync(distDir, { recursive: true });
+        const out = opts.verdict === undefined ? '' : JSON.stringify(opts.verdict);
+        const stub = [
+            '"use strict";',
+            'const fs = require("fs");',
+            `const out = ${JSON.stringify(out)};`,
+            'try { fs.readFileSync(0, "utf-8"); } catch { /* no stdin */ }',
+            'if (out) process.stdout.write(out + "\\n");',
+            `process.exit(${opts.exit ?? 0});`,
+            '',
+        ].join('\n');
+        const entry = path.join(distDir, 'index.js');
+        fs.writeFileSync(entry, stub);
+        return entry;
+    }
+    /** Run the rendered wrapper in `cwd` with an exact PATH value. */
+    function runWithPath(envelope, pathValue, event = 'transport-shield') {
+        const wrapperPath = path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs');
+        const res = spawnSync(process.execPath, [wrapperPath, '--event', event, '--strict'], {
+            cwd,
+            input: JSON.stringify(envelope),
+            encoding: 'utf-8',
+            timeout: 30000,
+            env: envWithPath(pathValue),
+        });
+        return { status: res.status, stderr: res.stderr ?? '' };
+    }
+    it('no repo-local CLI but a totem on PATH → the PATH arm evaluates (allow → exit 0)', () => {
+        writeCliUnder(pathDir, { verdict: ALLOW, exit: 0 });
+        const { status } = runWithPath(BOOTSTRAP, pathDir);
+        // Pre-fix this was exit 2: the wrapper never probed PATH, so a fresh clone's
+        // `pnpm install` was blocked by the gate it was about to install the CLI for.
+        expect(status).toBe(0);
+    });
+    it('the PATH CLI failing → exit 2 fail-closed, disclosing which CLI evaluated (basenames only)', () => {
+        // A CLI older than 2.2.0 has no `gate check --payload -` and lands exactly
+        // here (unknown option → non-zero exit). Fail-closed is UNCHANGED; the
+        // added line names the arm so the operator knows what to update.
+        const entry = writeCliUnder(pathDir, { exit: 1 });
+        const { status, stderr } = runWithPath(BOOTSTRAP, pathDir);
+        expect(status).toBe(2);
+        expect(stderr).toMatch(/fail-closed/i);
+        expect(stderr).toContain('evaluated by the PATH CLI at');
+        // The rendering is NON-resolvable: the PATH entry's basename plus the fixed
+        // package suffix. Hook stderr lands in transcripts that get pasted into
+        // issues, so a user-profile path must never ride along.
+        expect(stderr).toContain('evaluated by the PATH CLI at global-bin/node_modules/@mmnto/cli/dist/index.js');
+        expect(stderr).not.toContain(entry);
+        expect(stderr).not.toContain(cwd);
+    });
+    it('no CLI anywhere → exit 2 naming exits this gate does NOT block', () => {
+        const { status, stderr } = runWithPath(BOOTSTRAP, '');
+        expect(status).toBe(2);
+        expect(stderr).toMatch(/failing closed/i);
+        expect(stderr).toContain('terminal OUTSIDE the harness');
+        expect(stderr).toContain('.claude/settings.json');
+        // The cure must not be a command this very gate blocks (the pre-fix message
+        // said "Reinstall totem or run `totem eject`" — both Bash).
+        expect(stderr).not.toContain('totem eject');
+    });
+    it('the repo-local CLI still wins when both resolve (pinned beats ambient)', () => {
+        // ADR-072 §2 / Tenet 14: the PATH arm is a FALLBACK, never a preference.
+        // The PATH stub would fail closed if the cascade ever inverted.
+        writeCliUnder(cwd, { verdict: ALLOW, exit: 0 });
+        writeCliUnder(pathDir, { exit: 1 });
+        const { status, stderr } = runWithPath(BOOTSTRAP, pathDir);
+        expect(status).toBe(0);
+        expect(stderr).not.toContain('PATH CLI');
+    });
+});
+// ─── Install-time disclosure of the shell-matcher property (#2822) ─────
+describe('gate install discloses a Bash-matched gate applies to bootstrap', () => {
+    let cwd;
+    let originalCwd;
+    let lines;
+    let errorSpy;
+    beforeEach(() => {
+        cwd = makeTmpDir();
+        originalCwd = process.cwd();
+        process.chdir(cwd);
+        lines = [];
+        // `log.*` writes through console.error (ui.ts); capture the rendered lines.
+        // Restored per-test rather than via restoreAllMocks, which would also clear
+        // the module-level install-hooks seam this file mocks.
+        errorSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+            lines.push(args.map((a) => String(a)).join(' '));
+        });
+    });
+    afterEach(() => {
+        errorSpy.mockRestore();
+        process.chdir(originalCwd);
+        fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    });
+    it('prints the line for a Bash|PowerShell gate and NOT for a Write|Edit gate', async () => {
+        await gateInstallCommand({ name: 'transport-shield' });
+        const shield = lines.join('\n');
+        expect(shield).toContain('transport-shield matches Bash|PowerShell:');
+        expect(shield).toContain("fresh clone's bootstrap commands (your package manager's install and build; here pnpm install and pnpm build)");
+        expect(shield).toContain('bootstrap a fresh clone from a terminal outside the harness');
+        lines = [];
+        await gateInstallCommand({ name: 'freeze-check' });
+        const freeze = lines.join('\n');
+        // It DID install (the control), and said nothing about bootstrap: the
+        // property is the shell matcher's, not every gate's.
+        expect(freeze).toContain('freeze-check');
+        expect(freeze).not.toContain('bootstrap');
+        expect(freeze).not.toContain('matches Bash|PowerShell');
+        // A third install in the SAME cwd: transport-shield is already present, so
+        // the merge is a no-op — and the disclosure still prints beside it. The
+        // property belongs to the installed gate, not to the write that installed
+        // it, and a re-install is where an operator most often reads the output.
+        lines = [];
+        await gateInstallCommand({ name: 'transport-shield' });
+        const again = lines.join('\n');
+        expect(again).toContain('already present — no change');
+        expect(again).toContain('transport-shield matches Bash|PowerShell:');
+        expect(again).toContain('bootstrap a fresh clone from a terminal outside the harness');
+    });
 });
 // ─── eject parity ──────────────────────────────────────────────────────
 describe('eject removes the gate entry (parity with install)', () => {
@@ -433,7 +858,7 @@ describe('eject removes the gate entry (parity with install)', () => {
         fs.rmSync(cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     });
     it('scrubs the gate PreToolUse entry and the wrapper script on eject', async () => {
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
         await ejectCommand({ force: true });
@@ -449,7 +874,7 @@ describe('eject removes the gate entry (parity with install)', () => {
         fs.writeFileSync(path.join(cwd, '.claude', 'settings.json'), JSON.stringify({
             hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'mine' }] }] },
         }));
-        installGates(cwd, ['freeze-check']);
+        installGates(cwd, [FREEZE_CHECK]);
         await ejectCommand({ force: true });
         expect(fs.existsSync(path.join(cwd, '.claude', 'settings.json'))).toBe(true);
         const entries = preToolUseEntries(cwd);
@@ -475,12 +900,45 @@ describe('init --gates= routes through the shared installer', () => {
         expect(gateEntryCount(cwd, 'freeze-check')).toBe(1);
         expect(fs.existsSync(path.join(cwd, '.claude', 'hooks', 'gate-wrapper.cjs'))).toBe(true);
     });
-    it('init --gates=all installs every known gate', async () => {
+    it('init --gates=all installs every known gate under ITS registry matcher', async () => {
         await initCommand({ bare: true, gates: 'all' });
-        for (const event of knownGateEvents()) {
+        for (const { event, matcher } of knownGates()) {
             expect(gateEntryCount(cwd, event)).toBe(1);
+            expect(matchersFor(cwd, event)).toEqual([matcher]);
         }
     });
+    it('init --gates=transport-shield installs it under Bash|PowerShell (the pair, not a default)', async () => {
+        await initCommand({ bare: true, gates: 'transport-shield' });
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(matchersFor(cwd, 'transport-shield')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'transport-shield')).toBe('node .claude/hooks/gate-wrapper.cjs --event transport-shield --strict');
+    });
+    it('init --gates= discloses the bootstrap property for a Bash-matched gate, not for Write|Edit', async () => {
+        // The verb and init share `installGates` but NOT their output: init prints
+        // its own summary rows, so before mmnto-ai/totem#2822's shared helper the
+        // disclosure existed only on the verb and `--gates=` dropped it silently.
+        const shieldLines = [];
+        const shieldSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+            shieldLines.push(args.map((a) => String(a)).join(' '));
+        });
+        await initCommand({ bare: true, gates: 'transport-shield' });
+        shieldSpy.mockRestore();
+        const shield = shieldLines.join('\n');
+        expect(shield).toContain('transport-shield matches Bash|PowerShell:');
+        expect(shield).toContain('bootstrap a fresh clone from a terminal outside the harness');
+        const freezeLines = [];
+        const freezeSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+            freezeLines.push(args.map((a) => String(a)).join(' '));
+        });
+        await initCommand({ bare: true, gates: 'freeze-check' });
+        freezeSpy.mockRestore();
+        const freeze = freezeLines.join('\n');
+        // The control: freeze-check installs (a row names it) and says nothing
+        // about bootstrap — the property is the shell matcher's, not every gate's.
+        expect(freeze).toContain('freeze-check');
+        expect(freeze).not.toContain('bootstrap');
+        expect(freeze).not.toContain('matches Bash|PowerShell');
+    });
     it('init --gates= with an unknown member fails loud', async () => {
         await expect(initCommand({ bare: true, gates: 'made-up-gate' })).rejects.toThrow(/unknown gate/i);
     });