@mmnto/cli 1.119.0 → 1.121.0

package/dist/commands/install-hooks.js

@@ -124,6 +124,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 +334,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.
 
@@ -165,6 +347,17 @@ ${buildResolveBlock(fallbackCmd)}
 # exit-0-or-nothing contract (single-flight, atomic rename, no-clobber when gh is
 # missing) makes blind firing safe, and the merge must never wait on it. An absent
 # binary means the sidecar is not adopted here (non-cohort consumer) — skip silently.
+# A SECOND verb rides the same gate: \`totem-status refresh-obligation-store\`
+# (mmnto-ai/totem-status#127 slice-two residual, sibling of mmnto-ai/totem#2556)
+# writes the durable obligation store beside the GH snapshot, so it gets the same
+# post-merge moment. Same presence + primary-checkout gate, same backgrounded
+# subshell, same log — and each firing stamps its own verb= field, so the log
+# records WHICH verbs fired and in what order. That does NOT restore the #2570
+# per-child reap discriminator: child output carries no verb tag and the two
+# backgrounded children interleave nondeterministically, so a silent tail
+# attributes only to the LAST verb stamped. Reopen when the sidecar tags its own
+# output. Blind firing stays safe there too: the verb is in-process single-flight
+# only, so it races the daemon exactly the way its manual invocation already does.
 # PRIMARY checkout only ([ -d .git ]): in a linked worktree .git is a FILE, and a
 # detached child inheriting the worktree cwd holds a Windows directory lock that
 # breaks worktree removal; the primary's hooks + the daemon cover the workspace-level
@@ -172,9 +365,12 @@ ${buildResolveBlock(fallbackCmd)}
 if [ -d .git ] && command -v totem-status >/dev/null 2>&1; then
   # Observability leg (mmnto-ai/totem#2570): stamp each firing (time, cwd, and
   # WHICH binary resolved — the shell search order includes cwd on Windows, so
-  # a stale checkout-local exe can shadow the installed one) and hand the child
-  # the same log, so the verb's own success line lands after the stamp; a stamp
-  # with nothing after it means the child never finished. Repo-local inside
+  # a stale checkout-local exe can shadow the installed one) and hand the children
+  # the same log, so their output lands after the stamps. Measured caveat now that
+  # TWO verbs share one log: child output is unlabelled and the two children
+  # interleave nondeterministically, so a silent tail no longer discriminates per
+  # child — it attributes only to the LAST verb stamped. The stamps still record
+  # which verbs fired, and in what order. Repo-local inside
   # .git (never tracked, per-repo, writable wherever git itself writes); 1 MiB
   # self-cap. If the log is not writable, fall back to the previous blind
   # firing — the 2>/dev/null PRECEDES the append so the open failure itself
@@ -185,17 +381,25 @@ if [ -d .git ] && command -v totem-status >/dev/null 2>&1; then
   # fields pass through tr -d '[:cntrl:]' so a crafted checkout path cannot
   # forge stamp lines or inject terminal controls into the log.
   if [ -f "$TS_REFRESH_LOG" ] && [ "$(( $(wc -c < "$TS_REFRESH_LOG" 2>/dev/null || echo 0) ))" -gt 1048576 ]; then : > "$TS_REFRESH_LOG"; fi
-  if printf '[%s] post-merge spawn cwd=%s bin=%s\\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(pwd | tr -d '[:cntrl:]')" "$(command -v totem-status | tr -d '[:cntrl:]')" 2>/dev/null >> "$TS_REFRESH_LOG"; then
+  if printf '[%s] post-merge spawn cwd=%s bin=%s verb=%s\\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(pwd | tr -d '[:cntrl:]')" "$(command -v totem-status | tr -d '[:cntrl:]')" refresh-gh 2>/dev/null >> "$TS_REFRESH_LOG"; then
     (totem-status refresh-gh >> "$TS_REFRESH_LOG" 2>&1 &)
   else
     (totem-status refresh-gh >/dev/null 2>&1 &)
   fi
+  # Second verb, same gate and same log. Written out rather than looped so the
+  # stamp and the backgrounded invocation each carry a literal verb — a reader of
+  # the hook (or of the log) never has to resolve a variable to know which fired.
+  if printf '[%s] post-merge spawn cwd=%s bin=%s verb=%s\\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(pwd | tr -d '[:cntrl:]')" "$(command -v totem-status | tr -d '[:cntrl:]')" refresh-obligation-store 2>/dev/null >> "$TS_REFRESH_LOG"; then
+    (totem-status refresh-obligation-store >> "$TS_REFRESH_LOG" 2>&1 &)
+  else
+    (totem-status refresh-obligation-store >/dev/null 2>&1 &)
+  fi
 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)
@@ -204,7 +408,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.
 
@@ -220,34 +426,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 });
@@ -275,49 +490,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;
     }
@@ -333,11 +562,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;
@@ -367,7 +598,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);
@@ -376,10 +607,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
@@ -395,13 +627,69 @@ 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): the gate names `totem spec`,
+    // so it must pass on what `totem spec` actually writes — the grounded run
+    // artifact under .totem/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 .totem/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). 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.
     const strictBlock = `
-# Strict mode: require spec before commit
+# Strict mode: require spec EVIDENCE before commit (mmnto-ai/totem#2690).
+# 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.
+# 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 dir = ${JSON.stringify(runsDir)};
+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 };
+}
+if (!best) process.exit(2);
+const parsed = best.at ? Date.parse(best.at) : NaN;
+const days = Number.isNaN(parsed) ? -1 : Math.floor((Date.now() - parsed) / 86400000);
+process.stdout.write(dir + "/" + best.name + " (" + (best.at || "undated") + (days >= 0 ? ", " + days + " days old" : "") + ")");
+' 2>/dev/null)
+  # Reader status: 0 = evidence found · 2 = none found · anything else = the
+  # reader itself could not run (node missing from PATH, a crash) — reported
+  # distinctly, never as "no evidence", and still fail-closed.
+  reader_status=$?
+  if [ "$reader_status" = "0" ] && [ -n "$spec_evidence" ]; then
+    echo "[Totem] spec evidence: $spec_evidence"
+  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`;
@@ -423,8 +711,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
@@ -459,7 +749,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
@@ -467,14 +757,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
@@ -497,7 +787,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
@@ -589,7 +879,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;
@@ -702,9 +992,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.');
@@ -729,8 +1025,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);
             }
         }
     }
@@ -741,8 +1037,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
@@ -753,12 +1053,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);
@@ -769,11 +1069,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 };
 }
@@ -842,32 +1142,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
@@ -1228,8 +1513,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)
@@ -1286,9 +1575,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