refactor(hooks): stage absolute_git_hook_path scoping, and detect a dead pin

[Soph]

Two residuals from the local_dev removal (#1999), both about absolute_git_hook_path — the setting that makes git hooks embed an absolute binary path instead of bare entire, for GUI git clients that never source a shell profile.

The scope change is staged. Phase one warns and migrates; a later release flips it. See below for why a hard break was wrong.

Why staged

Verified against the pre-change binary from main:

$ entire configure --absolute-git-hook-path
✓ Settings updated (.entire/settings.json)
project: {"enabled":true,"absolute_git_hook_path":true}
local:   (none)

The documented way to enable the feature wrote it exclusively to the tracked file. So the affected population isn't an edge case — it's every user of it.

And the failure mode is the worst available: the setting exists because their GUI git client can't find entire on PATH. Unpinning means the guard takes else : there, capturing nothing, with no error. They'd lose checkpoints in exactly the tool they enabled it for.

This is a robustness fix, not a security one — the value only chooses between entire and os.Executable(), a binary the user already invoked. There's no case for breaking anyone quickly.

Phase one (this PR)

• The committed value is still honored. Nobody's hooks change.
• It reports a deprecation, in entire status and entire doctor.
• doctor offers the migration, reusing the confirm/--force/non-interactive degradation already here.
• New writes already go local, so the population stops growing now rather than at phase two.

Copy, not move. Editing a tracked file would land an unexpected change in the user's next commit. Once the local file sets the key the committed one is redundant, so it simply stops mattering when the scope is retired — and the warning goes quiet at that point, which the "no warning once the local file sets the key" case pins. Verified git status shows no tracked-file change after migrating.

Phase two (a release after this reaches stable)

recordAbsoluteGitHookPathDeprecation becomes the enforcing version and the table in absolute_hook_path_scope_test.go flips. Silent for anyone who ran doctor.

A dead pin failed silently

An upgrade into a new version directory, a binary built in a temp dir, a go install that relocates it — the guard takes its else branch, so git keeps working while nothing is captured. Verified before fixing:

$ git commit -m "after the binary moved"
Entire-Checkpoint trailers: 0
$ entire doctor
✓ Git hooks: OK          ← reported healthy

Now GitHooksOutdated, which makes it self-healing: reinstalling re-pins to the running binary. Nothing revalidated a pinned path after install before this. This helps the same population as the staged change above.

That gave GitHooksOutdated two causes needing different advice, so the check reports which — collapsing them told a user with a moved binary that their hook "runs Entire from the working tree", which is false and points at the wrong fix.

Found by /simplify, all reproduced first

• The flag wrote the key into the committed file. The struct assignment stayed and saveSettingsToTarget marshals the whole struct to the target, which defaults to project. My own earlier check missed it because the fixture already contained the key.
• configure --force decided pinning from an ungated read. settings.LoadFromFile reads one file verbatim, so it both missed a local-only value and honored a committed one directly. Now reads the merged view; LoadFromFile's doc says it's display-only.
• The pin parser was wrong: strings.Index(rest, " ]") matched inside a path, so /Users/a ]b/entire parsed as '/Users/a — a permanent false "outdated" plus a reinstall every turn-start that could never repair it.
• Nothing coupled the parser to the generator. Every existing test installed with absolutePath=false, so changing the guard would have silently disabled dead-pin detection with the suite green. Verified by swapping [ -x for test -x and watching the new round-trip test fail. Fixtures now come from buildHookSpecs, which also deleted a tc.name branch inside a table test.

Plus: one pass over the invocation line instead of two and one os.Stat instead of five; the mid-loop continue removed (it sat below two Absent returns, so a future Absent check would have been skipped for hooks 2–5); setEnabledRaw generalized to setRawKey, restoring a doc comment an earlier edit had orphaned and carrying a nil-map guard; provenance from rawHasKey rather than call order; three exported entry points → two; the settings test moved to loadMergedSettings + t.Parallel like its sibling (0.21s → 0.00s, no git subprocess per case).

Deliberately not done

• saveToFile stripping machine-local fields. Tempting as a single choke point, but while the committed value is still honored it would delete a working setting out of a tracked file as a side effect of an unrelated entire configure. Revisit at phase two, when the key is inert.
• A declarative per-field scope registry. Two gates with different verification depth and failure policy aren't a table's worth, and there's no seam to hang it on.
• Unified rejection reporting across the three existing shapes, and adding it to status --json. That's where a fourth such field's cost lands, but it's a separate change.
• A machine-readable pin marker in the hook format, which would remove the parse coupling entirely — needs a transition release, and the round-trip test buys the protection now.

Testing

mise run fmt && mise run lint && mise run test:ci pass. Every new guard was verified to fail against the defect it protects against.

Verified end to end with a built binary: an existing user's hooks stay pinned and they get a warning with a one-command fix; doctor --force migrates with no tracked-file change; the warning then stops and the hooks are still pinned; a moved binary is diagnosed with the right message and repaired.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1711857. Configure here.}

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR improves Git hook health reporting by distinguishing why hooks are considered outdated, and enforces absolute_git_hook_path as a machine-local-only setting (with user-visible feedback when rejected from the committed settings file).

Changes:

• Add hook-state “reason” plumbing and update doctor output to show actionable, cause-specific guidance.
• Detect and report drift when hooks are pinned to a missing absolute binary path.
• Enforce absolute_git_hook_path scope to .entire/settings.local.json, including new tests and status/doctor messaging.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/hooks.go	Adds CheckGitHookStateWithReason, dead-pin detection, and pinned-path parsing helpers.
cmd/entire/cli/strategy/hooks_test.go	Updates hook-state tests for new return signature; adds tests for dead pinned paths and reason strings.
cmd/entire/cli/doctor.go	Displays absolute_git_hook_path rejection and prints cause-specific outdated reasons.
cmd/entire/cli/status.go	Surfaces absolute_git_hook_path rejection in detailed status output.
cmd/entire/cli/setup.go	Writes absolute_git_hook_path to local settings and emits messaging about where it was written.
cmd/entire/cli/settings/settings.go	Drops committed-scope absolute_git_hook_path, records rejection reason, and exposes it via accessor.
cmd/entire/cli/settings/absolute_hook_path_scope.go	Implements scope enforcement and rejection reason for committed absolute_git_hook_path.
cmd/entire/cli/settings/absolute_hook_path_scope_test.go	Adds tests pinning the intended scope/rejection and guarding serialization behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.