@mmnto/cli 2.2.0 → 2.3.0

package/dist/commands/gate-install.test.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);
@@ -71,6 +91,7 @@ const TRANSPORT_SHIELD = {
     event: 'transport-shield',
     matcher: 'Bash|PowerShell',
 };
+const MERGE_READY = { event: 'merge-ready', 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
@@ -217,6 +238,15 @@ describe('installGates per-gate matcher (mmnto-ai/totem#2799)', () => {
             },
         ],
     };
+    const STRICT_MERGE_READY_ENTRY = {
+        matcher: 'Bash|PowerShell',
+        hooks: [
+            {
+                type: 'command',
+                command: 'node .claude/hooks/gate-wrapper.cjs --event merge-ready --strict',
+            },
+        ],
+    };
     beforeEach(() => {
         cwd = makeTmpDir();
         originalCwd = process.cwd();
@@ -266,6 +296,27 @@ describe('installGates per-gate matcher (mmnto-ai/totem#2799)', () => {
         expect(cmd).toContain('--strict');
         expect(cmd).not.toContain('--pilot');
     });
+    it('merge-ready writes ONE entry under Bash|PowerShell, beside transport-shield (mmnto-ai/totem#2800)', () => {
+        installGates(cwd, [MERGE_READY]);
+        expect(gateEntryCount(cwd, 'merge-ready')).toBe(1);
+        expect(matchersFor(cwd, 'merge-ready')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'merge-ready')).toBe('node .claude/hooks/gate-wrapper.cjs --event merge-ready --strict');
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_MERGE_READY_ENTRY]);
+        // A second Bash|PowerShell gate is its OWN entry, never folded into the
+        // first (each gate's --event is its identity).
+        installGates(cwd, [TRANSPORT_SHIELD]);
+        expect(gateEntryCount(cwd, 'merge-ready')).toBe(1);
+        expect(gateEntryCount(cwd, 'transport-shield')).toBe(1);
+        expect(preToolUseEntries(cwd)).toEqual([STRICT_MERGE_READY_ENTRY, STRICT_TRANSPORT_ENTRY]);
+    });
+    it('a merge-ready tier switch updates the one entry in place', () => {
+        installGates(cwd, [MERGE_READY], 'pilot');
+        expect(gateCommandFor(cwd, 'merge-ready')).toContain('--pilot');
+        const switched = installGates(cwd, [MERGE_READY], 'strict');
+        expect(switched.find((r) => r.event === 'merge-ready')?.action).toBe('updated');
+        expect(gateEntryCount(cwd, 'merge-ready')).toBe(1);
+        expect(gateCommandFor(cwd, 'merge-ready')).toBe('node .claude/hooks/gate-wrapper.cjs --event merge-ready --strict');
+    });
     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.
@@ -407,8 +458,19 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
     function writeStubCli(opts) {
         const distDir = path.join(cwd, 'node_modules', '@mmnto', 'cli', 'dist');
         fs.mkdirSync(distDir, { recursive: true });
+        // A fresh stub starts with NO record: the record is written only by a
+        // spawn, so `stubArgv() === null` after a run means "never spawned" and a
+        // `spawnedPayload()` after a run names THAT run's payload. Without this
+        // reset a loop of firing shapes that all name the same PR passed on the
+        // record left by its FIRST iteration — the PR-round-2 leg proved every
+        // later row green against the pre-fold wrapper (F2).
+        fs.rmSync(stubRecordPath(), { force: true });
         const verdictJson = opts.verdict === undefined ? '' : JSON.stringify(opts.verdict);
         const exitCode = opts.exit ?? 0;
+        // `stderr` stands in for the ENGINE's own agent-facing lines (merge-ready's
+        // override audit, its zero-checks fact): the wrapper must pass them through
+        // in every arm, allow included (mmnto-ai/totem#2800 fold F1).
+        const stderrText = opts.stderr ?? '';
         // CommonJS stub (the wrapper invokes via `node <path>`); .js is fine here
         // 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
@@ -422,6 +484,8 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
             'let stdin = "";',
             'try { stdin = fs.readFileSync(0, "utf-8"); } catch { stdin = ""; }',
             `fs.writeFileSync(${JSON.stringify(stubRecordPath())}, JSON.stringify({ argv: process.argv.slice(2), stdin }));`,
+            `const err = ${JSON.stringify(stderrText)};`,
+            'if (err) process.stderr.write(err + "\\n");',
             'if (out) process.stdout.write(out + "\\n");',
             `process.exit(${exitCode});`,
             '',
@@ -451,14 +515,20 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         expect(record.argv[at + 1]).toBe('-');
         return JSON.parse(record.stdin);
     }
-    /** Run the rendered wrapper with the given envelope + baked extra args. */
-    function runWrapper(envelope, extraArgs = [], event = 'freeze-check') {
+    /**
+     * 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', event, ...extraArgs], {
             cwd,
             input: JSON.stringify(envelope),
             encoding: 'utf-8',
             timeout: 30000,
+            ...(env ? { env } : {}),
         });
         return { status: res.status, stderr: res.stderr ?? '' };
     }
@@ -526,14 +596,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
@@ -597,6 +670,11 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
         const { status } = runWrapper(BASH_CMD, [], 'transport-shield');
         expect(status).toBe(0);
+        // The baked tier rides along since mmnto-ai/totem#2800 (R1): the engine owns
+        // the strict/pilot split for a gate's own unevaluable class.
+        // A STRICT wrapper forwards NO `--tier` (fold F3): strict is the engine's
+        // default, and an option a 2.2.x CLI cannot parse would fail the check
+        // closed — re-entering the mmnto-ai/totem#2822 bootstrap self-block.
         expect(stubArgv()).toEqual(['gate', 'check', '--event', 'transport-shield', '--payload', '-']);
         expect(spawnedPayload()).toEqual({
             tool: 'Bash',
@@ -643,6 +721,51 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         expect(stubArgv()).toEqual(['gate', 'check', '--event', 'freeze-check', '--payload', '-']);
         expect(spawnedPayload()).toEqual({ subsystem: 'rule-compilation' });
     });
+    it('a PILOT install forwards --tier pilot; a strict one forwards none (fold F3)', () => {
+        // The tier the ENGINE needs is the non-default one. Forwarding `--tier` on
+        // every entry made a 2.2.x CLI exit "unknown option" — the fail-closed arm —
+        // for every gated command, so only pilot pays that coupling and its
+        // install-time disclosure names the 2.3.0 floor.
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        runWrapper(DECLARED, ['--pilot']);
+        expect(stubArgv()).toEqual([
+            'gate',
+            'check',
+            '--event',
+            'freeze-check',
+            '--tier',
+            'pilot',
+            '--payload',
+            '-',
+        ]);
+        writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+        runWrapper(DECLARED, ['--strict']);
+        expect(stubArgv()).not.toContain('--tier');
+    });
+    it('the child CLI stderr reaches the transcript on ALLOW, not just on failure (fold F1)', () => {
+        // merge-ready writes its audited-override line and its zero-checks fact to
+        // stderr with an `allow` verdict. Printing the child's stderr only in the
+        // failure arm silently dropped exactly the lines that must never be silent.
+        writeStubCli({
+            verdict: ALLOW_VERDICT,
+            exit: 0,
+            stderr: '[totem merge-ready] OVERRIDE (TOTEM_MERGE_GATE_OVERRIDE=1): allowing repo#1',
+        });
+        const { status, stderr } = runWrapper(DECLARED);
+        expect(status).toBe(0);
+        expect(stderr).toContain('[totem merge-ready] OVERRIDE');
+    });
+    it('a warn verdict carries the child stderr through as well (fold F1)', () => {
+        writeStubCli({
+            verdict: { disposition: 'warn', reason: 'heads up', provenance: {} },
+            exit: 0,
+            stderr: '[totem merge-ready] ZERO status checks — predicate 1 passes as a fact',
+        });
+        const { status, stderr } = runWrapper(DECLARED);
+        expect(status).toBe(0);
+        expect(stderr).toContain('ZERO status checks');
+        expect(stderr).toContain('heads up');
+    });
     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');
@@ -656,6 +779,480 @@ describe('gate-wrapper.cjs disposition → exit code', () => {
         expect(status).toBe(2);
         expect(stubArgv()).toBeNull();
     });
+    // ─── merge-ready projection (mmnto-ai/totem#2800) ──────────────────────
+    //
+    // The gate installs under Bash|PowerShell, so this branch sees EVERY shell
+    // command: the load-bearing half is what it does NOT do — a command that is
+    // not `gh pr merge` at command position must pass through (exit 0) without
+    // ever spawning the CLI. `stubArgv() === null` is the filesystem record of
+    // "never spawned", not an inference from the exit code.
+    describe('merge-ready', () => {
+        /** Give the temp cwd a git identity so the projection can read repo/branch/head. */
+        function initGitRepo() {
+            spawnSync('git', ['init', '-b', 'feat/demo'], { cwd, encoding: 'utf-8' });
+            spawnSync('git', ['remote', 'add', 'origin', 'https://github.com/mmnto-ai/totem.git'], {
+                cwd,
+            });
+            fs.writeFileSync(path.join(cwd, 'file.txt'), 'x');
+            spawnSync('git', ['add', '-A'], { cwd });
+            spawnSync('git', ['-c', 'user.email=t@example.com', '-c', 'user.name=t', 'commit', '-m', 'init'], { cwd });
+            return spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf-8' }).stdout.trim();
+        }
+        const bash = (command) => ({
+            tool_name: 'Bash',
+            tool_input: { command },
+        });
+        it('projects { repo, pr, headSha } from `gh pr merge <number>`', () => {
+            const head = initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            const { status } = runWrapper(bash('gh pr merge 2800 --squash'), [], 'merge-ready');
+            expect(status).toBe(0);
+            // No `--tier` at the default strict tier (fold F3).
+            expect(stubArgv()).toEqual(['gate', 'check', '--event', 'merge-ready', '--payload', '-']);
+            expect(spawnedPayload()).toEqual({ repo: 'mmnto-ai/totem', pr: 2800, headSha: head });
+        });
+        it('projects pr: null + the CURRENT branch when the command names no PR', () => {
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge'), [], 'merge-ready');
+            const payload = spawnedPayload();
+            expect(payload.pr).toBeNull();
+            expect(payload.branch).toBe('feat/demo');
+            expect(payload.repo).toBe('mmnto-ai/totem');
+        });
+        it('reads the repo from -R / --repo= and the PR from a URL, over the git remote', () => {
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge --squash -R mmnto-ai/liquid-city 363'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ repo: 'mmnto-ai/liquid-city', pr: 363 });
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge https://github.com/mmnto-ai/totem-strategy/pull/1251 --merge'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ repo: 'mmnto-ai/totem-strategy', pr: 1251 });
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge 12 --repo=mmnto-ai/other'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ repo: 'mmnto-ai/other', pr: 12 });
+        });
+        it('a named branch is projected as the branch, not as a PR number', () => {
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge feat/other-branch'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: null, branch: 'feat/other-branch' });
+        });
+        it('a value-taking flag does not swallow the PR target (`-b "…" 42`)', () => {
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge -b "merge this now" 42'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 42 });
+        });
+        it("fires at command position after a separator, after the shell's command-position words, and behind an assignment prefix", () => {
+            initGitRepo();
+            for (const command of [
+                'git status && gh pr merge 7',
+                'git fetch; gh pr merge 7',
+                'for x in 1; do gh pr merge 7; done',
+                'if true; then gh pr merge 7; fi',
+                'git log |\ngh pr merge 7',
+                // PR round 1 (greptile): a merge used AS the condition, and one behind
+                // an assignment prefix, each left something other than `gh` at the
+                // segment's front and went unjudged.
+                'if gh pr merge 7; then echo merged; fi',
+                'if false; then :; elif gh pr merge 7; then :; fi',
+                'while gh pr merge 7; do break; done',
+                'until gh pr merge 7; do sleep 1; done',
+                'GH_TOKEN=x gh pr merge 7',
+                'GH_REPO=mmnto-ai/totem GH_TOKEN="a b" gh pr merge 7',
+                'exec gh pr merge 7',
+                'command gh pr merge 7',
+                // Round 2 (the leg's F1): two more reserved words and the builtin that
+                // runs an unquoted operand as the command.
+                'time gh pr merge 7',
+                'coproc gh pr merge 7',
+                'eval gh pr merge 7',
+            ]) {
+                writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+                runWrapper(bash(command), [], 'merge-ready');
+                expect(spawnedPayload(), command).toMatchObject({ pr: 7 });
+            }
+        });
+        it('does NOT fire inside a quoted string, a heredoc body, or on another gh verb — and never spawns', () => {
+            initGitRepo();
+            for (const command of [
+                'echo "gh pr merge 5"',
+                "echo 'gh pr merge 5'",
+                'gh pr list',
+                'gh pr view 3 | grep merge',
+                'git commit -m "gh pr merge"',
+                // A heredoc body is DATA, not commands (fold F4): firing here was a
+                // false deny — the direction this projection must not have.
+                'cat <<EOF\ngh pr merge 5\nEOF',
+                "cat <<'EOF'\ngh pr merge 5\nEOF",
+                'cat <<-EOF\n\tgh pr merge 5\n\tEOF',
+                'cat <<EOF > notes.txt\ngh pr merge 5\nEOF\necho done',
+                // An UNTERMINATED body runs to the end of the command and is still data.
+                'cat <<EOF\ngh pr merge 5',
+                // DISCLOSED misses (the gate does not fire — the safe direction): a
+                // wrapper PROGRAM takes the first token, so the position anchor never
+                // sees `gh` (an assignment prefix no longer hides it — PR round 1).
+                'sudo gh pr merge 5',
+                'timeout 30 gh pr merge 5',
+                'env GH_TOKEN=x gh pr merge 5',
+                // Round 2 (the leg's F1/F3), disclosed in the template's comment: a
+                // merge handed over as ONE quoted word, a builtin with a flag before
+                // `gh`, a backtick substitution, a leading redirection.
+                'eval "gh pr merge 5"',
+                'command -p gh pr merge 5',
+                'exec -a x gh pr merge 5',
+                // Round 3 (the leg's F1): the reserved word carrying its own flag.
+                'time -p gh pr merge 5',
+                'time -- gh pr merge 5',
+                'echo `gh pr merge 5`',
+                '> out.txt gh pr merge 5',
+            ]) {
+                writeStubCli({
+                    verdict: { disposition: 'deny', reason: 'should not run', provenance: {} },
+                });
+                const { status } = runWrapper(bash(command), [], 'merge-ready');
+                expect(status, command).toBe(0);
+                expect(stubArgv(), command).toBeNull();
+            }
+        });
+        it('every gh pr merge at command position is judged, not only the first (PR round 1, greptile)', () => {
+            initGitRepo();
+            // The stub overwrites its record on every spawn, so the record names the
+            // LAST payload judged. An allowing stub: the second merge is reached.
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            const allowed = runWrapper(bash('gh pr merge 7; gh pr merge 8'), [], 'merge-ready');
+            expect(allowed.status).toBe(0);
+            expect(spawnedPayload()).toMatchObject({ pr: 8 });
+            // A denying stub under strict: the FIRST deny exits 2, so the second
+            // merge is never spawned and the record still names the first.
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'not ready', provenance: {} } });
+            const denied = runWrapper(bash('gh pr merge 7 && gh pr merge 8'), [], 'merge-ready');
+            expect(denied.status).toBe(2);
+            expect(spawnedPayload()).toMatchObject({ pr: 7 });
+            expect(denied.stderr.match(/merge-ready \(deny\)/g)).toHaveLength(1);
+            // Under --pilot a deny prints and the NEXT merge is still judged: two
+            // deny lines, the record names the second merge, exit 0.
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'not ready', provenance: {} } });
+            const pilot = runWrapper(bash('gh pr merge 7; gh pr merge 8'), ['--pilot'], 'merge-ready');
+            expect(pilot.status).toBe(0);
+            expect(spawnedPayload()).toMatchObject({ pr: 8 });
+            expect(pilot.stderr.match(/merge-ready \(deny\)/g)).toHaveLength(2);
+        });
+        it('an arithmetic shift or a comment does not swallow the merge that follows (fold round 2, F1)', () => {
+            // `$((1<<2))` is a SHIFT and `# see <<note` is a comment: neither opens a
+            // heredoc. Before the guards, each swallowed the rest of the command and
+            // the real merge after it went unjudged — a silent miss on the exact
+            // command this gate exists for.
+            initGitRepo();
+            for (const command of [
+                'echo $((1<<2)); gh pr merge 5',
+                'echo $(( 3<<1 )); gh pr merge 5',
+                '# see <<note\ngh pr merge 5',
+                '(( 1<<3 ))\ngh pr merge 5',
+                'echo hi # <<EOF\ngh pr merge 5',
+            ]) {
+                writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+                runWrapper(bash(command), [], 'merge-ready');
+                expect(spawnedPayload(), command).toMatchObject({ pr: 5 });
+            }
+        });
+        it('a line continuation does not hide the anchor (round 3, F6)', () => {
+            // The shell removes a backslash-newline and joins the halves. Absorbing
+            // the newline into the token left the segment starting with something
+            // other than `gh`, so a real merge went unjudged.
+            initGitRepo();
+            for (const command of ['gh \\\npr merge 5', 'gh pr merge \\\n5', 'gh \\\r\npr merge 5']) {
+                writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+                runWrapper(bash(command), [], 'merge-ready');
+                expect(spawnedPayload(), JSON.stringify(command)).toMatchObject({ pr: 5 });
+            }
+            // A backslash before an ORDINARY character keeps its old meaning: it
+            // escapes that character into the token.
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge 5 --body a\\ b'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 5 });
+        });
+        it('a PowerShell block comment is data, not commands (round 3 F8; round 4 F1, F8)', () => {
+            initGitRepo();
+            const pwsh = (command) => ({
+                tool_name: 'PowerShell',
+                tool_input: { command },
+            });
+            // THE CONTROL (round 4, F1): a MULTI-LINE block comment. Without the
+            // `<#` arm this fires with pr 9 — verified by stripping the arm from a
+            // rendered copy. The single-line row below behaves the same either way
+            // (the `#` word-comment arm already covers it), so it is a companion, not
+            // a control.
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+            expect(runWrapper(pwsh('<#\ngh pr merge 9\n#>\necho hi'), [], 'merge-ready').status).toBe(0);
+            expect(stubArgv()).toBeNull();
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+            expect(runWrapper(pwsh('<# gh pr merge 9 #>\necho hi'), [], 'merge-ready').status).toBe(0);
+            expect(stubArgv()).toBeNull();
+            // The merge AFTER one is still judged — the blank must not eat it.
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(pwsh('<# notes #>\ngh pr merge 4'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 4 });
+            // ROUND 4 F8: the blank is a POWERSHELL rule. In bash `<#tmp` is a
+            // redirect from a file named `#tmp`, and blanking from it to a later `#>`
+            // would swallow the real merge on the next line.
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('sort <#tmp\ngh pr merge 8'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 8 });
+        });
+        it('a comment is not a command: a merge inside one never fires', () => {
+            initGitRepo();
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+            const { status } = runWrapper(bash('echo hi # gh pr merge 9'), [], 'merge-ready');
+            expect(status).toBe(0);
+            expect(stubArgv()).toBeNull();
+        });
+        it('EVERY heredoc queued on a line is read as data, not just the first (fold round 2, F2)', () => {
+            // bash reads `cat <<A <<B` as two bodies in order, so a command sitting
+            // in B's body is data too. Consuming only A's body left B's body as
+            // commands — a false deny on text.
+            initGitRepo();
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+            const { status } = runWrapper(bash('cat <<A <<B\nfirst\nA\ngh pr merge 5\nB\n'), [], 'merge-ready');
+            expect(status).toBe(0);
+            expect(stubArgv()).toBeNull();
+            // The complement: a heredoc as the merge's OWN operand still fires.
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge 5 <<EOF\nnotes\nEOF\n'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 5 });
+        });
+        it('still fires on a real merge that FOLLOWS a heredoc (the blanker keeps the segments)', () => {
+            // The heredoc blanker must not swallow the rest of the command: the
+            // terminator line ends the body and the next segment is judged normally.
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('cat <<EOF > body.md\nsome release notes\nEOF\ngh pr merge 21'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 21 });
+        });
+        it('an unexpanded shell variable rides as unresolvedTarget, not as a branch (fold F13)', () => {
+            // `gh pr merge $PR` names a target the hook cannot know — the shell
+            // expands it after the gate has already decided. Reading "$PR" as a
+            // branch would judge the wrong PR, or none.
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge $PR --squash'), [], 'merge-ready');
+            const payload = spawnedPayload();
+            expect(payload.unresolvedTarget).toBe('$PR');
+            expect(payload.pr).toBeNull();
+            // NOT the current-branch fallback: that is for a command naming no target.
+            expect(payload.branch).toBeUndefined();
+        });
+        it('a braced expansion keeps its braces in the evidence (round 2, F10)', () => {
+            // `${PR}` used to reach the engine as bare "$", because the tokenizer
+            // split on the braces. A `$( … )` deliberately still splits — a real
+            // merge inside a command substitution must keep firing.
+            initGitRepo();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('gh pr merge ${PR}'), [], 'merge-ready');
+            expect(spawnedPayload().unresolvedTarget).toBe('${PR}');
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper(bash('echo $(gh pr merge 8)'), [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 8 });
+        });
+        it('a Write envelope and a PowerShell command are treated by tool, not by text', () => {
+            initGitRepo();
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'should not run', provenance: {} } });
+            const write = runWrapper({ tool_name: 'Write', tool_input: { file_path: 'notes.md' } }, [], 'merge-ready');
+            expect(write.status).toBe(0);
+            expect(stubArgv()).toBeNull();
+            writeStubCli({ verdict: ALLOW_VERDICT, exit: 0 });
+            runWrapper({ tool_name: 'PowerShell', tool_input: { command: 'gh pr merge 11' } }, [], 'merge-ready');
+            expect(spawnedPayload()).toMatchObject({ pr: 11 });
+        });
+        it('an evaluation failure on an APPLICABLE merge blocks (fail-closed), pilot exits 0', () => {
+            initGitRepo();
+            writeStubCli({ exit: 1 });
+            const strict = runWrapper(bash('gh pr merge 2800'), [], 'merge-ready');
+            expect(strict.status).toBe(2);
+            expect(strict.stderr).toMatch(/fail-closed/i);
+            writeStubCli({ verdict: { disposition: 'deny', reason: 'behind', provenance: {} }, exit: 0 });
+            const pilot = runWrapper(bash('gh pr merge 2800'), ['--pilot'], 'merge-ready');
+            expect(pilot.status).toBe(0);
+            expect(pilot.stderr).toContain('behind');
+        });
+    });
+});
+// ─── 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');
+    });
+    // ─── Pilot-tier CLI floor (mmnto-ai/totem#2800 fold F3) ───────────────
+    it('a --pilot install names the CLI floor its wrapper needs; a strict one does not', async () => {
+        await gateInstallCommand({ name: 'merge-ready', pilot: true });
+        const pilot = lines.join('\n');
+        expect(pilot).toContain('gate check --tier pilot');
+        expect(pilot).toContain('2.3.0');
+        lines = [];
+        await gateInstallCommand({ name: 'freeze-check' });
+        const strict = lines.join('\n');
+        // A strict install forwards no tier, so it carries no floor to disclose.
+        expect(strict).not.toContain('2.3.0');
+        expect(strict).not.toContain('--tier');
+    });
+    it('init --gates= discloses the same pilot floor (it prints its own rows)', async () => {
+        await initCommand({ bare: true, gates: 'merge-ready', pilot: true });
+        const out = lines.join('\n');
+        expect(out).toContain('gate check --tier pilot');
+        expect(out).toContain('2.3.0');
+    });
 });
 // ─── eject parity ──────────────────────────────────────────────────────
 describe('eject removes the gate entry (parity with install)', () => {
@@ -727,6 +1324,38 @@ describe('init --gates= routes through the shared installer', () => {
         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=merge-ready installs it under Bash|PowerShell (mmnto-ai/totem#2800)', async () => {
+        await initCommand({ bare: true, gates: 'merge-ready' });
+        expect(gateEntryCount(cwd, 'merge-ready')).toBe(1);
+        expect(matchersFor(cwd, 'merge-ready')).toEqual(['Bash|PowerShell']);
+        expect(gateCommandFor(cwd, 'merge-ready')).toBe('node .claude/hooks/gate-wrapper.cjs --event merge-ready --strict');
+    });
     it('init --gates= with an unknown member fails loud', async () => {
         await expect(initCommand({ bare: true, gates: 'made-up-gate' })).rejects.toThrow(/unknown gate/i);
     });