graphify: fix the real gap (dropped doc-code edges), not the retrieval algorithm

.claude/skills/plan-with-graph/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: plan-with-graph
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies one-by-one, one question at a time — give your recommended answer for each.
+
+Where a question is answerable from existing knowledge, run `graphify query "<question>"`, `graphify explain "<concept>"`, or `graphify path "<A>" "<B>"` against `graphify-out/graph.json` instead of asking me. Treat its answer as your recommendation, and only surface it to me if it conflicts with what I've described — that conflict is what matters most to grill on, since it means intent and the current shared model are misaligned. If a query returns wrong, empty, or ambiguous results, fall back to a direct file read; don't log the correction anywhere for a future session to inherit unprompted (no `graphify save-result`/`reflect`, no `LESSONS.md` — those fold into every later session's context by default, for every topic: an unreviewed, accumulating nudge, not a deliberate one).
+
+**Fact and intent are folded in differently, and never cross-reference.** Only `docs/architecture/` is graphed — `.graphifyignore` deliberately excludes the rest of `docs/` as unbuilt aspiration, not a gap to patch.
+- Converged, currently-built understanding goes in `docs/architecture/`; deferred or aspirational design goes in `docs/intent/`. Write the actual files as understanding is reached — not a list of things to write.
+- **A fact doc must never reference an intent doc.** `docs/architecture/*` citing `docs/intent/*` points at something that, by definition, doesn't exist yet — the graph reports it unresolved — and runs the dependency backwards: fact stands on what's built, never on a plan for what isn't. Cite it only once the intent doc ships and becomes `docs/architecture/`.
+- **Every fact doc cites real code with the graph's markup, never backticks alone**: `[text](ref:label:ExactNodeLabel)` for a symbol, `[text](ref:path:relative/path/from/repo/root.ts)` for a file. graphify's own extraction never turns a prose code-mention into an edge, however formatted — this markup is the only thing the linker below acts on, deliberately, so it never has to guess whether a backtick span is illustrative code, a label, or a path.
+
+After writing or updating a fact doc, run `python3 .claude/skills/plan-with-graph/link_doc_to_code.py <doc-path>` — dry-run while drafting to check every `ref:` resolves, `--apply` once committed — for every doc this session touched; the post-commit hook re-applies it on later commits, so this covers only the current session. It only adds edges between existing nodes (never creates one, so it can't collide with graphify's own extraction/merge) and is idempotent, replacing just its own prior edges for that file. An unresolved `ref:` means the target isn't ingested yet — run a normal graphify build/update first, then re-link. Run it against an intent doc and it reports the doc excluded and skips — expected, not an error.
+
+If user intent is found to diverge from what is actually built, surface that as a concrete finding. A plan to close the gap may follow — but it's a consequence of the session, not its goal. The goal is a graph that accurately reflects the converged understanding of what Warden is, why it's built this way, and how its parts relate.