<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-08-27-1-precommit-hook-stable-entrypoint-and-repin-migration/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-27-1-precommit-hook-stable-entrypoint-and-repin-migration/</id>
  <title>Install-agnostic pre-commit hook fallback + spec-kitty migrate repin-hooks</title>
  <updated>2026-08-27T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-08-27-1-precommit-hook-stable-entrypoint-and-repin-migration/"/>
  <summary>Pre-commit hook falls back to a PATH-resolved spec-kitty entrypoint when its pinned interpreter is gone, and a repair command re-pins already-broken repos.</summary>
  <content type="html">&lt;span id=&quot;install-agnostic-pre-commit-hook-fallback--spec-kitty-migrate-repin-hooks&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-27-1-precommit-hook-stable-entrypoint-and-repin-migration.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-27&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Robert (Human-in-Control), ratified 2026-08-27 on the issue&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; spec-kitty/EXPERIMENTAL-spec-kitty#254&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/policy/hook_installer.py&lt;/code&gt; writes a &lt;code dir=&quot;auto&quot;&gt;.git/hooks/pre-commit&lt;/code&gt; shell script that
pins &lt;code dir=&quot;auto&quot;&gt;sys.executable&lt;/code&gt; — an absolute interpreter path — at install time, then &lt;code dir=&quot;auto&quot;&gt;exec&lt;/code&gt;s it
directly. This works until the install method changes: migrating a repo’s spec-kitty install
from &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;uv tool install&lt;/code&gt; moves (or removes) the pinned interpreter, and the &lt;em&gt;existing&lt;/em&gt;
hook keeps pointing at a path that no longer exists. The next commit then fails at the shell
level with a bare &lt;code dir=&quot;auto&quot;&gt;No such file or directory&lt;/code&gt; naming a stale path — not a diagnosis, and no
command re-pins it.&lt;/p&gt;
&lt;p&gt;Two prior regressions constrain the fix: #105 (the hook must not rely on a bare
&lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;python3&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;py&lt;/code&gt; resolved fresh off &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; — that lookup is exactly as fragile as the
absolute-path pin, just deferred) and #669 (the installer must preserve symlinks in
&lt;code dir=&quot;auto&quot;&gt;sys.executable&lt;/code&gt;, not resolve them — resolving strips a venv/pipx shim’s &lt;code dir=&quot;auto&quot;&gt;sys.prefix&lt;/code&gt;
context).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;No install method (pipx, uv, or anything else) should be able to leave a dead hook with no
recovery path.&lt;/li&gt;
&lt;li&gt;The already-broken case (existing repos with a stale pin) needs a one-time repair, not just
a fix for newly-installed hooks.&lt;/li&gt;
&lt;li&gt;Must not reintroduce #105 (bare &lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;) or regress #669 (symlink preservation).&lt;/li&gt;
&lt;li&gt;The failure mode, when nothing is reachable, must name a concrete remedy — not surface a
bare shell error.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A.&lt;/strong&gt; Re-pin automatically on every commit (detect staleness, self-heal silently).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.&lt;/strong&gt; Make the hook invoke a stable, install-agnostic entrypoint (&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; resolved off
&lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;) as a fallback when the pinned interpreter is gone, &lt;strong&gt;and&lt;/strong&gt; add a one-time
&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate repin-hooks&lt;/code&gt; command for repos already broken. &lt;strong&gt;(chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C.&lt;/strong&gt; Drop the absolute-path pin entirely; always resolve &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; off &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: “B”&lt;/strong&gt;, matching the issue’s ratified decision.&lt;/p&gt;
&lt;p&gt;Concretely, as shipped:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;hook_installer.HOOK_TEMPLATE&lt;/code&gt; now guards the primary &lt;code dir=&quot;auto&quot;&gt;exec&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;if [ -x &quot;{interpreter}&quot; ]&lt;/code&gt;
(pinned interpreter, preserved as a symlink per #669) and adds a second guarded branch:
&lt;code dir=&quot;auto&quot;&gt;if command -v {fallback_command}&lt;/code&gt; execs &lt;code dir=&quot;auto&quot;&gt;spec-kitty commit-guard-hook &quot;$@&quot;&lt;/code&gt; resolved fresh
off &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; at commit time. Neither branch is a bare, unguarded &lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;python3&lt;/code&gt; lookup, so
#105 is not reintroduced.&lt;/li&gt;
&lt;li&gt;If neither the pinned interpreter nor &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; is available, the hook exits 1
with a message naming the concrete remedy: &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate repin-hooks&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty commit-guard-hook&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;cli/commands/commit_guard_hook_cmd.py&lt;/code&gt;, a hidden Typer
command) is the install-agnostic fallback entrypoint — a thin &lt;code dir=&quot;auto&quot;&gt;typer.Exit&lt;/code&gt; wrapper around
&lt;code dir=&quot;auto&quot;&gt;specify_cli.policy.commit_guard_hook.main()&lt;/code&gt;’s existing int return code.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate repin-hooks&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;cli/commands/migrate_cmd.py&lt;/code&gt; +
&lt;code dir=&quot;auto&quot;&gt;cli/commands/migrate/repin_hooks.py&lt;/code&gt;) re-runs the same install the &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; lane already
calls internally, re-pinning &lt;code dir=&quot;auto&quot;&gt;.git/hooks/pre-commit&lt;/code&gt; to the &lt;em&gt;current&lt;/em&gt; interpreter. It takes
no &lt;code dir=&quot;auto&quot;&gt;--project-root&lt;/code&gt; option (resolves the current repo via &lt;code dir=&quot;auto&quot;&gt;locate_project_root()&lt;/code&gt;, matching
&lt;code dir=&quot;auto&quot;&gt;backfill-identity&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;backfill-topology&lt;/code&gt;), is idempotent, and does not depend on the hook it
is repairing.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;An install-method migration (pipx -&gt; uv, or any future method) can no longer leave a
hook that hard-fails with an undiagnosable shell error — there is always a fallback path or
a named remedy.&lt;/li&gt;
&lt;li&gt;Already-broken repos have a one-time, explicit repair command instead of requiring a manual
hook reinstall.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The hook script is slightly larger (two guarded &lt;code dir=&quot;auto&quot;&gt;exec&lt;/code&gt; branches instead of one) and takes a
process-spawn cost for &lt;code dir=&quot;auto&quot;&gt;command -v&lt;/code&gt; on the (rare) fallback path.&lt;/li&gt;
&lt;li&gt;A second discovery mechanism (&lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;-resolved &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;) now exists alongside the pinned
interpreter, which must both be kept working.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate repin-hooks&lt;/code&gt; mirrors the existing &lt;code dir=&quot;auto&quot;&gt;migrate&lt;/code&gt; subgroup’s shape and adds no
new CLI surface concepts.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Success signals, verified at ship time: (1) with the pinned interpreter gone and &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;
on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;, a commit succeeds via the fallback branch; (2) with neither available, a commit is
blocked with the named remedy in stderr, not a bare shell path/126/127 error; (3)
&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate repin-hooks&lt;/code&gt; re-pins a hook to the current interpreter regardless of what
it was previously pinned to, and is idempotent.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;a-automatic-silent-self-heal-on-every-commit&quot;&gt;A. Automatic silent self-heal on every commit&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; no user-visible repair step. &lt;strong&gt;Cons:&lt;/strong&gt; silently rewriting a git hook on every commit
is a surprising side effect for something that should fail loudly and rarely; also does not by
itself cover the “neither entrypoint reachable” case, which still needs a named remedy.&lt;/p&gt;
&lt;h3 id=&quot;b-install-agnostic-fallback-entrypoint--one-time-repin-command-chosen&quot;&gt;B. Install-agnostic fallback entrypoint + one-time repin command (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; covers both the “hook still runs, just via a different path” case and the
already-broken repo case explicitly, with a named remedy when both are exhausted. &lt;strong&gt;Cons:&lt;/strong&gt;
two code paths (pin + fallback) to maintain.&lt;/p&gt;
&lt;h3 id=&quot;c-drop-the-pin-always-resolve-off-path&quot;&gt;C. Drop the pin, always resolve off &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; simplest hook body. &lt;strong&gt;Cons:&lt;/strong&gt; reintroduces #105’s exact failure mode as the &lt;em&gt;only&lt;/em&gt;
path (no absolute-path fast path), and loses the #669 symlink-preservation benefit of pinning
the exact interpreter the hook was installed under.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Issue: spec-kitty/EXPERIMENTAL-spec-kitty#254&lt;/li&gt;
&lt;li&gt;Related regressions: #105 (no bare &lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;), #669 (preserve &lt;code dir=&quot;auto&quot;&gt;sys.executable&lt;/code&gt;
symlinks, don’t resolve).&lt;/li&gt;
&lt;li&gt;Standing distribution model (context, not directly actionable by this ADR): uv tool install
from private GitHub Releases + &lt;code dir=&quot;auto&quot;&gt;uv tool upgrade&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
