@mmnto/cli 1.121.0 → 1.123.0

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

@@ -1,10 +1,14 @@
-import { execSync, spawnSync } from 'node:child_process';
+import { execFileSync, execSync, spawnSync } from 'node:child_process';
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { GROUNDING_ANCHOR_FREE_TEXT, GROUNDING_ANCHOR_ISSUE, GROUNDING_ANCHOR_MIXED, GROUNDING_ANCHOR_RECORD, PROMPT_SOURCE_BUILTIN, PROMPT_SOURCE_OVERRIDE, RUN_ARTIFACT_SCHEMA_VERSION, RunArtifactSchema, } from '@mmnto/totem';
 import { cleanTmpDir } from '../test-utils.js';
 import { buildHookContent, buildPostCheckoutHookContent, buildPreCommitHook, buildPrePushHook, buildResolveBlock, checkHooksInstalled, detectTotemPrefix, generateHookHelpers, getFallbackCommand, installGitHook, installHooksNonInteractive, TOTEM_HOOK_END, TOTEM_HOOK_MARKER, TOTEM_PRECOMMIT_END, TOTEM_PRECOMMIT_MARKER, TOTEM_PREPUSH_END, TOTEM_PREPUSH_MARKER, upgradePrePushHookIfNeeded, } from './install-hooks.js';
+import { SPEC_REQUIRED_SECTIONS } from './spec-templates.js';
 // The default render options every pre-#2692 positional call implied
 // (mmnto-ai/totem#2692 C2 — the builders take a REQUIRED options object now, so
 // each site states the tier/totemDir/fallbackCmd it always assumed). Spread and
@@ -14,6 +18,84 @@ const RENDER = {
     totemDir: '.totem',
     fallbackCmd: 'pnpm dlx @mmnto/cli',
 };
+// ─── Anchored-evidence fixtures (mmnto-ai/totem#2700) ───
+//
+// Since #2700 an artifact is evidence only when it is ANCHORED and its SUBJECT
+// carries a shape. These build the smallest artifact that satisfies each arm,
+// so a test that means to exercise something else (age, newest-wins, torn
+// files) does not accidentally exercise the shape check.
+/** A draft that satisfies the TEMPLATE shape: every required heading with a body. */
+const TEMPLATE_DRAFT = SPEC_REQUIRED_SECTIONS.map((heading) => `${heading}\n\nA non-blank body under ${heading}.\n`).join('\n');
+/** A draft that satisfies only the looser DOCUMENT shape — one heading with a body. */
+const DOCUMENT_DRAFT = '## A hand-shaped section\n\nA body under it.\n';
+/** The minimal ISSUE-anchored, template-shaped run artifact the gate accepts. */
+function specEvidenceArtifact(overrides = {}) {
+    return {
+        admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_BUILTIN } },
+        grounding: { anchor: { kind: GROUNDING_ANCHOR_ISSUE, ref: '#2700' } },
+        output: { content: TEMPLATE_DRAFT },
+        createdAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+/**
+ * The fixture wrapped in the fields every run artifact must carry and the
+ * reader never touches — so the whole thing can be parsed by the REAL schema.
+ */
+function asRunArtifact(fixture) {
+    const grounding = fixture['grounding'];
+    const output = fixture['output'];
+    return {
+        ...fixture,
+        schemaVersion: RUN_ARTIFACT_SCHEMA_VERSION,
+        inputBundle: { maskedPrompt: 'the masked prompt' },
+        inputHash: 'a'.repeat(64),
+        grounding: { hash: 'b'.repeat(64), provenanceSummary: 'similarity-only:1', ...grounding },
+        backend: {
+            provider: 'gemini',
+            model: 'gemini-3-flash-preview',
+            qualifiedModel: 'gemini:gemini-3-flash-preview',
+            admissionClass: 'completion_only',
+            taskProfile: 'Spec',
+        },
+        output: { metrics: { durationMs: 500 }, ...output },
+    };
+}
+// The hook's reader is a rendered `node -e` string: it walks the artifact by
+// HAND-SPELLED paths (`grounding.anchor`, `admission.runMetadata.promptSource`,
+// `output.content`) that no type checker sees. These tests bind the PASS
+// fixtures those paths are exercised against to the real core schema, so a
+// rename or a shape change on the writer's side breaks a test here rather than
+// silently leaving the hook reading a field that no longer exists.
+describe('the anchored-evidence fixtures parse as real run artifacts (mmnto-ai/totem#2700)', () => {
+    it('the issue-anchored PASS fixture round-trips through RunArtifactSchema with its three read paths intact', () => {
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact()));
+        expect(parsed.grounding.anchor).toEqual({ kind: GROUNDING_ANCHOR_ISSUE, ref: '#2700' });
+        expect(parsed.admission?.runMetadata?.promptSource).toBe(PROMPT_SOURCE_BUILTIN);
+        expect(parsed.output.content).toBe(TEMPLATE_DRAFT);
+    });
+    it('the record-anchored PASS fixture round-trips, sha256 and all', () => {
+        const sha256 = 'a'.repeat(64);
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact({
+            grounding: {
+                anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/2700.md', sha256 },
+            },
+        })));
+        expect(parsed.grounding.anchor).toEqual({
+            kind: GROUNDING_ANCHOR_RECORD,
+            ref: '.totem/specs/2700.md',
+            sha256,
+        });
+    });
+    it('the override-prompt PASS fixture round-trips with promptSource "override"', () => {
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact({
+            admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE } },
+            output: { content: DOCUMENT_DRAFT },
+        })));
+        expect(parsed.admission?.runMetadata?.promptSource).toBe(PROMPT_SOURCE_OVERRIDE);
+        expect(parsed.output.content).toBe(DOCUMENT_DRAFT);
+    });
+});
 describe('detectTotemPrefix', () => {
     let tmpDir;
     beforeEach(() => {
@@ -1315,6 +1397,30 @@ describe('buildPreCommitHook with strict tier', () => {
         expect(hook).toContain('spec evidence:');
         expect(hook).not.toContain('(legacy marker)');
     });
+    // mmnto-ai/totem#2700 — the reader's vocabulary is RENDERED from the one
+    // canonical constant, never re-spelled in the hook text, so a change to the
+    // writer's spelling can never leave the gate reading a stale word.
+    it('renders SPEC_REQUIRED_SECTIONS and the anchor vocabulary as JSON literals', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        expect(hook).toContain(`const REQUIRED = ${JSON.stringify(SPEC_REQUIRED_SECTIONS)};`);
+        expect(hook).toContain(`const KIND_ISSUE = ${JSON.stringify(GROUNDING_ANCHOR_ISSUE)};`);
+        expect(hook).toContain(`const KIND_RECORD = ${JSON.stringify(GROUNDING_ANCHOR_RECORD)};`);
+        expect(hook).toContain(`const PROMPT_OVERRIDE = ${JSON.stringify(PROMPT_SOURCE_OVERRIDE)};`);
+    });
+    it('carries the exit-3 arm distinctly from the exit-2 and reader-failure arms', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        expect(hook).toContain('elif [ "$reader_status" = "3" ]; then');
+        expect(hook).toContain(`echo "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"`);
+        // The two pre-existing arms keep their exact text.
+        expect(hook).toContain('no totem spec run artifact under .totem/artifacts/runs/');
+        expect(hook).toContain('the spec-evidence reader could not run (node exit status');
+    });
+    it('the reader body carries no single quote (it lives inside a single-quoted node -e word)', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        const reader = hook.split("node -e '")[1]?.split("\n' 2>/dev/null)")[0] ?? '';
+        expect(reader.length).toBeGreaterThan(0);
+        expect(reader).not.toContain("'");
+    });
 });
 // The strict block EXECUTED under sh (mmnto-ai/totem#2690): the string checks
 // above pin the text; these pin the behavior the gate exists for. `git init` +
@@ -1382,10 +1488,7 @@ describe('buildPreCommitHook strict evidence — executed under sh (mmnto-ai/tot
         expect(r.stdout).toContain('no totem spec run artifact under .totem/artifacts/runs/');
     });
     it.skipIf(!shellOk)('passes on a spec run artifact and prints the evidence line with its age', () => {
-        writeRun('a.json', {
-            admission: { runMetadata: { caller: 'spec' } },
-            createdAt: new Date().toISOString(),
-        });
+        writeRun('a.json', specEvidenceArtifact());
         const r = runHook();
         expect(r.status).toBe(0);
         expect(r.stdout).toContain('[Totem] spec evidence: .totem/artifacts/runs/a.json (');
@@ -1423,10 +1526,7 @@ describe('buildPreCommitHook strict evidence — executed under sh (mmnto-ai/tot
     });
     it.skipIf(!shellOk)('skips a torn (unparseable) artifact and still passes on a valid one beside it', () => {
         writeRun('torn.json', '{"admission": {"runMetadata": {"caller": "spec"');
-        writeRun('ok.json', {
-            admission: { runMetadata: { caller: 'spec' } },
-            createdAt: new Date().toISOString(),
-        });
+        writeRun('ok.json', specEvidenceArtifact());
         const r = runHook();
         expect(r.status).toBe(0);
         expect(r.stdout).toContain('.totem/artifacts/runs/ok.json');
@@ -1437,18 +1537,463 @@ describe('buildPreCommitHook strict evidence — executed under sh (mmnto-ai/tot
         expect(r.status).toBe(1);
     });
     it.skipIf(!shellOk)('names the NEWEST spec artifact by its own createdAt', () => {
-        writeRun('old.json', {
-            admission: { runMetadata: { caller: 'spec' } },
-            createdAt: '2026-01-01T00:00:00.000Z',
+        writeRun('old.json', specEvidenceArtifact({ createdAt: '2026-01-01T00:00:00.000Z' }));
+        writeRun('new.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('.totem/artifacts/runs/new.json');
+        expect(r.stdout).not.toContain('old.json');
+    });
+});
+// The mmnto-ai/totem#2700 arm, EXECUTED: an artifact is evidence only when it
+// is ANCHORED (issue | record) and its SUBJECT carries a shape. Every negation
+// must BLOCK with its OWN named reason — never with the "no artifact" line and
+// never as a reader failure — because the reason is the whole cure.
+describe('buildPreCommitHook anchored evidence — executed under sh (mmnto-ai/totem#2700)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    /**
+     * Whether this platform (and this account) can make a symlink — a Windows
+     * account without SeCreateSymbolicLinkPrivilege cannot. Probed ONCE, outside
+     * any test, so the skip is a real capability check rather than a swallowed
+     * failure inside the assertion.
+     */
+    const symlinkable = (() => {
+        const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-link-probe-'));
+        const target = path.join(probeDir, 'target');
+        fs.writeFileSync(target, 'probe');
+        let ok = false;
+        try {
+            fs.symlinkSync(target, path.join(probeDir, 'sym'));
+            ok = true;
+        }
+        catch (err) {
+            void err;
+            ok = false;
+        }
+        cleanTmpDir(probeDir);
+        return ok;
+    })();
+    let tmpDir;
+    /** A directory OUTSIDE the worktree — the target of the escaping-symlink case. */
+    let outsideDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-anchor-'));
+        outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-outside-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/anchored', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook(RENDER));
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+        cleanTmpDir(outsideDir);
+    });
+    function runHook() {
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
         });
-        writeRun('new.json', {
+        return { status: r.status, stdout: r.stdout };
+    }
+    function writeRun(name, artifact) {
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, name), JSON.stringify(artifact, null, 2));
+    }
+    /** Write a bound record at a repo-relative path and return its sha256. */
+    function writeRecord(relPath, body) {
+        const abs = path.join(tmpDir, ...relPath.split('/'));
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, body, 'utf-8');
+        return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+    }
+    /** Every BLOCKED arm must be distinguishable from the other two arms. */
+    function expectDistinctBlock(stdout) {
+        expect(stdout).not.toContain('no totem spec run artifact');
+        expect(stdout).not.toContain('the spec-evidence reader could not run');
+    }
+    // ── The migration invariant ──
+    it.skipIf(!shellOk)('a PRE-EXISTING artifact (no grounding.anchor) BLOCKS with the `predates` reason, not the no-artifact line', () => {
+        writeRun('legacy.json', {
             admission: { runMetadata: { caller: 'spec' } },
+            output: { content: TEMPLATE_DRAFT },
             createdAt: new Date().toISOString(),
         });
         const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('predates the anchored-evidence rule (no grounding.anchor)');
+        expect(r.stdout).toContain('.totem/artifacts/runs/legacy.json');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The unanchored kinds ──
+    it.skipIf(!shellOk)('a `free-text` anchor BLOCKS, naming the kind and the topic', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'a loose slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is anchored ${GROUNDING_ANCHOR_FREE_TEXT} (a loose slug)`);
+        expect(r.stdout).toContain('not gate evidence');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a `mixed` anchor BLOCKS, naming the kind and the ref', () => {
+        writeRun('mx.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_MIXED, ref: '#2700 | a loose slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is anchored ${GROUNDING_ANCHOR_MIXED} (#2700 | a loose slug)`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('both cures are named on every BLOCKED arm', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.stdout).toContain("run 'totem spec <issue>' or 'totem spec --from <record>'");
+    });
+    // ── The TEMPLATE shape (issue anchor, built-in prompt) ──
+    it.skipIf(!shellOk)('the one-token draft (a lone newline) BLOCKS on the first missing heading', () => {
+        writeRun('thin.json', specEvidenceArtifact({ output: { content: '\n' } }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('is missing heading ### Problem Statement');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('both required headings present over EMPTY bodies BLOCK, naming the empty heading', () => {
+        writeRun('empty.json', specEvidenceArtifact({
+            output: { content: '### Problem Statement\n\n### Implementation Tasks\n' },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has an empty heading ### Problem Statement');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a second required heading left empty BLOCKS, naming THAT heading', () => {
+        writeRun('half.json', specEvidenceArtifact({
+            output: {
+                content: '### Problem Statement\n\nA real body.\n\n### Implementation Tasks\n',
+            },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has an empty heading ### Implementation Tasks');
+    });
+    it.skipIf(!shellOk)('both required headings with bodies PASS, and the evidence line carries the anchor and the shape', () => {
+        writeRun('ok.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('[Totem] spec evidence: .totem/artifacts/runs/ok.json (');
+        expect(r.stdout).toContain(`· anchor ${GROUNDING_ANCHOR_ISSUE} #2700`);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a non-string draft on an issue anchor BLOCKS as not-text', () => {
+        writeRun('nt.json', specEvidenceArtifact({ output: { content: { nested: true } } }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the draft is not text');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The DOCUMENT shape (override prompt on an issue anchor) ──
+    it.skipIf(!shellOk)('an OVERRIDE-prompt draft without the template headings PASSES on one heading with a body', () => {
+        writeRun('ov.json', specEvidenceArtifact({
+            admission: {
+                runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE },
+            },
+            output: { content: DOCUMENT_DRAFT },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    it.skipIf(!shellOk)('an OVERRIDE-prompt draft with no heading at all BLOCKS', () => {
+        writeRun('ovbad.json', specEvidenceArtifact({
+            admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE } },
+            output: { content: 'just prose, no heading\n' },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has no heading with a body');
+        expect(r.stdout).toContain('custom prompt');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The record arm: the SUBJECT is the record's bytes ──
+    function recordArtifact(ref, sha256, draft = TEMPLATE_DRAFT) {
+        return specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_RECORD, ref, sha256 } },
+            output: { content: draft },
+        });
+    }
+    it.skipIf(!shellOk)('a present record with a heading and a body PASSES, reporting `record sha256 matches`', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
         expect(r.status).toBe(0);
-        expect(r.stdout).toContain('.totem/artifacts/runs/new.json');
-        expect(r.stdout).not.toContain('old.json');
+        expect(r.stdout).toContain(`· anchor ${GROUNDING_ANCHOR_RECORD} .totem/specs/2700.md`);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a REVISED record still PASSES — the digest is a SENSOR, never a gate', () => {
+        const bound = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', bound));
+        const now = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract, folded.\n');
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain(`record revised since binding (bound ${bound.slice(0, 8)}, now ${now.slice(0, 8)})`);
+    });
+    it.skipIf(!shellOk)('a MISSING record BLOCKS, naming the path it was bound at', () => {
+        writeRun('rec.json', recordArtifact('.totem/specs/gone.md', 'b'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record is missing at .totem/specs/gone.md');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record with NO heading-with-a-body BLOCKS', () => {
+        const sha = writeRecord('.totem/specs/2700.md', 'prose with no heading\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record at .totem/specs/2700.md has no heading with a body');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record whose heading has no body BLOCKS (a heading alone is not a document)', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Heading only\n\n## Another heading\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has no heading with a body');
+    });
+    it.skipIf(!shellOk)('a THIN draft with a rich record PASSES — the reader never reads output.content on a record anchor', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha, '\n'));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a RICH draft with a missing record BLOCKS — the record is the subject, not the draft', () => {
+        writeRun('rec.json', recordArtifact('.totem/specs/gone.md', 'c'.repeat(64), TEMPLATE_DRAFT));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record is missing at');
+    });
+    // ── The body-line boundary is a HEADING, not a leading "#" ──
+    //
+    // `#2700 is the issue.` is prose about an issue number, not a heading: no
+    // space follows the hashes. Reading it as a boundary made a real body look
+    // empty — the exact sentence a totem design record is most likely to open a
+    // section with.
+    it.skipIf(!shellOk)('a body line starting with `#2700` is a BODY on the TEMPLATE arm', () => {
+        const draft = SPEC_REQUIRED_SECTIONS.map((heading) => `${heading}\n\n#2700 is the issue.\n`).join('\n');
+        writeRun('hashbody.json', specEvidenceArtifact({ output: { content: draft } }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a body line starting with `#2700` is a BODY on the DOCUMENT arm', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\n#2700 is the issue.\n');
+        writeRun('hashrec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    // ── The DOCUMENT shape tolerates two ordinary authoring bytes ──
+    it.skipIf(!shellOk)('a DRAFT opening with a UTF-8 BOM still reads as a template', () => {
+        // The BOM strip runs on the SUBJECT, before the split — so it covers the
+        // TEMPLATE arm too, where an unstripped BOM would make the first required
+        // heading fail its exact-line match and BLOCK a well-formed draft.
+        const bom = String.fromCharCode(0xfeff);
+        writeRun('bomdraft.json', specEvidenceArtifact({ output: { content: bom + TEMPLATE_DRAFT } }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a record opening with a UTF-8 BOM still reads as a document', () => {
+        const bom = String.fromCharCode(0xfeff);
+        const sha = writeRecord('.totem/specs/2700.md', `${bom}# Record\n\nThe ruled contract.\n`);
+        writeRun('bom.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    it.skipIf(!shellOk)('a heading separated from its text by a TAB is a heading', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '#\tTabbed heading\n\nThe body.\n');
+        writeRun('tab.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    // ── The artifact is hand-editable: nothing read out of it is trusted text ──
+    it.skipIf(!shellOk)('a newline in anchor.ref cannot forge a second [Totem] line', () => {
+        const forged = `slug${String.fromCharCode(0x0a)}[Totem] spec evidence: forged`;
+        writeRun('inject.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: forged } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        // Exactly one line of the hook's own output claims to be from Totem.
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        // The control character is collapsed, not dropped — the ref stays legible.
+        expect(r.stdout).toContain('slug?[Totem] spec evidence: forged');
+    });
+    it.skipIf(!shellOk)('a C1 control (U+0085 NEL) in anchor.ref is collapsed too', () => {
+        // A predicate stopping at 0x7f let the whole C1 band through; NEL is a
+        // LINE BREAK to some terminals and pagers, so it is a forged-line vector
+        // of exactly the same kind as 0x0a.
+        const forged = `slug${String.fromCharCode(0x85)}[Totem] spec evidence: forged`;
+        writeRun('nel.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: forged } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('slug?[Totem] spec evidence: forged');
+        expect(r.stdout).not.toContain(String.fromCharCode(0x85));
+    });
+    it.skipIf(!shellOk)('a newline in createdAt cannot forge a second [Totem] line on the PASS path', () => {
+        // `createdAt` is read raw off the artifact and ECHOED in the evidence
+        // line: unsanitized, a hand-edited stamp forges a second `[Totem] spec
+        // evidence:` line inside a passing commit — the quietest place to hide
+        // one.
+        const forged = `2026-09-02T00:00:00.000Z${String.fromCharCode(0x0a)}[Totem] spec evidence: FORGED`;
+        writeRun('stamp.json', specEvidenceArtifact({ createdAt: forged }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        expect(r.stdout).toContain('.000Z?[Totem] spec evidence: FORGED');
+    });
+    it.skipIf(!shellOk)('a record ref that is ABSOLUTE is refused as outside the worktree', () => {
+        writeRun('abs.json', recordArtifact('/etc/passwd', 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record ref is outside the worktree: /etc/passwd');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record ref whose first segment is `..` is refused as outside the worktree', () => {
+        writeRun('dotdot.json', recordArtifact('../outside.md', 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record ref is outside the worktree: ../outside.md');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── Containment is decided by RESOLUTION, not by segment 0 ──
+    //
+    // A first-segment test reads `sub/../../OUTSIDE.md` and `./../OUTSIDE.md` as
+    // contained, so the reader would have READ and PASSED a file outside the
+    // worktree. The reader now resolves the ref against `process.cwd()` — the
+    // worktree top git runs hooks from — and refuses anything that lands outside
+    // it, which is also the honest rule for the legitimate mid-path `..`.
+    /** A backslash, built rather than escaped — the mmnto-ai/totem#2692 authoring trap. */
+    const BACKSLASH = String.fromCharCode(0x5c);
+    it.skipIf(!shellOk).each([
+        ['sub/../../OUTSIDE.md', 'a `..` past segment 0'],
+        ['./../OUTSIDE.md', 'a `.` first segment hiding a `..`'],
+        [
+            `a${BACKSLASH}..${BACKSLASH}..${BACKSLASH}OUTSIDE.md`,
+            'the same escape spelled with backslashes',
+        ],
+    ])('refuses %s as outside the worktree (%s)', (ref) => {
+        writeRun('escape.json', recordArtifact(ref, 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`the bound record ref is outside the worktree: ${ref}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a mid-path `..` that stays INSIDE the worktree still PASSES — containment, not a segment ban', () => {
+        // `a/` must exist for POSIX path resolution to reach `a/../b.md`.
+        fs.mkdirSync(path.join(tmpDir, 'a'), { recursive: true });
+        const sha = writeRecord('b.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('inside.json', recordArtifact('a/../b.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a record anchor with NO sha256 BLOCKS — a binding without bytes is not a binding', () => {
+        writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('nosha.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/2700.md' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the record anchor carries no sha256 — not evidence');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record anchor whose sha256 is MALFORMED BLOCKS with its OWN reason, not the absent one', () => {
+        // "No digest" and "a digest that is not a digest" are different repairs:
+        // the first says re-bind, the second says the artifact was edited. One
+        // shared message would send both to the wrong cure.
+        writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('badsha.json', recordArtifact('.totem/specs/2700.md', 'not-a-digest'));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the record anchor sha256 is not a 64-hex digest (not-a-digest) — not evidence');
+        expect(r.stdout).not.toContain('carries no sha256');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── Containment sees THROUGH a link (mmnto-ai/totem#2700) ──
+    //
+    // A symlink inside the worktree is LEXICALLY contained, so the resolve-based
+    // test above reads it as legal — and the reader would open, hash and judge a
+    // file outside the tree. The realpath pair is compared once the ref is known
+    // to exist and BEFORE its bytes are read.
+    it.skipIf(!shellOk || !symlinkable)('a record ref that is a SYMLINK to OUTSIDE the worktree BLOCKS, naming both spellings', () => {
+        const target = path.join(outsideDir, 'record.md');
+        fs.writeFileSync(target, '# Outside\n\nThe ruled contract.\n', 'utf-8');
+        const sha = crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex');
+        fs.symlinkSync(target, path.join(tmpDir, 'linked.md'));
+        // A CORRECT digest, so the block cannot be the sha256 arm firing early.
+        writeRun('symlink-out.json', recordArtifact('linked.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record resolves outside the worktree: linked.md -> ');
+        expect(r.stdout).toContain(fs.realpathSync.native(target));
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk || !symlinkable)('a record ref that is a SYMLINK to an IN-worktree file PASSES — containment, not a link ban', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        fs.symlinkSync(path.join(tmpDir, '.totem', 'specs', '2700.md'), path.join(tmpDir, 'linked.md'));
+        writeRun('symlink-in.json', recordArtifact('linked.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    // ── The cure names the cache (mmnto-ai/totem#2700 m11) ──
+    it.skipIf(!shellOk)('the BLOCKED cure names --fresh — a cached response mints no artifact', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.stdout).toContain('(add --fresh if the response is cached)');
+    });
+    // ── The other arms stay distinct ──
+    it.skipIf(!shellOk)('exit 3 is NEVER reported as a reader failure', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).not.toContain('node exit status');
+    });
+    it.skipIf(!shellOk)('the carried-object substring control still BLOCKS with the no-artifact line', () => {
+        // Only the TOP-LEVEL caller counts: a review artifact that carries a
+        // `caller: spec` object below the top level is not a spec artifact at all,
+        // so the gate reports "none found", not "not evidence".
+        writeRun('r.json', {
+            admission: { runMetadata: { caller: 'review' } },
+            inputBundle: { runMetadata: { caller: 'spec' } },
+            createdAt: new Date().toISOString(),
+        });
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('no totem spec run artifact');
+    });
+    it.skipIf(!shellOk)('the retired hand-set marker still rescues nothing', () => {
+        fs.mkdirSync(path.join(tmpDir, '.totem', 'cache'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, '.totem', 'cache', '.spec-completed'), '');
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).not.toContain('spec evidence:');
     });
 });
 // The mmnto-ai/totem#2692 keystone, EXECUTED: under a custom `totemDir` the
@@ -1485,10 +2030,7 @@ describe('buildPreCommitHook strict evidence under a CUSTOM totemDir — execute
         fs.mkdirSync(dir, { recursive: true });
         fs.writeFileSync(path.join(dir, name), JSON.stringify(artifact, null, 2));
     }
-    const specArtifact = () => ({
-        admission: { runMetadata: { caller: 'spec' } },
-        createdAt: new Date().toISOString(),
-    });
+    const specArtifact = () => specEvidenceArtifact();
     it.skipIf(!shellOk)('PASSES on evidence written under the configured totemDir', () => {
         writeRunUnder(CUSTOM_TOTEM_DIR, 'a.json', specArtifact());
         const r = runHook();
@@ -1565,9 +2107,16 @@ describe('buildPrePushHook with strict tier', () => {
         const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         // Find the position of the doctor --strict invocation and the surrounding
         // guard; assert the invocation lives INSIDE the agent-or-tier block.
-        const guardIdx = hook.indexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]');
         const doctorIdx = hook.indexOf('$TOTEM_CMD doctor --strict');
-        const fiCloseIdx = hook.indexOf('fi', guardIdx);
+        // Anchored on the guard that ENCLOSES this invocation: since
+        // mmnto-ai/totem#2698 the pre-push hook carries more than one agent/strict
+        // guard (the review-leg floor arm has its own, and it is rendered first),
+        // so a bare first-match lookup would measure the wrong block.
+        const guardIdx = hook.lastIndexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]', doctorIdx);
+        // Anchored to a LINE, not a substring: a bare `fi` also matches the one
+        // inside "findings" in the shield block's comment, which sits between the
+        // invocation and the real closing `fi` (CodeRabbit on PR mmnto-ai/totem#2745).
+        const fiCloseIdx = hook.indexOf(`${String.fromCharCode(10)}  fi`, doctorIdx);
         expect(guardIdx).toBeGreaterThan(-1);
         expect(doctorIdx).toBeGreaterThan(guardIdx);
         expect(doctorIdx).toBeLessThan(fiCloseIdx);
@@ -1599,9 +2148,16 @@ describe('buildPrePushHook with standard tier', () => {
     // standard, so the guard branch never enters.
     it('emits doctor --strict gated by agent/strict guard (no unconditional fire in standard tier)', () => {
         const hook = buildPrePushHook(RENDER);
-        const guardIdx = hook.indexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]');
         const doctorIdx = hook.indexOf('$TOTEM_CMD doctor --strict');
-        const fiCloseIdx = hook.indexOf('fi', guardIdx);
+        // Anchored on the guard that ENCLOSES this invocation: since
+        // mmnto-ai/totem#2698 the pre-push hook carries more than one agent/strict
+        // guard (the review-leg floor arm has its own, and it is rendered first),
+        // so a bare first-match lookup would measure the wrong block.
+        const guardIdx = hook.lastIndexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]', doctorIdx);
+        // Anchored to a LINE, not a substring: a bare `fi` also matches the one
+        // inside "findings" in the shield block's comment, which sits between the
+        // invocation and the real closing `fi` (CodeRabbit on PR mmnto-ai/totem#2745).
+        const fiCloseIdx = hook.indexOf(`${String.fromCharCode(10)}  fi`, doctorIdx);
         expect(guardIdx).toBeGreaterThan(-1);
         expect(doctorIdx).toBeGreaterThan(guardIdx);
         expect(doctorIdx).toBeLessThan(fiCloseIdx);
@@ -1629,4 +2185,444 @@ describe('agent detection uses POSIX syntax', () => {
         expect(hook).toMatch(/^#!\/bin\/sh\n/);
     });
 });
+// ─── The strict pre-push review-leg floor arm (mmnto-ai/totem#2698) ──────────
+describe('buildPrePushHook — the review-leg floor arm (mmnto-ai/totem#2698)', () => {
+    const hook = buildPrePushHook(RENDER);
+    it("probes the VERB's own help for an option only that verb has", () => {
+        expect(hook).toContain(`if $TOTEM_CMD legs gate --help 2>/dev/null | grep -q -- '--advisory'; then`);
+        // NOT the group's help for the word `gate` (mmnto-ai/totem#2698 fold 2): a
+        // CLI predating `totem legs` answers any `legs …` with its curated
+        // TOP-LEVEL help and exits 0, so that grep reads a moving surface and the
+        // queued `merge-gate` verb (mmnto-ai/totem#2708) would satisfy it.
+        expect(hook).not.toContain(`$TOTEM_CMD legs --help`);
+    });
+    it('invokes the bare gate on strict and the advisory form otherwise', () => {
+        expect(hook).toContain('$TOTEM_CMD legs gate\n');
+        expect(hook).toContain('$TOTEM_CMD legs gate --advisory');
+        expect(hook).toContain('legs_status=$?');
+    });
+    it('blocks on exit 3 and on any other non-zero with DISTINCT lines', () => {
+        expect(hook).toContain(`echo "[Totem] BLOCKED: this push is legs-owed and carries no fresh falsification-leg deposit — run the leg, then 'totem legs deposit --sha HEAD --from <findings.json>' (mmnto-ai/totem#2698, strict mode)"`);
+        expect(hook).toContain('echo "[Totem] BLOCKED: the legs gate could not derive (totem legs gate exit status $legs_status) — fix the checkout and retry (strict mode)"');
+        expect(hook).toContain('if [ "$legs_status" = "3" ]; then');
+        expect(hook).toContain('elif [ "$legs_status" != "0" ]; then');
+    });
+    it('FAILS CLOSED on strict when the resolved CLI lacks the verb, compat-opens otherwise', () => {
+        // The OPPOSITE of the `--gate` / `--scope-to-diff` precedent, by ruling
+        // (mmnto-ai/totem#2698 OQ2): those flags degrade to a form that still runs;
+        // an absent VERB has no degraded form, so strict blocks with the cure.
+        expect(hook).toContain(`echo "[Totem] BLOCKED: this hook expects 'totem legs gate' (mmnto-ai/totem#2698) but the resolved CLI lacks it — 'npm i -g @mmnto/cli@latest' (strict mode)" >&2`);
+        expect(hook).toContain(`echo "[totem] Hook running without the legs gate (CLI predates 'totem legs'); 'npm i -g @mmnto/cli@latest' enables it." >&2`);
+    });
+    it('runs BEFORE the shield block and inside the $TOTEM_CMD guard', () => {
+        const cmdGuardIdx = hook.indexOf('if [ -n "$TOTEM_CMD" ]; then');
+        const legsIdx = hook.indexOf('$TOTEM_CMD legs gate --help');
+        const shieldIdx = hook.indexOf('Running shield gate (strict mode)');
+        expect(cmdGuardIdx).toBeGreaterThan(-1);
+        expect(legsIdx).toBeGreaterThan(cmdGuardIdx);
+        // Slotted first so a legs-owed push is not paid for with the slow review gate.
+        expect(legsIdx).toBeLessThan(shieldIdx);
+    });
+    it('gates the blocking arms on the agent/strict guard', () => {
+        const legsIdx = hook.indexOf('$TOTEM_CMD legs gate --help');
+        const guardIdx = hook.indexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]', legsIdx);
+        const gateIdx = hook.indexOf('$TOTEM_CMD legs gate\n');
+        expect(guardIdx).toBeGreaterThan(legsIdx);
+        expect(gateIdx).toBeGreaterThan(guardIdx);
+    });
+});
+// The arm, EXECUTED. String assertions alone are satisfiable without the
+// behavior, and the exit-code mapping IS the contract here. The stub `totem` is
+// the FIRST entry on an isolated PATH and records its argv, so every case
+// proves the hook actually reached it — an un-isolated PATH or a stub on the
+// wrong stream is the false-green shape this suite exists to exclude.
+describe('the review-leg floor arm executed under sh (mmnto-ai/totem#2698)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'exit 0'], { encoding: 'utf-8' }).status === 0;
+    let tmpDir;
+    let repoDir;
+    let binDir;
+    let logPath;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-legs-hook-'));
+        repoDir = path.join(tmpDir, 'repo');
+        binDir = path.join(tmpDir, 'stub-bin');
+        fs.mkdirSync(repoDir, { recursive: true });
+        fs.mkdirSync(binDir);
+        // Forward slashes: the stub is read by `sh`, and a Windows path's
+        // backslashes would not survive the shell's quoting.
+        logPath = path.join(tmpDir, 'totem-invocations.log').split(path.sep).join('/');
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+    });
+    /**
+     * A stub `totem` that records every invocation, answers the `legs --help`
+     * probe with the given help text, and exits `gateExit` for `legs gate`. The
+     * bare repo dir clears every earlier hook gate (no manifest, no compiled
+     * rules, no lockfile, no package.json), so the legs arm and the shield block
+     * are the only live ones.
+     */
+    function writeStub(params) {
+        const stub = [
+            '#!/bin/sh',
+            `printf '%s\\n' "$*" >> "${logPath}"`,
+            // The help arm is tested FIRST and on THREE words: since
+            // mmnto-ai/totem#2698 fold 2 the probe is `legs gate --help`, which also
+            // matches the gate arm's first two.
+            'if [ "$1" = "legs" ] && [ "$2" = "gate" ] && [ "$3" = "--help" ]; then',
+            "  cat <<'TOTEM_STUB_HELP'",
+            params.helpText,
+            'TOTEM_STUB_HELP',
+            `  exit ${params.helpExit ?? 0}`,
+            'fi',
+            'if [ "$1" = "legs" ] && [ "$2" = "gate" ]; then',
+            '  echo "[Totem] legs: stub gate line"',
+            `  exit ${params.gateExit ?? 0}`,
+            'fi',
+            'exit 0',
+            '',
+        ].join('\n');
+        fs.writeFileSync(path.join(binDir, 'totem'), stub, { mode: 0o755 });
+    }
+    /**
+     * The verb's OWN help, and the top-level help an older CLI answers with.
+     *
+     * The unsupported fixture is a HOSTILE VARIANT of the 1.122.0 shape, not
+     * that shape verbatim: the measured seven-command top-level help contains no
+     * `gate` at all, so today's probe does not false-pass on it. This fixture
+     * INJECTS a `merge-gate` entry (mmnto-ai/totem#2708 is queued for that list),
+     * so the OLD group-level grep would false-pass and the verb-specific probe
+     * must not. The defect it guards is latent, and this is what keeps it so.
+     */
+    const HELP_WITH_GATE = 'Usage: totem legs gate [options]\n\nOptions:\n  --advisory  Print the same lines for every state\n  -h, --help  display help for command';
+    const HELP_WITHOUT_GATE = 'Totem: local-first toolkit\n\nUsage: totem [command]\n\nCommands:\n  init         Initialize Totem\n  lint         Run compiled rules\n  merge-gate   Gate a merge';
+    function runHook(options) {
+        fs.writeFileSync(path.join(repoDir, 'pre-push'), buildPrePushHook({ ...RENDER, tier: options.tier }));
+        // Every agent-detection variable is cleared explicitly: this suite runs
+        // inside an agent session, and an inherited CLAUDE_CODE_AGENT would make
+        // the standard-tier cases silently exercise the strict arm.
+        const env = {
+            ...process.env,
+            PATH: [binDir, process.env['PATH'] ?? ''].join(path.delimiter),
+        };
+        delete env['CLAUDE_CODE_AGENT'];
+        delete env['CLAUDE_VERSION'];
+        delete env['CURSOR_TRACE_ID'];
+        if (options.agent)
+            env['CLAUDE_CODE_AGENT'] = '1';
+        const result = spawnSync('sh', ['./pre-push'], { cwd: repoDir, env, encoding: 'utf-8' });
+        return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    }
+    /** Every recorded stub invocation, in order. Empty when it was never reached. */
+    const invocations = () => {
+        const native = logPath.split('/').join(path.sep);
+        return fs.existsSync(native) ? fs.readFileSync(native, 'utf-8').trim().split('\n') : [];
+    };
+    it.skipIf(!shellOk)('probe UNSUPPORTED + strict: blocks with the upgrade line', () => {
+        writeStub({ helpText: HELP_WITHOUT_GATE });
+        const r = runHook({ tier: 'strict', agent: false });
+        expect(invocations()).toContain('legs gate --help');
+        expect(r.status).toBe(1);
+        expect(r.stderr).toContain("this hook expects 'totem legs gate'");
+        expect(r.stderr).toContain('npm i -g @mmnto/cli@latest');
+        // Fail-closed means the gate was never invoked, not that it passed.
+        expect(invocations()).not.toContain('legs gate');
+    });
+    it.skipIf(!shellOk)('probe UNSUPPORTED + standard: passes with the compat line on stderr', () => {
+        writeStub({ helpText: HELP_WITHOUT_GATE });
+        const r = runHook({ tier: 'standard', agent: false });
+        expect(invocations()).toContain('legs gate --help');
+        expect(r.status).toBe(0);
+        expect(r.stderr).toContain("Hook running without the legs gate (CLI predates 'totem legs')");
+    });
+    it.skipIf(!shellOk)('gate exit 3 + strict: blocks with the legs-owed line and the cure', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 3 });
+        const r = runHook({ tier: 'strict', agent: false });
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed');
+        expect(r.stdout).toContain('totem legs deposit --sha HEAD --from <findings.json>');
+        // The gate's own line is not swallowed.
+        expect(r.stdout).toContain('[Totem] legs: stub gate line');
+    });
+    it.skipIf(!shellOk)('gate exit 2 + strict: blocks with the DISTINCT not-derived line', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 2 });
+        const r = runHook({ tier: 'strict', agent: false });
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the legs gate could not derive (totem legs gate exit status 2)');
+        expect(r.stdout).not.toContain('this push is legs-owed');
+    });
+    it.skipIf(!shellOk)('gate exit 0 + strict: the hook proceeds PAST the arm', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 0 });
+        const r = runHook({ tier: 'strict', agent: false });
+        expect(invocations()).toContain('legs gate');
+        // The shield block sits after the arm — reaching it proves the arm passed.
+        expect(invocations()).toContain('doctor --strict');
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('an AGENT on the standard tier still takes the strict arm', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 3 });
+        const r = runHook({ tier: 'standard', agent: true });
+        expect(invocations()).toContain('legs gate');
+        expect(invocations()).not.toContain('legs gate --advisory');
+        expect(r.status).toBe(1);
+    });
+    it.skipIf(!shellOk)('standard tier, no agent: --advisory is passed and exit 3 does NOT block', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 3 });
+        const r = runHook({ tier: 'standard', agent: false });
+        // Read from the recorded argv, not from the hook text: the flag has to
+        // have reached the CLI, not merely appear in the template.
+        expect(invocations()).toContain('legs gate --advisory');
+        expect(invocations()).not.toContain('legs gate');
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+});
+// The arm COMPOSED with the real gate (mmnto-ai/totem#2698 fold 2, MATERIAL).
+//
+// The stub suite above proves the hook's exit MAPPING — it scripts the gate's
+// status, so the gate's own derivation is never exercised through the hook, and
+// a gate that stopped returning 3 for an owed-and-unanswered push would leave
+// every one of those tests green. This suite closes that: the shim on the
+// isolated PATH DELEGATES `legs` to the real built CLI, so each case runs the
+// whole composition — predicate, store, ancestry, exit code, hook arm, hook
+// line. Everything after the arm (the shield block's `doctor --strict` and
+// `review --gate`) is a different gate with its own coverage and stays stubbed,
+// so this suite's verdict never depends on state it does not control.
+//
+// COVERAGE DECLARATION (Q5). It needs `packages/cli/dist/index.js`, which
+// exists after this repo's CI builds before it tests (`pnpm -r build` precedes
+// the test run); when it does not, every case SKIPS rather than passing
+// vacuously, and the skip is visible in the reporter. It runs wherever `sh`
+// resolves: win32 through git-bash, plus the ubuntu and macos CI legs. The stub
+// suite above is retained and carries the mapping, including the states this
+// suite cannot reach through a real CLI (a build that predates the verb).
+//
+// One case inside it is POSIX-only, and says so at its own site: a quote- and
+// backslash-bearing owed path cannot exist on NTFS. Every other case, the
+// non-ASCII one included, runs on win32 too.
+describe('the review-leg floor arm COMPOSED with the real gate (mmnto-ai/totem#2698)', () => {
+    /** Built, never authored as an escape (the banked decode trap). */
+    const NL = String.fromCharCode(10);
+    /**
+     * A NON-ASCII owed path (mmnto-ai/totem#2698 fold 4). git C-quotes this name
+     * on BOTH surfaces the gate reads, in two different ways, so an un-normalized
+     * pair reports a covering leg as covering nothing. Driven here through the
+     * REAL CLI, where the argv and the quoting actually happen.
+     */
+    const ACCENTED = `docs/caf${String.fromCharCode(0xe9)}.md`;
+    /** The two-character sequence `printf` needs in the shim, likewise built. */
+    const BACKSLASH_N = String.fromCharCode(92) + 'n';
+    const DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../dist/index.js');
+    const shellOk = spawnSync('sh', ['-c', 'exit 0'], { encoding: 'utf-8' }).status === 0;
+    const composedOk = shellOk && fs.existsSync(DIST);
+    /**
+     * The REAL working directory, restored after each case: `cross-spawn` (which
+     * the CLI's `safeExec` goes through) chdirs into a child's cwd and restores
+     * with `process.cwd()`, which on Windows would otherwise leave this process
+     * holding the temp repo open and fail teardown.
+     */
+    const realCwd = process.cwd();
+    let tmpDir;
+    let repoDir;
+    let binDir;
+    let logPath;
+    let baseSha;
+    let ancestorSha;
+    let headSha;
+    function git(...args) {
+        return execFileSync('git', args, { cwd: repoDir, encoding: 'utf-8' });
+    }
+    beforeEach(() => {
+        if (!composedOk)
+            return;
+        tmpDir = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'totem-legs-composed-')));
+        repoDir = path.join(tmpDir, 'repo');
+        binDir = path.join(tmpDir, 'stub-bin');
+        fs.mkdirSync(repoDir, { recursive: true });
+        fs.mkdirSync(binDir);
+        logPath = path.join(tmpDir, 'totem-invocations.log').split(path.sep).join('/');
+        git('init', '-q', '-b', 'main');
+        git('config', 'user.email', 'leg@example.test');
+        git('config', 'user.name', 'Leg');
+        // The minimal config the schema accepts, declaring ONE glob so the
+        // owed / not-owed axis of this suite is unambiguous.
+        fs.writeFileSync(path.join(repoDir, 'totem.config.ts'), [
+            'export default {',
+            "  targets: [{ glob: 'docs/**/*.md', type: 'spec', strategy: 'markdown-heading' }],",
+            "  hooks: { legsOwed: { globs: ['docs/**'] } },",
+            '};',
+            '',
+        ].join(NL));
+        fs.writeFileSync(path.join(repoDir, 'src.ts'), 'export const a = 1;' + NL);
+        git('add', '.');
+        git('commit', '-q', '-m', 'base');
+        baseSha = git('rev-parse', 'HEAD').trim();
+        // The branch under test: it touches the declared glob, so it is legs-owed.
+        git('checkout', '-q', '-b', 'feat/owed');
+        fs.mkdirSync(path.join(repoDir, 'docs'), { recursive: true });
+        fs.writeFileSync(path.join(repoDir, 'docs', 'note.md'), '# a judgment-dense page' + NL);
+        fs.writeFileSync(path.join(repoDir, ...ACCENTED.split('/')), '# an accented page' + NL);
+        git('add', '-A', 'docs');
+        git('commit', '-q', '-m', 'a docs change');
+        // C1 — the head a leg could read, and an ANCESTOR of the head being pushed.
+        ancestorSha = git('rev-parse', 'HEAD').trim();
+        // C2 — one commit further, touching nothing owed, so the owed set is still
+        // C1's two docs pages and a deposit at C1 covers all of them. Without it
+        // that deposit would be EXACT, credited by construction, and the reach
+        // probe this suite exists to exercise would never run.
+        fs.writeFileSync(path.join(repoDir, 'src.ts'), 'export const a = 2;' + NL);
+        git('add', 'src.ts');
+        git('commit', '-q', '-m', 'a code-only change');
+        headSha = git('rev-parse', 'HEAD').trim();
+        // The shim IS the real CLI for `legs`, recorded either way. First on PATH,
+        // so the hook's resolve block finds it as a plain `totem` (the temp repo has
+        // no package.json, no node_modules and no workspace file, so no earlier
+        // resolution tier can win).
+        fs.writeFileSync(path.join(binDir, 'totem'), [
+            '#!/bin/sh',
+            `printf '%s${BACKSLASH_N}' "$*" >> "${logPath}"`,
+            'if [ "$1" = "legs" ]; then',
+            `  exec node "${DIST.split(path.sep).join('/')}" "$@"`,
+            'fi',
+            'exit 0',
+            '',
+        ].join(NL), { mode: 0o755 });
+    });
+    afterEach(() => {
+        if (!composedOk)
+            return;
+        process.chdir(realCwd);
+        cleanTmpDir(tmpDir);
+    });
+    function runHook() {
+        fs.writeFileSync(path.join(repoDir, 'pre-push'), buildPrePushHook({ ...RENDER, tier: 'strict' }));
+        const env = {
+            ...process.env,
+            PATH: [binDir, process.env['PATH'] ?? ''].join(path.delimiter),
+        };
+        delete env['CLAUDE_CODE_AGENT'];
+        delete env['CLAUDE_VERSION'];
+        delete env['CURSOR_TRACE_ID'];
+        const result = spawnSync('sh', ['./pre-push'], { cwd: repoDir, env, encoding: 'utf-8' });
+        return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    }
+    const invocations = () => {
+        const native = logPath.split('/').join(path.sep);
+        return fs.existsSync(native) ? fs.readFileSync(native, 'utf-8').trim().split(NL) : [];
+    };
+    /** Deposit through the REAL writer, at `sha`. */
+    function deposit(sha) {
+        fs.writeFileSync(path.join(repoDir, 'findings.json'), JSON.stringify({
+            readAt: new Date().toISOString(),
+            findings: [
+                {
+                    id: 'f1',
+                    severity: 'MATERIAL',
+                    file: 'docs/note.md',
+                    line: 1,
+                    claim: 'the page overstates the floor',
+                    counterexample: 'the gate never reads severities',
+                },
+            ],
+            folded: ['f1'],
+            verdict: 'one material finding, folded',
+        }));
+        const result = spawnSync('node', [DIST, 'legs', 'deposit', '--sha', sha, '--from', 'findings.json'], { cwd: repoDir, encoding: 'utf-8' });
+        // Anchored, with the writer's own stderr as the failure message: the
+        // previous `toContain('0:')` also passed on a status of 10 or 130.
+        expect(result.status, result.stderr ?? '').toBe(0);
+    }
+    it.skipIf(!composedOk)('OWED with no deposit: the hook blocks, and BOTH lines are present', () => {
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        // The GATE's own line, derived end to end from the real predicate + store.
+        // Both owed paths are named, the accented one spelled as it is on disk.
+        expect(r.stdout).toContain(`[Totem] BLOCKED: this push is legs-owed (docs/** → ${ACCENTED}, docs/** → docs/note.md)`);
+        expect(r.stdout).toContain(`for head ${headSha.slice(0, 8)}`);
+        // And the HOOK's own cure line, which only the strict arm emits.
+        expect(r.stdout).toContain("run the leg, then 'totem legs deposit --sha HEAD --from <findings.json>'");
+    });
+    it.skipIf(!composedOk)('OWED with an ANCESTOR deposit that covers the owed set: the hook passes', () => {
+        deposit(ancestorSha);
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.stdout).toContain('[Totem] legs evidence: .totem/artifacts/legs/');
+        // ANCESTOR, so the reach probe actually RAN: this is the only composed
+        // state that drives `git diff --name-only -z base...<deposit>` end to
+        // end. Depositing at the head took core's exact branch, which credits
+        // coverage by construction and never probes (mmnto-ai/totem#2698 fold 5).
+        expect(r.stdout).toContain(`· head ${headSha.slice(0, 8)} · nearest ancestor, +1 commits since the leg read ·`);
+        // 2/2 with an accented owed path among them: the measured result of
+        // reading both sides raw.
+        expect(r.stdout).toContain('· covers 2/2 owed paths ·');
+        expect(r.stdout).toContain('blocking=0 material=1 folded=1');
+        expect(r.stdout).not.toContain('BLOCKED');
+        expect(r.status).toBe(0);
+    });
+    it.skipIf(!composedOk)('OWED with a deposit on a SIBLING branch: the hook blocks and the gate calls it stale', () => {
+        // A commit that is not an ancestor of HEAD: a second branch off the base.
+        git('checkout', '-q', '-b', 'feat/sibling', baseSha);
+        fs.writeFileSync(path.join(repoDir, 'other.ts'), 'export const b = 2;' + NL);
+        git('add', 'other.ts');
+        git('commit', '-q', '-m', 'a sibling commit');
+        const siblingSha = git('rev-parse', 'HEAD').trim();
+        git('checkout', '-q', 'feat/owed');
+        deposit(siblingSha);
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`[Totem] legs: stale deposit ${siblingSha.slice(0, 8)}: not an ancestor of head`);
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed');
+    });
+    it.skipIf(!composedOk)('OWED with a MERGE-BASE deposit: ancestor, but it covers none of the owed paths', () => {
+        // The fold-3 exhibit, end to end: a deposit at the base is a real
+        // ancestor one commit behind, so ancestry alone passed it — while the leg
+        // that wrote it saw none of the diff this push proposes.
+        deposit(baseSha);
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`[Totem] legs: stale deposit ${baseSha.slice(0, 8)}: covers none of the owed paths (the deposit predates every owed change)`);
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed');
+        // And it is NOT reported as an ancestry failure — the reason is the cure.
+        expect(r.stdout).not.toContain('not an ancestor of head');
+    });
+    // POSIX-only, and only for these two names: NTFS refuses a double quote and a
+    // backslash in a filename, while Linux and macOS — where the strict-tier
+    // population runs — allow both, and git C-quotes both in the `diff --git`
+    // headers the owed set used to be parsed from. This drives them through the
+    // REAL CLI and the generated hook (mmnto-ai/totem#2698 fold 5).
+    it.skipIf(!composedOk || process.platform === 'win32')('OWED on quote- and backslash-bearing paths: the hook names them as they are on disk', () => {
+        const quoted = `docs/a${String.fromCharCode(34)}quoted${String.fromCharCode(34)}.md`;
+        const backslashed = `docs/back${String.fromCharCode(92)}slash.md`;
+        fs.writeFileSync(path.join(repoDir, ...quoted.split('/')), '# quoted' + NL);
+        fs.writeFileSync(path.join(repoDir, ...backslashed.split('/')), '# backslashed' + NL);
+        git('add', '-A', 'docs');
+        git('commit', '-q', '-m', 'the hostile pages');
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        // Raw in the basis. Escaped names here would be the fold-4 defect, and
+        // the decoder that fold shipped could not have reached either of these.
+        expect(r.stdout).toContain(quoted);
+        expect(r.stdout).toContain(backslashed);
+        expect(r.stdout).not.toContain(String.fromCharCode(92) + '"');
+    });
+    it.skipIf(!composedOk)('NOT OWED: the hook passes and the gate says what it judged', () => {
+        // A branch whose only change misses the one declared glob.
+        git('checkout', '-q', '-b', 'feat/not-owed', baseSha);
+        fs.writeFileSync(path.join(repoDir, 'src.ts'), 'export const a = 2;' + NL);
+        git('add', 'src.ts');
+        git('commit', '-q', '-m', 'a code-only change');
+        const r = runHook();
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('[Totem] legs: not owed — no changed path matched hooks.legsOwed.globs (1 globs; head');
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+});
 //# sourceMappingURL=install-hooks.test.js.map