@mmnto/cli 1.120.0 → 1.122.0

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

@@ -1,10 +1,100 @@
 import { execSync, spawnSync } from 'node:child_process';
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { GROUNDING_ANCHOR_FREE_TEXT, GROUNDING_ANCHOR_ISSUE, GROUNDING_ANCHOR_MIXED, GROUNDING_ANCHOR_RECORD, PROMPT_SOURCE_BUILTIN, PROMPT_SOURCE_OVERRIDE, RUN_ARTIFACT_SCHEMA_VERSION, RunArtifactSchema, } from '@mmnto/totem';
 import { cleanTmpDir } from '../test-utils.js';
 import { buildHookContent, buildPostCheckoutHookContent, buildPreCommitHook, buildPrePushHook, buildResolveBlock, checkHooksInstalled, detectTotemPrefix, generateHookHelpers, getFallbackCommand, installGitHook, installHooksNonInteractive, TOTEM_HOOK_END, TOTEM_HOOK_MARKER, TOTEM_PRECOMMIT_END, TOTEM_PRECOMMIT_MARKER, TOTEM_PREPUSH_END, TOTEM_PREPUSH_MARKER, upgradePrePushHookIfNeeded, } from './install-hooks.js';
+import { SPEC_REQUIRED_SECTIONS } from './spec-templates.js';
+// The default render options every pre-#2692 positional call implied
+// (mmnto-ai/totem#2692 C2 — the builders take a REQUIRED options object now, so
+// each site states the tier/totemDir/fallbackCmd it always assumed). Spread and
+// override the one field a case actually varies.
+const RENDER = {
+    tier: 'standard',
+    totemDir: '.totem',
+    fallbackCmd: 'pnpm dlx @mmnto/cli',
+};
+// ─── Anchored-evidence fixtures (mmnto-ai/totem#2700) ───
+//
+// Since #2700 an artifact is evidence only when it is ANCHORED and its SUBJECT
+// carries a shape. These build the smallest artifact that satisfies each arm,
+// so a test that means to exercise something else (age, newest-wins, torn
+// files) does not accidentally exercise the shape check.
+/** A draft that satisfies the TEMPLATE shape: every required heading with a body. */
+const TEMPLATE_DRAFT = SPEC_REQUIRED_SECTIONS.map((heading) => `${heading}\n\nA non-blank body under ${heading}.\n`).join('\n');
+/** A draft that satisfies only the looser DOCUMENT shape — one heading with a body. */
+const DOCUMENT_DRAFT = '## A hand-shaped section\n\nA body under it.\n';
+/** The minimal ISSUE-anchored, template-shaped run artifact the gate accepts. */
+function specEvidenceArtifact(overrides = {}) {
+    return {
+        admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_BUILTIN } },
+        grounding: { anchor: { kind: GROUNDING_ANCHOR_ISSUE, ref: '#2700' } },
+        output: { content: TEMPLATE_DRAFT },
+        createdAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+/**
+ * The fixture wrapped in the fields every run artifact must carry and the
+ * reader never touches — so the whole thing can be parsed by the REAL schema.
+ */
+function asRunArtifact(fixture) {
+    const grounding = fixture['grounding'];
+    const output = fixture['output'];
+    return {
+        ...fixture,
+        schemaVersion: RUN_ARTIFACT_SCHEMA_VERSION,
+        inputBundle: { maskedPrompt: 'the masked prompt' },
+        inputHash: 'a'.repeat(64),
+        grounding: { hash: 'b'.repeat(64), provenanceSummary: 'similarity-only:1', ...grounding },
+        backend: {
+            provider: 'gemini',
+            model: 'gemini-3-flash-preview',
+            qualifiedModel: 'gemini:gemini-3-flash-preview',
+            admissionClass: 'completion_only',
+            taskProfile: 'Spec',
+        },
+        output: { metrics: { durationMs: 500 }, ...output },
+    };
+}
+// The hook's reader is a rendered `node -e` string: it walks the artifact by
+// HAND-SPELLED paths (`grounding.anchor`, `admission.runMetadata.promptSource`,
+// `output.content`) that no type checker sees. These tests bind the PASS
+// fixtures those paths are exercised against to the real core schema, so a
+// rename or a shape change on the writer's side breaks a test here rather than
+// silently leaving the hook reading a field that no longer exists.
+describe('the anchored-evidence fixtures parse as real run artifacts (mmnto-ai/totem#2700)', () => {
+    it('the issue-anchored PASS fixture round-trips through RunArtifactSchema with its three read paths intact', () => {
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact()));
+        expect(parsed.grounding.anchor).toEqual({ kind: GROUNDING_ANCHOR_ISSUE, ref: '#2700' });
+        expect(parsed.admission?.runMetadata?.promptSource).toBe(PROMPT_SOURCE_BUILTIN);
+        expect(parsed.output.content).toBe(TEMPLATE_DRAFT);
+    });
+    it('the record-anchored PASS fixture round-trips, sha256 and all', () => {
+        const sha256 = 'a'.repeat(64);
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact({
+            grounding: {
+                anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/2700.md', sha256 },
+            },
+        })));
+        expect(parsed.grounding.anchor).toEqual({
+            kind: GROUNDING_ANCHOR_RECORD,
+            ref: '.totem/specs/2700.md',
+            sha256,
+        });
+    });
+    it('the override-prompt PASS fixture round-trips with promptSource "override"', () => {
+        const parsed = RunArtifactSchema.parse(asRunArtifact(specEvidenceArtifact({
+            admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE } },
+            output: { content: DOCUMENT_DRAFT },
+        })));
+        expect(parsed.admission?.runMetadata?.promptSource).toBe(PROMPT_SOURCE_OVERRIDE);
+        expect(parsed.output.content).toBe(DOCUMENT_DRAFT);
+    });
+});
 describe('detectTotemPrefix', () => {
     let tmpDir;
     beforeEach(() => {
@@ -152,76 +242,75 @@ describe('buildResolveBlock', () => {
 });
 describe('buildPreCommitHook', () => {
     it('contains the marker for idempotency', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain(TOTEM_PRECOMMIT_MARKER);
     });
     it('blocks main and master branches', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('"main"');
         expect(hook).toContain('"master"');
     });
     it('prints a helpful error message with override instructions', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('git checkout -b feat/my-feature');
         expect(hook).toContain('git commit --no-verify');
     });
     it('starts with a shebang', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toMatch(/^#!\/bin\/sh\n/);
     });
     it('exits with code 1 when on protected branch', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('exit 1');
     });
 });
 describe('buildPrePushHook', () => {
-    const FALLBACK = 'pnpm dlx @mmnto/cli';
     it('contains the marker for idempotency', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain(TOTEM_PREPUSH_MARKER);
     });
     it('starts with a shebang', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toMatch(/^#!\/bin\/sh\n/);
     });
     it('does not advertise --no-verify escape hatch', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).not.toContain('--no-verify');
     });
     it('contains verify-manifest check', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('verify-manifest');
         expect(hook).toContain('compile manifest is stale');
     });
     it('contains $TOTEM_CMD lint', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('$TOTEM_CMD lint');
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('contains $TOTEM_CMD verify-badges (mmnto-ai/totem#1926)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // totem-context: substring match on hook script content (not secret masking) — toContain is correct here
         expect(hook).toContain('$TOTEM_CMD verify-badges');
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('gates verify-badges on README.md existing', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toMatch(/-f "README\.md".*verify-badges/s);
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('contains $TOTEM_CMD verify-lockfile-sync (mmnto-ai/totem#1961)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // totem-context: substring match on hook script content (not secret masking) — toContain is correct here
         expect(hook).toContain('$TOTEM_CMD verify-lockfile-sync');
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('gates verify-lockfile-sync on pnpm-lock.yaml existing', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toMatch(/-f "pnpm-lock\.yaml".*verify-lockfile-sync/s);
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('slots verify-lockfile-sync before claim-discipline in the pre-push sequence', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // Assert presence with toContain (precise matcher); index comparison is
         // safe only because both substrings are guaranteed present by the
         // toContain assertions above.
@@ -235,12 +324,12 @@ describe('buildPrePushHook', () => {
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('contains $TOTEM_CMD doctor --claim-discipline --strict (Proposal 279 Q3)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('$TOTEM_CMD doctor --claim-discipline --strict');
     });
     // totem-context: hook-content assertion (mmnto-ai/totem#2002 — diff-scope narrowing)
     it('contains --scope-to-diff on the claim-discipline invocation (mmnto-ai/totem#2002)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // The flag must appear on the same `doctor --claim-discipline` line so the
         // hook narrows the WWND scan to diff-touched files. Standing-gate full scan
         // produced N=8 false-positive bypasses in <24hr on a pre-existing surface
@@ -249,7 +338,7 @@ describe('buildPrePushHook', () => {
     });
     // totem-context: hook-content assertion (mmnto-ai/totem#2002 — bootstrap defensive degrade)
     it('defensively degrades --scope-to-diff when CLI predates 1.47.0 (cohort bootstrap safety)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // The hook MUST detect --scope-to-diff support via --help and fall back to
         // standing-scan when the resolved CLI doesn't carry the flag. Required so a
         // cohort agent whose global @mmnto/cli predates 1.47.0 doesn't fail commander
@@ -270,13 +359,13 @@ describe('buildPrePushHook', () => {
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('gates claim-discipline on at-least-one in-scope public surface existing', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // The gate fires when any of README.md, AGENTS.md, design-tenets.md, or docs/wiki/ exists
         expect(hook).toMatch(/-f "README\.md".*-f "AGENTS\.md".*-f "design-tenets\.md".*-d "docs\/wiki"/s);
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('slots claim-discipline after verify-badges in the pre-push sequence', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         const verifyBadgesIdx = hook.indexOf('$TOTEM_CMD verify-badges');
         const claimDisciplineIdx = hook.indexOf('$TOTEM_CMD doctor --claim-discipline');
         expect(verifyBadgesIdx).toBeGreaterThan(-1);
@@ -285,36 +374,36 @@ describe('buildPrePushHook', () => {
     });
     // totem-context: hook-content assertion (not an orchestrator test, no LLM calls — default vitest timeout is sufficient)
     it('mentions TOTEM_GATE_BYPASS_JUSTIFICATION as the bypass mechanism (Proposal 279 Q3 standardized convention)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('TOTEM_GATE_BYPASS_JUSTIFICATION');
     });
     it('does NOT contain old flag-file references', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).not.toContain('.lint-passed');
         expect(hook).not.toContain('.shield-passed');
         expect(hook).not.toContain('.target-globs');
     });
     it('does NOT contain merge-base (no ancestry checks)', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).not.toContain('merge-base');
     });
     it('uses the resolve block', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('TOTEM_CMD=');
         expect(hook).toContain('command -v totem');
     });
     it('uses POSIX-compatible syntax only', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         // Must use [ ] not [[ ]]
         expect(hook).not.toContain('[[');
         expect(hook).not.toContain(']]');
     });
     it('embeds the provided fallback command', () => {
-        const hook = buildPrePushHook('yarn dlx @mmnto/cli');
+        const hook = buildPrePushHook({ ...RENDER, fallbackCmd: 'yarn dlx @mmnto/cli' });
         expect(hook).toContain('yarn dlx @mmnto/cli');
     });
     it('includes format:check before push', () => {
-        const hook = buildPrePushHook(FALLBACK);
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('format:check');
         expect(hook).toContain('Formatting check failed');
     });
@@ -330,7 +419,7 @@ describe('installGitHook', () => {
         cleanTmpDir(tmpDir);
     });
     it('creates a new hook file when none exists', () => {
-        const content = buildPreCommitHook();
+        const content = buildPreCommitHook(RENDER);
         const result = installGitHook(hooksDir, 'pre-commit', content, TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('installed');
         expect(fs.existsSync(path.join(hooksDir, 'pre-commit'))).toBe(true);
@@ -339,11 +428,11 @@ describe('installGitHook', () => {
     });
     it('creates parent directories as needed', () => {
         expect(fs.existsSync(hooksDir)).toBe(false);
-        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(fs.existsSync(hooksDir)).toBe(true);
     });
     it('returns exists when marker is already present (idempotent)', () => {
-        const content = buildPreCommitHook();
+        const content = buildPreCommitHook(RENDER);
         installGitHook(hooksDir, 'pre-commit', content, TOTEM_PRECOMMIT_MARKER);
         const result = installGitHook(hooksDir, 'pre-commit', content, TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('exists');
@@ -353,7 +442,7 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-commit');
         const userHook = '#!/bin/sh\necho "user hook"\n';
         fs.writeFileSync(hookPath, userHook);
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
         const written = fs.readFileSync(hookPath, 'utf-8');
         expect(written).toContain('echo "user hook"');
@@ -366,13 +455,13 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-push');
         const userHook = '#!/bin/sh\nrun_my_tests\n';
         fs.writeFileSync(hookPath, userHook);
-        installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER);
+        installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER);
         const written = fs.readFileSync(hookPath, 'utf-8');
         expect(written).toContain('run_my_tests');
         expect(written).toContain(TOTEM_PREPUSH_MARKER);
     });
     it('is idempotent — double install does not duplicate', () => {
-        const content = buildPrePushHook('pnpm dlx @mmnto/cli');
+        const content = buildPrePushHook(RENDER);
         installGitHook(hooksDir, 'pre-push', content, TOTEM_PREPUSH_MARKER);
         installGitHook(hooksDir, 'pre-push', content, TOTEM_PREPUSH_MARKER);
         const written = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
@@ -384,7 +473,7 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-commit');
         const nodeHook = '#!/usr/bin/env node\nconsole.log("lint");\n'; // totem-ignore — test fixture, not real logging
         fs.writeFileSync(hookPath, nodeHook);
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('skipped-non-shell');
         const written = fs.readFileSync(hookPath, 'utf-8');
         expect(written).toBe(nodeHook); // File untouched
@@ -394,7 +483,7 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-push');
         const pythonHook = '#!/usr/bin/env python3\nimport subprocess\n';
         fs.writeFileSync(hookPath, pythonHook);
-        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER);
+        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER);
         expect(result).toBe('skipped-non-shell');
         const written = fs.readFileSync(hookPath, 'utf-8');
         expect(written).toBe(pythonHook); // File untouched
@@ -403,33 +492,33 @@ describe('installGitHook', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-commit');
         fs.writeFileSync(hookPath, '#!/bin/sh\necho "existing"\n');
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
     });
     it('appends normally to bash hooks', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-commit');
         fs.writeFileSync(hookPath, '#!/bin/bash\necho "existing"\n');
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
     });
     it('appends normally to env bash hooks', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-commit');
         fs.writeFileSync(hookPath, '#!/usr/bin/env bash\necho "existing"\n');
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
     });
     it('appends to hooks without a shebang (plain text)', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-commit');
         fs.writeFileSync(hookPath, 'echo "no shebang"\n');
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         expect(result).toBe('appended');
     });
     it('handles pre-commit and pre-push independently', () => {
-        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
-        installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER);
+        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
+        installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER);
         expect(fs.existsSync(path.join(hooksDir, 'pre-commit'))).toBe(true);
         expect(fs.existsSync(path.join(hooksDir, 'pre-push'))).toBe(true);
         const preCommit = fs.readFileSync(path.join(hooksDir, 'pre-commit'), 'utf-8');
@@ -444,7 +533,7 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-push');
         // Write an old-format hook with the marker
         fs.writeFileSync(hookPath, `#!/bin/sh\n# ${TOTEM_PREPUSH_MARKER}\n$TOTEM_CMD lint\n`);
-        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER, true);
+        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER, true);
         expect(result).toBe('overwritten');
         const content = fs.readFileSync(hookPath, 'utf-8');
         expect(content).toContain('verify-manifest'); // new format
@@ -453,7 +542,7 @@ describe('installGitHook', () => {
     it('returns exists when on-disk content already matches canonical (idempotent)', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-push');
-        const canonical = buildPrePushHook('pnpm dlx @mmnto/cli');
+        const canonical = buildPrePushHook(RENDER);
         fs.writeFileSync(hookPath, canonical);
         const result = installGitHook(hooksDir, 'pre-push', canonical, TOTEM_PREPUSH_MARKER);
         expect(result).toBe('exists');
@@ -464,7 +553,7 @@ describe('installGitHook', () => {
         // A totem-owned whole file frozen at an older generator's output — but it carries
         // the bounded end marker, so drift-repair may upgrade it in place without --force.
         fs.writeFileSync(hookPath, `#!/bin/sh\n# ${TOTEM_PREPUSH_MARKER}\n$TOTEM_CMD lint\n# ${TOTEM_PREPUSH_END}\n`);
-        const canonical = buildPrePushHook('pnpm dlx @mmnto/cli');
+        const canonical = buildPrePushHook(RENDER);
         const result = installGitHook(hooksDir, 'pre-push', canonical, TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
         expect(result).toBe('overwritten');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical);
@@ -473,7 +562,7 @@ describe('installGitHook', () => {
         fs.mkdirSync(hooksDir, { recursive: true });
         const hookPath = path.join(hooksDir, 'pre-commit');
         fs.writeFileSync(hookPath, `#!/bin/sh\n# ${TOTEM_PRECOMMIT_MARKER}\nstale body\n# ${TOTEM_PRECOMMIT_END}\n`);
-        const canonical = buildPreCommitHook();
+        const canonical = buildPreCommitHook(RENDER);
         const result = installGitHook(hooksDir, 'pre-commit', canonical, TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
         expect(result).toBe('overwritten');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(canonical);
@@ -486,7 +575,7 @@ describe('installGitHook', () => {
         // marker → the region cannot be bounded → drift-repair declines (legacy path).
         const legacy = `#!/bin/sh\n# ${TOTEM_PRECOMMIT_MARKER}\nstale legacy body\n`;
         fs.writeFileSync(hookPath, legacy);
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
         expect(result).toBe('exists');
         // Left untouched — the legacy hook takes one `totem hook install --force`.
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(legacy);
@@ -498,7 +587,7 @@ describe('installGitHook', () => {
         // block is bounded by an end marker.
         const userThenTotem = `#!/bin/sh\nrun_my_tests\n# ${TOTEM_PREPUSH_MARKER}\nold content\n# ${TOTEM_PREPUSH_END}\n`;
         fs.writeFileSync(hookPath, userThenTotem);
-        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
+        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
         expect(result).toBe('exists');
         // Left untouched — the user's hook is preserved verbatim.
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(userThenTotem);
@@ -510,7 +599,7 @@ describe('installGitHook', () => {
         // whole-file overwrite would clobber it, so the end-marker guard must decline.
         const staleWithTrailingUser = `#!/bin/sh\n# ${TOTEM_PRECOMMIT_MARKER}\nstale body\n# ${TOTEM_PRECOMMIT_END}\necho "my pre-commit notice"\n`;
         fs.writeFileSync(hookPath, staleWithTrailingUser);
-        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
+        const result = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER, false, TOTEM_PRECOMMIT_END);
         expect(result).toBe('exists');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(staleWithTrailingUser);
     });
@@ -519,7 +608,7 @@ describe('installGitHook', () => {
         const hookPath = path.join(hooksDir, 'pre-push');
         const staleWithTrailingUser = `#!/bin/sh\n# ${TOTEM_PREPUSH_MARKER}\nstale body\n# ${TOTEM_PREPUSH_END}\necho "my pre-push notice"\n`;
         fs.writeFileSync(hookPath, staleWithTrailingUser);
-        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook('pnpm dlx @mmnto/cli'), TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
+        const result = installGitHook(hooksDir, 'pre-push', buildPrePushHook(RENDER), TOTEM_PREPUSH_MARKER, false, TOTEM_PREPUSH_END);
         expect(result).toBe('exists');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(staleWithTrailingUser);
     });
@@ -530,7 +619,7 @@ describe('installGitHook', () => {
         // whole-file overwrite would clobber it, so the end-marker guard must decline.
         const staleWithTrailingUser = `#!/bin/sh\n# ${TOTEM_HOOK_MARKER}\nstale body\n# ${TOTEM_HOOK_END}\necho "my deploy notice"\n`;
         fs.writeFileSync(hookPath, staleWithTrailingUser);
-        const result = installGitHook(hooksDir, 'post-merge', buildHookContent('pnpm dlx @mmnto/cli'), TOTEM_HOOK_MARKER, false, TOTEM_HOOK_END);
+        const result = installGitHook(hooksDir, 'post-merge', buildHookContent(RENDER), TOTEM_HOOK_MARKER, false, TOTEM_HOOK_END);
         expect(result).toBe('exists');
         expect(fs.readFileSync(hookPath, 'utf-8')).toBe(staleWithTrailingUser);
     });
@@ -545,7 +634,7 @@ describe('generateHookHelpers', () => {
         cleanTmpDir(tmpDir);
     });
     it('creates .totem/hooks/ directory and writes all 4 .sh files', () => {
-        generateHookHelpers(tmpDir, 'pnpm dlx @mmnto/cli');
+        generateHookHelpers(tmpDir, RENDER);
         const hooksDir = path.join(tmpDir, '.totem', 'hooks');
         expect(fs.existsSync(path.join(hooksDir, 'post-merge.sh'))).toBe(true);
         expect(fs.existsSync(path.join(hooksDir, 'post-checkout.sh'))).toBe(true);
@@ -553,7 +642,7 @@ describe('generateHookHelpers', () => {
         expect(fs.existsSync(path.join(hooksDir, 'pre-push.sh'))).toBe(true);
     });
     it('generated scripts contain expected content', () => {
-        generateHookHelpers(tmpDir, 'pnpm dlx @mmnto/cli');
+        generateHookHelpers(tmpDir, RENDER);
         const hooksDir = path.join(tmpDir, '.totem', 'hooks');
         const postMerge = fs.readFileSync(path.join(hooksDir, 'post-merge.sh'), 'utf-8');
         expect(postMerge).toContain('command -v totem');
@@ -563,8 +652,8 @@ describe('generateHookHelpers', () => {
         expect(prePush).toContain('verify-manifest');
     });
     it('is idempotent — calling twice does not error', () => {
-        generateHookHelpers(tmpDir, 'pnpm dlx @mmnto/cli');
-        generateHookHelpers(tmpDir, 'pnpm dlx @mmnto/cli');
+        generateHookHelpers(tmpDir, RENDER);
+        generateHookHelpers(tmpDir, RENDER);
         const hooksDir = path.join(tmpDir, '.totem', 'hooks');
         expect(fs.existsSync(path.join(hooksDir, 'post-merge.sh'))).toBe(true);
     });
@@ -578,14 +667,14 @@ describe('installHooksNonInteractive', () => {
     afterEach(() => {
         cleanTmpDir(tmpDir);
     });
-    it('returns null when not a git repo', () => {
-        const result = installHooksNonInteractive(tmpDir);
+    it('returns null when not a git repo', async () => {
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result).toBeNull();
     });
-    it('installs all four hooks in a git repo', () => {
+    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'), '');
-        const result = installHooksNonInteractive(tmpDir);
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result).not.toBeNull();
         expect(result.preCommit).toBe('installed');
         expect(result.prePush).toBe('installed');
@@ -598,33 +687,33 @@ describe('installHooksNonInteractive', () => {
         expect(fs.existsSync(path.join(hooksDir, 'post-merge'))).toBe(true);
         expect(fs.existsSync(path.join(hooksDir, 'post-checkout'))).toBe(true);
     });
-    it('is idempotent — second call returns exists for all hooks', () => {
+    it('is idempotent — second call returns exists for all hooks', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
-        installHooksNonInteractive(tmpDir);
-        const result = installHooksNonInteractive(tmpDir);
+        await installHooksNonInteractive(tmpDir);
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result).not.toBeNull();
         expect(result.preCommit).toBe('exists');
         expect(result.prePush).toBe('exists');
         expect(result.postMerge).toBe('exists');
         expect(result.postCheckout).toBe('exists');
     });
-    it('returns null and generates helper scripts when hook manager is detected', () => {
+    it('returns null and generates helper scripts when hook manager is detected', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.mkdirSync(path.join(tmpDir, '.husky'), { recursive: true });
-        const result = installHooksNonInteractive(tmpDir);
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result).toBeNull();
         // Verify helper scripts were generated
         const hooksDir = path.join(tmpDir, '.totem', 'hooks');
         expect(fs.existsSync(path.join(hooksDir, 'post-merge.sh'))).toBe(true);
         expect(fs.existsSync(path.join(hooksDir, 'pre-push.sh'))).toBe(true);
     });
-    it('installs hooks at git root when run from a subdirectory', () => {
+    it('installs hooks at git root when run from a subdirectory', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
         const subDir = path.join(tmpDir, 'packages', 'cli');
         fs.mkdirSync(subDir, { recursive: true });
-        const result = installHooksNonInteractive(subDir);
+        const result = await installHooksNonInteractive(subDir);
         expect(result).not.toBeNull();
         expect(result.preCommit).toBe('installed');
         expect(result.prePush).toBe('installed');
@@ -638,31 +727,31 @@ describe('installHooksNonInteractive', () => {
         expect(fs.existsSync(path.join(hooksDir, 'post-checkout'))).toBe(true);
         expect(fs.existsSync(path.join(subDir, '.git'))).toBe(false);
     });
-    it('check passes from subdirectory after install', () => {
+    it('check passes from subdirectory after install', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
         const subDir = path.join(tmpDir, 'packages', 'cli');
         fs.mkdirSync(subDir, { recursive: true });
-        installHooksNonInteractive(subDir);
+        await installHooksNonInteractive(subDir);
         expect(checkHooksInstalled(subDir)).toBe(true);
     });
-    it('appends to existing hooks without clobbering', () => {
+    it('appends to existing hooks without clobbering', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
         fs.writeFileSync(path.join(tmpDir, '.git', 'hooks', 'pre-push'), '#!/bin/sh\nrun_my_tests\n');
-        const result = installHooksNonInteractive(tmpDir);
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result.prePush).toBe('appended');
         const content = fs.readFileSync(path.join(tmpDir, '.git', 'hooks', 'pre-push'), 'utf-8');
         expect(content).toContain('run_my_tests');
         expect(content).toContain(TOTEM_PREPUSH_MARKER);
     });
-    it('force-overwrites all hooks when force is true', () => {
+    it('force-overwrites all hooks when force is true', async () => {
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
         // First install — creates hooks
-        installHooksNonInteractive(tmpDir);
+        await installHooksNonInteractive(tmpDir);
         // Second install with force — overwrites all hooks
-        const result = installHooksNonInteractive(tmpDir, true);
+        const result = await installHooksNonInteractive(tmpDir, true);
         expect(result).not.toBeNull();
         expect(result.preCommit).toBe('overwritten');
         expect(result.prePush).toBe('overwritten');
@@ -684,14 +773,14 @@ describe('checkHooksInstalled', () => {
     it('returns false when no hooks are installed', () => {
         expect(checkHooksInstalled(tmpDir)).toBe(false);
     });
-    it('returns true when all hooks are installed', () => {
-        installHooksNonInteractive(tmpDir);
+    it('returns true when all hooks are installed', async () => {
+        await installHooksNonInteractive(tmpDir);
         expect(checkHooksInstalled(tmpDir)).toBe(true);
     });
     it('returns false when only some hooks are installed', () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
-        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(), TOTEM_PRECOMMIT_MARKER);
+        installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(RENDER), TOTEM_PRECOMMIT_MARKER);
         // Missing pre-push and post-merge
         expect(checkHooksInstalled(tmpDir)).toBe(false);
     });
@@ -716,8 +805,8 @@ describe('post-merge hook content', () => {
     afterEach(() => {
         cleanTmpDir(tmpDir);
     });
-    it('generates post-merge hook with git diff-tree lesson check', () => {
-        installHooksNonInteractive(tmpDir);
+    it('generates post-merge hook with git diff-tree lesson check', async () => {
+        await installHooksNonInteractive(tmpDir);
         const hookPath = path.join(tmpDir, '.git', 'hooks', 'post-merge');
         const content = fs.readFileSync(hookPath, 'utf-8');
         expect(content).toContain('ORIG_HEAD');
@@ -728,17 +817,17 @@ describe('post-merge hook content', () => {
         expect(content).toContain('[totem] post-merge hook');
         expect(content).toContain('[totem] end post-merge');
     });
-    it('passes quiet flag to sync command in post-merge hook', () => {
-        installHooksNonInteractive(tmpDir);
+    it('passes quiet flag to sync command in post-merge hook', async () => {
+        await installHooksNonInteractive(tmpDir);
         const hookPath = path.join(tmpDir, '.git', 'hooks', 'post-merge');
         const content = fs.readFileSync(hookPath, 'utf-8');
         expect(content).toContain('--quiet');
     });
-    it('preserves existing hooks when appending post-merge block', () => {
+    it('preserves existing hooks when appending post-merge block', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         fs.writeFileSync(path.join(hooksDir, 'post-merge'), '#!/bin/sh\necho "my custom hook"\n');
-        installHooksNonInteractive(tmpDir);
+        await installHooksNonInteractive(tmpDir);
         const content = fs.readFileSync(path.join(hooksDir, 'post-merge'), 'utf-8');
         expect(content).toContain('echo "my custom hook"');
         expect(content).toContain('[totem] post-merge hook');
@@ -757,8 +846,8 @@ describe('post-checkout hook content', () => {
     afterEach(() => {
         cleanTmpDir(tmpDir);
     });
-    it('generates post-checkout hook with branch switch guard', () => {
-        installHooksNonInteractive(tmpDir);
+    it('generates post-checkout hook with branch switch guard', async () => {
+        await installHooksNonInteractive(tmpDir);
         const hookPath = path.join(tmpDir, '.git', 'hooks', 'post-checkout');
         const content = fs.readFileSync(hookPath, 'utf-8');
         expect(content).toContain('$3');
@@ -767,18 +856,18 @@ describe('post-checkout hook content', () => {
         expect(content).toContain('[totem] end post-checkout');
     });
     it('handles null SHA for initial checkout', () => {
-        const hook = buildPostCheckoutHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildPostCheckoutHookContent(RENDER);
         expect(hook).toContain('0000000000000000000000000000000000000000');
         expect(hook).toContain('.totem');
     });
-    it('uses quiet sync command', () => {
-        installHooksNonInteractive(tmpDir);
+    it('uses quiet sync command', async () => {
+        await installHooksNonInteractive(tmpDir);
         const hookPath = path.join(tmpDir, '.git', 'hooks', 'post-checkout');
         const content = fs.readFileSync(hookPath, 'utf-8');
         expect(content).toContain('--quiet');
     });
-    it('includes post-checkout in non-interactive install', () => {
-        const result = installHooksNonInteractive(tmpDir);
+    it('includes post-checkout in non-interactive install', async () => {
+        const result = await installHooksNonInteractive(tmpDir);
         expect(result).not.toBeNull();
         expect(result.postCheckout).toBe('installed');
     });
@@ -787,7 +876,7 @@ describe('post-checkout hook content', () => {
 // ─── totem-status refresh-gh wiring (mmnto-ai/totem#2556) ─
 describe('post-merge hook fires totem-status refresh-gh', () => {
     it('invokes refresh-gh presence-gated and backgrounded (mmnto-ai/totem-status#127 C3)', () => {
-        const hook = buildHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildHookContent(RENDER);
         // Presence gate (absent binary = zero noise) AND primary-checkout gate: in a
         // linked worktree .git is a pointer FILE and a backgrounded child inheriting
         // the worktree cwd holds a Windows directory lock that breaks worktree removal.
@@ -799,7 +888,7 @@ describe('post-merge hook fires totem-status refresh-gh', () => {
         expect(hook.trimEnd().endsWith(`# ${TOTEM_HOOK_END}`)).toBe(true);
     });
     it('#2570: stamps each firing and hands the child the same log (observability leg)', () => {
-        const hook = buildHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildHookContent(RENDER);
         // Repo-local log inside .git; the stamp carries the firing site, cwd, and
         // WHICH binary resolved (shell search order can be shadowed by a
         // checkout-local exe on Windows).
@@ -822,7 +911,7 @@ describe('post-merge hook fires totem-status refresh-gh', () => {
     // (mmnto-ai/totem-status#127; sibling of mmnto-ai/totem#2556.) The durable
     // obligation store gets the same post-merge moment as the GH snapshot.
     it('also fires refresh-obligation-store under the SAME gate and log (mmnto-ai/totem-status#127)', () => {
-        const hook = buildHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildHookContent(RENDER);
         // One gate, not two: both verbs live inside the single presence +
         // primary-checkout `if`, so a worktree/non-adopter skips BOTH.
         const gateIdx = hook.indexOf('if [ -d .git ] && command -v totem-status >/dev/null 2>&1; then');
@@ -905,7 +994,7 @@ describe.skipIf(process.platform === 'win32')('post-merge refresh-gh behavior (P
         const repo = path.join(tmpDir, 'repo');
         fs.mkdirSync(path.join(repo, '.git'), { recursive: true });
         const hookPath = path.join(repo, 'post-merge');
-        fs.writeFileSync(hookPath, buildHookContent('pnpm dlx @mmnto/cli'), { mode: 0o755 });
+        fs.writeFileSync(hookPath, buildHookContent(RENDER), { mode: 0o755 });
         execSync('sh ./post-merge', {
             cwd: repo,
             env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
@@ -935,7 +1024,7 @@ describe.skipIf(process.platform === 'win32')('post-merge refresh-gh behavior (P
         // append; falsification round, MAJOR 1).
         fs.mkdirSync(path.join(repo, '.git', 'totem-status-refresh-hook.log'), { recursive: true });
         const hookPath = path.join(repo, 'post-merge');
-        fs.writeFileSync(hookPath, buildHookContent('pnpm dlx @mmnto/cli'), { mode: 0o755 });
+        fs.writeFileSync(hookPath, buildHookContent(RENDER), { mode: 0o755 });
         const result = spawnSync('sh', ['./post-merge'], {
             cwd: repo,
             env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
@@ -953,7 +1042,7 @@ describe.skipIf(process.platform === 'win32')('post-merge refresh-gh behavior (P
         // Linked-worktree shape: .git is a pointer FILE, not a directory.
         fs.writeFileSync(path.join(repo, '.git'), 'gitdir: /elsewhere/.git/worktrees/x\n');
         const hookPath = path.join(repo, 'post-merge');
-        fs.writeFileSync(hookPath, buildHookContent('pnpm dlx @mmnto/cli'), { mode: 0o755 });
+        fs.writeFileSync(hookPath, buildHookContent(RENDER), { mode: 0o755 });
         execSync('sh ./post-merge', {
             cwd: repo,
             env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
@@ -967,14 +1056,14 @@ describe.skipIf(process.platform === 'win32')('post-merge refresh-gh behavior (P
 });
 describe('sync-log redirect resolves the git dir (worktree-safe)', () => {
     it('post-merge hook derives the log path from git rev-parse --git-dir', () => {
-        const hook = buildHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildHookContent(RENDER);
         expect(hook).toContain('GIT_DIR_RESOLVED=$(git rev-parse --git-dir 2>/dev/null || echo .git)');
         expect(hook).toContain('> "$GIT_DIR_RESOLVED/totem-sync.log"');
         // The hardcoded `.git/`-as-directory redirect must be gone (ENOTDIR in a worktree).
         expect(hook).not.toContain('> .git/totem-sync.log');
     });
     it('post-checkout hook derives the log path from git rev-parse --git-dir on both branches', () => {
-        const hook = buildPostCheckoutHookContent('pnpm dlx @mmnto/cli');
+        const hook = buildPostCheckoutHookContent(RENDER);
         expect(hook).toContain('GIT_DIR_RESOLVED=$(git rev-parse --git-dir 2>/dev/null || echo .git)');
         // Both the null-SHA and the branch-diff redirect use the resolved dir.
         expect(hook.match(/> "\$GIT_DIR_RESOLVED\/totem-sync\.log"/g)).toHaveLength(2);
@@ -988,13 +1077,19 @@ describe('upgradePrePushHookIfNeeded', () => {
         tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hooks-upgrade-'));
         execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
         fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), '');
+        // Pin the repo-local render options: since mmnto-ai/totem#2692 the upgrade
+        // path resolves `hooks.tier` from config, and a config-less temp repo would
+        // fall through to the developer's global `~/.totem/` profile — a global
+        // `hooks.tier: strict` would then break the standard-tier expectation below
+        // (CodeRabbit on mmnto-ai/totem#2701).
+        fs.writeFileSync(path.join(tmpDir, 'totem.yaml'), 'targets:\n  - glob: "docs/*.md"\n    type: lesson\n    strategy: markdown-heading\nhooks:\n  tier: standard\n', 'utf-8');
     });
     afterEach(() => {
         cleanTmpDir(tmpDir);
     });
     /**
      * Helper: extract the totem block from a hook file and compare it against
-     * the canonical output of buildPrePushHook('pnpm dlx @mmnto/cli') (shebang stripped, trimmed).
+     * the canonical output of buildPrePushHook(RENDER) (shebang stripped, trimmed).
      * Catches stale shell fragments or splice boundary bugs that toContain would miss.
      * The stateless format is now bounded by the pre-push end marker, so the block is the
      * span from the start-marker comment through the end-marker comment line inclusive —
@@ -1012,11 +1107,11 @@ describe('upgradePrePushHookIfNeeded', () => {
     }
     /** Canonical totem block: shebang stripped, trimmed — the expected upgrade output. */
     function expectedTotemBlock() {
-        return buildPrePushHook(getFallbackCommand(tmpDir))
+        return buildPrePushHook({ ...RENDER, fallbackCmd: getFallbackCommand(tmpDir) })
             .replace(/^#!\/bin\/sh\n/, '')
             .trim();
     }
-    it('upgrades old command-executing hook to stateless format', () => {
+    it('upgrades old command-executing hook to stateless format', async () => {
         // Install an old-style hook that executes $TOTEM_CMD lint
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
@@ -1032,7 +1127,7 @@ if [ -f ".totem/compiled-rules.json" ]; then
 fi
 `;
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldHook);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(true);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         expect(content).toContain('verify-manifest');
@@ -1044,41 +1139,41 @@ fi
         const actual = extractTotemBlock(content);
         expect(actual).toBe(expectedTotemBlock());
     });
-    it('skips hook without totem marker', () => {
+    it('skips hook without totem marker', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         const userHook = '#!/bin/sh\necho "user hook"\n';
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), userHook);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(false);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         expect(content).toBe(userHook); // File untouched
     });
-    it('skips hook that already uses stateless format', () => {
+    it('skips hook that already uses stateless format', async () => {
         // Install the current-version hook via non-interactive installer
-        installHooksNonInteractive(tmpDir);
+        await installHooksNonInteractive(tmpDir);
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         const beforeContent = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(false);
         const afterContent = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         expect(afterContent).toBe(beforeContent); // File untouched
     });
-    it('returns false when no pre-push hook exists', () => {
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+    it('returns false when no pre-push hook exists', async () => {
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(false);
     });
-    it('returns false when not a git repo', () => {
+    it('returns false when not a git repo', async () => {
         const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-no-git-'));
         try {
-            const upgraded = upgradePrePushHookIfNeeded(nonGitDir);
+            const upgraded = await upgradePrePushHookIfNeeded(nonGitDir);
             expect(upgraded).toBe(false);
         }
         finally {
             cleanTmpDir(nonGitDir);
         }
     });
-    it('preserves user-appended content when upgrading', () => {
+    it('preserves user-appended content when upgrading', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         // Simulate an old totem hook with user content appended after it
@@ -1093,7 +1188,7 @@ fi
 `;
         const userAppended = '\n# My custom deploy notification\ncurl -X POST https://hooks.example.com/deploy\n';
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldTotemBlock + userAppended);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(true);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         // New totem block should use stateless format
@@ -1107,7 +1202,7 @@ fi
         const actual = extractTotemBlock(content);
         expect(actual).toBe(expectedTotemBlock());
     });
-    it('preserves user-appended if/fi blocks without corrupting them', () => {
+    it('preserves user-appended if/fi blocks without corrupting them', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         // Old totem block (needs upgrade) PLUS user content that contains its own if/fi structures
@@ -1138,7 +1233,7 @@ if [ -n "$SLACK_WEBHOOK" ]; then
 fi
 `;
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldTotemBlock + userIfFiBlock);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(true);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         // Totem block must match canonical output exactly
@@ -1156,7 +1251,7 @@ fi
         const userBlockStart = content.indexOf('# Custom deploy guard');
         expect(userBlockStart).toBeGreaterThan(totemBlockEnd);
     });
-    it('leaves no stale fi or orphaned shell fragments after upgrade', () => {
+    it('leaves no stale fi or orphaned shell fragments after upgrade', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         const oldHook = `#!/bin/sh
@@ -1171,7 +1266,7 @@ if [ -f ".totem/compiled-rules.json" ]; then
 fi
 `;
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldHook);
-        upgradePrePushHookIfNeeded(tmpDir);
+        await upgradePrePushHookIfNeeded(tmpDir);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         // Count if/fi balance: every `if` must have a matching `fi`.
         // Inline `if ... fi` on a single line are self-balanced and excluded from both counts.
@@ -1187,7 +1282,7 @@ fi
         const actual = extractTotemBlock(content);
         expect(actual).toBe(expectedTotemBlock());
     });
-    it('upgrades old flag-checking hook to stateless format', () => {
+    it('upgrades old flag-checking hook to stateless format', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         // Simulate the previous flag-checking format that used .lint-passed
@@ -1208,7 +1303,7 @@ if [ -f ".totem/compiled-rules.json" ]; then
 fi
 `;
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldHook);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(true);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         expect(content).toContain('verify-manifest');
@@ -1218,7 +1313,7 @@ fi
         const actual = extractTotemBlock(content);
         expect(actual).toBe(expectedTotemBlock());
     });
-    it('upgrades hook with auto-refresh and $TOTEM_CMD to stateless format', () => {
+    it('upgrades hook with auto-refresh and $TOTEM_CMD to stateless format', async () => {
         const hooksDir = path.join(tmpDir, '.git', 'hooks');
         fs.mkdirSync(hooksDir, { recursive: true });
         // Simulate a hook with the auto-refresh logic still using $TOTEM_CMD
@@ -1248,7 +1343,7 @@ if [ -f ".totem/compiled-rules.json" ]; then
 fi
 `;
         fs.writeFileSync(path.join(hooksDir, 'pre-push'), oldHook);
-        const upgraded = upgradePrePushHookIfNeeded(tmpDir);
+        const upgraded = await upgradePrePushHookIfNeeded(tmpDir);
         expect(upgraded).toBe(true);
         const content = fs.readFileSync(path.join(hooksDir, 'pre-push'), 'utf-8');
         expect(content).toContain('verify-manifest');
@@ -1263,7 +1358,7 @@ fi
 // ─── Enforcement tier: agent detection & strict mode ──
 describe('buildPreCommitHook agent detection', () => {
     it('includes agent detection snippet', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('is_agent=0');
         expect(hook).toContain('is_agent=1');
         expect(hook).toContain('CLAUDE_CODE_AGENT');
@@ -1272,52 +1367,730 @@ describe('buildPreCommitHook agent detection', () => {
         // GEMINI_API_KEY intentionally excluded — human devs export it for Totem's embedding provider
     });
     it('includes TOTEM_HOOK_TIER variable', () => {
-        const hook = buildPreCommitHook();
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('TOTEM_HOOK_TIER="standard"');
     });
     it('sets TOTEM_HOOK_TIER to strict when tier is strict', () => {
-        const hook = buildPreCommitHook('strict');
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('TOTEM_HOOK_TIER="strict"');
     });
 });
 describe('buildPreCommitHook with strict tier', () => {
-    it('includes spec-completed check', () => {
-        const hook = buildPreCommitHook('strict');
-        expect(hook).toContain('.spec-completed');
+    it('gates on spec evidence and never on the retired hand-set marker', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        // The former `.totem/cache/.spec-completed` sentinel (mmnto-ai/totem#2690)
+        // may be NAMED in a comment that says it is not honored, but no test-able
+        // path may read it.
+        expect(hook).not.toMatch(/-f\s+"?\.totem\/cache\/\.spec-completed/);
         expect(hook).toContain("Run 'totem spec <issue>' before committing (strict mode)");
     });
     it('gates spec check on agent detection or strict tier', () => {
-        const hook = buildPreCommitHook('strict');
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('$is_agent');
         expect(hook).toContain('$TOTEM_HOOK_TIER');
     });
+    it('gates on the totem spec run artifact, JSON-aware — the only evidence', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        expect(hook).toContain('.totem/artifacts/runs');
+        expect(hook).toContain('admission.runMetadata.caller');
+        expect(hook).toContain('spec evidence:');
+        expect(hook).not.toContain('(legacy marker)');
+    });
+    // mmnto-ai/totem#2700 — the reader's vocabulary is RENDERED from the one
+    // canonical constant, never re-spelled in the hook text, so a change to the
+    // writer's spelling can never leave the gate reading a stale word.
+    it('renders SPEC_REQUIRED_SECTIONS and the anchor vocabulary as JSON literals', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        expect(hook).toContain(`const REQUIRED = ${JSON.stringify(SPEC_REQUIRED_SECTIONS)};`);
+        expect(hook).toContain(`const KIND_ISSUE = ${JSON.stringify(GROUNDING_ANCHOR_ISSUE)};`);
+        expect(hook).toContain(`const KIND_RECORD = ${JSON.stringify(GROUNDING_ANCHOR_RECORD)};`);
+        expect(hook).toContain(`const PROMPT_OVERRIDE = ${JSON.stringify(PROMPT_SOURCE_OVERRIDE)};`);
+    });
+    it('carries the exit-3 arm distinctly from the exit-2 and reader-failure arms', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        expect(hook).toContain('elif [ "$reader_status" = "3" ]; then');
+        expect(hook).toContain(`echo "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"`);
+        // The two pre-existing arms keep their exact text.
+        expect(hook).toContain('no totem spec run artifact under .totem/artifacts/runs/');
+        expect(hook).toContain('the spec-evidence reader could not run (node exit status');
+    });
+    it('the reader body carries no single quote (it lives inside a single-quoted node -e word)', () => {
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
+        const reader = hook.split("node -e '")[1]?.split("\n' 2>/dev/null)")[0] ?? '';
+        expect(reader.length).toBeGreaterThan(0);
+        expect(reader).not.toContain("'");
+    });
+});
+// The strict block EXECUTED under sh (mmnto-ai/totem#2690): the string checks
+// above pin the text; these pin the behavior the gate exists for. `git init` +
+// a feature branch so the protected-branch block does not fire; the agent
+// env var arms the strict tier the way an agent commit does.
+describe('buildPreCommitHook strict evidence — executed under sh (mmnto-ai/totem#2690)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-evidence-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/evidence', { 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), typeof artifact === 'string' ? artifact : JSON.stringify(artifact, null, 2));
+    }
+    // A `node` shim that fails: first on PATH, so the hook's reader cannot run.
+    // Exercises the reader-failure arm without touching the real runtime.
+    function shimNodeExiting(status) {
+        const shimDir = path.join(tmpDir, 'node-shim');
+        fs.mkdirSync(shimDir, { recursive: true });
+        fs.writeFileSync(path.join(shimDir, 'node'), `#!/bin/sh\nexit ${status}\n`, { mode: 0o755 });
+        return {
+            ...process.env,
+            CLAUDE_CODE_AGENT: '1',
+            PATH: `${shimDir}${path.delimiter}${process.env.PATH ?? ''}`,
+        };
+    }
+    function runHookWith(env) {
+        const r = spawnSync('sh', ['./pre-commit'], { cwd: tmpDir, encoding: 'utf-8', env });
+        return { status: r.status, stdout: r.stdout };
+    }
+    it.skipIf(!shellOk)('reports a reader that cannot run DISTINCTLY from missing evidence, and still fails closed', () => {
+        const r = runHookWith(shimNodeExiting(5));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('[Totem] BLOCKED: the spec-evidence reader could not run (node exit status 5');
+        expect(r.stdout).not.toContain('no totem spec run artifact');
+    });
+    it.skipIf(!shellOk)('a hand-set marker does not rescue a reader that cannot run — still the distinct failure, still closed', () => {
+        fs.mkdirSync(path.join(tmpDir, '.totem', 'cache'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, '.totem', 'cache', '.spec-completed'), '');
+        const r = runHookWith(shimNodeExiting(127));
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the spec-evidence reader could not run (node exit status 127');
+        expect(r.stdout).not.toContain('legacy');
+    });
+    it.skipIf(!shellOk)('blocks when this checkout carries no evidence at all', () => {
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain("[Totem] BLOCKED: Run 'totem spec <issue>' before committing (strict mode)");
+        expect(r.stdout).toContain('no totem spec run artifact under .totem/artifacts/runs/');
+    });
+    it.skipIf(!shellOk)('passes on a spec run artifact and prints the evidence line with its age', () => {
+        writeRun('a.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('[Totem] spec evidence: .totem/artifacts/runs/a.json (');
+        expect(r.stdout).toContain('0 days old');
+    });
+    it.skipIf(!shellOk)('does NOT pass on a review artifact that merely CARRIES a caller:spec object below the top level (the substring hazard)', () => {
+        // A substring read of the run store would match this file: the key
+        // spelling appears verbatim, as a carried OBJECT under inputBundle (the
+        // shape a review over run metadata produces). Only the TOP-LEVEL
+        // admission.runMetadata.caller is evidence. (Carried TEXT — a prompt that
+        // quotes the key — is JSON-escaped on disk and never matches either read;
+        // the carried-object form is the real hazard, so it is the control.)
+        writeRun('r.json', {
+            admission: { runMetadata: { caller: 'review' } },
+            inputBundle: { runMetadata: { caller: 'spec' } },
+            createdAt: new Date().toISOString(),
+        });
+        const onDisk = fs.readFileSync(path.join(tmpDir, '.totem/artifacts/runs/r.json'), 'utf-8');
+        // Mutation check on the control itself: the naive pattern WOULD match.
+        expect(/"caller": *"spec"/.test(onDisk)).toBe(true);
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('BLOCKED');
+    });
+    it.skipIf(!shellOk)('ignores the retired hand-set marker — a marker alone is BLOCKED', () => {
+        // No CLI path ever wrote `.totem/cache/.spec-completed`; honoring it would be
+        // compatibility with a hand hack, not with a user (operator ruling
+        // 2026-08-29, mmnto-ai/totem#2690).
+        fs.mkdirSync(path.join(tmpDir, '.totem', 'cache'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, '.totem', 'cache', '.spec-completed'), '');
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('no totem spec run artifact under .totem/artifacts/runs/');
+        expect(r.stdout).not.toContain('spec evidence:');
+    });
+    it.skipIf(!shellOk)('skips a torn (unparseable) artifact and still passes on a valid one beside it', () => {
+        writeRun('torn.json', '{"admission": {"runMetadata": {"caller": "spec"');
+        writeRun('ok.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('.totem/artifacts/runs/ok.json');
+    });
+    it.skipIf(!shellOk)('blocks when the only artifact is torn', () => {
+        writeRun('torn.json', '{"admission": {"runMetadata": {"caller": "spec"');
+        const r = runHook();
+        expect(r.status).toBe(1);
+    });
+    it.skipIf(!shellOk)('names the NEWEST spec artifact by its own createdAt', () => {
+        writeRun('old.json', specEvidenceArtifact({ createdAt: '2026-01-01T00:00:00.000Z' }));
+        writeRun('new.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('.totem/artifacts/runs/new.json');
+        expect(r.stdout).not.toContain('old.json');
+    });
+});
+// The mmnto-ai/totem#2700 arm, EXECUTED: an artifact is evidence only when it
+// is ANCHORED (issue | record) and its SUBJECT carries a shape. Every negation
+// must BLOCK with its OWN named reason — never with the "no artifact" line and
+// never as a reader failure — because the reason is the whole cure.
+describe('buildPreCommitHook anchored evidence — executed under sh (mmnto-ai/totem#2700)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    /**
+     * Whether this platform (and this account) can make a symlink — a Windows
+     * account without SeCreateSymbolicLinkPrivilege cannot. Probed ONCE, outside
+     * any test, so the skip is a real capability check rather than a swallowed
+     * failure inside the assertion.
+     */
+    const symlinkable = (() => {
+        const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-link-probe-'));
+        const target = path.join(probeDir, 'target');
+        fs.writeFileSync(target, 'probe');
+        let ok = false;
+        try {
+            fs.symlinkSync(target, path.join(probeDir, 'sym'));
+            ok = true;
+        }
+        catch (err) {
+            void err;
+            ok = false;
+        }
+        cleanTmpDir(probeDir);
+        return ok;
+    })();
+    let tmpDir;
+    /** A directory OUTSIDE the worktree — the target of the escaping-symlink case. */
+    let outsideDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-anchor-'));
+        outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-outside-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/anchored', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook(RENDER));
+    });
+    afterEach(() => {
+        cleanTmpDir(tmpDir);
+        cleanTmpDir(outsideDir);
+    });
+    function runHook() {
+        const r = spawnSync('sh', ['./pre-commit'], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            env: { ...process.env, CLAUDE_CODE_AGENT: '1' },
+        });
+        return { status: r.status, stdout: r.stdout };
+    }
+    function writeRun(name, artifact) {
+        const dir = path.join(tmpDir, '.totem', 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, name), JSON.stringify(artifact, null, 2));
+    }
+    /** Write a bound record at a repo-relative path and return its sha256. */
+    function writeRecord(relPath, body) {
+        const abs = path.join(tmpDir, ...relPath.split('/'));
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, body, 'utf-8');
+        return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+    }
+    /** Every BLOCKED arm must be distinguishable from the other two arms. */
+    function expectDistinctBlock(stdout) {
+        expect(stdout).not.toContain('no totem spec run artifact');
+        expect(stdout).not.toContain('the spec-evidence reader could not run');
+    }
+    // ── The migration invariant ──
+    it.skipIf(!shellOk)('a PRE-EXISTING artifact (no grounding.anchor) BLOCKS with the `predates` reason, not the no-artifact line', () => {
+        writeRun('legacy.json', {
+            admission: { runMetadata: { caller: 'spec' } },
+            output: { content: TEMPLATE_DRAFT },
+            createdAt: new Date().toISOString(),
+        });
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('predates the anchored-evidence rule (no grounding.anchor)');
+        expect(r.stdout).toContain('.totem/artifacts/runs/legacy.json');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The unanchored kinds ──
+    it.skipIf(!shellOk)('a `free-text` anchor BLOCKS, naming the kind and the topic', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'a loose slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is anchored ${GROUNDING_ANCHOR_FREE_TEXT} (a loose slug)`);
+        expect(r.stdout).toContain('not gate evidence');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a `mixed` anchor BLOCKS, naming the kind and the ref', () => {
+        writeRun('mx.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_MIXED, ref: '#2700 | a loose slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`is anchored ${GROUNDING_ANCHOR_MIXED} (#2700 | a loose slug)`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('both cures are named on every BLOCKED arm', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.stdout).toContain("run 'totem spec <issue>' or 'totem spec --from <record>'");
+    });
+    // ── The TEMPLATE shape (issue anchor, built-in prompt) ──
+    it.skipIf(!shellOk)('the one-token draft (a lone newline) BLOCKS on the first missing heading', () => {
+        writeRun('thin.json', specEvidenceArtifact({ output: { content: '\n' } }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('is missing heading ### Problem Statement');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('both required headings present over EMPTY bodies BLOCK, naming the empty heading', () => {
+        writeRun('empty.json', specEvidenceArtifact({
+            output: { content: '### Problem Statement\n\n### Implementation Tasks\n' },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has an empty heading ### Problem Statement');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a second required heading left empty BLOCKS, naming THAT heading', () => {
+        writeRun('half.json', specEvidenceArtifact({
+            output: {
+                content: '### Problem Statement\n\nA real body.\n\n### Implementation Tasks\n',
+            },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has an empty heading ### Implementation Tasks');
+    });
+    it.skipIf(!shellOk)('both required headings with bodies PASS, and the evidence line carries the anchor and the shape', () => {
+        writeRun('ok.json', specEvidenceArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('[Totem] spec evidence: .totem/artifacts/runs/ok.json (');
+        expect(r.stdout).toContain(`· anchor ${GROUNDING_ANCHOR_ISSUE} #2700`);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a non-string draft on an issue anchor BLOCKS as not-text', () => {
+        writeRun('nt.json', specEvidenceArtifact({ output: { content: { nested: true } } }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the draft is not text');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The DOCUMENT shape (override prompt on an issue anchor) ──
+    it.skipIf(!shellOk)('an OVERRIDE-prompt draft without the template headings PASSES on one heading with a body', () => {
+        writeRun('ov.json', specEvidenceArtifact({
+            admission: {
+                runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE },
+            },
+            output: { content: DOCUMENT_DRAFT },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    it.skipIf(!shellOk)('an OVERRIDE-prompt draft with no heading at all BLOCKS', () => {
+        writeRun('ovbad.json', specEvidenceArtifact({
+            admission: { runMetadata: { caller: 'spec', promptSource: PROMPT_SOURCE_OVERRIDE } },
+            output: { content: 'just prose, no heading\n' },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has no heading with a body');
+        expect(r.stdout).toContain('custom prompt');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── The record arm: the SUBJECT is the record's bytes ──
+    function recordArtifact(ref, sha256, draft = TEMPLATE_DRAFT) {
+        return specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_RECORD, ref, sha256 } },
+            output: { content: draft },
+        });
+    }
+    it.skipIf(!shellOk)('a present record with a heading and a body PASSES, reporting `record sha256 matches`', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain(`· anchor ${GROUNDING_ANCHOR_RECORD} .totem/specs/2700.md`);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a REVISED record still PASSES — the digest is a SENSOR, never a gate', () => {
+        const bound = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', bound));
+        const now = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract, folded.\n');
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain(`record revised since binding (bound ${bound.slice(0, 8)}, now ${now.slice(0, 8)})`);
+    });
+    it.skipIf(!shellOk)('a MISSING record BLOCKS, naming the path it was bound at', () => {
+        writeRun('rec.json', recordArtifact('.totem/specs/gone.md', 'b'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record is missing at .totem/specs/gone.md');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record with NO heading-with-a-body BLOCKS', () => {
+        const sha = writeRecord('.totem/specs/2700.md', 'prose with no heading\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record at .totem/specs/2700.md has no heading with a body');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record whose heading has no body BLOCKS (a heading alone is not a document)', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Heading only\n\n## Another heading\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('has no heading with a body');
+    });
+    it.skipIf(!shellOk)('a THIN draft with a rich record PASSES — the reader never reads output.content on a record anchor', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('rec.json', recordArtifact('.totem/specs/2700.md', sha, '\n'));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a RICH draft with a missing record BLOCKS — the record is the subject, not the draft', () => {
+        writeRun('rec.json', recordArtifact('.totem/specs/gone.md', 'c'.repeat(64), TEMPLATE_DRAFT));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record is missing at');
+    });
+    // ── The body-line boundary is a HEADING, not a leading "#" ──
+    //
+    // `#2700 is the issue.` is prose about an issue number, not a heading: no
+    // space follows the hashes. Reading it as a boundary made a real body look
+    // empty — the exact sentence a totem design record is most likely to open a
+    // section with.
+    it.skipIf(!shellOk)('a body line starting with `#2700` is a BODY on the TEMPLATE arm', () => {
+        const draft = SPEC_REQUIRED_SECTIONS.map((heading) => `${heading}\n\n#2700 is the issue.\n`).join('\n');
+        writeRun('hashbody.json', specEvidenceArtifact({ output: { content: draft } }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a body line starting with `#2700` is a BODY on the DOCUMENT arm', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\n#2700 is the issue.\n');
+        writeRun('hashrec.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    // ── The DOCUMENT shape tolerates two ordinary authoring bytes ──
+    it.skipIf(!shellOk)('a DRAFT opening with a UTF-8 BOM still reads as a template', () => {
+        // The BOM strip runs on the SUBJECT, before the split — so it covers the
+        // TEMPLATE arm too, where an unstripped BOM would make the first required
+        // heading fail its exact-line match and BLOCK a well-formed draft.
+        const bom = String.fromCharCode(0xfeff);
+        writeRun('bomdraft.json', specEvidenceArtifact({ output: { content: bom + TEMPLATE_DRAFT } }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape TEMPLATE');
+    });
+    it.skipIf(!shellOk)('a record opening with a UTF-8 BOM still reads as a document', () => {
+        const bom = String.fromCharCode(0xfeff);
+        const sha = writeRecord('.totem/specs/2700.md', `${bom}# Record\n\nThe ruled contract.\n`);
+        writeRun('bom.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    it.skipIf(!shellOk)('a heading separated from its text by a TAB is a heading', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '#\tTabbed heading\n\nThe body.\n');
+        writeRun('tab.json', recordArtifact('.totem/specs/2700.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· shape DOCUMENT');
+    });
+    // ── The artifact is hand-editable: nothing read out of it is trusted text ──
+    it.skipIf(!shellOk)('a newline in anchor.ref cannot forge a second [Totem] line', () => {
+        const forged = `slug${String.fromCharCode(0x0a)}[Totem] spec evidence: forged`;
+        writeRun('inject.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: forged } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        // Exactly one line of the hook's own output claims to be from Totem.
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        // The control character is collapsed, not dropped — the ref stays legible.
+        expect(r.stdout).toContain('slug?[Totem] spec evidence: forged');
+    });
+    it.skipIf(!shellOk)('a C1 control (U+0085 NEL) in anchor.ref is collapsed too', () => {
+        // A predicate stopping at 0x7f let the whole C1 band through; NEL is a
+        // LINE BREAK to some terminals and pagers, so it is a forged-line vector
+        // of exactly the same kind as 0x0a.
+        const forged = `slug${String.fromCharCode(0x85)}[Totem] spec evidence: forged`;
+        writeRun('nel.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: forged } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('slug?[Totem] spec evidence: forged');
+        expect(r.stdout).not.toContain(String.fromCharCode(0x85));
+    });
+    it.skipIf(!shellOk)('a newline in createdAt cannot forge a second [Totem] line on the PASS path', () => {
+        // `createdAt` is read raw off the artifact and ECHOED in the evidence
+        // line: unsanitized, a hand-edited stamp forges a second `[Totem] spec
+        // evidence:` line inside a passing commit — the quietest place to hide
+        // one.
+        const forged = `2026-09-02T00:00:00.000Z${String.fromCharCode(0x0a)}[Totem] spec evidence: FORGED`;
+        writeRun('stamp.json', specEvidenceArtifact({ createdAt: forged }));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout.split('\n').filter((line) => line.startsWith('[Totem]'))).toHaveLength(1);
+        expect(r.stdout).toContain('.000Z?[Totem] spec evidence: FORGED');
+    });
+    it.skipIf(!shellOk)('a record ref that is ABSOLUTE is refused as outside the worktree', () => {
+        writeRun('abs.json', recordArtifact('/etc/passwd', 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record ref is outside the worktree: /etc/passwd');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record ref whose first segment is `..` is refused as outside the worktree', () => {
+        writeRun('dotdot.json', recordArtifact('../outside.md', 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record ref is outside the worktree: ../outside.md');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── Containment is decided by RESOLUTION, not by segment 0 ──
+    //
+    // A first-segment test reads `sub/../../OUTSIDE.md` and `./../OUTSIDE.md` as
+    // contained, so the reader would have READ and PASSED a file outside the
+    // worktree. The reader now resolves the ref against `process.cwd()` — the
+    // worktree top git runs hooks from — and refuses anything that lands outside
+    // it, which is also the honest rule for the legitimate mid-path `..`.
+    /** A backslash, built rather than escaped — the mmnto-ai/totem#2692 authoring trap. */
+    const BACKSLASH = String.fromCharCode(0x5c);
+    it.skipIf(!shellOk).each([
+        ['sub/../../OUTSIDE.md', 'a `..` past segment 0'],
+        ['./../OUTSIDE.md', 'a `.` first segment hiding a `..`'],
+        [
+            `a${BACKSLASH}..${BACKSLASH}..${BACKSLASH}OUTSIDE.md`,
+            'the same escape spelled with backslashes',
+        ],
+    ])('refuses %s as outside the worktree (%s)', (ref) => {
+        writeRun('escape.json', recordArtifact(ref, 'd'.repeat(64)));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`the bound record ref is outside the worktree: ${ref}`);
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a mid-path `..` that stays INSIDE the worktree still PASSES — containment, not a segment ban', () => {
+        // `a/` must exist for POSIX path resolution to reach `a/../b.md`.
+        fs.mkdirSync(path.join(tmpDir, 'a'), { recursive: true });
+        const sha = writeRecord('b.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('inside.json', recordArtifact('a/../b.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    it.skipIf(!shellOk)('a record anchor with NO sha256 BLOCKS — a binding without bytes is not a binding', () => {
+        writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('nosha.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_RECORD, ref: '.totem/specs/2700.md' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the record anchor carries no sha256 — not evidence');
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk)('a record anchor whose sha256 is MALFORMED BLOCKS with its OWN reason, not the absent one', () => {
+        // "No digest" and "a digest that is not a digest" are different repairs:
+        // the first says re-bind, the second says the artifact was edited. One
+        // shared message would send both to the wrong cure.
+        writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        writeRun('badsha.json', recordArtifact('.totem/specs/2700.md', 'not-a-digest'));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the record anchor sha256 is not a 64-hex digest (not-a-digest) — not evidence');
+        expect(r.stdout).not.toContain('carries no sha256');
+        expectDistinctBlock(r.stdout);
+    });
+    // ── Containment sees THROUGH a link (mmnto-ai/totem#2700) ──
+    //
+    // A symlink inside the worktree is LEXICALLY contained, so the resolve-based
+    // test above reads it as legal — and the reader would open, hash and judge a
+    // file outside the tree. The realpath pair is compared once the ref is known
+    // to exist and BEFORE its bytes are read.
+    it.skipIf(!shellOk || !symlinkable)('a record ref that is a SYMLINK to OUTSIDE the worktree BLOCKS, naming both spellings', () => {
+        const target = path.join(outsideDir, 'record.md');
+        fs.writeFileSync(target, '# Outside\n\nThe ruled contract.\n', 'utf-8');
+        const sha = crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex');
+        fs.symlinkSync(target, path.join(tmpDir, 'linked.md'));
+        // A CORRECT digest, so the block cannot be the sha256 arm firing early.
+        writeRun('symlink-out.json', recordArtifact('linked.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('the bound record resolves outside the worktree: linked.md -> ');
+        expect(r.stdout).toContain(fs.realpathSync.native(target));
+        expectDistinctBlock(r.stdout);
+    });
+    it.skipIf(!shellOk || !symlinkable)('a record ref that is a SYMLINK to an IN-worktree file PASSES — containment, not a link ban', () => {
+        const sha = writeRecord('.totem/specs/2700.md', '# Record\n\nThe ruled contract.\n');
+        fs.symlinkSync(path.join(tmpDir, '.totem', 'specs', '2700.md'), path.join(tmpDir, 'linked.md'));
+        writeRun('symlink-in.json', recordArtifact('linked.md', sha));
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain('· record sha256 matches');
+    });
+    // ── The cure names the cache (mmnto-ai/totem#2700 m11) ──
+    it.skipIf(!shellOk)('the BLOCKED cure names --fresh — a cached response mints no artifact', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.stdout).toContain('(add --fresh if the response is cached)');
+    });
+    // ── The other arms stay distinct ──
+    it.skipIf(!shellOk)('exit 3 is NEVER reported as a reader failure', () => {
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).not.toContain('node exit status');
+    });
+    it.skipIf(!shellOk)('the carried-object substring control still BLOCKS with the no-artifact line', () => {
+        // Only the TOP-LEVEL caller counts: a review artifact that carries a
+        // `caller: spec` object below the top level is not a spec artifact at all,
+        // so the gate reports "none found", not "not evidence".
+        writeRun('r.json', {
+            admission: { runMetadata: { caller: 'review' } },
+            inputBundle: { runMetadata: { caller: 'spec' } },
+            createdAt: new Date().toISOString(),
+        });
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain('no totem spec run artifact');
+    });
+    it.skipIf(!shellOk)('the retired hand-set marker still rescues nothing', () => {
+        fs.mkdirSync(path.join(tmpDir, '.totem', 'cache'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, '.totem', 'cache', '.spec-completed'), '');
+        writeRun('ft.json', specEvidenceArtifact({
+            grounding: { anchor: { kind: GROUNDING_ANCHOR_FREE_TEXT, ref: 'slug' } },
+        }));
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).not.toContain('spec evidence:');
+    });
+});
+// The mmnto-ai/totem#2692 keystone, EXECUTED: under a custom `totemDir` the
+// hook's reader and `totem spec`'s writer must name the SAME tree. The fixture
+// writes where the WRITER writes (`<totemDir>/artifacts/runs`, the
+// `path.join(configRoot, config.totemDir)/artifacts/runs` the run store uses) and
+// the hook is rendered at that same totemDir — so a pass here is the two halves
+// agreeing, and the control below is the pre-fix behavior (evidence under
+// `.totem/` while the hook reads `knowledge/`) still failing closed.
+describe('buildPreCommitHook strict evidence under a CUSTOM totemDir — executed under sh (mmnto-ai/totem#2692)', () => {
+    const shellOk = spawnSync('sh', ['-c', 'command -v node >/dev/null 2>&1'], { encoding: 'utf-8' }).status === 0;
+    const CUSTOM_TOTEM_DIR = 'knowledge';
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'totem-hook-customdir-'));
+        execSync('git init -q', { cwd: tmpDir, stdio: 'ignore' });
+        execSync('git checkout -q -b feat/evidence', { cwd: tmpDir, stdio: 'ignore' });
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook({ ...RENDER, totemDir: CUSTOM_TOTEM_DIR }));
+    });
+    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 };
+    }
+    /** Write a run artifact where the WRITER writes it, for an arbitrary totemDir. */
+    function writeRunUnder(totemDir, name, artifact) {
+        const dir = path.join(tmpDir, ...totemDir.split('/'), 'artifacts', 'runs');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, name), JSON.stringify(artifact, null, 2));
+    }
+    const specArtifact = () => specEvidenceArtifact();
+    it.skipIf(!shellOk)('PASSES on evidence written under the configured totemDir', () => {
+        writeRunUnder(CUSTOM_TOTEM_DIR, 'a.json', specArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain(`[Totem] spec evidence: ${CUSTOM_TOTEM_DIR}/artifacts/runs/a.json (`);
+    });
+    it.skipIf(!shellOk)('the pre-fix control: evidence under .totem/ does NOT satisfy a hook rendered for knowledge/', () => {
+        // This is the mmnto-ai/totem#2692 defect, inverted: before the fix the hook
+        // ALWAYS read `.totem/artifacts/runs` while the writer used the configured
+        // dir, so the gate failed closed forever. With the hook rendered at the
+        // configured dir, evidence in the WRONG tree is correctly not evidence.
+        writeRunUnder('.totem', 'a.json', specArtifact());
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain(`no totem spec run artifact under ${CUSTOM_TOTEM_DIR}/artifacts/runs/`);
+    });
+    it.skipIf(!shellOk)('blocks with a message naming the configured directory', () => {
+        const r = runHook();
+        expect(r.status).toBe(1);
+        expect(r.stdout).toContain("[Totem] BLOCKED: Run 'totem spec <issue>' before committing (strict mode)");
+        expect(r.stdout).toContain(`under ${CUSTOM_TOTEM_DIR}/artifacts/runs/`);
+        expect(r.stdout).not.toContain('.totem');
+    });
+    it.skipIf(!shellOk)('a nested totemDir survives the same round trip', () => {
+        const nested = 'var/totem-state';
+        fs.writeFileSync(path.join(tmpDir, 'pre-commit'), buildPreCommitHook({ ...RENDER, totemDir: nested }));
+        writeRunUnder(nested, 'a.json', specArtifact());
+        const r = runHook();
+        expect(r.status).toBe(0);
+        expect(r.stdout).toContain(`[Totem] spec evidence: ${nested}/artifacts/runs/a.json (`);
+    });
 });
 describe('buildPreCommitHook with standard tier', () => {
-    it('includes spec-completed check guarded by agent/tier condition', () => {
-        const hook = buildPreCommitHook('standard');
-        expect(hook).toContain('.spec-completed');
+    it('includes the spec-evidence check guarded by agent/tier condition', () => {
+        const hook = buildPreCommitHook(RENDER);
+        expect(hook).toContain('.totem/artifacts/runs');
         expect(hook).toContain('is_agent');
         expect(hook).toContain('TOTEM_HOOK_TIER="standard"');
     });
-    it('defaults to standard tier when no tier specified', () => {
-        const hook = buildPreCommitHook();
+    // Pre-mmnto-ai/totem#2692 this read "defaults to standard tier when no tier
+    // specified". There is no default any more — the options object is required and
+    // the RESOLVER supplies 'standard' — so the surviving intent is that the
+    // standard-tier render still names the run store the resolver hands it.
+    it('renders the run store at the options it was given', () => {
+        const hook = buildPreCommitHook(RENDER);
         expect(hook).toContain('TOTEM_HOOK_TIER="standard"');
-        expect(hook).toContain('.spec-completed');
+        expect(hook).toContain('.totem/artifacts/runs');
     });
 });
 describe('buildPrePushHook with strict tier', () => {
-    const FALLBACK = 'pnpm dlx @mmnto/cli';
     it('includes shield gate', () => {
-        const hook = buildPrePushHook(FALLBACK, 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('review');
         expect(hook).toContain('shield gate (strict mode)');
     });
     it('includes TOTEM_HOOK_TIER set to strict', () => {
-        const hook = buildPrePushHook(FALLBACK, 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('TOTEM_HOOK_TIER="strict"');
     });
     it('includes agent detection snippet', () => {
-        const hook = buildPrePushHook(FALLBACK, 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('is_agent=0');
         expect(hook).toContain('CLAUDE_CODE_AGENT');
     });
@@ -1325,12 +2098,12 @@ describe('buildPrePushHook with strict tier', () => {
     // shieldBlock alongside the existing `totem review` gate. Repo-state
     // checks (like checkAgentsMdCanonical) now block push when they fail.
     it('includes $TOTEM_CMD doctor --strict in the shield block', () => {
-        const hook = buildPrePushHook(FALLBACK, 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         expect(hook).toContain('$TOTEM_CMD doctor --strict');
         expect(hook).toContain('doctor --strict (repo-state gate)');
     });
     it('gates doctor --strict on the agent/strict guard (does NOT fire unconditionally)', () => {
-        const hook = buildPrePushHook(FALLBACK, 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         // Find the position of the doctor --strict invocation and the surrounding
         // guard; assert the invocation lives INSIDE the agent-or-tier block.
         const guardIdx = hook.indexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]');
@@ -1342,20 +2115,22 @@ describe('buildPrePushHook with strict tier', () => {
     });
 });
 describe('buildPrePushHook with standard tier', () => {
-    const FALLBACK = 'pnpm dlx @mmnto/cli';
     it('includes shield gate guarded by agent/tier condition', () => {
-        const hook = buildPrePushHook(FALLBACK, 'standard');
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('shield gate');
         expect(hook).toContain('is_agent');
         expect(hook).toContain('TOTEM_HOOK_TIER="standard"');
     });
-    it('defaults to standard tier when no tier specified', () => {
-        const hook = buildPrePushHook(FALLBACK);
+    // Pre-mmnto-ai/totem#2692 this read "defaults to standard tier when no tier
+    // specified" — the builders take a REQUIRED options object now, so the
+    // surviving intent is that a standard-tier render stamps the standard tier.
+    it('stamps the standard tier it was given', () => {
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('TOTEM_HOOK_TIER="standard"');
         expect(hook).toContain('shield gate');
     });
     it('still includes agent detection', () => {
-        const hook = buildPrePushHook(FALLBACK, 'standard');
+        const hook = buildPrePushHook(RENDER);
         expect(hook).toContain('is_agent=0');
     });
     // mmnto-ai/totem#1908 — even in standard tier, the doctor --strict line
@@ -1364,7 +2139,7 @@ describe('buildPrePushHook with standard tier', () => {
     // operators bypass it because their `is_agent=0` and `TOTEM_HOOK_TIER` is
     // standard, so the guard branch never enters.
     it('emits doctor --strict gated by agent/strict guard (no unconditional fire in standard tier)', () => {
-        const hook = buildPrePushHook(FALLBACK, 'standard');
+        const hook = buildPrePushHook(RENDER);
         const guardIdx = hook.indexOf('if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]');
         const doctorIdx = hook.indexOf('$TOTEM_CMD doctor --strict');
         const fiCloseIdx = hook.indexOf('fi', guardIdx);
@@ -1375,7 +2150,7 @@ describe('buildPrePushHook with standard tier', () => {
 });
 describe('agent detection uses POSIX syntax', () => {
     it('pre-commit hook has no bashisms', () => {
-        const hook = buildPreCommitHook('strict');
+        const hook = buildPreCommitHook({ ...RENDER, tier: 'strict' });
         // Must use [ ] not [[ ]]
         expect(hook).not.toContain('[[');
         expect(hook).not.toContain(']]');
@@ -1385,7 +2160,7 @@ describe('agent detection uses POSIX syntax', () => {
         expect(hook).toMatch(/^#!\/bin\/sh\n/);
     });
     it('pre-push hook has no bashisms', () => {
-        const hook = buildPrePushHook('pnpm dlx @mmnto/cli', 'strict');
+        const hook = buildPrePushHook({ ...RENDER, tier: 'strict' });
         // Must use [ ] not [[ ]]
         expect(hook).not.toContain('[[');
         expect(hook).not.toContain(']]');