chore: added graphify tool implementation

[Ignacio Nistal (ignacionistal)]

chore: added graphify tool implementation

Type of Change*

• New feature
• Bug fix
• Documentation update
• Refactoring
• Hotfix
• Security patch
• UI/UX improvement

Description

Adds Graphify as a pilot for AI-assisted navigation: committed code knowledge graph, Cursor rules/MCP, setup scripts, and docs so the team can trial lower token usage and faster codebase questions.

Testing*

Tested locally comparing difference between queries with and without graphify to compare token usage and speed.

Impact

This is only a developer tool, does not affect the application.

Additional Information

Graphify docs: https://graphifylabs.ai/

Checklist*

• No new errors or warnings have been introduced.
• All tests pass successfully and new tests added as necessary.
• Documentation has been updated accordingly.
• Code adheres to the coding and style guidelines of the project.
• Code has been commented in particularly hard-to-understand areas.

[Kevin Loftus (kevin-loftus-dept)]

1. Committed Husky hooks run for every developer (highest impact)

Problem: .husky/post-commit and .husky/post-checkout are committed, so they run for the whole team after pnpm install — not only for people who ran pnpm graphify:setup. post-checkout triggers a full graph rebuild on every branch switch when graphify-out/ exists (which it always will). Docs say opt-out is “don’t run setup,” but the hooks are already active.

Proposed solution: Make hooks opt-in, not repo-default.

• Remove .husky/post-commit and .husky/post-checkout from the committed repo.
• Let pnpm graphify:setup / graphify hook install add them locally only (gitignored or documented as local-only).
• Update docs/development/graphify.md opt-out section: hooks are only present after setup; without setup, no hook behavior.
• Optional safety: add GRAPHIFY_SKIP_HOOK=1 support to post-checkout (already exists for post-commit) so developers can disable rebuilds temporarily.

---

2. Merge driver configured locally but referenced globally in .gitattributes

Problem: .gitattributes sets graphify-out/graph.json merge=graphify, but merge.graphify.driver is only set by pnpm graphify:setup in local git config. Anyone merging branches that both change graph.json without running setup gets an “unknown merge driver” error.

Proposed solution: Pick one of these (recommended: A + C):

• A. Document as required onboarding — In contributing.md and graphify.md, state clearly: after clone, run pnpm graphify:setup once before merging branches that touch graphify-out/. Add a troubleshooting entry for the exact error message.
• B. Remove the merge driver from committed .gitattributes until the team standardizes on setup — conflicts resolve by re-running pnpm graphify:build after merge instead of union-merge.
• C. Add a CI/check script (e.g. scripts/graphify-check-setup.sh) that warns if merge.graphify.driver is missing when graphify-out/ exists — run in docs or as a soft pre-merge reminder, not a hard gate.

Git cannot commit merge-driver config repo-wide; local setup or dropping .gitattributes merge rule are the realistic options.

---

3. Machine-specific Python path hardcoded in shared hooks

Problem: Both hooks contain _PINNED='/Users/ignacionistal/.local/share/uv/tools/graphifyy/bin/python'. Fallbacks prevent breakage on other machines, but a committed author-specific path is wrong and makes hook debugging harder.

Proposed solution:

• If hooks stay committed (not recommended — see feat(EG-309): add conventional commit message & branch naming restrictions #1): set _PINNED="" and rely on graphify-out/.graphify_python, PATH/shebang probing, and python3/python fallbacks.
• If hooks are install-time only (recommended): let graphify hook install write _PINNED into local hook files; never commit that value. Add graphify-out/.graphify_python to .gitignore if it would contain machine paths.

---

Suggested fix order: Fix #1 first (stops team-wide surprise), then #2 (prevents merge failures once multiple graph updates land), then #3 (quick cleanup, especially if hooks become install-time only).