@mmnto/cli 1.120.0 → 1.122.0

package/dist/commands/install-hooks.js

@@ -3,7 +3,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { stdin as input, stdout as output } from 'node:process';
 import * as readline from 'node:readline/promises';
+import { GROUNDING_ANCHOR_ISSUE, GROUNDING_ANCHOR_RECORD, PROMPT_SOURCE_OVERRIDE, } from '../artifact-vocabulary.js';
 import { resolveGitRoot } from '../git.js';
+import { SPEC_REQUIRED_SECTIONS } from './spec-templates.js';
 export const TOTEM_HOOK_MARKER = '[totem] post-merge hook';
 export const TOTEM_HOOK_END = '[totem] end post-merge';
 export const TOTEM_CHECKOUT_MARKER = '[totem] post-checkout hook';
@@ -12,6 +14,12 @@ export const TOTEM_PRECOMMIT_MARKER = '[totem] pre-commit hook';
 export const TOTEM_PRECOMMIT_END = '[totem] end pre-commit';
 export const TOTEM_PREPUSH_MARKER = '[totem] pre-push hook';
 export const TOTEM_PREPUSH_END = '[totem] end pre-push';
+/**
+ * Hex characters of each sha256 the strict reader's record SENSOR shows when
+ * a bound record has been revised (mmnto-ai/totem#2700). Identity at a glance,
+ * not a full digest — the comparison itself is over the whole hash.
+ */
+const RECORD_HASH_DISPLAY_PREFIX = 8;
 // ─── Hooks-directory resolution (mmnto-ai/totem#2418) ─────────
 /**
  * Resolve the git hooks directory for `gitRoot`. In a plain checkout this is
@@ -124,6 +132,186 @@ export function detectTotemPrefix(cwd) {
         return 'bunx totem';
     return 'npx totem';
 }
+// ─── Hook render options (mmnto-ai/totem#2692) ────────────────
+/** The `totemDir` every hook renders when the repo configures none. */
+export const DEFAULT_TOTEM_DIR = '.totem';
+/**
+ * Whether `value` carries a character that cannot be rendered SAFELY into the
+ * managed hooks: a single quote (breaks the `sh` single-quoted word AND the
+ * single-quoted `node -e '…'` reader), a double quote or a backslash (breaks the
+ * JS string literal inside that reader), a dollar sign or a backtick (the only
+ * characters that stay ACTIVE inside the double-quoted `sh` words every guard
+ * uses — refusing them is what lets those sites keep the one plain
+ * double-quoted form `tools/*` ships; mmnto-ai/totem#2692 amendment A2), or a
+ * control character / newline (breaks both, and can forge lines in the hook
+ * body).
+ *
+ * Written as a code-point walk rather than a regex with escape literals so the
+ * predicate carries no escape sequence of its own to mis-author.
+ */
+export function hasUnrenderableTotemDirChar(value) {
+    for (const ch of value) {
+        if (ch === "'" || ch === '"' || ch === '\\' || ch === '$' || ch === '`')
+            return true;
+        const code = ch.codePointAt(0) ?? 0;
+        // Control characters, DEL, and everything non-ASCII: git C-quotes any path
+        // byte above 0x7e in the `diff --name-only` output the two `grep -q` diff
+        // filters read (`core.quotePath`, on by default), so a directory name
+        // carrying one could never match — the silent-skip class this closes.
+        if (code < 0x20 || code > 0x7e)
+            return true;
+    }
+    return false;
+}
+/**
+ * Why `totemDir` cannot be rendered into the managed hooks, or `null` when it
+ * can (mmnto-ai/totem#2692 C4 + amendment A7). Two classes:
+ *
+ *  - CHARACTERS the quoting regimes cannot carry (see
+ *    {@link hasUnrenderableTotemDirChar}) — the `@mmnto/totem` schema refuses
+ *    the same set, so a validated config never reaches this arm.
+ *  - SHAPES the hooks could never govern, which the schema deliberately still
+ *    accepts because other verbs can use them (`.` is the global profile's own
+ *    spelling): empty, a trailing slash, `.`, a `.` or empty segment, a `..`
+ *    segment, a leading `-`. Each of these renders a hook whose post-merge /
+ *    post-checkout diff filter (`grep -q '<dir>/…'` over the repo-relative
+ *    paths git prints) can never match, or — for the empty value — an ABSOLUTE
+ *    run-store path in the strict pre-commit reader. The schema normalises a
+ *    trailing slash away; a raw value reaching a builder directly is refused,
+ *    never normalised here (a builder is a pure function of its options).
+ */
+export function hookTotemDirProblem(totemDir) {
+    if (hasUnrenderableTotemDirChar(totemDir)) {
+        return 'a single quote, double quote, backslash, dollar sign, backtick, non-ASCII character, newline or control character cannot be safely rendered into the managed hooks (git C-quotes non-ASCII paths, so a diff filter naming one could never match)';
+    }
+    if (totemDir.length === 0) {
+        return "an empty totemDir renders an ABSOLUTE run-store path ('/artifacts/runs') into the strict pre-commit reader and a diff filter that matches every path";
+    }
+    if (totemDir.endsWith('/')) {
+        return "a trailing slash renders 'dir//…' into the post-merge / post-checkout diff filters, which then never match — spell it without the slash";
+    }
+    if (totemDir === '.') {
+        return "'.' names the config directory itself; the hooks' diff filters ('grep -q <dir>/…') could never match the repo-relative paths git prints";
+    }
+    const segments = totemDir.split('/');
+    if (segments.includes('.') || segments.includes('')) {
+        return "a '.' segment (or '//') never appears in the repo-relative paths git prints, so the diff filters would never match";
+    }
+    if (segments.includes('..')) {
+        return "a '..' segment points outside the worktree the hooks run in; git prints repo-relative paths, so the diff filters could never match";
+    }
+    if (totemDir.startsWith('-')) {
+        return "a leading '-' is read as an option by grep in the diff filters";
+    }
+    return null;
+}
+/**
+ * Refuse — loudly, naming the value and the reason — a `totemDir` the hook
+ * templates cannot render (mmnto-ai/totem#2692 C4/A7). Called by the resolver
+ * on the configured value and by every builder as the render-path backstop for
+ * direct-API and hand-threaded call sites.
+ *
+ * Throws rather than degrades: a hook rendered from a value we could not quote
+ * is a shell-injection surface, and silently falling back to `.totem` would
+ * re-create the very writer/reader split this slice closes (Tenet 4).
+ */
+export function assertRenderableTotemDir(totemDir) {
+    const problem = hookTotemDirProblem(totemDir);
+    if (problem === null)
+        return;
+    // A plain Error, unprefixed: this backstop sits on the SYNC render path (the
+    // builders), where `@mmnto/totem`'s TotemError cannot be lazy-imported; the
+    // resolver — the CLI's actual entry — raises the TotemError form of the same
+    // refusal. `handleError` adds the `[Totem Error]` tag, so the message carries
+    // none of its own (Gemini on mmnto-ai/totem#2701).
+    throw new Error(`Refusing to render git hooks for totemDir ${JSON.stringify(totemDir)}: ${problem}. ` +
+        'Set `totemDir` to a plain relative directory inside the repo and re-run `totem hook install --force`.');
+}
+/**
+ * Escape a validated `totemDir` for a POSIX Basic Regular Expression — the two
+ * `grep -q '…'` diff filters. BRE specials are `\ ^ $ . * [ ]`; `^` and `$` are
+ * only special positionally, but escaping them unconditionally is still a
+ * literal match and keeps the rule one line.
+ */
+function escapeBre(value) {
+    return value.replace(/[\\^$.*[\]]/g, '\\$&');
+}
+/**
+ * THE resolver: config → the options every hook writer renders from
+ * (mmnto-ai/totem#2692 C1).
+ *
+ * `tier` = explicit flag > `hooks.tier` from config > `'standard'` (the
+ * precedence `hooksCommand` already implemented, moved here so `totem init`,
+ * `installHooksNonInteractive` and the silent pre-push upgrade honor it too) —
+ * from whichever config resolves, global profile included, exactly as before.
+ *
+ * `totemDir` = the REPO-LOCAL config's `totemDir` > `.totem`. Repo-local only,
+ * and deliberately asymmetric with `tier`: the value is a path rendered into a
+ * hook that runs at the worktree top, so only this project's config can name it.
+ * The global `~/.totem/` profile `totem init --global` writes declares
+ * `totemDir: '.'` — describing that profile directory itself — and honoring it
+ * here would silently re-render every config-less repo's hooks against the
+ * checkout root on any machine that has a profile (the mmnto-ai/totem#2692 C3
+ * "no consumer's hooks drift on upgrade" invariant, and the same
+ * machine-dependence `doctor --parity` guards with `isGlobalConfigPath`).
+ *
+ * `fallbackCmd` = the lockfile probe anchored at `cwd` — pass the GIT ROOT, the
+ * anchor the installer has always used, so a hook installed from a subdirectory
+ * still names the repo's package manager.
+ *
+ * No config at all → the defaults, silently: a config-less repo installing hooks
+ * is a supported path, not an error. A config that RESOLVES but will not LOAD
+ * (a syntax error, a `totemDir` the schema refines out) → the defaults, LOUDLY:
+ * one line names the file and the failure, so a repo whose config says
+ * `knowledge/` never gets `.totem/` hooks without a word (mmnto-ai/totem#2692
+ * amendment A8 — the silent→loud shape of mmnto-ai/totem#2685). A config that
+ * loads but names a `totemDir` the hooks cannot govern (`.`, a `..` segment, a
+ * leading `-`) REFUSES — {@link assertRenderableTotemDir}.
+ */
+export async function resolveHookRenderOptions(cwd, flags) {
+    const fallbackCmd = getFallbackCommand(cwd);
+    const defaults = {
+        tier: flags?.tier ?? 'standard',
+        totemDir: DEFAULT_TOTEM_DIR,
+        fallbackCmd,
+    };
+    const { loadConfig, loadEnv, resolveConfigPath, isGlobalConfigPath } = await import('../utils.js');
+    loadEnv(cwd);
+    let configPath;
+    try {
+        configPath = resolveConfigPath(cwd);
+        // totem-context: no config anywhere (resolveConfigPath throws CONFIG_MISSING) is the honest-default path — hooks install in config-less repos by design.
+    }
+    catch {
+        return defaults;
+    }
+    let config;
+    try {
+        config = await loadConfig(configPath);
+        // totem-context: LOUD default, not a swallow — the failure is printed on the line below and surfaced as `configError`; a repo whose config will not load still gets default hooks rather than an aborted install (mmnto-ai/totem#2692 A8, the silent→loud shape of mmnto-ai/totem#2685).
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`[Totem] Could not load ${configPath} (${reason.split('\n')[0]}) — the git hooks are rendered at the defaults (totemDir '${DEFAULT_TOTEM_DIR}', tier '${defaults.tier}'); fix the config and re-run \`totem hook install --force\`.`);
+        return { ...defaults, configError: reason };
+    }
+    const totemDir = isGlobalConfigPath(configPath)
+        ? DEFAULT_TOTEM_DIR
+        : (config.totemDir ?? DEFAULT_TOTEM_DIR);
+    // The CLI-layer form of the refusal: a TotemError with a recovery hint (the
+    // sync builders keep the plain-Error backstop, `assertRenderableTotemDir`).
+    const problem = hookTotemDirProblem(totemDir);
+    if (problem !== null) {
+        const { TotemError } = await import('@mmnto/totem');
+        throw new TotemError('CONFIG_INVALID', `Refusing to render git hooks for totemDir ${JSON.stringify(totemDir)}: ${problem}`, 'Set `totemDir` to a plain relative directory inside the repo and re-run `totem hook install --force`.');
+    }
+    return {
+        tier: flags?.tier ?? config.hooks?.tier ?? 'standard',
+        totemDir,
+        fallbackCmd,
+        configPath,
+    };
+}
 /**
  * Build a POSIX shell block that resolves the totem command at runtime.
  *
@@ -154,7 +342,9 @@ else
   TOTEM_CMD=""
 fi`;
 }
-export function buildHookContent(fallbackCmd) {
+export function buildHookContent(options) {
+    const { fallbackCmd, totemDir } = options;
+    assertRenderableTotemDir(totemDir);
     return `#!/bin/sh
 # ${TOTEM_HOOK_MARKER} — background re-index after pull/merge.
 
@@ -217,7 +407,7 @@ fi
 # Only sync when lessons changed (suppress errors if ORIG_HEAD is missing).
 # The trailing -- terminates the revision list so a ref/path ambiguity can never
 # reinterpret ORIG_HEAD/HEAD as pathspecs.
-if [ -n "$TOTEM_CMD" ] && git diff-tree -r --name-only ORIG_HEAD HEAD -- 2>/dev/null | grep -q '\\.totem/lessons/'; then
+if [ -n "$TOTEM_CMD" ] && git diff-tree -r --name-only ORIG_HEAD HEAD -- 2>/dev/null | grep -q '${escapeBre(totemDir)}/lessons/'; then
   # Resolve the real git dir so the sync-log redirect works in a linked worktree,
   # where .git is a FILE (gitdir: pointer), not a directory (mmnto-ai/totem#2376).
   GIT_DIR_RESOLVED=$(git rev-parse --git-dir 2>/dev/null || echo .git)
@@ -226,7 +416,9 @@ fi
 # ${TOTEM_HOOK_END}
 `;
 }
-export function buildPostCheckoutHookContent(fallbackCmd) {
+export function buildPostCheckoutHookContent(options) {
+    const { fallbackCmd, totemDir } = options;
+    assertRenderableTotemDir(totemDir);
     return `#!/bin/sh
 # ${TOTEM_CHECKOUT_MARKER} — background re-index on branch switch.
 
@@ -242,34 +434,43 @@ ${buildResolveBlock(fallbackCmd)}
 # where .git is a FILE (gitdir: pointer), not a directory (mmnto-ai/totem#2376).
 GIT_DIR_RESOLVED=$(git rev-parse --git-dir 2>/dev/null || echo .git)
 
-# Handle initial checkout (null SHA) — sync if .totem/ exists
+# Handle initial checkout (null SHA) — sync if ${totemDir}/ exists
 if [ "$1" = "0000000000000000000000000000000000000000" ]; then
-  if [ -n "$TOTEM_CMD" ] && [ -d ".totem" ]; then
+  if [ -n "$TOTEM_CMD" ] && [ -d "${totemDir}" ]; then
     ($TOTEM_CMD sync --incremental --quiet > "$GIT_DIR_RESOLVED/totem-sync.log" 2>&1) &
   fi
   exit 0
 fi
 
-# Only sync when .totem/ files differ between branches. The trailing -- terminates
+# Only sync when ${totemDir}/ files differ between branches. The trailing -- terminates
 # the revision list so the "$1"/"$2" SHAs can never be reinterpreted as pathspecs.
-if [ -n "$TOTEM_CMD" ] && git diff --name-only "$1" "$2" -- 2>/dev/null | grep -q '\\.totem/'; then
+if [ -n "$TOTEM_CMD" ] && git diff --name-only "$1" "$2" -- 2>/dev/null | grep -q '${escapeBre(totemDir)}/'; then
   ($TOTEM_CMD sync --incremental --quiet > "$GIT_DIR_RESOLVED/totem-sync.log" 2>&1) &
 fi
 # ${TOTEM_CHECKOUT_END}
 `;
 }
 /**
- * Generate helper shell scripts under `.totem/hooks/` for hook manager integration.
- * These scripts contain the full guard logic (diff checks, null-SHA guards) that
- * bare inline commands would skip.
+ * Generate helper shell scripts under `<totemDir>/hooks/` for hook manager
+ * integration. These scripts contain the full guard logic (diff checks, null-SHA
+ * guards) that bare inline commands would skip.
+ *
+ * Takes the RESOLVED {@link HookRenderOptions} rather than resolving config
+ * itself: both callers already hold the one resolution for this invocation, and
+ * a required parameter is the same compiler-enforced thread the builders use
+ * (mmnto-ai/totem#2692 C1/C2).
  */
-export function generateHookHelpers(gitRoot, fallbackCmd, options) {
-    const hooksDir = path.join(gitRoot, '.totem', 'hooks');
+export function generateHookHelpers(gitRoot, render) {
+    // Refuse BEFORE the mkdir: the helper dir is joined from the value, and a
+    // `..` segment would create a directory outside the checkout before any
+    // builder got the chance to refuse it (mmnto-ai/totem#2692 amendment A7).
+    assertRenderableTotemDir(render.totemDir);
+    const hooksDir = path.join(gitRoot, render.totemDir, 'hooks');
     fs.mkdirSync(hooksDir, { recursive: true });
-    const postMerge = buildHookContent(fallbackCmd);
-    const postCheckout = buildPostCheckoutHookContent(fallbackCmd);
-    const preCommit = buildPreCommitHook(options?.tier);
-    const prePush = buildPrePushHook(fallbackCmd, options?.tier);
+    const postMerge = buildHookContent(render);
+    const postCheckout = buildPostCheckoutHookContent(render);
+    const preCommit = buildPreCommitHook(render);
+    const prePush = buildPrePushHook(render);
     fs.writeFileSync(path.join(hooksDir, 'post-merge.sh'), postMerge, { mode: 0o755 });
     fs.writeFileSync(path.join(hooksDir, 'post-checkout.sh'), postCheckout, { mode: 0o755 });
     fs.writeFileSync(path.join(hooksDir, 'pre-commit.sh'), preCommit, { mode: 0o755 });
@@ -297,49 +498,63 @@ function detectHookManager(cwd) {
     }
     return null;
 }
-function printHookManagerGuidance(manager) {
+/**
+ * Print the manual wiring a detected hook manager needs. `totemDir` is the
+ * RESOLVED value the helper scripts were just written under — guidance that
+ * names `.totem/` in a repo that configured something else points the consumer
+ * at files that do not exist (mmnto-ai/totem#2692 C5).
+ */
+function printHookManagerGuidance(manager, totemDir) {
+    // The validator accepts whitespace in a totemDir; an unquoted word would split
+    // into two arguments in every consumer's shell (CodeRabbit on
+    // mmnto-ai/totem#2701). Quote only when needed so the default guidance stays
+    // the familiar `sh .totem/hooks/…`. `$` and a backtick are refused upstream, so
+    // double quotes are inert; the JSON form escapes them for package.json.
+    const needsQuotes = /\s/.test(totemDir);
+    const sh = needsQuotes ? `"${totemDir}"` : totemDir;
+    const json = needsQuotes ? `\\"${totemDir}\\"` : totemDir;
     switch (manager) {
         case 'husky':
             console.error('[Totem] Detected husky. Add the following to your hook files:');
             console.error('');
             console.error('  # .husky/pre-commit');
-            console.error('  sh .totem/hooks/pre-commit.sh');
+            console.error(`  sh ${sh}/hooks/pre-commit.sh`);
             console.error('');
             console.error('  # .husky/pre-push');
-            console.error('  sh .totem/hooks/pre-push.sh');
+            console.error(`  sh ${sh}/hooks/pre-push.sh`);
             console.error('');
             console.error('  # .husky/post-merge');
-            console.error('  sh .totem/hooks/post-merge.sh');
+            console.error(`  sh ${sh}/hooks/post-merge.sh`);
             console.error('');
             console.error('  # .husky/post-checkout');
-            console.error('  sh .totem/hooks/post-checkout.sh');
+            console.error(`  sh ${sh}/hooks/post-checkout.sh`);
             break;
         case 'lefthook':
             console.error('[Totem] Detected lefthook. Add to your lefthook.yml:');
             console.error('  pre-commit:');
             console.error('    commands:');
             console.error('      totem-block-main:');
-            console.error('        run: sh .totem/hooks/pre-commit.sh');
+            console.error(`        run: sh ${sh}/hooks/pre-commit.sh`);
             console.error('  pre-push:');
             console.error('    commands:');
             console.error('      totem-review:');
-            console.error('        run: sh .totem/hooks/pre-push.sh');
+            console.error(`        run: sh ${sh}/hooks/pre-push.sh`);
             console.error('  post-merge:');
             console.error('    commands:');
             console.error('      totem-sync:');
-            console.error('        run: sh .totem/hooks/post-merge.sh');
+            console.error(`        run: sh ${sh}/hooks/post-merge.sh`);
             console.error('  post-checkout:');
             console.error('    commands:');
             console.error('      totem-sync-checkout:');
-            console.error('        run: sh .totem/hooks/post-checkout.sh');
+            console.error(`        run: sh ${sh}/hooks/post-checkout.sh`);
             break;
         case 'simple-git-hooks':
             console.error('[Totem] Detected simple-git-hooks. Add to your package.json:');
             console.error('  "simple-git-hooks": {');
-            console.error('    "pre-commit": "sh .totem/hooks/pre-commit.sh",');
-            console.error('    "pre-push": "sh .totem/hooks/pre-push.sh",');
-            console.error('    "post-merge": "sh .totem/hooks/post-merge.sh",');
-            console.error('    "post-checkout": "sh .totem/hooks/post-checkout.sh"');
+            console.error(`    "pre-commit": "sh ${json}/hooks/pre-commit.sh",`);
+            console.error(`    "pre-push": "sh ${json}/hooks/pre-push.sh",`);
+            console.error(`    "post-merge": "sh ${json}/hooks/post-merge.sh",`);
+            console.error(`    "post-checkout": "sh ${json}/hooks/post-checkout.sh"`);
             console.error('  }');
             break;
     }
@@ -355,11 +570,13 @@ export async function installPostMergeHook(cwd, rl, options) {
             : '[Totem] Not a git repository — skipping hook installation.');
         return;
     }
-    const fallbackCmd = getFallbackCommand(gitRoot);
+    // One config read per invocation, anchored at the git root — the same anchor
+    // getFallbackCommand has always used (mmnto-ai/totem#2692 C1).
+    const render = await resolveHookRenderOptions(gitRoot, { tier: options?.tier });
     const manager = detectHookManager(gitRoot);
     if (manager) {
-        generateHookHelpers(gitRoot, fallbackCmd, options);
-        printHookManagerGuidance(manager);
+        generateHookHelpers(gitRoot, render);
+        printHookManagerGuidance(manager, render.totemDir);
         return;
     }
     const interactive = options?.interactive ?? process.stdin.isTTY === true;
@@ -389,7 +606,7 @@ export async function installPostMergeHook(cwd, rl, options) {
         }
         // Append to existing hook — reuse buildHookContent, strip shebang
         const separator = existing.endsWith('\n') ? '' : '\n';
-        const appendBlock = buildHookContent(fallbackCmd)
+        const appendBlock = buildHookContent(render)
             .replace(/^#!\/bin\/sh\n/, '')
             .trimStart();
         fs.appendFileSync(hookPath, separator + '\n' + appendBlock);
@@ -398,10 +615,11 @@ export async function installPostMergeHook(cwd, rl, options) {
     }
     // Create new hook
     fs.mkdirSync(hooksDir, { recursive: true });
-    fs.writeFileSync(hookPath, buildHookContent(fallbackCmd));
+    fs.writeFileSync(hookPath, buildHookContent(render));
     // Make executable (no-op on Windows, git bash handles it)
     try {
         fs.chmodSync(hookPath, 0o755);
+        // totem-context: intentional cleanup — chmod may fail on Windows; the hook still runs via git bash, so a failed mode bit is not a failed install.
     }
     catch {
         // chmod may fail on Windows — hooks still work via git bash
@@ -417,13 +635,227 @@ if [ -n "$CLAUDE_CODE_AGENT" ] || [ -n "$CLAUDE_VERSION" ] || [ -n "$CURSOR_TRAC
 fi`;
 }
 // ─── Enforcement hooks (pre-commit + pre-push) ──────────
-export function buildPreCommitHook(tier) {
-    const effectiveTier = tier ?? 'standard';
+export function buildPreCommitHook(options) {
+    const effectiveTier = options.tier;
+    const totemDir = options.totemDir;
+    assertRenderableTotemDir(totemDir);
+    // The run store the strict arm reads, rendered from the CONFIGURED totemDir so
+    // the reader names the tree `totem spec` actually writes (mmnto-ai/totem#2692).
+    const runsDir = `${totemDir}/artifacts/runs`;
+    // Strict-tier evidence (mmnto-ai/totem#2690, tightened by
+    // mmnto-ai/totem#2700): the gate names `totem spec`, so it must pass on what
+    // `totem spec` actually writes — the grounded run artifact under
+    // <totemDir>/artifacts/runs/ (mmnto-ai/totem#2100; written on every
+    // successful run, --fresh included) whose TOP-LEVEL
+    // admission.runMetadata.caller is "spec". The read is JSON-aware on purpose:
+    // the run store is written by every orchestrator caller, and a `review`
+    // artifact's inputBundle embeds the reviewed diff — a substring grep would
+    // pass the gate on a review of any text that merely QUOTES the key (this
+    // very test fixture). node is already assumed by the pre-push template's
+    // format-check block; ~50 ms, no CLI boot, nothing written (Tenet 13). The
+    // former <totemDir>/cache/.spec-completed marker is NOT honored: no CLI path
+    // ever wrote it, so "compatibility" with it would be compatibility with a
+    // hand hack (operator ruling 2026-08-29 — no legacy shims while there is no
+    // hard consumer, Tenet 19).
+    //
+    // #2700 adds the second half of the rule: an artifact is EVIDENCE only when
+    // it is ANCHORED (`grounding.anchor.kind` of "issue" or "record" — a
+    // "free-text" or "mixed" run is the confabulation surface the rule exists
+    // for) and its SUBJECT carries a real shape. The SUBJECT depends on the
+    // anchor: for an `issue` run it is the draft (`output.content`); for a
+    // `record` run it is the RECORD'S OWN BYTES, re-read from disk at commit
+    // time — the draft is discarded on that path, so checking it would check
+    // nothing. The record's sha256 is compared and REPORTED (matches / revised
+    // since binding) but never blocks: blocking on revision would price every
+    // fold of a design record at one LLM call, the friction this slice retires.
+    // Exit vocabulary: 0 evidence · 2 no spec artifact · 3 the newest spec
+    // artifact is NOT evidence (reason on stdout) · anything else = the reader
+    // itself could not run. The evidence line makes a stale pass VISIBLE (age
+    // from the artifact's own createdAt); a freshness rule is a separate policy,
+    // deliberately not here. This is the ONLY reader of the rule — the repo's
+    // pre-managed-era `.gemini/hooks/BeforeTool.js` (unregistered, inert) was
+    // deleted with the marker rather than kept in step.
+    //
+    // Every value the reader compares against is RENDERED from the one canonical
+    // constant via JSON.stringify (the runsDir precedent): the required section
+    // headings from `SPEC_REQUIRED_SECTIONS`, the anchor kinds and the
+    // prompt-source spelling from the core schema's exported constants. The hook
+    // text can never drift from the writer's vocabulary by re-spelling it.
+    //
+    // The artifact is a plain JSON file a seat can hand-edit, and its NAME comes
+    // off the filesystem, so nothing echoed is trusted as text: EVERY value that
+    // reaches stdout — the artifact's path, its `createdAt`, `anchor.kind`,
+    // `anchor.ref` and each required heading — passes through `safe()` first. A
+    // newline in any of them would otherwise forge a second `[Totem]` line in the
+    // hook's own output; `safe()` collapses C0 (0x00–0x1f) AND the DEL/C1 band
+    // (0x7f–0x9f), because U+0085 (NEL) breaks a line on some terminals.
+    // Containment is decided by RESOLUTION, not by inspecting one segment, and
+    // it is decided TWICE. Lexically first: a `record` ref that is absolute
+    // (either path flavor) or whose `path.resolve` against `process.cwd()` — the
+    // worktree top git runs hooks from — lands outside it is refused, so
+    // `sub/../../x.md` and `./../x.md` are caught where a first-segment test let
+    // them through, while a mid-path `..` that stays inside stays legal. Then by
+    // REALPATH, once the ref is known to exist and before its bytes are read: an
+    // in-repo SYMLINK whose target lives outside the tree is lexically contained
+    // and would otherwise be read and judged, so the resolved pair is compared
+    // too and the block names both spellings. A `record` anchor whose `sha256` is
+    // missing and one whose `sha256` is not a 64-hex digest are refused with
+    // their OWN reasons — "no sha256" and "not a 64-hex digest" are different
+    // repairs — rather than as one malformed sensor line. Every reason and the
+    // pass line go out through `fs.writeSync(1, …)`: `process.stdout.write` is
+    // asynchronous on a pipe (macOS), so `process.exit` could truncate the text
+    // the `sh` arm is about to echo.
     const strictBlock = `
-# Strict mode: require spec before commit
+# Strict mode: require spec EVIDENCE before commit (mmnto-ai/totem#2690, mmnto-ai/totem#2700).
+# Evidence = a totem spec run artifact (${runsDir}/*.json with a
+# top-level admission.runMetadata.caller of "spec"), read JSON-aware — a
+# substring match would accept a review artifact that merely quotes the key —
+# that is ANCHORED on an issue or a bound design record, and whose subject
+# carries a real shape: the required headings each with a body (an issue run
+# drafted by the built-in prompt), or at least one heading with a body (a
+# record run, or an issue run drafted under a custom prompt). A record run is
+# judged on the bytes of the record at grounding.anchor.ref, re-read here from
+# the worktree top; its sha256 is REPORTED, never enforced.
+# The former ${totemDir}/cache/.spec-completed marker is not honored (no CLI wrote it).
 if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]; then
-  if [ ! -f ".totem/cache/.spec-completed" ]; then
-    echo "[Totem] BLOCKED: Run 'totem spec <issue>' before committing (strict mode)"
+  spec_evidence=$(node -e '
+const fs = require("fs");
+const crypto = require("crypto");
+const nodePath = require("path");
+const dir = ${JSON.stringify(runsDir)};
+const REQUIRED = ${JSON.stringify(SPEC_REQUIRED_SECTIONS)};
+const KIND_ISSUE = ${JSON.stringify(GROUNDING_ANCHOR_ISSUE)};
+const KIND_RECORD = ${JSON.stringify(GROUNDING_ANCHOR_RECORD)};
+const PROMPT_OVERRIDE = ${JSON.stringify(PROMPT_SOURCE_OVERRIDE)};
+let names = [];
+try { names = fs.readdirSync(dir); } catch (err) { names = []; }
+let best = null;
+for (const name of names) {
+  if (!name.endsWith(".json")) continue;
+  let a = null;
+  try { a = JSON.parse(fs.readFileSync(dir + "/" + name, "utf8")); } catch (err) { continue; }
+  const caller = a && a.admission && a.admission.runMetadata && a.admission.runMetadata.caller;
+  if (["spec"].indexOf(caller) < 0) continue;
+  const at = ["string"].indexOf(typeof a.createdAt) < 0 ? "" : a.createdAt;
+  if (!best || at > best.at) best = { name: name, at: at, art: a };
+}
+if (!best) process.exit(2);
+const file = dir + "/" + best.name;
+// fs.writeSync, not process.stdout.write: stdout is a PIPE here (the sh arm
+// captures it) and a piped write is asynchronous on macOS, so process.exit
+// below could truncate the very text the sh arm is about to echo.
+function emit(text) { fs.writeSync(1, text); }
+function block(reason) { emit(reason); process.exit(3); }
+function safe(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    const control = code < 32 || (code >= 127 && code <= 159);
+    out = out + (control ? "?" : text.charAt(i));
+  }
+  return out;
+}
+const shownFile = safe(file);
+const shownAt = safe(best.at);
+function isHeading(line) {
+  let n = 0;
+  while (n < line.length && ["#"].indexOf(line.charAt(n)) > -1) n = n + 1;
+  if (n < 1 || n > 6) return false;
+  if ([" ", "\\t"].indexOf(line.charAt(n)) < 0) return false;
+  return line.slice(n + 1).trim().length > 0;
+}
+function escapesTop(rel) {
+  const norm = rel.split("\\\\").join("/");
+  if (nodePath.win32.isAbsolute(norm) || nodePath.posix.isAbsolute(norm)) return true;
+  return [".."].indexOf(norm) > -1 || ["../"].indexOf(norm.slice(0, 3)) > -1;
+}
+function outsideWorktree(r) {
+  const norm = r.split("\\\\").join("/");
+  if (nodePath.win32.isAbsolute(norm) || nodePath.posix.isAbsolute(norm)) return true;
+  const top = process.cwd();
+  return escapesTop(nodePath.relative(top, nodePath.resolve(top, norm)));
+}
+const art = best.art;
+const grounding = art.grounding;
+const anchor = grounding && grounding.anchor;
+if (!anchor || ["string"].indexOf(typeof anchor.kind) < 0) block("the newest spec run artifact (" + shownFile + ") predates the anchored-evidence rule (no grounding.anchor)");
+const kind = anchor.kind;
+const ref = ["string"].indexOf(typeof anchor.ref) < 0 ? "(no ref)" : anchor.ref;
+const shownKind = safe(kind);
+const shownRef = safe(ref);
+if (kind !== KIND_ISSUE && kind !== KIND_RECORD) block("the newest spec run artifact (" + shownFile + ") is anchored " + shownKind + " (" + shownRef + "), which is not gate evidence");
+let subject = "";
+let shape = "";
+let recordStatus = "";
+if (kind !== KIND_RECORD) {
+  const content = art.output && art.output.content;
+  if (["string"].indexOf(typeof content) < 0) block("the newest spec run artifact (" + shownFile + ") is not evidence: the draft is not text");
+  subject = content;
+  const meta = art.admission && art.admission.runMetadata;
+  const source = meta && meta.promptSource;
+  shape = source !== PROMPT_OVERRIDE ? "TEMPLATE" : "DOCUMENT";
+} else {
+  if (outsideWorktree(ref)) block("the bound record ref is outside the worktree: " + shownRef);
+  const bound = ["string"].indexOf(typeof anchor.sha256) < 0 ? "" : anchor.sha256;
+  if (bound.length < 1) block("the record anchor carries no sha256 — not evidence (" + shownFile + ")");
+  if (!/^[0-9a-f]{64}$/.test(bound)) block("the record anchor sha256 is not a 64-hex digest (" + safe(bound) + ") — not evidence (" + shownFile + ")");
+  const missingRecord = "the bound record is missing at " + shownRef + " (bound by " + shownFile + ")";
+  if (!fs.existsSync(ref)) block(missingRecord);
+  const realRef = fs.realpathSync.native(ref);
+  if (escapesTop(nodePath.relative(fs.realpathSync.native(process.cwd()), realRef))) block("the bound record resolves outside the worktree: " + shownRef + " -> " + safe(realRef));
+  let bytes = null;
+  let read = false;
+  try { bytes = fs.readFileSync(ref); read = true; } catch (err) { read = false; }
+  if (!read) block(missingRecord);
+  subject = bytes.toString("utf8");
+  shape = "DOCUMENT";
+  const now = crypto.createHash("sha256").update(bytes).digest("hex");
+  recordStatus = now !== bound ? "record revised since binding (bound " + bound.slice(0, ${RECORD_HASH_DISPLAY_PREFIX}) + ", now " + now.slice(0, ${RECORD_HASH_DISPLAY_PREFIX}) + ")" : "record sha256 matches";
+}
+if ([65279].indexOf(subject.charCodeAt(0)) > -1) subject = subject.slice(1);
+const lines = subject.split("\\n");
+function hasBodyAfter(start) {
+  for (let i = start + 1; i < lines.length; i++) {
+    if (isHeading(lines[i])) return false;
+    if (lines[i].trim().length > 0) return true;
+  }
+  return false;
+}
+if (shape !== "DOCUMENT") {
+  for (const heading of REQUIRED) {
+    let at = -1;
+    for (let i = 0; i < lines.length; i++) { if ([heading].indexOf(lines[i].trimEnd()) > -1) { at = i; break; } }
+    if (at < 0) block("the draft in " + shownFile + " is missing heading " + safe(heading));
+    if (!hasBodyAfter(at)) block("the draft in " + shownFile + " has an empty heading " + safe(heading));
+  }
+} else {
+  let bodied = false;
+  for (let i = 0; i < lines.length; i++) { if (isHeading(lines[i]) && hasBodyAfter(i)) { bodied = true; break; } }
+  if (!bodied && kind !== KIND_RECORD) block("the draft in " + shownFile + " has no heading with a body (custom prompt: the built-in template skeleton is not required)");
+  if (!bodied) block("the bound record at " + shownRef + " has no heading with a body");
+}
+const stamp = best.at ? Date.parse(best.at) : NaN;
+const days = Number.isNaN(stamp) ? -1 : Math.floor((Date.now() - stamp) / 86400000);
+let out = shownFile + " (" + (shownAt || "undated") + (days >= 0 ? ", " + days + " days old" : "") + ")";
+out = out + " · anchor " + shownKind + " " + shownRef + " · shape " + shape;
+if (recordStatus.length > 0) out = out + " · " + recordStatus;
+emit(out);
+' 2>/dev/null)
+  # Reader status: 0 = evidence found · 2 = no spec artifact at all · 3 = the
+  # newest spec artifact is NOT evidence (the reason is on stdout) · anything
+  # else = the reader itself could not run (node missing from PATH, a crash) —
+  # each reported distinctly, never as "no evidence", and all fail-closed.
+  reader_status=$?
+  if [ "$reader_status" = "0" ] && [ -n "$spec_evidence" ]; then
+    echo "[Totem] spec evidence: $spec_evidence"
+  elif [ "$reader_status" = "3" ]; then
+    echo "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"
+    exit 1
+  elif [ "$reader_status" != "2" ]; then
+    echo "[Totem] BLOCKED: the spec-evidence reader could not run (node exit status $reader_status — node missing from PATH, or ${runsDir}/ unreadable); fix the runtime and retry (strict mode)"
+    exit 1
+  else
+    echo "[Totem] BLOCKED: Run 'totem spec <issue>' before committing (strict mode) — no totem spec run artifact under ${runsDir}/ in this checkout"
     exit 1
   fi
 fi`;
@@ -445,8 +877,10 @@ ${strictBlock}
 # ${TOTEM_PRECOMMIT_END}
 `;
 }
-export function buildPrePushHook(fallbackCmd, tier) {
-    const effectiveTier = tier ?? 'standard';
+export function buildPrePushHook(options) {
+    const { fallbackCmd, totemDir } = options;
+    const effectiveTier = options.tier;
+    assertRenderableTotemDir(totemDir);
     // Strict-tier gate per Proposal 273 § 6 Q2 (mmnto-ai/totem#1908): operator-invoked
     // is the default for new checks while behavior calibrates. Doctor's `--strict`
     // mode gates on repo-state `fail` results; unconditional firing would break
@@ -481,7 +915,7 @@ ${buildResolveBlock(fallbackCmd)}
 
 if [ -n "$TOTEM_CMD" ]; then
   # Verify compile manifest is current
-  if [ -f ".totem/compile-manifest.json" ]; then
+  if [ -f "${totemDir}/compile-manifest.json" ]; then
     if ! $TOTEM_CMD verify-manifest > /dev/null 2>&1; then
       echo "[totem] Push blocked: compile manifest is stale. Run 'totem lesson compile'." >&2
       exit 1
@@ -489,14 +923,14 @@ if [ -n "$TOTEM_CMD" ]; then
   fi
 
   # Run deterministic lint
-  if [ -f ".totem/compiled-rules.json" ]; then
+  if [ -f "${totemDir}/compiled-rules.json" ]; then
     if ! $TOTEM_CMD lint; then
       exit 1
     fi
   fi
 
   # Verify shields.io badges in README.md (mmnto-ai/totem#1926 — deterministic claim-discipline)
-  if [ -f "README.md" ] && [ -f ".totem/compiled-rules.json" ]; then
+  if [ -f "README.md" ] && [ -f "${totemDir}/compiled-rules.json" ]; then
     if ! $TOTEM_CMD verify-badges; then
       exit 1
     fi
@@ -519,7 +953,7 @@ if [ -n "$TOTEM_CMD" ]; then
   # missing-Goal-prefix, covenant-without-backing). Fires only when at
   # least one in-scope surface exists. Bypass with mandatory justification:
   #   TOTEM_GATE_BYPASS_JUSTIFICATION="<reason>" git push
-  if [ -f ".totem/compiled-rules.json" ] && { [ -f "README.md" ] || [ -f "AGENTS.md" ] || [ -f "design-tenets.md" ] || [ -d "docs/wiki" ]; }; then
+  if [ -f "${totemDir}/compiled-rules.json" ] && { [ -f "README.md" ] || [ -f "AGENTS.md" ] || [ -f "design-tenets.md" ] || [ -d "docs/wiki" ]; }; then
     # --scope-to-diff (mmnto-ai/totem#2002): narrow the WWND scan to files
     # touched in the current push diff. Eliminates the standing-gate
     # false-positive class where pre-existing warnings on in-scope surfaces
@@ -611,7 +1045,7 @@ function writeExecutableHook(hookPath, content) {
  *     overwrite would clobber it, so such a file is NOT owned (only trailing
  *     whitespace may follow the end marker).
  */
-function isTotemOwnedWholeFile(content, marker, endMarker) {
+export function isTotemOwnedWholeFile(content, marker, endMarker) {
     const idx = content.indexOf(marker);
     if (idx === -1)
         return false;
@@ -724,9 +1158,15 @@ export async function installEnforcementHooks(cwd, rl, options) {
         console.error(HOOKS_DIR_UNRESOLVED_MSG);
         return skip;
     }
-    const fallbackCmd = getFallbackCommand(gitRoot);
-    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(options?.tier), TOTEM_PRECOMMIT_MARKER, undefined, TOTEM_PRECOMMIT_END);
-    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(fallbackCmd, options?.tier), TOTEM_PREPUSH_MARKER, undefined, TOTEM_PREPUSH_END);
+    // `totem init` writes the config BEFORE this runs, so — when init runs at the
+    // git root, the supported layout — the resolved options are the ones the repo
+    // just declared, and init and `totem hook install` render identically
+    // (mmnto-ai/totem#2692 C1/C7). Off the root, init writes its config at cwd
+    // while every hook writer resolves at the git root: a pre-existing split this
+    // slice names and does not close.
+    const render = await resolveHookRenderOptions(gitRoot, { tier: options?.tier });
+    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(render), TOTEM_PRECOMMIT_MARKER, undefined, TOTEM_PRECOMMIT_END);
+    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(render), TOTEM_PREPUSH_MARKER, undefined, TOTEM_PREPUSH_END);
     // Warn about non-shell hooks that Totem cannot safely append to
     if (preCommit === 'skipped-non-shell') {
         console.error('[Totem] Warning: pre-commit hook uses a non-shell interpreter. Manually integrate branch protection into your existing hook.');
@@ -751,8 +1191,8 @@ export async function installHooksCommand() {
             const postMerge = path.join(hooksDir, 'post-merge');
             const hasPostMerge = fs.existsSync(postMerge) && fs.readFileSync(postMerge, 'utf-8').includes(TOTEM_HOOK_MARKER);
             if (hasPostMerge) {
-                const fallbackCmd = getFallbackCommand(gitRoot);
-                installGitHook(hooksDir, 'post-checkout', buildPostCheckoutHookContent(fallbackCmd), TOTEM_CHECKOUT_MARKER, undefined, TOTEM_CHECKOUT_END);
+                const render = await resolveHookRenderOptions(gitRoot);
+                installGitHook(hooksDir, 'post-checkout', buildPostCheckoutHookContent(render), TOTEM_CHECKOUT_MARKER, undefined, TOTEM_CHECKOUT_END);
             }
         }
     }
@@ -763,8 +1203,12 @@ export async function installHooksCommand() {
 /**
  * Non-interactive hook installer for `totem hooks` and `prepare` scripts.
  * Installs pre-commit, pre-push, and post-merge hooks without prompting.
+ *
+ * Async since mmnto-ai/totem#2692: the hook text is rendered from the repo's
+ * CONFIGURED `totemDir` (and `hooks.tier`), which means one config read —
+ * {@link resolveHookRenderOptions} — before anything is written.
  */
-export function installHooksNonInteractive(cwd, force, options) {
+export async function installHooksNonInteractive(cwd, force, options) {
     // Guard: must be a git repo — resolve root from any subdirectory. Not-a-repo
     // stays a silent null (the documented contract — callers print); the malformed
     // pointer prints its declared-skip line here so a direct API caller honors the
@@ -775,12 +1219,12 @@ export function installHooksNonInteractive(cwd, force, options) {
             console.error(HOOKS_DIR_UNRESOLVED_MSG);
         return null;
     }
-    const fallbackCmd = getFallbackCommand(gitRoot);
+    const render = await resolveHookRenderOptions(gitRoot, { tier: options?.tier });
     // Hook managers handle their own installation — generate helper scripts + print guidance
     const manager = detectHookManager(gitRoot);
     if (manager) {
-        generateHookHelpers(gitRoot, fallbackCmd, options);
-        printHookManagerGuidance(manager);
+        generateHookHelpers(gitRoot, render);
+        printHookManagerGuidance(manager, render.totemDir);
         return null;
     }
     const hooksDir = resolveHooksDir(gitRoot);
@@ -791,11 +1235,11 @@ export function installHooksNonInteractive(cwd, force, options) {
         console.error(HOOKS_DIR_UNRESOLVED_MSG);
         return null;
     }
-    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(options?.tier), TOTEM_PRECOMMIT_MARKER, force, TOTEM_PRECOMMIT_END);
-    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(fallbackCmd, options?.tier), TOTEM_PREPUSH_MARKER, force, TOTEM_PREPUSH_END);
-    const postMergeContent = buildHookContent(fallbackCmd);
+    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(render), TOTEM_PRECOMMIT_MARKER, force, TOTEM_PRECOMMIT_END);
+    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(render), TOTEM_PREPUSH_MARKER, force, TOTEM_PREPUSH_END);
+    const postMergeContent = buildHookContent(render);
     const postMerge = installGitHook(hooksDir, 'post-merge', postMergeContent, TOTEM_HOOK_MARKER, force, TOTEM_HOOK_END);
-    const postCheckoutContent = buildPostCheckoutHookContent(fallbackCmd);
+    const postCheckoutContent = buildPostCheckoutHookContent(render);
     const postCheckout = installGitHook(hooksDir, 'post-checkout', postCheckoutContent, TOTEM_CHECKOUT_MARKER, force, TOTEM_CHECKOUT_END);
     return { preCommit, prePush, postMerge, postCheckout };
 }
@@ -864,32 +1308,17 @@ export async function hooksCommand(opts) {
         }
         return;
     }
-    // Resolve tier + pilot: CLI flag > config file > default ('standard')
-    let tier;
-    // Resolve tier: CLI flag > config file > default ('standard')
-    try {
-        const { loadConfig, loadEnv, resolveConfigPath } = await import('../utils.js');
-        loadEnv(cwd);
-        const configPath = resolveConfigPath(cwd);
-        if (configPath) {
-            const config = await loadConfig(configPath);
-            if (!opts.strict && !opts.standard) {
-                tier = config.hooks?.tier;
-            }
-        }
-    }
-    catch (err) {
-        if (process.env.TOTEM_DEBUG) {
-            console.error('[Totem] Could not load config for tier resolution:', err);
-        }
-    }
-    if (opts.strict) {
-        tier = 'strict';
-    }
-    else if (opts.standard) {
-        tier = 'standard';
-    }
-    const result = installHooksNonInteractive(cwd, opts.force, { tier });
+    // Tier precedence (CLI flag > config `hooks.tier` > 'standard') now lives in
+    // `resolveHookRenderOptions`, the ONE config→hook-render seam
+    // (mmnto-ai/totem#2692 C1) — which `installHooksNonInteractive` calls with the
+    // flag below, so the config is read exactly once per invocation and at the
+    // git-root anchor the installer writes from.
+    const tier = opts.strict
+        ? 'strict'
+        : opts.standard
+            ? 'standard'
+            : undefined;
+    const result = await installHooksNonInteractive(cwd, opts.force, { tier });
     // The git-hook summary prints ONLY when git hooks were actually written. A null
     // result means a hook manager (husky/lefthook) was detected and
     // installHooksNonInteractive already printed its guidance — but this MUST NOT
@@ -1250,8 +1679,12 @@ async function printGeminiHookMigrationSummary(cwd, force) {
  * stateless format that runs verify-manifest + lint directly.
  *
  * Returns true if the hook was upgraded, false otherwise.
+ *
+ * Async since mmnto-ai/totem#2692: the spliced block is rendered from the repo's
+ * configured `totemDir` and `hooks.tier` like every other writer, so it no
+ * longer silently downgrades a strict hook to standard on the upgrade path.
  */
-export function upgradePrePushHookIfNeeded(cwd) {
+export async function upgradePrePushHookIfNeeded(cwd) {
     try {
         const gitRoot = resolveGitRoot(cwd);
         if (!gitRoot)
@@ -1308,9 +1741,9 @@ export function upgradePrePushHookIfNeeded(cwd) {
         if (endOffset === -1)
             return false;
         const blockEnd = markerIdx + endOffset;
-        const fallbackCmd = getFallbackCommand(gitRoot);
+        const render = await resolveHookRenderOptions(gitRoot);
         // Build the replacement block (strip shebang — we're splicing into existing file)
-        const newBlock = buildPrePushHook(fallbackCmd)
+        const newBlock = buildPrePushHook(render)
             .replace(/^#!\/bin\/sh\n/, '')
             .trimStart();
         // Splice: preserve everything before and after the totem block