docs(process): open Understand at the code graph for structural questions (ub-gwe)

[miguelramos]

Closes the tracker task ub-gwe — make the code graph a stated first move for structural questions.

Why

A session-start protocol tells every session to reach for the code-graph MCP tools first when navigating code. Across the whole preceding task (ub-og3, the D48 stdout-channel work) that never happened once and was never disclosed: structural questions — who calls this, what does this reach — were answered with grep sweeps, and one of those answers, that a function had exactly one caller, turned out load-bearing enough that a gate script now rests on it. A check afterwards showed the graph server had zero projects indexed, so the protocol could not have been followed as written even by a session that tried.

The hard rules already carried the negative half of the rule — semantic search is discovery, not authority. What was missing was the positive half: that a structural question opens at the graph, and what a session owes when it cannot.

What changed

CLAUDE.md — the existing hard-rules bullet is replaced in place, not supplemented. A second rule about the same subject in a second document is how these decay. The rewritten bullet routes structural questions to the code-graph tools before any grep sweep, leaves text questions to grep, and forbids silently falling back when the graph is unavailable, unindexed or indexed at another commit. The authority cap survives word for word, its subject widened from semantic search alone to the graph and semantic search together. The list stays at five bullets.

docs/PROCESS.md §4 — the Explore sentence is narrowed to broad text search (unamended it was the only other statement about how an Understand team searches, and it licensed exactly the habit this change exists to stop), and a new paragraph carries the mechanics: which server, which verbs index it and report its state, that the index is machine-local and commit-stamped so it is the main checkout that gets indexed, that branch work is therefore the normal case in which the graph legitimately answers for main's commit, and the one-line field the Understand comment now carries.

.mcp.json — the codebase-memory server entry, committed as it stands by an explicit decision, with the trade-off stated in its commit message rather than hidden.

Tracker + run-report — the record re-export and .knowledge/wiki/runs/2026-08-07-code-graph-first-move.md, written by the Track step on top of the gated commits.

Gates

Design Review — PASS WITH CHANGES. Three adversarial lenses (architecture, evidence, operability) plus a coordinator. Its consolidated output superseded the design brief's wording in full and became a byte-exact implementation spec, so the implementer made no judgement calls.

Verify — PASS WITH NOTES, zero must-fixes. Three adversarial lenses (claim audit, executable gates, coupling-and-mutation), each in its own private checkout, plus a read-only coordinator. It proposed three one-clause hardenings; all three were applied, all inside the process-guide paragraph, leaving CLAUDE.md byte-identical to the gated version (proven by md5 of the diff hunk). Each closed a real hole: the rule prescribed a remedy it never named and would have collapsed into its escape hatch; the expected steady state during branch work was unstated though it is the common case; and the stale-value placeholder invited a token the run-report gate's session-local-id predicate matches, which would have silently flipped a trivial record re-export to substantive.

Delta re-verification (run because the gate said explicitly that its verdict did not cover the hardenings): six check scripts exit 0, doc-lint OK across 19 documents, knowledge-lint OK across 63 pages, layering OK, run-report gate passes, plus the mechanical property set the design spec fixed.

Findings filed rather than absorbed

id	finding
ub-4ne	No spawned agent team can reach the graph tools — every agent definition declares an explicit tool allow-list naming no MCP tool. Separately, the entry committed here is project-scoped and inert until approved, so it reads as wired without starting.
ub-wvh	scripts/knowledge/tests/landing-verify.sh has been red since it landed, with four failures byte-identical on pristine main, and is wired into no workflow.
ub-lg7	No executable check anchors the CLAUDE.md hard rules: deleting the entire rewritten bullet leaves all six check scripts and the doc-lint green — proven non-vacuous by a positive control.
ub-tge	The decision-range check enforces only presence, while its own rationale rests on there being exactly one occurrence; a future cascade adding a second mention defeats it silently.
ub-amw	The repo describes no MCP server other than unblock, and AGENTS.md is a fully generated single-server block with no place to put one.

Note for the reviewer

The rule is inert for spawned teams today — by the tooling's design, not the text's. That is what ub-4ne exists to fix, and it is deliberately not in this pull request: its fix lives under .claude, an always-substantive path, which would drag a second run-report obligation into a change that is two prose edits.