feat(explore): graphify code graph as a freshness-gated, lead-not-evidence explore role

[choiyounggi]

Summary

Integrates the local graphify code-graph CLI into dev-loop as an optional, freshness-gated explore role — a lead-not-evidence orientation layer for planning. With graphify absent, behavior is byte-for-byte unchanged (full suite green with graphify off PATH; resolve-tools explore default still default).

• scripts/graph-freshness.sh (new): one stdout token + exit contract — fresh/0, stale <N>/2, absent/3, cannot-evaluate <usage|no-cli|bad-graph|not-git>/4. Freshness = graph.json mtime vs git log --since=@<epoch> -m --first-parent --name-only (graph.json stores no commit sha). It never executes graphify — the CLI exits 0 on a missing node, a missing file, and a JSON decode error (measured on graphifyy 0.4.23), so the graph is validated with jq instead. Unborn HEAD, commits touching only the graph output dir, and uncommitted edits are handled.
• orchestrate SKILL.md: Preflight runs the freshness check; on stale one chooser offers the AST-only graphify update <root> (consent-gated, never a full build); Phase 2 uses graphify explain/path as leads to seed affected files and shared surfaces, recorded only paired with a search (graphify explain X -> N connections; grep ... -> n hits); the brief's <tools_guidance> carries the explore row with --graph <main-root>/graphify-out/graph.json (worktrees carry no graphify-out).
• wiki-plan A2: a graph citation is allowed only in the same bullet as a grep/file-backed evidence: token; plan-gate.sh untouched.
• loop-implement step 1 / step 6: explain/path before opening source when explore is graphify; graph-derived: <assumption> on the report's NOTES line; CLI only, the graphify skill document is never loaded.
• Docs: references/tool-profile.md explore subsection, examples/tools.example.json, resolve-tools explore when text.
• Wiki: new page infrastructure/agent-orchestration/code-graph-as-orientation-layer.md (field-tested; sources: Developers Digest, AQ Score, Autonoma, Tiare Balbi, graphify README, plus measurements below) + index row, INDEX.md scope text, log.md entry.
• Plan: plans/graphify-explore-role/ — analysis (spikes S1–S5), design (plan-reviewer PASS), 5 tasks.

Measurements that shaped the design (linkly-calendar, 1,306-node graph)

Observation	Consequence
free-text graphify query "<planning sentence>" returned unrelated nodes; explain <Class> returned 20 precise connections; path A B a 3-hop route	skills prescribe symbol-anchored explain/path; query only for orientation with --budget 800
graphify benchmark → 11.4x avg token reduction (6.3x–22.2x), not the advertised 27–70x	the wiki page states the measured figure as an upper bound and asks runs to measure before keeping the graph
--budget on explain is ignored	output bounded with | head -40
graph.json graph metadata empty; 97 files changed since the last build → stale	mtime-vs-git-log freshness gate before any use
graphify-out/ gitignored → worktrees carry none	brief points --graph at the main checkout

Test plan

• bats tests/graph-freshness.bats — 19 cases (usage ×3, absent, fresh, stale, bad-graph ×2, no-cli, not-git, dirty-worktree, empty nodes, --graph override, output-dir-only commit, unborn HEAD, old-branch merge, distinct-path count, single-line stdout, binary never executed); the -m --first-parent and output-dir filters are mutation-proven
• bats tests/orchestrate-graph-explore.bats — 22 section-scoped doc-gates, each with a negative-control fixture
• bats tests/resolve-tools.bats — +2 (graphify cli config resolves; no-config default unchanged)
• full suite with graphify off PATH: rc 0; node scripts/wiki-structure-checks.js wiki → findings 0; wiki-lint-prohibitions.js → violations 0
• plan-reviewer PASS; test-quality-auditor PASS on tasks 01–04; independent code review → 1 Important finding (unborn HEAD exit 128) fixed with a test
• CI on ubuntu + macos (date -r / stat fallback chain, bats compatibility)

Follow-ups (not in this PR): mention graphify in skills/configure/SKILL.md's explore examples; per-repo graphify hook install for post-commit refresh.

🤖 Generated with Claude Code

https://claude.ai/code/session_018nX2peuAu8mwFdTpDoBNnA