@mmnto/cli 1.124.0 → 2.1.0

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

@@ -4,11 +4,11 @@ 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 { afterEach, beforeEach, describe, expect, it, vi } 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';
+import { buildHookContent, buildPostCheckoutHookContent, buildPreCommitHook, buildPrePushHook, buildResolveBlock, checkHooksInstalled, declaredHookTier, detectTotemPrefix, generateHookHelpers, getFallbackCommand, installGitHook, installHooksNonInteractive, isAttestedTrailer, isTotemOwnedWithAttestedTrailer, TOTEM_CHECKOUT_END, TOTEM_CHECKOUT_MARKER, 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, SPEC_SYSTEM_PROMPT } 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
@@ -18,6 +18,76 @@ const RENDER = {
     totemDir: '.totem',
     fallbackCmd: 'pnpm dlx @mmnto/cli',
 };
+// ─── Attested-extension fixtures (mmnto-ai/totem#2753) ───
+//
+// The measured liquid-city extension shape (`tools/git-hooks/install.cjs`, block 1):
+// a `# [lc] …` comment line, THEN the attestation, then the extension's commands.
+// Transcribed from that file's own string arrays and joined the way it joins them
+// (`block.join('\n')`, appended straight onto a hook that ends with a newline), so
+// each fixture is the exact byte sequence a liquid-city checkout carries after
+// `# [totem] end <hook>` (mmnto-ai/liquid-city#1174).
+//
+// The attestation is NOT on the trailer's first non-blank line. An earlier reading of
+// this contract required that, and it declined the founding datum outright.
+const ATTESTED_FORK_LINE = '# <!-- totem:fork reason="lc docs-inject pre-commit extension (divergence-census justified fork)" owner="satur8d" attested="2026-06-07" -->';
+/** install.cjs `STDIN_CAPTURE`. */
+const LC_STDIN_CAPTURE = [
+    'LC_STDIN=$(cat)',
+    'lc_feed() { if [ -n "$LC_STDIN" ]; then printf \'%s\\n\' "$LC_STDIN"; fi; }',
+];
+/** install.cjs EXTENSIONS block 1 — pre-commit docs-inject. */
+const ATTESTED_TRAILER = [
+    '',
+    '# [lc] docs-inject extension',
+    ATTESTED_FORK_LINE,
+    'sh "tools/git-hooks/pre-commit-docs-inject.sh"',
+    '',
+].join('\n');
+/** install.cjs EXTENSIONS block 2 — pre-push validate-fixtures. */
+const LC_PREPUSH_FIXTURES_BLOCK = [
+    '',
+    '# [lc] validate-fixtures extension',
+    '# <!-- totem:fork reason="lc fail-closed fixture-contract validator pre-push extension (ADR-025 A2; divergence-census justified fork)" owner="satur8d" attested="2026-06-20" -->',
+    ...LC_STDIN_CAPTURE,
+    'lc_feed | sh "tools/git-hooks/pre-push-validate-fixtures.sh" || exit 1',
+    '',
+].join('\n');
+/** install.cjs EXTENSIONS block 3 — pre-push validate-assets. */
+const LC_PREPUSH_ASSETS_BLOCK = [
+    '',
+    '# [lc] validate-assets extension',
+    '# <!-- totem:fork reason="lc fail-closed interior-asset validator pre-push extension (mmnto-ai/liquid-city#543 Phase 2; divergence-census justified fork)" owner="satur8d" attested="2026-06-27" -->',
+    'lc_feed | sh "tools/git-hooks/pre-push-validate-assets.sh" || exit 1',
+    '',
+].join('\n');
+/**
+ * The canonical with ONE comment line inside the managed block altered — a hook
+ * frozen at an older template. Alters neither marker nor the trailer seam, so the
+ * ONLY difference a rewrite has to cure is the block's own text.
+ */
+function withStaleComment(canonical, endMarker) {
+    const lines = canonical.split('\n');
+    const endLine = lines.findIndex((line) => line.includes(endMarker));
+    const commentLine = lines.findIndex((line, i) => i > 1 && i < endLine && line.trimStart().startsWith('#') && !line.includes('[totem]'));
+    // Loud, not silent: a template with no alterable comment line would make every
+    // test below compare the canonical against itself and pass vacuously.
+    if (commentLine === -1)
+        throw new Error('no alterable comment line inside the managed block');
+    lines[commentLine] = `${lines[commentLine]} (frozen at an older template)`;
+    return lines.join('\n');
+}
+/** The text from the start marker through the end marker, inclusive. */
+function managedBlockOf(text, marker, endMarker) {
+    const start = text.indexOf(marker);
+    const end = text.indexOf(endMarker, start + marker.length);
+    return text.slice(start, end + endMarker.length);
+}
+/** The bytes after the end marker — the trailer, its seam terminator included. */
+function trailerOf(text, marker, endMarker) {
+    const start = text.indexOf(marker);
+    const end = text.indexOf(endMarker, start + marker.length);
+    return text.slice(end + endMarker.length);
+}
 // ─── Anchored-evidence fixtures (mmnto-ai/totem#2700) ───
 //
 // Since #2700 an artifact is evidence only when it is ANCHORED and its SUBJECT
@@ -443,8 +513,13 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-commit');
         const userHook = '#!/bin/sh\necho "user hook"\n';
         fs.writeFileSync(hookPath, userHook);
+        // The append is a whole-file atomic replacement since mmnto-ai/totem#2760
+        // round 1 (an interrupted append leaves a hook truncated mid-block): the
+        // inode changes under rename-over, where an in-place append kept it.
+        const inodeBefore = fs.statSync(hookPath, { bigint: true }).ino;
         const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
+        expect(fs.statSync(hookPath, { bigint: true }).ino).not.toBe(inodeBefore);
         const written = fs.readFileSync(hookPath, 'utf-8');
         expect(written).toContain('echo "user hook"');
         expect(written).toContain(TOTEM_PRECOMMIT_MARKER);
@@ -624,6 +699,404 @@ describe('installGitHook', () => {
         expect(result).toBe('exists');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(staleWithTrailingUser);
     });
+    // ── Attested-extension carry-through (mmnto-ai/totem#2753) ──
+    //
+    // The liquid-city shape: a consumer appends its own blocks AFTER totem's end
+    // marker, each headed by a full `totem:fork` attestation. Before this slice a bare
+    // install DECLINED such a file, so `totem init -y` reported "Upgraded reflexes to
+    // v13" while both hooks stayed frozen at the 1.121.0 managed text (measured at
+    // `@mmnto/cli` 1.123.0, mmnto-ai/liquid-city#1174).
+    it('a bare install rewrites a stale managed block in place and carries an attested trailer through byte-for-byte', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER;
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(result).toBe('block-rewritten');
+        const written = fs.readFileSync(hookPath, 'utf-8');
+        // The managed block is the CURRENT canonical …
+        expect(managedBlockOf(written, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe(managedBlockOf(canonical, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END));
+        // … and everything past the end marker is byte-identical to what was there.
+        expect(trailerOf(written, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe(trailerOf(existing, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END));
+        // The seam carries exactly ONE newline: the canonical's own, not a duplicate.
+        expect(written).toBe(canonical + ATTESTED_TRAILER);
+    });
+    it('carries an attested trailer through on pre-push', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-push');
+        const canonical = buildPrePushHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PREPUSH_END) + ATTESTED_TRAILER;
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-push', canonical, TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
+        expect(result).toBe('block-rewritten');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical + ATTESTED_TRAILER);
+    });
+    it('carries an attested trailer through on post-merge', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'post-merge');
+        const canonical = buildHookContent(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_HOOK_END) + ATTESTED_TRAILER;
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'post-merge', canonical, TOTEM_HOOK_MARKER, false, TOTEM_HOOK_END);
+        expect(result).toBe('block-rewritten');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical + ATTESTED_TRAILER);
+    });
+    it('is idempotent — a second bare install on the rewritten hook writes nothing and reports current', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        fs.writeFileSync(hookPath, withStaleComment(canonical, TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        const afterFirst = fs.readFileSync(hookPath, 'utf-8');
+        const second = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        // `exists` IS the no-write arm — the function returns before `writeExecutableHook`
+        // — so the action plus byte-equality is the whole claim.
+        expect(second).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(afterFirst);
+    });
+    it('declines a stale block whose trailer is UNATTESTED (unchanged: byte-for-byte untouched)', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PRECOMMIT_END) +
+            '# my own pre-commit extension\necho "[me] extension"\n';
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(result).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(existing);
+    });
+    it('declines a trailer headed by a BARE totem:fork marker (a fork claim is not an attestation)', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PRECOMMIT_END) +
+            '# <!-- totem:fork -->\necho "[me] extension"\n';
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(result).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(existing);
+    });
+    it('declines a trailer attested with only a reason (owner and attested are required too)', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PRECOMMIT_END) +
+            '# <!-- totem:fork reason="lc docs-inject pre-commit extension" -->\necho "[me] extension"\n';
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(result).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(existing);
+    });
+    it('--force still overwrites the WHOLE file, attested trailer included (semantics unchanged)', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        fs.writeFileSync(hookPath, withStaleComment(canonical, TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, true, // force
+        TOTEM_PRECOMMIT_END);
+        expect(result).toBe('overwritten');
+        const written = fs.readFileSync(hookPath, 'utf-8');
+        expect(written).toBe(canonical);
+        expect(written).not.toContain('totem:fork');
+    });
+    it('carries a TWO-block liquid-city pre-push trailer through — the FIRST block attests', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-push');
+        const canonical = buildPrePushHook(RENDER);
+        // install.cjs blocks 2 and 3, appended back to back exactly as a liquid-city
+        // checkout carries them. Only the first block's comment run is the trailer's
+        // leading run; the second block's marker sits far below a command.
+        const trailer = LC_PREPUSH_FIXTURES_BLOCK + LC_PREPUSH_ASSETS_BLOCK;
+        fs.writeFileSync(hookPath, withStaleComment(canonical, TOTEM_PREPUSH_END) + trailer);
+        const result = installGitHook(hooksDir, 'pre-push', canonical, TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
+        expect(result).toBe('block-rewritten');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical + trailer);
+    });
+    it('declines when the fork line sits BELOW the extension first command', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        const existing = withStaleComment(canonical, TOTEM_PRECOMMIT_END) +
+            [
+                '',
+                '# [lc] docs-inject extension',
+                'if [ -f "docs/wiki/Home.md" ]; then',
+                '  echo "[lc] docs-inject extension"',
+                'fi',
+                ATTESTED_FORK_LINE,
+                '',
+            ].join('\n');
+        fs.writeFileSync(hookPath, existing);
+        const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(result).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(existing);
+    });
+    it('carries an attested trailer through on post-checkout', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'post-checkout');
+        const canonical = buildPostCheckoutHookContent(RENDER);
+        fs.writeFileSync(hookPath, withStaleComment(canonical, TOTEM_CHECKOUT_END) + ATTESTED_TRAILER);
+        const result = installGitHook(hooksDir, 'post-checkout', canonical, TOTEM_CHECKOUT_MARKER, false, TOTEM_CHECKOUT_END);
+        expect(result).toBe('block-rewritten');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical + ATTESTED_TRAILER);
+    });
+    it('strips exactly one CRLF seam and keeps the CRLF bytes inside the trailer', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        // A win32 checkout: the whole file, trailer included, is CRLF. The seam the
+        // rewrite removes is the end marker's own `\r\n`, and only that one.
+        const crlfTrailer = ATTESTED_TRAILER.replace(/\n/g, '\r\n');
+        fs.writeFileSync(hookPath, withStaleComment(canonical, TOTEM_PRECOMMIT_END).replace(/\n/g, '\r\n') + crlfTrailer);
+        const first = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(first).toBe('block-rewritten');
+        const written = fs.readFileSync(hookPath, 'utf-8');
+        // One seam consumed, not two: the terminator removed is the stale block's own
+        // `\r\n` after the end marker, so the trailer keeps every byte it had — its
+        // leading blank line included — behind the canonical's `\n`.
+        expect(written).toBe(canonical + crlfTrailer);
+        expect(written).toContain('\r\n# [lc] docs-inject extension\r\n');
+        const second = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(second).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(written);
+    });
+    it('handles an end marker with text on the SAME line, and is idempotent after', () => {
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        const canonical = buildPreCommitHook(RENDER);
+        // No terminator after the end marker: the trailer begins mid-line. The offset
+        // `ownedTrailerStart` returns is the byte AFTER the marker, so the trailer is
+        // ` ${ATTESTED_FORK_LINE}\n…` — attested, because its first non-blank line
+        // trims to a comment carrying the marker.
+        const sameLineTrailer = ` ${ATTESTED_FORK_LINE}\nsh "tools/git-hooks/pre-commit-docs-inject.sh"\n`;
+        const stale = withStaleComment(canonical, TOTEM_PRECOMMIT_END).replace(`${TOTEM_PRECOMMIT_END}\n`, TOTEM_PRECOMMIT_END);
+        expect(isTotemOwnedWithAttestedTrailer(stale + sameLineTrailer, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe(true);
+        fs.writeFileSync(hookPath, stale + sameLineTrailer);
+        const first = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        // Nothing was removed — there was no seam terminator to consume — so the
+        // same-line text is carried through verbatim, now behind the canonical's own
+        // newline.
+        expect(first).toBe('block-rewritten');
+        const written = fs.readFileSync(hookPath, 'utf-8');
+        expect(written).toBe(canonical + sameLineTrailer);
+        const second = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        expect(second).toBe('exists');
+        expect(fs.readFileSync(hookPath, 'utf-8')).toBe(written);
+    });
+});
+// ─── isAttestedTrailer (mmnto-ai/totem#2753) ────────
+describe('isAttestedTrailer', () => {
+    it('is false for a blank trailer', () => {
+        expect(isAttestedTrailer('')).toBe(false);
+        expect(isAttestedTrailer('\n\n   \n')).toBe(false);
+    });
+    it('is true when a full marker heads the trailer past leading blank lines', () => {
+        expect(isAttestedTrailer(`\n\n${ATTESTED_FORK_LINE}\necho hi\n`)).toBe(true);
+    });
+    // The founding datum: liquid-city labels its block, THEN signs it. A rule that
+    // reads only the trailer's first non-blank line declines this.
+    it('is true for the real liquid-city block — a `# [lc] …` label line above the marker', () => {
+        expect(isAttestedTrailer(`\n${ATTESTED_TRAILER}`)).toBe(true);
+    });
+    it('is true when the marker sits several comment lines deep, still above the first command', () => {
+        expect(isAttestedTrailer(`\n# one\n\n#   two\n${ATTESTED_FORK_LINE}\nsh "x.sh"\n`)).toBe(true);
+    });
+    it('is false once a COMMAND has opened the run — an attestation below code vouches for nothing', () => {
+        expect(isAttestedTrailer(`\necho hi\n${ATTESTED_FORK_LINE}\n`)).toBe(false);
+        expect(isAttestedTrailer(`\n# a label\nsh "x.sh"\n${ATTESTED_FORK_LINE}\n`)).toBe(false);
+    });
+    // A marker riding a command line is not a signature (falsification-leg F10).
+    it('is false when the marker rides a NON-comment line', () => {
+        expect(isAttestedTrailer(`\nrm -rf ./build ${ATTESTED_FORK_LINE.slice(2)}\n`)).toBe(false);
+    });
+    // The marker is parsed per LINE here, so core's multi-line (dotAll) form of it is
+    // deliberately not in play: a marker split across two comment lines does not attest.
+    it('is false when the marker is split across two comment lines', () => {
+        const split = [
+            '',
+            '# [lc] docs-inject extension',
+            '# <!-- totem:fork reason="lc docs-inject pre-commit extension"',
+            '#      owner="satur8d" attested="2026-06-07" -->',
+            'sh "tools/git-hooks/pre-commit-docs-inject.sh"',
+            '',
+        ].join('\n');
+        expect(isAttestedTrailer(split)).toBe(false);
+    });
+    it('is false for a comment run carrying no full marker', () => {
+        expect(isAttestedTrailer('\n# [lc] docs-inject extension\n# <!-- totem:fork -->\nsh "x.sh"\n')).toBe(false);
+    });
+    // Core's parser captures the quoted value raw; a field that is only whitespace
+    // is present to a length check and absent to a reader (Greptile P2, round 1).
+    it('is false when any of the three fields is whitespace-only', () => {
+        const blankReason = '# <!-- totem:fork reason=" " owner="satur8d" attested="2026-06-07" -->';
+        const blankOwner = '# <!-- totem:fork reason="deploy notice" owner="   " attested="2026-06-07" -->';
+        const blankAttested = '# <!-- totem:fork reason="deploy notice" owner="satur8d" attested="\t" -->';
+        const allBlank = '# <!-- totem:fork reason=" " owner=" " attested=" " -->';
+        for (const line of [blankReason, blankOwner, blankAttested, allBlank]) {
+            expect(isAttestedTrailer(`\n${line}\nsh "x.sh"\n`), line).toBe(false);
+        }
+    });
+});
+// ─── declaredHookTier (mmnto-ai/totem#2753) ────────
+describe('declaredHookTier', () => {
+    const block = (lines) => ['#!/bin/sh', `# ${TOTEM_PRECOMMIT_MARKER}`, ...lines, `# ${TOTEM_PRECOMMIT_END}`, ''].join('\n');
+    it('reads the assignment the template emits', () => {
+        expect(declaredHookTier(block(['TOTEM_HOOK_TIER="strict"']), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
+    // Gemini, round 1: an unanchored match would have read the COMMENT first and
+    // re-rendered a standard hook as strict — or, mirrored, a strict one as standard.
+    it('ignores a comment inside the block that quotes the assignment', () => {
+        const content = block([
+            '# TOTEM_HOOK_TIER="strict" turns on the spec-evidence gate below',
+            'TOTEM_HOOK_TIER="standard"',
+        ]);
+        expect(declaredHookTier(content, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('standard');
+    });
+    it('is undefined when the only mention is a comment — a quoted assignment is not a declaration', () => {
+        const content = block(['# TOTEM_HOOK_TIER="strict" was the old default']);
+        expect(declaredHookTier(content, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBeUndefined();
+    });
+    it('still reads a CRLF block', () => {
+        const content = block(['TOTEM_HOOK_TIER="strict"']).replace(/\n/g, '\r\n');
+        expect(declaredHookTier(content, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
+});
+// ─── the hook write is atomic (Greptile P1, mmnto-ai/totem#2760 round 1) ────────
+describe('installGitHook writes atomically', () => {
+    // The attested-extension rewrite carries the consumer's own lines, which no
+    // template can regenerate — so the write must leave the old file or the new one,
+    // never a truncated hook. `writeExecutableHook` routes through core's
+    // `writeFileAtomicSync`: a same-directory temp, mode on the temp, rename last.
+    it('leaves no temp sibling behind and the rewritten hook is executable', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-atomic-'));
+        try {
+            const hooksDir = path.join(tmpDir, 'hooks');
+            fs.mkdirSync(hooksDir);
+            const hookPath = path.join(hooksDir, 'pre-commit');
+            const canonical = buildPreCommitHook(RENDER);
+            fs.writeFileSync(hookPath, `#!/bin/sh\n# ${TOTEM_PRECOMMIT_MARKER}\nstale body\n# ${TOTEM_PRECOMMIT_END}\n${ATTESTED_TRAILER}`);
+            // The control that tells the two implementations apart (re-armed leg F1): an
+            // in-place `writeFileSync` truncates the SAME file — its inode survives — while
+            // rename-over replaces the directory entry with the temp's, so the inode
+            // changes. Cleanup and mode alone were satisfied by the old code too.
+            const inodeBefore = fs.statSync(hookPath, { bigint: true }).ino;
+            const action = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+            expect(action).toBe('block-rewritten');
+            expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical + ATTESTED_TRAILER);
+            expect(fs.statSync(hookPath, { bigint: true }).ino).not.toBe(inodeBefore);
+            // The helper's temp is `<target>.<pid>-<uuid8>.tmp` beside the target; after a
+            // completed write the directory holds the hook alone.
+            expect(fs.readdirSync(hooksDir)).toEqual(['pre-commit']);
+            if (process.platform !== 'win32') {
+                expect(fs.statSync(hookPath).mode & 0o777).toBe(0o755);
+            }
+        }
+        finally {
+            cleanTmpDir(tmpDir);
+        }
+    });
+    // The user's file is carried as BYTES (re-armed leg F8/F9): a hook that does not
+    // round-trip UTF-8 — one cp1252 `0xE9` in a comment — must come back with that
+    // byte, never with U+FFFD (EF BF BD) in its place. Decoding for the probes is
+    // fine; re-encoding for the write is the corruption.
+    const NON_UTF8_COMMENT = Buffer.from([0x23, 0x20, 0x63, 0x61, 0x66, 0xe9, 0x0a]); // "# caf\xE9\n"
+    const REPLACEMENT_CHAR = Buffer.from([0xef, 0xbf, 0xbd]);
+    it('appends to a user hook that is not valid UTF-8 without touching its bytes', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-bytes-'));
+        try {
+            const hooksDir = path.join(tmpDir, 'hooks');
+            fs.mkdirSync(hooksDir);
+            const hookPath = path.join(hooksDir, 'pre-commit');
+            const userBytes = Buffer.concat([
+                Buffer.from('#!/bin/sh\n', 'utf-8'),
+                NON_UTF8_COMMENT,
+                Buffer.from('echo "user hook"\n', 'utf-8'),
+            ]);
+            fs.writeFileSync(hookPath, userBytes);
+            const action = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
+            expect(action).toBe('appended');
+            const after = fs.readFileSync(hookPath);
+            expect(after.subarray(0, userBytes.length).equals(userBytes)).toBe(true);
+            expect(after.includes(REPLACEMENT_CHAR)).toBe(false);
+            expect(after.toString('utf-8')).toContain(TOTEM_PRECOMMIT_MARKER);
+        }
+        finally {
+            cleanTmpDir(tmpDir);
+        }
+    });
+    it('rewrites the managed block and carries a non-UTF-8 attested trailer through byte-for-byte', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-bytes-'));
+        try {
+            const hooksDir = path.join(tmpDir, 'hooks');
+            fs.mkdirSync(hooksDir);
+            const hookPath = path.join(hooksDir, 'pre-commit');
+            const canonical = buildPreCommitHook(RENDER);
+            // The real liquid-city trailer, then one comment line git would never see
+            // as UTF-8. The attestation still parses (it sits above, in the decoded run).
+            const trailerBytes = Buffer.concat([
+                Buffer.from(ATTESTED_TRAILER, 'utf-8'),
+                NON_UTF8_COMMENT,
+            ]);
+            fs.writeFileSync(hookPath, Buffer.concat([
+                Buffer.from(`#!/bin/sh\n# ${TOTEM_PRECOMMIT_MARKER}\nstale body\n# ${TOTEM_PRECOMMIT_END}\n`, 'utf-8'),
+                trailerBytes,
+            ]));
+            const first = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+            expect(first).toBe('block-rewritten');
+            const after = fs.readFileSync(hookPath);
+            const canonicalBytes = Buffer.from(canonical, 'utf-8');
+            expect(after.subarray(0, canonicalBytes.length).equals(canonicalBytes)).toBe(true);
+            expect(after.subarray(canonicalBytes.length).equals(trailerBytes)).toBe(true);
+            expect(after.includes(REPLACEMENT_CHAR)).toBe(false);
+            // Idempotent on the same bytes: the recomposed file equals the file on disk.
+            // `exists` is unambiguous here — the decline below has its own action.
+            const second = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+            expect(second).toBe('exists');
+            expect(fs.readFileSync(hookPath).equals(after)).toBe(true);
+        }
+        finally {
+            cleanTmpDir(tmpDir);
+        }
+    });
+    // The MANAGED REGION itself failing to decode is the one shape the rewrite arm
+    // cannot serve (no provable byte offset), and it must not hide behind `exists`:
+    // three silent runs against a doctor row prescribing the bare install is the
+    // inert-instruction loop this slice exists to remove (re-armed leg F13). The
+    // fixture is the realistic one: an ANSI-editor save turns the template's em dash
+    // (E2 80 94) into the single cp1252 byte 0x97.
+    it('reports skipped-non-utf8 when the managed region does not decode, leaves the file byte-identical, and --force still writes the canonical', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-bytes-'));
+        try {
+            const hooksDir = path.join(tmpDir, 'hooks');
+            fs.mkdirSync(hooksDir);
+            const hookPath = path.join(hooksDir, 'pre-commit');
+            const canonical = buildPreCommitHook(RENDER);
+            const canonicalBytes = Buffer.from(canonical, 'utf-8');
+            const emDash = Buffer.from([0xe2, 0x80, 0x94]);
+            const dashAt = canonicalBytes.indexOf(emDash);
+            expect(dashAt).toBeGreaterThan(-1); // the template's marker line carries one
+            const ansiSaved = Buffer.concat([
+                canonicalBytes.subarray(0, dashAt),
+                Buffer.from([0x97]),
+                canonicalBytes.subarray(dashAt + emDash.length),
+                Buffer.from(ATTESTED_TRAILER, 'utf-8'),
+            ]);
+            fs.writeFileSync(hookPath, ansiSaved);
+            const bare = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+            expect(bare).toBe('skipped-non-utf8');
+            expect(fs.readFileSync(hookPath).equals(ansiSaved)).toBe(true);
+            expect(fs.readdirSync(hooksDir)).toEqual(['pre-commit']);
+            // The prescribed way out writes the canonical alone — nothing of the file is
+            // carried, so the bytes never needed to decode.
+            const forced = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, true, TOTEM_PRECOMMIT_END);
+            expect(forced).toBe('overwritten');
+            expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical);
+        }
+        finally {
+            cleanTmpDir(tmpDir);
+        }
+    });
 });
 // ─── generateHookHelpers ────────────────────────────
 describe('generateHookHelpers', () => {
@@ -672,6 +1145,190 @@ describe('installHooksNonInteractive', () => {
         const result = await installHooksNonInteractive(tmpDir);
         expect(result).toBeNull();
     });
+    // ── The installed tier survives a bare rewrite (mmnto-ai/totem#2753 fold F4) ──
+    //
+    // A bare install exists to keep a hook CURRENT. Re-rendering a `--strict` hook at
+    // `standard` because nobody re-stated the tier is a silent enforcement downgrade
+    // performed by the very command the doctor's stale-block remedy sends people to.
+    it('keeps a strict-installed hook strict on a bare rewrite past an attested trailer', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        fs.writeFileSync(path.join(hooksDir, 'pre-push'), withStaleComment(buildPrePushHook(strict), TOTEM_PREPUSH_END) + ATTESTED_TRAILER);
+        // No flag, no config `hooks.tier` — the hooks' own declaration must decide.
+        const result = await installHooksNonInteractive(tmpDir);
+        expect(result.preCommit).toBe('block-rewritten');
+        expect(result.prePush).toBe('block-rewritten');
+        const preCommit = fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8');
+        const prePush = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
+        expect(declaredHookTier(preCommit, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+        expect(declaredHookTier(prePush, TOTEM_PREPUSH_MARKER, TOTEM_PREPUSH_END)).toBe('strict');
+        expect(preCommit).toBe(buildPreCommitHook(strict) + ATTESTED_TRAILER);
+        expect(prePush.endsWith(ATTESTED_TRAILER)).toBe(true);
+    });
+    it('keeps a strict-installed OWNED-WHOLE hook strict on a bare drift-repair', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END));
+        const result = await installHooksNonInteractive(tmpDir);
+        expect(result.preCommit).toBe('overwritten');
+        expect(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8')).toBe(buildPreCommitHook(strict));
+    });
+    it('lets an explicit tier flag win over the installed hook declaration', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        const downgraded = await installHooksNonInteractive(tmpDir, false, { tier: 'standard' });
+        expect(downgraded.preCommit).toBe('block-rewritten');
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('standard');
+        const upgraded = await installHooksNonInteractive(tmpDir, false, { tier: 'strict' });
+        expect(upgraded.preCommit).toBe('block-rewritten');
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
+    // ── The flag wins when NO config resolves (fold 3 F1) ──
+    //
+    // The test above passes on any machine that happens to carry a global profile at
+    // `~/.totem/totem.config.ts`, because that sends `resolveHookRenderOptions` down
+    // its fully-resolved return. The two EARLY returns — no config anywhere, and a
+    // config that will not load — handed back a `defaults` object with no
+    // `tierPinned`, so the installed hook's declaration overrode the flag. These two
+    // pin those returns with the home directory controlled, so no global profile can
+    // resolve and the outcome does not depend on whose machine runs them.
+    /** Run `body` with `os.homedir()` pointed at an empty directory. */
+    async function withEmptyHome(body) {
+        const home = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-home-'));
+        const saved = { USERPROFILE: process.env.USERPROFILE, HOME: process.env.HOME };
+        process.env.USERPROFILE = home;
+        process.env.HOME = home;
+        try {
+            return await body();
+        }
+        finally {
+            if (saved.USERPROFILE === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = saved.USERPROFILE;
+            if (saved.HOME === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = saved.HOME;
+            cleanTmpDir(home);
+        }
+    }
+    it('lets an explicit tier flag win when NO config resolves at all', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        await withEmptyHome(async () => {
+            // No local config in tmpDir, no global profile under the empty home →
+            // `resolveConfigPath` throws and the config-missing early return is taken.
+            const result = await installHooksNonInteractive(tmpDir, false, { tier: 'standard' });
+            expect(result.preCommit).toBe('block-rewritten');
+        });
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('standard');
+    });
+    it('lets --strict UPGRADE a standard-installed hook when no config resolves', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const standard = { ...RENDER, fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(standard), TOTEM_PRECOMMIT_END));
+        await withEmptyHome(async () => {
+            const result = await installHooksNonInteractive(tmpDir, false, { tier: 'strict' });
+            expect(result.preCommit).toBe('overwritten');
+        });
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
+    it('lets an explicit tier flag win when the config RESOLVES but will not load', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        // A local config that resolves and then fails to parse → the LOUD-defaults
+        // early return (mmnto-ai/totem#2692 A8).
+        fs.writeFileSync(path.join(tmpDir, 'totem.yaml'), ':\n  not: [valid\n');
+        const stderr = [];
+        const spy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+            stderr.push(args.map(String).join(' '));
+        });
+        try {
+            await withEmptyHome(async () => {
+                const result = await installHooksNonInteractive(tmpDir, false, { tier: 'standard' });
+                expect(result.preCommit).toBe('block-rewritten');
+            });
+        }
+        finally {
+            spy.mockRestore();
+        }
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('standard');
+        // The loud line must not claim a tier it does not decide (fold 4 F6): the
+        // defaults it names are the totemDir only.
+        const loud = stderr.find((line) => line.includes('rendered at the defaults')) ?? '';
+        expect(loud).toContain("the tier follows an explicit flag, else the tier each installed hook declares, else 'standard'");
+        expect(loud).not.toContain("tier 'standard')");
+    });
+    it('lets --strict UPGRADE a standard-installed hook when the config will not load', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const standard = { ...RENDER, fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(standard), TOTEM_PRECOMMIT_END));
+        fs.writeFileSync(path.join(tmpDir, 'totem.yaml'), ':\n  not: [valid\n');
+        const spy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        try {
+            await withEmptyHome(async () => {
+                const result = await installHooksNonInteractive(tmpDir, false, { tier: 'strict' });
+                expect(result.preCommit).toBe('overwritten');
+            });
+        }
+        finally {
+            spy.mockRestore();
+        }
+        expect(declaredHookTier(fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
+    it('renders --force at the installed tier when nothing is pinned', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END) + ATTESTED_TRAILER);
+        // `--force` rewrites the WHOLE file (the trailer is gone) but it is still not a
+        // tier decision: with no flag and no `hooks.tier`, the hook keeps the tier it
+        // declared.
+        await withEmptyHome(async () => {
+            const result = await installHooksNonInteractive(tmpDir, true);
+            expect(result.preCommit).toBe('overwritten');
+        });
+        const written = fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8');
+        expect(declaredHookTier(written, TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+        expect(written).not.toContain('totem:fork');
+    });
+    it('keeps a strict hook-manager helper strict when nothing is pinned', async () => {
+        execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+        // A husky repo: `installHooksNonInteractive` takes the manager path, which
+        // regenerates `<totemDir>/hooks/*.sh` instead of writing .git/hooks.
+        fs.mkdirSync(path.join(tmpDir, '.husky'), { recursive: true });
+        const helperDir = path.join(tmpDir, '.totem', 'hooks');
+        fs.mkdirSync(helperDir, { recursive: true });
+        const strict = { ...RENDER, tier: 'strict', fallbackCmd: getFallbackCommand(tmpDir) };
+        fs.writeFileSync(path.join(helperDir, 'pre-push.sh'), withStaleComment(buildPrePushHook(strict), TOTEM_PREPUSH_END));
+        fs.writeFileSync(path.join(helperDir, 'pre-commit.sh'), withStaleComment(buildPreCommitHook(strict), TOTEM_PRECOMMIT_END));
+        await withEmptyHome(async () => {
+            // Manager detected → null result, helpers regenerated.
+            expect(await installHooksNonInteractive(tmpDir)).toBeNull();
+        });
+        expect(declaredHookTier(fs.readFileSync(path.join(helperDir, 'pre-push.sh'), 'utf-8'), TOTEM_PREPUSH_MARKER, TOTEM_PREPUSH_END)).toBe('strict');
+        expect(declaredHookTier(fs.readFileSync(path.join(helperDir, 'pre-commit.sh'), 'utf-8'), TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END)).toBe('strict');
+    });
     it('installs all four hooks in a git repo', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
@@ -1140,6 +1797,22 @@ fi
         const actual = extractTotemBlock(content);
         expect(actual).toBe(expectedTotemBlock());
     });
+    // The splice keeps the user's text on both sides of the block, so it is byte-exact
+    // only for a file that decodes losslessly; one that does not is declined with the
+    // upgrader's ruled silent `false` and left byte-identical (re-armed leg F9/F15).
+    it('declines a hook that does not decode as UTF-8 and leaves it byte-identical', async () => {
+        const hooksDir = path.join(tmpDir, '.git', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const oldHook = Buffer.concat([
+            Buffer.from(`#!/bin/sh\n# ${TOTEM_PREPUSH_MARKER} `, 'utf-8'),
+            Buffer.from([0x97]), // the em dash as one cp1252 byte — an ANSI-editor save
+            Buffer.from(' run compiled rules before push.\n# Override with: git push --no-verify\n\nif [ -f ".totem/compiled-rules.json" ]; then\n  TOTEM_CMD="totem"\n  if [ -n "$TOTEM_CMD" ]; then\n    $TOTEM_CMD lint\n  fi\nfi\n', 'utf-8'),
+        ]);
+        fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldHook);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
+        expect(upgraded).toBe(false);
+        expect(fs.readFileSync(path.join(hooksDir, 'pre-push')).equals(oldHook)).toBe(true);
+    });
     it('skips hook without totem marker', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
@@ -1410,7 +2083,15 @@ describe('buildPreCommitHook with strict tier', () => {
     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)"`);
+        // printf, not echo (mmnto-ai/totem#2737 fold 3): `dash` — /bin/sh on Debian
+        // and Ubuntu — expands backslash escapes in `echo`, so a literal `\n` in an
+        // artifact value forged a second [Totem] line there while staying inert
+        // under bash. The two sinks that carry $spec_evidence print literally.
+        const bs = String.fromCharCode(0x5c);
+        expect(hook).toContain(`printf '%s${bs}n' "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"`);
+        expect(hook).toContain(`printf '%s${bs}n' "[Totem] spec evidence: $spec_evidence"`);
+        expect(hook).not.toContain('echo "[Totem] spec evidence:');
+        expect(hook).not.toContain('echo "[Totem] BLOCKED: $spec_evidence');
         // 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');
@@ -1660,7 +2341,7 @@ describe('buildPreCommitHook anchored evidence — executed under sh (mmnto-ai/t
         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', () => {
+    it.skipIf(!shellOk)('a promised heading present over an EMPTY body BLOCKS, naming the empty heading', () => {
         writeRun('empty.json', specEvidenceArtifact({
             output: { content: '### Problem Statement\n\n### Implementation Tasks\n' },
         }));
@@ -1669,10 +2350,17 @@ describe('buildPreCommitHook anchored evidence — executed under sh (mmnto-ai/t
         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', () => {
+    it.skipIf(!shellOk)('a LATER required heading left empty BLOCKS, naming THAT heading', () => {
+        // Every heading the promise names BEFORE `### Implementation Tasks` gets a
+        // body, so the reader reaches it rather than blocking earlier on a missing
+        // one: the assertion is about which heading is NAMED, and it can only be
+        // about that if the draft is well-formed right up to the mutation
+        // (mmnto-ai/totem#2737 extended the promise from two headings to nine).
         writeRun('half.json', specEvidenceArtifact({
             output: {
-                content: '### Problem Statement\n\nA real body.\n\n### Implementation Tasks\n',
+                content: SPEC_REQUIRED_SECTIONS.map((heading) => heading === '### Implementation Tasks'
+                    ? `${heading}\n`
+                    : `${heading}\n\nA real body.\n`).join('\n'),
             },
         }));
         const r = runHook();
@@ -1848,6 +2536,68 @@ describe('buildPreCommitHook anchored evidence — executed under sh (mmnto-ai/t
         expect(r.stdout).toContain('slug?[Totem] spec evidence: forged');
         expect(r.stdout).not.toContain(String.fromCharCode(0x85));
     });
+    it.skipIf(!shellOk)('a U+2028 in anchor.ref is collapsed and cannot forge a second [Totem] line', () => {
+        // The third member of the newline family: U+2028 LINE SEPARATOR is a
+        // PRINTABLE-plane code point that terminals and pagers still break on, so
+        // a `safe()` stopping at the C1 band left it through (mmnto-ai/totem#2737).
+        const ls = String.fromCharCode(0x2028);
+        const forged = `slug${ls}[Totem] spec evidence: forged`;
+        writeRun('ls.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(ls);
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+    });
+    // ── The forge that lives in PRINTABLE bytes (mmnto-ai/totem#2737 fold 3) ──
+    //
+    // `safe()` cannot close this one: a literal backslash followed by `n` is two
+    // printable characters (0x5c, 0x6e), so it passes every control-character
+    // predicate untouched. The expansion happens at the SHELL, wherever `/bin/sh`
+    // expands backslash escapes in `echo` — `dash` on Debian and Ubuntu, and
+    // macOS's `/bin/sh`, a bash built with `xpg_echo` on — where the pair becomes
+    // a real newline and forges the second `[Totem]` line. The cure is the sink,
+    // not the sanitizer: both values print through `printf '%s\n'`, which treats
+    // its argument as literal text on every POSIX shell.
+    //
+    // NOTE ON REACH: `sh` on this machine is Git Bash's bash, whose `echo` does
+    // NOT expand the escape, so these two tests pass here even against the
+    // unfixed hook. Git Bash and a plain bash are the only shells that leave it
+    // inert; these are real falsifiers on the Ubuntu and macOS CI legs. Measured
+    // directly against `/usr/bin/dash` before the fix: TWO [Totem] lines; after:
+    // one.
+    it.skipIf(!shellOk)('a literal backslash-n in anchor.ref cannot forge a second [Totem] line under any /bin/sh', () => {
+        const bs = String.fromCharCode(0x5c);
+        const forged = `2737${bs}n[Totem] spec evidence: FORGED`;
+        writeRun('backslash-n.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: forged } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        // The two characters survive as themselves — not expanded, not stripped.
+        expect(r.stdout).toContain(`2737${bs}n[Totem] spec evidence: FORGED`);
+    });
+    it.skipIf(!shellOk)('a literal backslash-n in a tolerantly-matched heading cannot forge a second [Totem] line', () => {
+        // The same payload on the fold's newest sink: the `(matched as …)` clause
+        // echoes a line taken from the DRAFT, which is attacker-shaped text.
+        const bs = String.fromCharCode(0x5c);
+        const promised = SPEC_SYSTEM_PROMPT.split('\n').filter((line) => line.startsWith('### '));
+        const verification = promised.find((h) => h.startsWith('### Verification')) ?? '';
+        const forgedHeading = `### Verification (${bs}n[Totem] spec evidence: FORGED)`;
+        const content = promised
+            .map((heading) => heading === verification
+            ? `${forgedHeading}\n`
+            : `${heading}\n\nA non-blank body under ${heading}.\n`)
+            .join('\n');
+        writeRun('tolerant-forge.json', specEvidenceArtifact({ output: { content } }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        expect(r.stdout).toContain(`(matched as ${forgedHeading})`);
+    });
     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
@@ -2196,22 +2946,33 @@ describe('buildPrePushHook — the review-leg floor arm (mmnto-ai/totem#2698)',
         // 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', () => {
+    it('invokes the bare gate on strict and the advisory form otherwise, recording the status on BOTH arms', () => {
         expect(hook).toContain('$TOTEM_CMD legs gate\n');
-        expect(hook).toContain('$TOTEM_CMD legs gate --advisory');
-        expect(hook).toContain('legs_status=$?');
+        expect(hook).toContain('$TOTEM_CMD legs gate --advisory\n      legs_status=$?');
+        expect(hook).toContain('legs_strict=1\n      $TOTEM_CMD legs gate\n      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)"');
+    it('blocks on exit 3 and exit 2 at ANY tier with DISTINCT lines that name the knob; any other non-zero blocks on strict only (mmnto-ai/totem#2771)', () => {
+        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, an agent seat, or hooks.legsOwed.enforce: block)"`);
+        expect(hook).toContain('echo "[Totem] BLOCKED: the legs gate could not derive (totem legs gate exit status 2) — fix the checkout and retry (strict mode, an agent seat, or hooks.legsOwed.enforce: block)"');
+        expect(hook).toContain('echo "[Totem] BLOCKED: the legs gate failed before deriving (totem legs gate exit status $legs_status) — fix the config or the CLI and retry (strict mode or an agent seat)"');
         expect(hook).toContain('if [ "$legs_status" = "3" ]; then');
-        expect(hook).toContain('elif [ "$legs_status" != "0" ]; then');
+        expect(hook).toContain('elif [ "$legs_status" = "2" ]; then');
+        expect(hook).toContain('elif [ "$legs_status" != "0" ] && [ "$legs_strict" = "1" ]; then');
+        // The mapping sits AFTER both invocations, outside the tier guard: the
+        // advisory arm falls through to the same three checks the strict arm does.
+        const advisoryIdx = hook.indexOf('$TOTEM_CMD legs gate --advisory');
+        const mappingIdx = hook.indexOf('if [ "$legs_status" = "3" ]; then');
+        expect(advisoryIdx).toBeGreaterThan(-1);
+        expect(mappingIdx).toBeGreaterThan(advisoryIdx);
+        // And the hook never reads the config itself — the knob reaches it only as
+        // an exit code (the gate is the one reader of hooks.legsOwed.enforce).
+        expect(hook).not.toContain('totem.config');
     });
     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] 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 or an agent seat)" >&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', () => {
@@ -2369,8 +3130,8 @@ describe('the review-leg floor arm executed under sh (mmnto-ai/totem#2698)', ()
         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 });
+    it.skipIf(!shellOk)('standard tier, no agent: --advisory is passed and exit 0 proceeds past the arm', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 0 });
         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.
@@ -2379,6 +3140,44 @@ describe('the review-leg floor arm executed under sh (mmnto-ai/totem#2698)', ()
         expect(r.status).toBe(0);
         expect(r.stdout).not.toContain('BLOCKED');
     });
+    // Since mmnto-ai/totem#2771 the advisory arm's exit code is READ. A real gate
+    // under --advisory returns 3 or 2 only when hooks.legsOwed.enforce says
+    // block, so a stub exiting 3 here IS the knob's shape as the hook sees it.
+    it.skipIf(!shellOk)('standard tier + gate exit 3 (the enforce: block shape): BLOCKS with the line that names the knob', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 3 });
+        const r = runHook({ tier: 'standard', agent: false });
+        expect(invocations()).toContain('legs gate --advisory');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed');
+        expect(r.stdout).toContain('strict mode, an agent seat, or hooks.legsOwed.enforce: block');
+        expect(r.stdout).toContain('[Totem] legs: stub gate line');
+    });
+    it.skipIf(!shellOk)('standard tier + gate exit 2: blocks with the DISTINCT not-derived line', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 2 });
+        const r = runHook({ tier: 'standard', agent: false });
+        expect(invocations()).toContain('legs gate --advisory');
+        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');
+    });
+    // A PIN, not a falsifier: this case holds on the pre-knob hook too (whose
+    // standard arm never read the status at all). It is here so the one
+    // behaviour the knob must NOT change stays asserted next to the ones it does.
+    it.skipIf(!shellOk)('standard tier + gate exit 1 (a failure BEFORE the derivation): passes, byte for byte the pre-knob behaviour', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 1 });
+        const r = runHook({ tier: 'standard', agent: false });
+        expect(invocations()).toContain('legs gate --advisory');
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('strict tier + gate exit 1: blocks with the failed-before-deriving line, not the not-derived one', () => {
+        writeStub({ helpText: HELP_WITH_GATE, gateExit: 1 });
+        const r = runHook({ tier: 'strict', agent: false });
+        expect(invocations()).toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the legs gate failed before deriving (totem legs gate exit status 1)');
+        expect(r.stdout).not.toContain('could not derive');
+    });
 });
 // The arm COMPOSED with the real gate (mmnto-ai/totem#2698 fold 2, MATERIAL).
 //
@@ -2497,8 +3296,8 @@ describe('the review-leg floor arm COMPOSED with the real gate (mmnto-ai/totem#2
         process.chdir(realCwd);
         cleanTmpDir(tmpDir);
     });
-    function runHook() {
-        fs.writeFileSync(path.join(repoDir, 'pre-push'), buildPrePushHook({ ...RENDER, tier: 'strict' }));
+    function runHook(tier = 'strict') {
+        fs.writeFileSync(path.join(repoDir, 'pre-push'), buildPrePushHook({ ...RENDER, tier }));
         const env = {
             ...process.env,
             PATH: [binDir, process.env['PATH'] ?? ''].join(path.delimiter),
@@ -2509,6 +3308,20 @@ describe('the review-leg floor arm COMPOSED with the real gate (mmnto-ai/totem#2
         const result = spawnSync('sh', ['./pre-push'], { cwd: repoDir, env, encoding: 'utf-8' });
         return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
     }
+    /**
+     * Rewrite the fixture's config with the knob — in the WORKING TREE only. The
+     * gate judges the committed branch diff, so an uncommitted config edit never
+     * enters the owed set; the gate's config LOAD reads the working file.
+     */
+    function setEnforce(enforce) {
+        fs.writeFileSync(path.join(repoDir, 'totem.config.ts'), [
+            'export default {',
+            "  targets: [{ glob: 'docs/**/*.md', type: 'spec', strategy: 'markdown-heading' }],",
+            `  hooks: { legsOwed: { globs: ['docs/**'], enforce: '${enforce}' } },`,
+            '};',
+            '',
+        ].join(NL));
+    }
     const invocations = () => {
         const native = logPath.split('/').join(path.sep);
         return fs.existsSync(native) ? fs.readFileSync(native, 'utf-8').trim().split(NL) : [];
@@ -2624,5 +3437,708 @@ describe('the review-leg floor arm COMPOSED with the real gate (mmnto-ai/totem#2
         expect(r.stdout).toContain('[Totem] legs: not owed — no changed path matched hooks.legsOwed.globs (1 globs; head');
         expect(r.stdout).not.toContain('BLOCKED');
     });
+    // The knob, end to end (mmnto-ai/totem#2771): the config declares it, the
+    // REAL gate reads it and maps the exit, the STANDARD-tier hook — which passes
+    // --advisory and, before the knob, ignored the status entirely — blocks on
+    // what comes back. No stub scripts the 3 here; the derivation produces it.
+    it.skipIf(!composedOk)("OWED, no deposit, STANDARD tier, hooks.legsOwed.enforce: 'block': the hook blocks and names the knob", () => {
+        setEnforce('block');
+        const r = runHook('standard');
+        // The advisory FLAG was passed — the tier did not change — and the gate
+        // still returned 3 because the knob overrode it.
+        expect(invocations()).toContain('legs gate --advisory');
+        expect(invocations()).not.toContain('legs gate');
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed (docs/** →');
+        expect(r.stdout).toContain('[Totem] legs: hooks.legsOwed.enforce = block');
+        expect(r.stdout).toContain('strict mode, an agent seat, or hooks.legsOwed.enforce: block');
+        // The shield block after the arm was never reached.
+        expect(invocations()).not.toContain('doctor --strict');
+    });
+    it.skipIf(!composedOk)("OWED, no deposit, STRICT tier, hooks.legsOwed.enforce: 'advisory': the gate's text prints, the hook passes", () => {
+        setEnforce('advisory');
+        const r = runHook('strict');
+        expect(invocations()).toContain('legs gate');
+        // The gate's own verdict text is byte-identical to the blocking case —
+        // only the exit code moved — and the knob line says why.
+        expect(r.stdout).toContain('[Totem] BLOCKED: this push is legs-owed (docs/** →');
+        expect(r.stdout).toContain('[Totem] legs: hooks.legsOwed.enforce = advisory');
+        // The HOOK's block line never fires, and the hook proceeds to the shield block.
+        expect(r.stdout).not.toContain('strict mode, an agent seat, or hooks.legsOwed.enforce: block');
+        expect(invocations()).toContain('doctor --strict');
+        expect(r.status).toBe(0);
+    });
+    it.skipIf(!composedOk)("OWED with a covering ANCESTOR deposit under enforce: 'block' on the STANDARD tier: the hook passes on evidence", () => {
+        setEnforce('block');
+        deposit(ancestorSha);
+        const r = runHook('standard');
+        expect(invocations()).toContain('legs gate --advisory');
+        expect(r.stdout).toContain('[Totem] legs evidence: .totem/artifacts/legs/');
+        expect(r.stdout).toContain('[Totem] legs: hooks.legsOwed.enforce = block');
+        expect(r.stdout).not.toContain('BLOCKED');
+        expect(r.status).toBe(0);
+    });
+});
+// ─── Fences and bare hash lines (mmnto-ai/totem#2769) ─────
+//
+// Two holes the mmnto-ai/totem#2759 round declined as pre-existing. Each
+// NEGATIVE case here passes on the reader as it stood on main (a lone `####`
+// counted as body; a promised heading inside a fenced block matched); each must
+// BLOCK after. The POSITIVE cases pin what the fix must not take with it: a
+// section whose only content is a code block is a written section, and a
+// fenced quote of a heading beside a real section changes nothing.
+describe('buildPreCommitHook spec-gate reader — fences and bare hash lines (mmnto-ai/totem#2769)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    const PROMISED = SPEC_SYSTEM_PROMPT.split('\n').filter((line) => line.startsWith('### '));
+    function promised(prefix) {
+        const found = PROMISED.find((heading) => heading.startsWith(prefix));
+        if (found === undefined)
+            throw new Error(`no promised heading starts with ${prefix}`);
+        return found;
+    }
+    const EDGE_CASES = promised('### Edge Cases');
+    const EXECUTION_FLOW = promised('### Execution Flow');
+    const TEST_PLAN = promised('### Test Plan');
+    /** Three backticks, built rather than authored (three quoting layers sit between here and the reader). */
+    const FENCE = String.fromCharCode(96, 96, 96);
+    const NL = String.fromCharCode(10);
+    function nineBodied(overrides = {}) {
+        return PROMISED.map((heading) => {
+            const override = overrides[heading];
+            return override === undefined
+                ? `${heading}${NL}${NL}A non-blank body under ${heading}.${NL}`
+                : override;
+        })
+            .filter((block) => block.length > 0)
+            .join(NL);
+    }
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-2769-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/fence-suite', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook(RENDER));
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+    });
+    function judge(content) {
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'draft.json'), JSON.stringify(specEvidenceArtifact({ output: { content } }), null, 2));
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        return { status: r.status, stdout: r.stdout };
+    }
+    // ── Negative: pass today, must block ──
+    it.skipIf(!shellOk)('a lone #### line is not a body (hole 1)', () => {
+        const r = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}${NL}####${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+    });
+    it.skipIf(!shellOk)('a run of # characters with only whitespace around it is not a body either', () => {
+        const r = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}${NL}   ###   ${NL}#${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+    });
+    it.skipIf(!shellOk)('the promised skeleton quoted inside a fenced block is not the sections it names (hole 2)', () => {
+        const r = judge(`Some prose about the draft.${NL}${NL}${FENCE}${NL}${nineBodied()}${NL}${FENCE}${NL}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+    });
+    it.skipIf(!shellOk)('a tilde fence hides a heading the same way', () => {
+        const r = judge(nineBodied({ [TEST_PLAN]: `~~~${NL}${TEST_PLAN}${NL}${NL}quoted, not written${NL}~~~${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${TEST_PLAN}`);
+    });
+    it.skipIf(!shellOk)('a heading whose only content is an EMPTY fence is empty', () => {
+        const r = judge(nineBodied({ [EXECUTION_FLOW]: `${EXECUTION_FLOW}${NL}${FENCE}${NL}${FENCE}${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EXECUTION_FLOW}`);
+    });
+    // ── Positive: must keep passing ──
+    it.skipIf(!shellOk)('a section whose only content is a code block is a written section', () => {
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: `${EXECUTION_FLOW}${NL}${FENCE}mermaid${NL}A --> B${NL}${FENCE}${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('a fenced quote of a heading beside the real section changes nothing', () => {
+        const r = judge(nineBodied({
+            [TEST_PLAN]: `${TEST_PLAN}${NL}${NL}Real plan text.${NL}${NL}${FENCE}${NL}${EDGE_CASES}${NL}(quoted as an example)${NL}${FENCE}${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+        expect(r.stdout).not.toContain('tolerated');
+    });
+    it.skipIf(!shellOk)('a heading that appears fenced first and real later is found at the real line — the disclosure proves which', () => {
+        // The EXACT promised heading sits inside a fence; the real section below
+        // is written in the TOLERANT form. On the pre-fix reader the exact pass
+        // matched the fenced copy and the pass line carried no tolerance; skipping
+        // the fenced copy makes the tolerant pass find the real line and SAY so.
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: `${FENCE}${NL}${EXECUTION_FLOW}${NL}${FENCE}${NL}${NL}### Execution Flow${NL}${NL}The real section, in the tolerant spelling.${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+        expect(r.stdout).toContain(`tolerated ${EXECUTION_FLOW} ~ ### Execution Flow`);
+    });
+    it.skipIf(!shellOk)('an unclosed fence runs to the end of the draft, and the block says where it opened', () => {
+        // Everything after an unclosed opener is inside the fence: the headings
+        // quoted there are not candidates, so the draft is missing them — and the
+        // reason names the fence, so the cure is never a heading the draft contains.
+        const r = judge(`Intro.${NL}${FENCE}${NL}${nineBodied()}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+        expect(r.stdout).toContain('it appears only inside a fenced code block opened at line 2');
+        expect(r.stdout).toContain('that fence is never closed');
+    });
+    // ── The fence state's edges (the leg's probes, pinned) ──
+    it.skipIf(!shellOk)('a three-backtick line does not close a four-backtick fence', () => {
+        // CommonMark: the closer is the same character, at least as long. A draft
+        // wrapped in a four-backtick fence with one nested three-backtick example
+        // is one code block with zero headings.
+        const FENCE4 = FENCE + String.fromCharCode(96);
+        const r = judge(`Intro prose.${NL}${FENCE4}${NL}quoted example:${NL}${FENCE}${NL}${nineBodied()}${NL}${FENCE4}${NL}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+        expect(r.stdout).toContain('inside a fenced code block opened at line 2');
+    });
+    it.skipIf(!shellOk)('a four-backtick closer closes a three-backtick fence', () => {
+        const FENCE4 = FENCE + String.fromCharCode(96);
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: `${EXECUTION_FLOW}${NL}${FENCE}${NL}A --> B${NL}${FENCE4}${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('a fence line indented four spaces is not a fence (an indented code block, or a lazy continuation after a paragraph)', () => {
+        // CommonMark: up to three spaces of indentation keeps a fence a fence; four
+        // makes it an indented code block. The DISCRIMINATING shape: an indented
+        // fence line with the whole skeleton after it and no closer. A reader that
+        // treated the indented line as an opener would swallow every heading; this
+        // one reads it as text, so the draft passes.
+        const r = judge(`Intro.${NL}    ${FENCE}${NL}${nineBodied()}`);
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('a backtick opener whose info string carries a backtick is not a fence', () => {
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: `${EXECUTION_FLOW}${NL}${FENCE}js${String.fromCharCode(96)}x${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('a run of tildes used as a divider opens a fence in Markdown too, and the block says so', () => {
+        // Twenty tildes are a fence opener under CommonMark (a thematic break is
+        // ---, *** or ___); every heading after it is code until a closer at
+        // least as long. The block names the fence rather than a heading the
+        // draft contains verbatim.
+        const rule = '~'.repeat(20);
+        const r = judge(nineBodied({ [PROMISED[1]]: `${PROMISED[1]}${NL}${NL}Body.${NL}${NL}${rule}${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[2]}`);
+        // Line 9: three lines for the first section, one blank, then the override's
+        // heading, blank, body, blank, and the divider.
+        expect(r.stdout).toContain('it appears only inside a fenced code block opened at line 9');
+        expect(r.stdout).toContain('that fence is never closed');
+    });
+    it.skipIf(!shellOk)('a fenced promised heading in its TOLERANT spelling is not body either', () => {
+        // The matcher treats the parenthetical-dropped spelling as the same heading;
+        // the body rule now does too, whatever the indentation inside the fence.
+        const tolerant = EXECUTION_FLOW.replace(/ \([^)]*\)$/, '');
+        expect(tolerant).not.toBe(EXECUTION_FLOW);
+        const r = judge(nineBodied({
+            [EDGE_CASES]: `${EDGE_CASES}${NL}${FENCE}${NL}  ${tolerant}${NL}${FENCE}${NL}`,
+        }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+        expect(r.stdout).toContain('nothing under it counts as body: a promised heading quoted inside a fenced code block');
+    });
+    it.skipIf(!shellOk)('an INDENTED fenced copy of a missing heading is still found and named', () => {
+        const indented = nineBodied()
+            .split(NL)
+            .map((line) => `  ${line}`)
+            .join(NL);
+        const r = judge(`Prose.${NL}${FENCE}${NL}${indented}${NL}${FENCE}${NL}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+        expect(r.stdout).toContain('it appears only inside a fenced code block opened at line 2');
+        // Closed fence: the cure is to write the section outside it, not to close it.
+        expect(r.stdout).toContain('write the section outside the fence');
+        expect(r.stdout).not.toContain('never closed');
+    });
+    it.skipIf(!shellOk)('a lone #### under a heading names the rule that emptied the section', () => {
+        const r = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}${NL}####${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES} — nothing under it counts as body: a line of # characters`);
+    });
+    it.skipIf(!shellOk)('every rule that emptied a section is named, and an empty fence pair is one of them', () => {
+        // Both rules at once: a bare hash line and a fenced promised heading.
+        const both = judge(nineBodied({
+            [EDGE_CASES]: `${EDGE_CASES}${NL}####${NL}${FENCE}${NL}${TEST_PLAN}${NL}${FENCE}${NL}`,
+        }));
+        expect(both.status).toBe(1);
+        expect(both.stdout).toContain('nothing under it counts as body: a promised heading quoted inside a fenced code block; a line of # characters');
+        // An empty fence pair is a rule this slice introduced; it names itself too.
+        const empty = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}${NL}${FENCE}${NL}${FENCE}${NL}` }));
+        expect(empty.status).toBe(1);
+        expect(empty.stdout).toContain('nothing under it counts as body: an empty fenced code block');
+    });
+    it.skipIf(!shellOk)('a closing fence that repeats the info string does not close (the cure names a bare closer)', () => {
+        // A common model output error: ```mermaid … ```mermaid. Under CommonMark the
+        // second line is not a closer, so every heading after it is fenced.
+        const idx = PROMISED.indexOf(EXECUTION_FLOW);
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: `${EXECUTION_FLOW}${NL}${FENCE}mermaid${NL}A --> B${NL}${FENCE}mermaid${NL}`,
+        }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[idx + 1]}`);
+        expect(r.stdout).toContain('close it with a bare closing fence');
+    });
+    it.skipIf(!shellOk)('the never-closed cure is offered only for the fence the copy sits in', () => {
+        // Test Plan exists only as a copy inside a CLOSED fence; an unrelated fence
+        // is left open at the end of the draft. The cure must not blame that one.
+        const r = judge(`${nineBodied({
+            [EDGE_CASES]: `${EDGE_CASES}${NL}${NL}A real body line.${NL}${NL}${FENCE}${NL}${TEST_PLAN}${NL}${FENCE}${NL}`,
+            [TEST_PLAN]: '',
+        })}${NL}${FENCE}${NL}stray, never closed${NL}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${TEST_PLAN}`);
+        expect(r.stdout).toContain('write the section outside the fence');
+        expect(r.stdout).not.toContain('never closed');
+    });
+    it.skipIf(!shellOk)('RECORD: a bound record whose only headings sit inside a fence has no heading with a body', () => {
+        const abs = path.join(tmpDir, '.totem', 'specs', 'rec.md');
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, `${FENCE}yaml${NL}# Problem${NL}problem: the thing${NL}${FENCE}${NL}`, 'utf-8');
+        const sha256 = crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'draft.json'), JSON.stringify(specEvidenceArtifact({
+            grounding: {
+                anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/rec.md', sha256 },
+            },
+        }), null, 2));
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record at .totem/specs/rec.md has no heading with a body');
+        // A real heading above the fence cures it — the record is edited, not re-run.
+        fs.writeFileSync(abs, `# Record${NL}${NL}${FENCE}yaml${NL}problem: the thing${NL}${FENCE}${NL}`, 'utf-8');
+        const sha2 = crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+        fs.writeFileSync(path.join(dir, 'draft.json'), JSON.stringify(specEvidenceArtifact({
+            grounding: {
+                anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/rec.md', sha256: sha2 },
+            },
+        }), null, 2));
+        const ok = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        expect(ok.status).toBe(0);
+        expect(ok.stdout).toContain('record sha256 matches');
+    });
+    it.skipIf(!shellOk)('#### inside a fence is code, and code is body', () => {
+        const r = judge(nineBodied({
+            [EDGE_CASES]: `${EDGE_CASES}${NL}${FENCE}${NL}####${NL}#####${NL}${FENCE}${NL}`,
+        }));
+        expect(r.status).toBe(0);
+        expect(r.stdout).not.toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('seven hashes are a bare hash line, not a heading and not a body', () => {
+        const r = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}${NL}#######${NL}` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+    });
+    it.skipIf(!shellOk)('a fenced promised heading is not body for the section above it', () => {
+        // Zero authored words: the only content under Edge Cases is the next
+        // promised heading, quoted. Not a written section.
+        const r = judge(nineBodied({
+            [EDGE_CASES]: `${EDGE_CASES}${NL}${FENCE}${NL}${PROMISED[PROMISED.indexOf(EDGE_CASES) + 1]}${NL}${FENCE}${NL}`,
+        }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+    });
+    it.skipIf(!shellOk)('a closer followed by a non-breaking space does not close the fence', () => {
+        // CommonMark permits only spaces and tabs after a closing fence; JS trim()
+        // would accept U+00A0 and close a fence Markdown keeps open, letting the
+        // skeleton after it reach the gate.
+        const NBSP = String.fromCharCode(160);
+        const r = judge(`Intro.${NL}${FENCE}${NL}quoted${NL}${FENCE}${NBSP}${NL}${nineBodied()}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+        expect(r.stdout).toContain('that fence is never closed');
+        // A closer followed by ordinary spaces and a tab still closes.
+        const TAB = String.fromCharCode(9);
+        const ok = judge(`Intro.${NL}${FENCE}${NL}quoted${NL}${FENCE}  ${TAB}${NL}${NL}${nineBodied()}`);
+        expect(ok.status).toBe(0);
+    });
+    it.skipIf(!shellOk)('a matching delimiter indented four spaces does not close the fence', () => {
+        // CommonMark: a closing fence may be indented at most three spaces. The
+        // reader counts the run only when the indent is under four, so a
+        // four-space delimiter is text inside the fence and the skeleton after it
+        // stays fenced (Greptile follow-up on mmnto-ai/totem#2769).
+        const r = judge(`Intro.${NL}${FENCE}${NL}quoted${NL}    ${FENCE}${NL}${nineBodied()}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROMISED[0]}`);
+        expect(r.stdout).toContain('that fence is never closed');
+        // Three spaces still close.
+        const ok = judge(`Intro.${NL}${FENCE}${NL}quoted${NL}   ${FENCE}${NL}${NL}${nineBodied()}`);
+        expect(ok.status).toBe(0);
+    });
+    // ── The DOCUMENT arm (overridden prompt, bound record) under fences ──
+    function judgeDocument(content) {
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'draft.json'), JSON.stringify(specEvidenceArtifact({
+            admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE } },
+            output: { content },
+        }), null, 2));
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        return { status: r.status, stdout: r.stdout };
+    }
+    it.skipIf(!shellOk)('DOCUMENT: a heading that exists only inside a fence is no heading', () => {
+        // A YAML document whose "# Problem" lines sit inside a fence has no
+        // markdown heading at all; the pre-fix reader read the comments as headings.
+        const r = judgeDocument(`The spec, as YAML:${NL}${NL}${FENCE}yaml${NL}# Problem${NL}problem: the thing${NL}# Tasks${NL}tasks: [a, b]${NL}${FENCE}${NL}`);
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has no heading with a body');
+    });
+    it.skipIf(!shellOk)('DOCUMENT: a real heading whose body is a code block is bodied', () => {
+        const r = judgeDocument(`## The spec${NL}${NL}${FENCE}yaml${NL}problem: the thing${NL}${FENCE}${NL}`);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('shape DOCUMENT');
+    });
+});
+// ─── The frozen mutation suite (mmnto-ai/totem#2737) ─────
+//
+// Authored against the FINAL contract — all NINE promised headings — and run
+// once against the UNCHANGED reader before either predicate moved, then frozen:
+// never edited by the commits that follow it. The RED/GREEN pattern it printed
+// on the unchanged reader is what makes each case evidence of a predicate
+// rather than a transcription of whatever the implementation happened to do.
+//
+// The nine come off SPEC_SYSTEM_PROMPT, not SPEC_REQUIRED_SECTIONS: the
+// constant still named two headings when this was frozen, and reading the
+// prompt keeps the suite byte-identical across all three commits. It is also
+// how no case here ever retypes the em dash in `### Verification (MANDATORY —
+// do not skip)` (the mmnto-ai/totem#2692 authoring trap). After the extension
+// the two surfaces are the same nine strings in the same order.
+describe('buildPreCommitHook spec-gate reader — frozen mutation suite (mmnto-ai/totem#2737)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    /** The nine `### ` lines of the built-in prompt, in prompt order. */
+    const PROMISED = SPEC_SYSTEM_PROMPT.split('\n').filter((line) => line.startsWith('### '));
+    /** Pick a promised heading by an ASCII prefix — never retype the em dash. */
+    function promised(prefix) {
+        const found = PROMISED.find((heading) => heading.startsWith(prefix));
+        if (found === undefined)
+            throw new Error(`no promised heading starts with ${prefix}`);
+        return found;
+    }
+    const PROBLEM_STATEMENT = promised('### Problem Statement');
+    const FILES_TO_EXAMINE = promised('### Files to Examine');
+    const EDGE_CASES = promised('### Edge Cases');
+    const IMPLEMENTATION_TASKS = promised('### Implementation Tasks');
+    const EXECUTION_FLOW = promised('### Execution Flow');
+    const VERIFICATION = promised('### Verification');
+    const TEST_PLAN = promised('### Test Plan');
+    /** A TAB, built rather than escaped (the mmnto-ai/totem#2692 authoring trap). */
+    const TAB = String.fromCharCode(9);
+    /**
+     * All nine promised headings, each over one plain body line. An override
+     * replaces exactly ONE heading's whole block, so each case changes one thing;
+     * an empty override DROPS that heading from the draft entirely.
+     */
+    function nineBodied(overrides = {}) {
+        return PROMISED.map((heading) => {
+            const override = overrides[heading];
+            return override === undefined
+                ? `${heading}\n\nA non-blank body under ${heading}.\n`
+                : override;
+        })
+            .filter((block) => block.length > 0)
+            .join('\n');
+    }
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-2737-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/frozen-suite', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook(RENDER));
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+    });
+    function runHook() {
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        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));
+    }
+    /** 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');
+    }
+    /** Judge one draft written under the BUILT-IN prompt on an ISSUE anchor. */
+    function judge(content) {
+        writeRun('draft.json', specEvidenceArtifact({ output: { content } }));
+        return runHook();
+    }
+    // ── Positive mutations: each must PASS ──
+    it.skipIf(!shellOk)('a section that opens with a deeper heading is not empty', () => {
+        const r = judge(nineBodied({
+            [IMPLEMENTATION_TASKS]: `${IMPLEMENTATION_TASKS}\n#### 1. Sub\nA step under the sub-heading.\n`,
+        }));
+        expect(r.status, r.stdout).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a promised heading with its parenthetical dropped matches and is named', () => {
+        const r = judge(nineBodied({
+            [EXECUTION_FLOW]: '### Execution Flow\n\nA body under the shortened heading.\n',
+            [VERIFICATION]: '### Verification\n\nA body under the shortened heading.\n',
+        }));
+        expect(r.status, r.stdout).toBe(0);
+        expect(r.stdout).toContain(`· tolerated ${EXECUTION_FLOW} ~ ### Execution Flow`);
+        expect(r.stdout).toContain(`${VERIFICATION} ~ ### Verification`);
+    });
+    it.skipIf(!shellOk)('trailing whitespace on a heading line is tolerated silently', () => {
+        const r = judge(nineBodied({
+            [PROBLEM_STATEMENT]: `${PROBLEM_STATEMENT}   ${TAB}\n\nA body under it.\n`,
+        }));
+        expect(r.status, r.stdout).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+        expect(r.stdout).not.toContain('· tolerated');
+    });
+    it.skipIf(!shellOk)('a different trailing parenthetical matches and is named', () => {
+        const r = judge(nineBodied({ [VERIFICATION]: '### Verification (required)\n\nA body under it.\n' }));
+        expect(r.status, r.stdout).toBe(0);
+        expect(r.stdout).toContain('· tolerated');
+        expect(r.stdout).toContain(`${VERIFICATION} ~ ### Verification (required)`);
+    });
+    // ── Negative mutations: each must BLOCK, by name ──
+    it.skipIf(!shellOk)('a genuinely absent promised heading blocks by name', () => {
+        const r = judge(nineBodied({ [TEST_PLAN]: '' }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${TEST_PLAN}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a genuinely empty section blocks by name', () => {
+        const r = judge(nineBodied({ [PROBLEM_STATEMENT]: PROBLEM_STATEMENT }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${PROBLEM_STATEMENT}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a whitespace-only body is empty', () => {
+        const r = judge(nineBodied({ [FILES_TO_EXAMINE]: `${FILES_TO_EXAMINE}\n   \n${TAB}${TAB}\n\n` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${FILES_TO_EXAMINE}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a deeper heading with nothing under it is not a body', () => {
+        const r = judge(nineBodied({ [EDGE_CASES]: `${EDGE_CASES}\n#### none` }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${EDGE_CASES}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a shallower heading ends the section', () => {
+        const r = judge(nineBodied({
+            [IMPLEMENTATION_TASKS]: `${IMPLEMENTATION_TASKS}\n## Notes\nProse under the shallower heading.\n`,
+        }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${IMPLEMENTATION_TASKS}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('the heading level is exact', () => {
+        const r = judge(nineBodied({ [PROBLEM_STATEMENT]: '## Problem Statement\n\nA body under it.\n' }));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is missing heading ${PROBLEM_STATEMENT}`);
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The ruled falsifier (operator ruling 2026-09-03) ──
+    //
+    // The denominator is all SEVEN drafts the R3 probe actually recorded, and the
+    // claim is that none is blocked; the mutated negatives above carry the "flags
+    // the defective" half. The four schema-constrained runs carry the promised
+    // headings BYTE-IDENTICAL, em dash included, so they must match on the EXACT
+    // pass and name no tolerance — which makes this test the executed proof, on
+    // every CI OS, that the em-dash heading round-trips through JSON.stringify,
+    // the single-quoted `node -e` word, sh and node without drift.
+    /** The recorded R3 fixture directory, found by walking up to the repo root. */
+    function resolveR3FixtureDir() {
+        let dir = path.dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8; i++) {
+            const candidate = path.join(dir, '.totem', 'fixtures', 'spec-runs-2026-09-02');
+            if (fs.existsSync(candidate))
+                return candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return '';
+    }
+    /** The ORIGINAL run's draft: the artifacts.ndjson row whose id starts e5a15c9c. */
+    function readOriginalDraft(dir) {
+        const ndjson = fs.readFileSync(path.join(dir, 'artifacts.ndjson'), 'utf-8');
+        for (const line of ndjson.split('\n')) {
+            if (line.trim().length === 0)
+                continue;
+            let row;
+            try {
+                row = JSON.parse(line);
+            }
+            catch (err) {
+                void err;
+                continue;
+            }
+            if (typeof row.id === 'string' && row.id.startsWith('e5a15c9c')) {
+                const content = row.output?.content;
+                if (typeof content === 'string')
+                    return content;
+            }
+        }
+        return '';
+    }
+    it.skipIf(!shellOk)('the extended reader blocks none of the seven recorded R3 drafts and names the tolerance on the three that dropped parentheticals', () => {
+        const dir = resolveR3FixtureDir();
+        expect(dir, 'the recorded R3 drafts (.totem/fixtures/spec-runs-2026-09-02/) are not in this checkout — the ruled falsifier cannot run').not.toBe('');
+        const original = readOriginalDraft(dir);
+        expect(original.length, 'the original R3 draft (artifacts.ndjson row id e5a15c9c…) was not found').toBeGreaterThan(0);
+        const read = (name) => fs.readFileSync(path.join(dir, name), 'utf-8');
+        const drafts = [
+            {
+                name: 'the original artifact (artifacts.ndjson row id e5a15c9c…)',
+                content: original,
+                tolerated: true,
+            },
+            {
+                name: 'r3-unconstrained-run1.md',
+                content: read('r3-unconstrained-run1.md'),
+                tolerated: true,
+            },
+            {
+                name: 'r3-unconstrained-run2.md',
+                content: read('r3-unconstrained-run2.md'),
+                tolerated: true,
+            },
+            {
+                name: 'r3-responseSchema-run1.md',
+                content: read('r3-responseSchema-run1.md'),
+                tolerated: false,
+            },
+            {
+                name: 'r3-responseSchema-run2.md',
+                content: read('r3-responseSchema-run2.md'),
+                tolerated: false,
+            },
+            {
+                name: 'r3-responseJsonSchema-minLength1-run1.md',
+                content: read('r3-responseJsonSchema-minLength1-run1.md'),
+                tolerated: false,
+            },
+            {
+                name: 'r3-responseJsonSchema-minLength1-run2.md',
+                content: read('r3-responseJsonSchema-minLength1-run2.md'),
+                tolerated: false,
+            },
+        ];
+        // The denominator is ruled: all seven, or the claim is a different one.
+        expect(drafts).toHaveLength(7);
+        for (const draft of drafts) {
+            const r = judge(draft.content);
+            expect(r.status, `${draft.name} was BLOCKED: ${r.stdout}`).toBe(0);
+            expect(r.stdout, `${draft.name} did not read as TEMPLATE`).toContain('· shape TEMPLATE');
+            if (draft.tolerated) {
+                expect(r.stdout, `${draft.name} dropped a promised parenthetical but the evidence line named no tolerance`).toContain('· tolerated');
+            }
+            else {
+                expect(r.stdout, `${draft.name} carries the promised headings verbatim but the evidence line named a tolerance`).not.toContain('· tolerated');
+            }
+        }
+    });
+});
+// A tolerantly-matched heading that then blocks for an empty body used to name
+// a string the draft does not contain: the seat reads `has an empty heading
+// ### Verification (MANDATORY — do not skip)`, searches the draft for it, finds
+// nothing, and cannot see that the reader matched `### Verification` and judged
+// THAT section. The block now carries both spellings. Outside the frozen block
+// (mmnto-ai/totem#2737 fold round) — the suite above was run against the
+// unchanged reader and is not edited after.
+describe('buildPreCommitHook spec-gate reader — tolerance disclosure on the block path (mmnto-ai/totem#2737 fold)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    const PROMISED = SPEC_SYSTEM_PROMPT.split('\n').filter((line) => line.startsWith('### '));
+    const VERIFICATION = PROMISED.find((heading) => heading.startsWith('### Verification')) ?? '';
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-2737-fold-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/fold', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook(RENDER));
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+    });
+    it.skipIf(!shellOk)('an EMPTY section under a tolerantly-matched heading names both the promised and the matched line', () => {
+        // Every promised heading bodied except Verification, which appears with
+        // its parenthetical dropped AND no body — so the reader must reach the
+        // empty-body block by way of the tolerant pass.
+        const content = PROMISED.map((heading) => heading === VERIFICATION
+            ? '### Verification\n'
+            : `${heading}\n\nA non-blank body under ${heading}.\n`).join('\n');
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'tolerant-empty.json'), JSON.stringify(specEvidenceArtifact({ output: { content } }), null, 2));
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`has an empty heading ${VERIFICATION} (matched as ### Verification)`);
+        // Still distinguishable from the other two BLOCKED arms.
+        expect(r.stdout).not.toContain('no totem spec run artifact');
+        expect(r.stdout).not.toContain('the spec-evidence reader could not run');
+        // The new clause echoes a DRAFT line, so it is a forged-line sink like
+        // every other value that reaches stdout.
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        // …and the matched line passes through `safe()`: a C1 control inside the
+        // heading is collapsed rather than echoed into the block message.
+        const nel = String.fromCharCode(0x85);
+        const forgedHeading = `### Verification (a${nel}b)`;
+        const forgedContent = PROMISED.map((heading) => heading === VERIFICATION
+            ? `${forgedHeading}\n`
+            : `${heading}\n\nA non-blank body under ${heading}.\n`).join('\n');
+        fs.writeFileSync(path.join(dir, 'tolerant-empty.json'), JSON.stringify(specEvidenceArtifact({ output: { content: forgedContent } }), null, 2));
+        const forgedRun = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        expect(forgedRun.status).toBe(1);
+        expect(forgedRun.stdout).toContain(`has an empty heading ${VERIFICATION} (matched as ### Verification (a?b))`);
+        expect(forgedRun.stdout).not.toContain(nel);
+        expect(forgedRun.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+    });
 });
 //# sourceMappingURL=install-hooks.test.js.map