Worktree agents cannot query the graphify graph — port the .githooks/ bootstrap from claude-coordinator

[JDonaghy]

Problem

Agents working in a git worktree in this repo are graph-blind: they cannot query the graphify knowledge graph, and silently fall back to grep.

graphify-out/ is gitignored by design (only its .gitignore is tracked — the graph is multi-MB, rewritten every commit, and would conflict across parallel worker branches), so git worktree add materialises an empty graphify-out/. And graphify query resolves graphify-out/graph.json strictly relative to cwd — no upward walk, and query has no --graph override (only path/explain/diagnose do).

claude-coordinator solved this in PRs #1613 + #1614. This issue ports that solution here.

What to do

Copy the .githooks/ directory from the claude-coordinator checkout, which exists at ~/src/claude-coordinator/.githooks/ on every machine in the fleet:

• _lib.sh — shared gfy_abs / gfy_common_dir / gfy_is_linked_worktree / gfy_chain
• post-checkout — in a linked worktree, symlinks graphify-out at the base checkout's graph, then exits without rebuilding; in the main worktree, chains to $GIT_COMMON_DIR/hooks/post-checkout
• post-commit, post-merge — skip in linked worktrees, otherwise chain to the machine-local hook

Adapt only the comments that name claude-coordinator specifics. Do not change the logic — it is load-bearing and was arrived at by trial and error (see the two PRs above).

Non-negotiable details, each of which broke during the original work

1. The hooks MUST be committed mode 100755. Git silently ignores a non-executable hook — it prints an advice hint at most and carries on as if no hook existed. Verify with git ls-files -s .githooks/ and confirm every hook (not _lib.sh) shows 100755.
2. core.hooksPath REPLACES .git/hooks wholesale — no merge, no fallback. Every hook kind graphify installs locally needs a counterpart in .githooks/ or it is silently disabled. That is why post-commit and post-merge shims exist alongside post-checkout; shipping only post-checkout was the #1614 bug.
3. Never rebuild inside a linked worktree. graphify-out there is a symlink to the SHARED base graph, so a rebuild would overwrite it from a feature-branch tree — and a worktree can be reaped mid-rebuild.

Testing

Add an integration test that drives the hook through real git — build a temp repo, copy in the real .githooks/, git config core.hooksPath .githooks, commit the hooks, seed a fake graphify-out/graph.json, run git worktree add, and assert the worktree's graphify-out is a symlink resolving to the base graph. std::process::Command is sufficient; no new dependencies.

Cover at minimum:

• worktree add produces the symlink
• no symlink when the base checkout has no graph.json (must not create a dangling link)
• a real graph already in the worktree is never clobbered
• anti-vacuity: assert the hook is actually reachable from inside a worktree before asserting "X does not happen" there. Git resolves a relative core.hooksPath against the invoking directory, so .githooks/ must be committed or in-worktree checkouts never run the hook at all — two of the original tests passed for weeks without the hook ever running.
• the checked-in hooks are mode 100755

Out of scope

• Do not edit CLAUDE.md, README, or any shared docs — the coordinator handles documentation.
• Do not add a coord diagnose --graph equivalent; that lives in claude-coordinator and already covers every repo on the machine.
• Enabling the hook (git config core.hooksPath .githooks) is a per-checkout deployment step the operator runs; it is not part of this PR.

Before coding

Verify this isn't already present — check whether .githooks/ already exists in this repo.

[JDonaghy]

Coordinator Assignment

Machine: precision
Repo: vimcode
Files: (unspecified)
Do not touch: (nothing else in flight)

Briefing

Issue #611: Worktree agents cannot query the graphify graph — port the .githooks/ bootstrap from claude-coordinator

Problem

Agents working in a git worktree in this repo are graph-blind: they cannot query the graphify knowledge graph, and silently fall back to grep.

graphify-out/ is gitignored by design (only its .gitignore is tracked — the graph is multi-MB, rewritten every commit, and would conflict across parallel worker branches), so git worktree add materialises an empty graphify-out/. And graphify query resolves graphify-out/graph.json strictly relative to cwd — no upward walk, and query has no --graph override (only path/explain/diagnose do).

claude-coordinator solved this in PRs #1613 + #1614. This issue ports that solution here.

What to do

Copy the .githooks/ directory from the claude-coordinator checkout, which exists at ~/src/claude-coordinator/.githooks/ on every machine in the fleet:

• _lib.sh — shared gfy_abs / gfy_common_dir / gfy_is_linked_worktree / gfy_chain
• post-checkout — in a linked worktree, symlinks graphify-out at the base checkout's graph, then exits without rebuilding; in the main worktree, chains to $GIT_COMMON_DIR/hooks/post-checkout
• post-commit, post-merge — skip in linked worktrees, otherwise chain to the machine-local hook

Adapt only the comments that name claude-coordinator specifics. Do not change the logic — it is load-bearing and was arrived at by trial and error (see the two PRs above).

Non-negotiable details, each of which broke during the original work

1. The hooks MUST be committed mode 100755. Git silently ignores a non-executable hook — it prints an advice hint at most and carries on as if no hook existed. Verify with git ls-files -s .githooks/ and confirm every hook (not _lib.sh) shows 100755.
2. core.hooksPath REPLACES .git/hooks wholesale — no merge, no fallback. Every hook kind graphify installs locally needs a counterpart in .githooks/ or it is silently disabled. That is why post-commit and post-merge shims exist alongside post-checkout; shipping only post-checkout was the #1614 bug.
3. Never rebuild inside a linked worktree. graphify-out there is a symlink to the SHARED base graph, so a rebuild would overwrite it from a feature-branch tree — and a worktree can be reaped mid-rebuild.

Testing

Add an integration test that drives the hook through real git — build a temp repo, copy in the real .githooks/, git config core.hooksPath .githooks, commit the hooks, seed a fake graphify-out/graph.json, run git worktree add, and assert the worktree's graphify-out is a symlink resolving to the base graph. std::process::Command is sufficient; no new dependencies.

Cover at minimum:

• worktree add produces the symlink
• no symlink when the base checkout has no graph.json (must not create a dangling link)
• a real graph already in the worktree is never clobbered
• anti-vacuity: assert the hook is actually reachable from inside a worktree before asserting "X does not happen" there. Git resolves a relative core.hooksPath against the invoking directory, so .githooks/ must be committed or in-worktree checkouts never run the hook at all — two of the original tests passed for weeks without the hook ever running.
• the checked-in hooks are mode 100755

Out of scope

• Do not edit CLAUDE.md, README, or any shared docs — the coordinator handles documentation.
• Do not add a coord diagnose --graph equivalent; that lives in claude-coordinator and already covers every repo on the machine.
• Enabling the hook (git config core.hooksPath .githooks) is a per-checkout deployment step the operator runs; it is not part of this PR.

Before coding

Verify this isn't already present — check whether .githooks/ already exists in this repo.

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 7m 46s
Log: /home/john/.coord/logs/74da6f153c4b.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 1m 55s
Log: /home/john/.coord/logs/c91072fe5ca5.log

[JDonaghy]

Review Complete — ⚠️ Changes Requested

Reviewer findings could not be posted directly to PR #612 (gh pr review was rejected — likely a self-review restriction). Findings are reproduced here.

Blocking findings

• tests/githooks_worktree_graph.rs:96-101 (init_base_repo) — the mode-regression test is vacuous. It unconditionally force-chmods every copied hook to 0o755/0o644 before committing, discarding the real mode of the source files under .githooks/. hooks_are_committed_as_executable then asserts on that hardcoded mode, not on the actual repo's tracked permissions. This means the test can never catch the exact regression the issue calls "non-negotiable Develop #1" (a hook silently committed non-executable) — it will pass even if .githooks/post-checkout loses its executable bit in a future commit. This directly contradicts the issue's explicit test requirement ("the checked-in hooks are mode 100755") and the file's own stated anti-vacuity design goal. Suggest reading the real mode from githooks_src_dir() via PermissionsExt::mode() & 0o111 (or comparing against it) instead of overwriting it, or running git ls-files -s .githooks directly against CARGO_MANIFEST_DIR's own checkout rather than a re-chmod'd scratch copy.

Non-blocking concerns

• tests/githooks_worktree_graph.rs:325-363 — the post-commit/post-merge shim test only proves the git operation doesn't error and that the hook ran per GIT_TRACE; it can't distinguish "skipped due to linked worktree" from "chained to a nonexistent machine-local hook" since the fixture has no $GIT_COMMON_DIR/hooks/post-commit installed. Low priority since the skip/chain branch is unchanged, verbatim-ported logic.
• The new test module isn't #[cfg(unix)]-gated overall, only the set_permissions call is. CI is currently fully disabled (ci.yml.disabled) so this isn't live, but if a Windows leg is re-enabled later, these tests (which rely on real symlinks and POSIX sh hook execution) will likely fail rather than skip.

Nits

None.

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 5m 41s
Log: /home/john/.coord/logs/d2def13c8f4d.log

[JDonaghy]

Review Complete — ✅ Approved

Reviewer findings could not be posted directly to PR #612 (gh pr review was rejected — likely a self-review restriction). Findings are reproduced here.

This re-review covers only the fix commit 5a2ef87 (the prior round requested changes to make two tests non-vacuous).

Verified the fix directly:

• hooks_are_committed_as_executable now runs git ls-files -s .githooks against CARGO_MANIFEST_DIR (the real repo root) instead of a scratch-repo copy that init_base_repo had just force-chmod'd — confirmed via git ls-tree that the real committed blobs are 100755 for post-checkout/post-commit/post-merge and 100644 for _lib.sh, so this test now actually exercises what it claims to and would catch a real regression.
• post_commit_and_post_merge_shims_skip_in_linked_worktree_and_chain_in_main now installs fake machine-local hooks under the base repo's .git/hooks/ and asserts marker-file presence/absence in both the linked-worktree case (must skip, no chain) and the main-worktree case (must chain), correctly distinguishing "skipped due to linked worktree" from "chained to a hook that was never installed" — the exact vacuity the previous review flagged.
• #![cfg(unix)] now gates the whole module, and the previously-duplicated #[cfg(unix)] block inside init_base_repo was correctly removed as redundant.

No changes to .githooks/* logic in this commit (test-only fix, as expected/in scope). No regressions found; test structure, naming, and doc comments are internally consistent with the new behavior.

Blocking findings

None.

Non-blocking concerns

None.

Nits

None.

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 2m 1s
Log: /home/john/.coord/logs/c0af5ee095a9.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 9m 51s
Log: /home/john/.coord/logs/000419b87cc0.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: elitebook
Status: done
Exit code: 0
Duration: 8m 2s
Log: /home/john/.coord/logs/e413e5f1fd2d.log

[JDonaghy]

Review Complete — ✅ Approved

Reviewer findings could not be posted directly to PR #612 (gh pr review was rejected — likely a self-review restriction). Findings are reproduced here.

Scoped this re-review to the two fix commits pushed since the last round (5a2ef87 "make githooks mode/chain tests non-vacuous per review" and 1e3ab80 "symlink graphify-out/* contents, not the directory itself"), diffed against the prior d756076 base.

Verification method: I independently checked the worker's claim that this rewrite matches an upstream claude-coordinator fix. My local ~/src/claude-coordinator checkout was itself 4 commits behind origin/main (unpulled), so I pulled/diffed against origin/main directly. It contains commit c4d1f35 "Fix #1617: symlink graphify-out/* contents, not the directory itself", timestamped ~1.5 hours before the vimcode worker's 1e3ab80. I then diffed the vimcode-committed .githooks/post-checkout, post-commit, post-merge, and _lib.sh against origin/main's versions byte-for-byte: post-commit and post-merge are identical, and post-checkout/_lib.sh differ only in comment lines that name claude-coordinator specifics (e.g. "coord's dispatch code" → "any one creator's dispatch code", dropping the coord diagnose --graph reference per the issue's out-of-scope note). No executable logic differs from upstream. This is exactly what the issue mandated ("Do not change the logic") — the worker correctly tracked a canonical-source update between review rounds rather than inventing a deviation.

Fix commit 1 (5a2ef87, test rigor): Addresses what were almost certainly round-1 review complaints about vacuous tests — hooks_are_committed_as_executable now reads git ls-files -s .githooks against CARGO_MANIFEST_DIR (the real repo's index) instead of a scratch copy the test itself had just chmod'd (previously circular — could never catch a real mode regression). The post-commit/post-merge shim test now installs a fake machine-local hook and asserts skip-vs-chain behavior via a marker file, rather than just checking exit codes.

Fix commit 2 (1e3ab80, hook logic + matching tests): Reworks the bootstrap from "replace graphify-out/ with a directory symlink" to "keep the directory, symlink each entry inside it, skip .gitignore." I traced through the shell logic for correctness:

• The mkdir -p graphify-out + per-entry glob loop ("$_base"/graphify-out/* "$_base"/graphify-out/.[!.]*) correctly preserves the tracked .gitignore and only creates entries that actually exist in the base (unmatched globs are filtered by [ -e "$_entry" ] || continue, the standard idiom).
• The "already bootstrapped / real local graph" gate now keys off graphify-out/graph.json specifically (absent or itself a symlink → re-link; present as a real file → skip entirely), correctly matching the new per-entry design.
• New test worktree_remove_leaves_the_base_graph_intact pins down that a directory-level symlink (e.g. cache/) is never followed/recursed into by git worktree remove, protecting the base graph — good defensive coverage for the new multi-entry-symlink shape.
• worktree_add_leaves_git_status_empty and worktree_add_preserves_the_tracked_gitignore are exactly the assertions whose absence let the original claude-coordinator#1617 incident ship; both are now present and correctly ordered (checking the parent isn't a symlink before trusting file-level assertions under it).

Only .githooks/post-checkout and tests/githooks_worktree_graph.rs changed in this round (confirmed via git diff --stat d756076..1e3ab80) — no docs, README, or CLAUDE.md touched, staying in scope. Hook file modes are still correctly 100755 for the three hooks and 100644 for _lib.sh (confirmed via git ls-tree).

I found no regressions and no remaining review-round issues. This is a careful, well-verified port.

Blocking findings

None.

Non-blocking concerns

• The new per-entry symlink loop inherits a latent edge case directly from upstream (not introduced by this port): if a worktree previously had graphify-out replaced by a directory-level symlink under the old (pre-#1617) hook behavior, mkdir -p graphify-out on a symlink-to-directory is a no-op on most mkdir implementations, so the loop would then write new symlinks through that link into the base checkout's real graphify-out/. This can't happen on a fresh vimcode adoption (no prior hook version was ever installed here) and is present in the canonical claude-coordinator source too, so it's correctly out of scope per "do not change the logic" — just flagging for awareness in case it's worth a follow-up issue upstream.

Nits

None.