feat(launchpad): ProjectGraph with typed edges and traversal over buzz-core

[serina-mcfall]

Summary

Implements all 6 steps of #207's plan: a ProjectGraph that materializes 4 of the design doc's 8
edge types (calls/called_by, tested_by, configured_by, documented_by) from #206's
already-indexed Symbol records, plus real BFS traversal (reachable()).

Stacked on #213 (this branch is task/206-project-indexer + this PR's own commits) since
#207 ingests #206's output directly. Base is task/206-project-indexer, not launchpad --
review this PR's own two commits; the earlier ones are #213's, already under review there.

Related issue

Refs #207 (a stacked PR's base isn't the default branch, so GitHub won't create a real closing
link from "Closes" here -- retarget to launchpad once #213 merges, then this can close #207
for real)

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-sonnet-5
Session reference	N/A - harness does not expose a session/run URL
Initiating human	@serina-mcfall

Objective

Build a ProjectGraph that ingests #206's Symbol records into typed, directional edges and
answers traversal queries, per #207.

Impacted components

launchpad/project-intelligence/graph.py
launchpad/project-intelligence/test_graph.py

Approach and rejected alternatives

Chosen: implement 4 of the design doc's 8 edge types (calls/called_by, tested_by,
configured_by, documented_by) -- the ones #206's Symbol schema already produces directly.
Rejected: also building imports, deployed_by, owns, depends_on in this task. Those need
extraction #206 does not currently do (Rust use statements, deployment units, Cargo.toml
dependencies), which is a larger task than "ingest a ProjectIndexer's Symbol records" as #207's
own Objective states it. Flagged explicitly as an OPEN scope question in the plan rather than
silently deciding either way -- this needs a human call before #207 is considered fully done
against the design doc, even though it satisfies #207's own stated Definition of done.

Chosen: derive called_by as calls[]'s own structural inverse inside ProjectGraph, rather
than also reading #206's separately-computed called_by[] field. Rejected reading both, since
#206 already computes called_by[] from calls[] itself (with_called_by()) -- treating them
as two independent sources would double every edge from the same underlying fact.

Verification

Command run:

$ python3 -m unittest test_symbol test_indexer test_graph

Raw output:

..................
----------------------------------------------------------------------
Ran 18 tests in 0.001s

OK

Command run:

$ python3 graph.py buzz-core

Raw output:

=== STEP 6: every edge for one chosen real symbol ===

is_shared_gated_kind --called_by--> tests::shared_gated_kinds_membership  (Symbol.calls[] (inverse))
is_shared_gated_kind --calls--> contains  (Symbol.calls[])
is_shared_gated_kind --tested_by--> tests::shared_gated_kinds_membership  (Symbol.tests[])
is_shared_gated_kind --documented_by--> ARCHITECTURE.md  (Symbol.documentation_links[])
is_shared_gated_kind --documented_by--> launchpad/plans/2026-08-18-issue-207-project-graph.md  (Symbol.documentation_links[])
is_shared_gated_kind --called_by--> is_unshared_gated_event  (Symbol.calls[] (inverse))

=== STEP 4: a 2-hop relationship the flat Symbol record alone cannot show ===

reachable('tests::is_unshared_gated_event_author_always_allowed', max_hops=2) includes 'is_shared_gated_kind': True
  path: tests::is_unshared_gated_event_author_always_allowed -> is_unshared_gated_event -> is_shared_gated_kind

=== STEP 5: the negative case -- vague questions need a starting symbol ===

Query: reachable(graph, 'the code that checks kind gating', ...)
Result: [] -- empty, because 'the code that checks kind gating' is not a symbol_id
this graph knows about. Resolving a description to a starting symbol is
#210's (SemanticIndex) job, not this graph's -- confirming the boundary.

Also separately confirmed a real tested_by edge (tests::shared_gated_kinds_membership) and a
real configured_by edge (service_resource -> OTEL_SERVICE_NAME, in buzz-relay) during
development, both cross-checked against real source lines.

A real bug was found and fixed during self-review, not by a test: tested_by and
documented_by initially had source/target reversed (read "the test is tested_by the symbol"
instead of "the symbol is tested_by the test") -- caught by reading the STEP 6 CLI output
literally, fixed, and a new EdgeDirectionTest (3 tests) added so the class of bug (right
construction, wrong direction, invisible to a test that only checks an edge exists) is caught by
the suite next time.

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

Only tested against buzz-core's indexed data (matching #206's own single-crate scope). Did not
measure traversal performance at a larger scale (the in-memory dict-of-lists structure is
adequate for 453 symbols; unverified beyond that). Did not verify behavior when #206's indexer
is re-run after the underlying code changes (a "dirty" re-index scenario) -- this task assumes a
fresh build_index() call each time, matching #206's own scope.

Security implications

N/A - a pure in-memory data structure over already-indexed data; no code execution, network
access, or trust-boundary changes beyond what #206 already does (which this PR does not modify).

Escalations

The OPEN item from the plan, restated here because it matters for whoever reviews this: is
4-of-8 edge types acceptable for #207 to be "done" against the design doc, or does the design
doc's full edge-type list need a follow-up task (or a scope note added to #207 itself, the way
#193 did for the lefthook exception)? This PR satisfies #207's own Definition of done exactly as
written, but that list is narrower than the design doc's 8 edge types, and I did not decide
silently which reading governs.

[serina-mcfall]

Codex's independent review confirmed all 3 findings (all P2) — fixed in the follow-up commit:

• Namespaced synthetic nodes: config keys and doc paths are now config:KEY / doc:PATH, so a symbol whose qualified_name happened to match one (e.g. a symbol literally named the same as an env var it reads) can no longer collide onto the same graph node.
• Rejected negative max_hops: the old hop == max_hops check silently ignored negative bounds, traversing the whole graph instead of respecting the caller's limit. Now raises ValueError for negative values and checks hop >= max_hops.
• Fixed the inverse-dedup test: the fixture left callee.called_by empty, so a regression (reading both calls[] and called_by[] as independent sources, doubling the edge) would have passed anyway. Populated it so the test actually exercises what it claims.

Added 3 new tests covering the first two directly. All 21 tests pass; live re-verified against real buzz-core data with the namespaced output.

[benmitchell11]

Reviewing this PR's own two commits (graph.py, test_graph.py, the plan doc) — confirmed the diff against task/206-project-indexer doesn't re-touch #213's files, so the stacking is legitimate, not accidental scope creep.

Genuinely good catch during self-review: the initially-reversed tested_by/documented_by edge direction is exactly the kind of bug a test that only checks 'edge exists' would never catch — confirmed EdgeDirectionTest actually asserts direction, not just presence. The STEP 5 negative-case output ('a vague description isn't a symbol_id this graph knows about') is a good, honest boundary check against scope creep into #210's job.

Approving the code on its merits. Do not merge as-is — base is task/206-project-indexer, not launchpad; per the PR body this needs retargeting once #213 lands, or merging now would pull #213's commits in through the wrong PR. Also flagging, not deciding: the open question of whether 4-of-8 design-doc edge types is 'done enough' for #207, or needs a follow-up task/scope note the way #193 did for the lefthook exception — that's a real scope call for a maintainer, not something to wave through silently.

[joshuavial]

Produced with the pr-review-panel skill: two reviewers on different models (Claude Fable and codex gpt-5.6-sol at xhigh reasoning) reviewed this PR independently with no shared context, their verdicts were consolidated, and the result was reviewed and approved by a human before posting. Claims marked "verified" or "reproduced" were re-checked by hand against the code, not taken from a reviewer's word.

Review panel: two independent reviewers (Fable, codex gpt-5.6-sol @ xhigh)

Each read the diff, the worktree at PR head, #207 and this PR's comments; neither saw the other's output. Scope: this PR's own commits only (graph.py, test_graph.py, the plan doc) — symbol.py/indexer.py from #213 read for context, not reviewed.

python3 -m unittest test_symbol test_indexer test_graph → 21/21 pass, confirmed by both. The live graph.py buzz-core run could not be reproduced (rql not on PATH in this checkout), so the pasted output is taken on trust.

The implementation is sound. The four self-review and Codex-review fixes are real and mutation-verified: reverting the tested_by direction, re-reading called_by[] as an independent source, restoring hop == max_hops, or dropping config: namespacing each fails the suite. BFS handles cycles, self-return, zero hops and nearest-first ordering correctly. Findings below are test-coverage gaps and one scope decision, not defects in shipped behaviour.

---

Blocking

1. Base branch — do not merge as-is. Base is task/206-project-indexer, not launchpad. Merging now lands these commits into #213's branch and no closing link to #207 ever forms. Already acknowledged in the PR body and by @benmitchell11; retarget once #213 lands. Process, not code.

2. 4-of-8 edge types needs an explicit maintainer decision. #207's Objective names all eight (imports, calls/called_by, configured_by, tested_by, documented_by, deployed_by, owns, depends_on), and the DoD's "edge types are explicit and directional as specified" points back at that list. The PR body's claim that this "satisfies #207's own Definition of done exactly as written" is the weaker reading — the narrower checkbox list doesn't override the Objective it refers to.

Both reviewers reached this independently, and we agree with the technical call: imports, deployed_by, owns and depends_on need extraction #206 does not perform (Rust use statements, deployment units, Cargo.toml deps), so building them here would be a different task. Declaring all nine strings in EdgeType (graph.py:20-30) while only four can ever be materialized is the visible symptom. The fix is a scope decision — narrow #207 with a written note and file the remainder as a follow-up, the way #193 did for the lefthook exception — not more code in this PR. The author flagged this openly rather than deciding silently, which is the right call; it just needs someone to actually make the decision.

High

3. reachable()'s edge_types filter is not pinned by any test — removing it entirely leaves the suite green. graph.py:90-94. Verified directly: deleting the filter from edges_from() so it always returns every edge still passes all 12 tests. Every traversal fixture in test_graph.py has only one outgoing edge type per node, so filtering is never exercised. edge_types is the feature #207's DoD asks for by name ("filtered by edge type"), and it is currently unprotected. Needs a fixture where one node has outgoing calls and tested_by/configured_by edges to different unvisited nodes, asserting the filtered traversal reaches only one of them.

(Found by codex; independently reproduced.)

4. Reachable.path is never read by any test — a truncated path passes the suite. graph.py:129, documented at graph.py:101 as "the node sequence from the start, inclusive of both ends". Verified: mutating new_path = path + (edge.target,) to new_path = (edge.target,) keeps all 12 tests green, while the STEP 4 CLI output would silently print a wrong path. This is precisely the class of bug the PR's own EdgeDirectionTest exists to prevent — right node, wrong provenance, invisible to a test that only checks presence. Fix is cheap: in test_graph.py:143, also assert the full expected tuple for both the 1-hop and 2-hop results.

(Both reviewers flagged this.)

Medium

5. Unresolved external call targets become un-namespaced hub nodes. graph.py:61-67. When #206 cannot resolve a callee (std-lib or other-crate names — contains appears in the PR's own STEP 6 output), the bare short name becomes a graph node, and the inverse edge makes it a hub: every symbol calling anything named contains gets a called_by edge from that single node. A mixed-type traversal such as reachable(g, "A", ("calls", "called_by"), 2) then reports unrelated symbol B as reachable from A purely because both call same-named methods on different types.

The root cause is #206's accepted best-effort resolution, but this PR amplifies it by adding the inverse edges — and the config:/doc: namespacing comments at graph.py:74-83 read as if synthetic-node collisions are now fully handled, when this one is not. Minimum: document the limitation where the inverse edge is built. Better (reasonable follow-up): namespace unresolved targets too, e.g. extern:contains, via a membership check against the input qualified names.

(Fable.)

6. Edge.source's docstring contradicts the actual node identity. graph.py:35 says "symbol_id or a synthetic node id", but nodes are keyed by qualified_name (graph.py:66) — so edges_from(sym.symbol_id) always returns [], and two Symbol records sharing a qualified name silently merge into one node. The class docstring at graph.py:46-47 does state the qualified_name choice, so this is a stale field comment, not a design error.

To be clear about what we are not recommending: codex proposed keying nodes by symbol_id and mapping qualified names through it. We disagree — Symbol.calls[] contains qualified names (indexer.py:168), so symbol_id-keyed nodes would break traversal outright. qualified_name is the correct key here. Fix the comment, and note the same-qualified-name merge as a known limitation. (Whether real rql output actually produces colliding qualified names is unverified — no rql in this checkout.)

(codex, narrowed.)

Low

7. STEP 4's done-when is only half-demonstrated. The plan (launchpad/plans/2026-08-18-issue-207-project-graph.md:43-44) says to print is_shared_gated_kind's own called_by[] alongside the reachable() result, so the "the flat record alone can't show this" contrast is visible. graph.py:166-172 prints only the traversal side. One extra print closes it.

8. EdgeFieldsTest asserts fields on edges[0] only (test_graph.py:29-32), where STEP 1's done-when says "asserts every field". Cosmetic — and the test is near-tautological anyway, constructing dataclasses rather than exercising graph logic.

9. Placeholder-free f-strings at graph.py:158, graph.py:166, graph.py:174 (ruff F541).

---

What's right

• Edge direction is coherent across all four types, and EdgeDirectionTest (test_graph.py:65-98) pins direction rather than mere existence — reverting it fails.
• Deriving called_by as the structural inverse instead of re-reading Symbol.called_by[] is correct: indexer.py:151-156 computes that field from calls[] over the same symbol list, so reading both would double every edge from one fact. The fixture fix in the follow-up commit makes test_graph.py:48 genuinely catch that regression.
• BFS is right: visited seeded with the start node prevents cycles and self-return; hop >= max_hops and the negative-bound ValueError are both mutation-pinned; edges_from uses .get on the defaultdict (graph.py:91) so lookups don't pollute _by_source.
• config:/doc: namespacing is real, tested from both directions, and those nodes are correctly sinks.
• Nothing security-, migration-, or persistence-shaped: a pure in-memory structure over already-indexed data, adding only new isolated files, so no existing caller can break.
• The negative case (STEP 5) is an honest boundary check against creeping into #210's job, and the plan doc's OPEN escalation is the right way to surface finding 2.

Recommendation

Comment. The shipped behaviour is correct and the suite is real — findings 3 and 4 are missing tests around two guarantees #207 asks for by name, both cheap to add and both in the spirit of the test discipline this PR already demonstrates. Findings 1 and 2 must be settled before merge, but neither is a code change: one is a retarget, the other is a maintainer's scope call.

Dropped

• codex's "valid called_by data is silently discarded" — its premise is wrong. The code explicitly documents not re-reading that field (graph.py:62-65), and indexer.py:151 derives called_by from calls[] across the same list, so no edge can be lost for any index #206 actually produces. Only a hypothetical future producer supplying materialized inverses would be affected; not actionable today.
• codex's prescription to key nodes by symbol_id — see finding 6.

[serina-mcfall]

Fix plan for the review panel's findings (not implemented yet)

Verified each finding against this PR's actual code at 2964938f before planning a fix —
mutation-tested findings 3 and 4 (deleting the edge_types filter, and truncating path
accumulation, both leave all 12 tests green), reproduced finding 5 live (two unrelated
symbols sharing an unresolved external call target become falsely reachable from each
other), and read the code/plan doc directly for the rest. All findings hold as stated.

Not a fix — needs a decision first:

• probe: verifying issues are enabled #1 (base branch) — process only; retarget to launchpad once feat(launchpad): ProjectIndexer producing Symbol records for buzz-core #213 merges.
• prd 0 - Deploy the relay to a VPS and verify two people can log in #2 (4-of-8 edge types) — maintainer scope call: narrow task: build a ProjectGraph with typed edges and traversal over ProjectIndexer output #207 with a written note +
  follow-up issue (per adr: fourth upstream-boundary exception for the Hermit lefthook pin (bin/lefthook, bin/.lefthook-*.pkg) #193's lefthook precedent), or accept the narrower reading as-is.

Planned code changes, in implementation order

High — pin invariants #207's DoD names by number:

1. Add a fixture where one node has two outgoing edge types to different unvisited
   targets (e.g. calls to one node, tested_by to another); assert a filtered
   reachable()/edges_from() call reaches only the matching-type target. Closes the gap
   where the edge_types filter can be deleted with no test failing (graph.py:90-94).
2. Extend test_two_hop_chain_matches_the_verified_real_example (and the 1-hop case) to
   assert .path equals the full expected tuple, not just .hop. Closes the gap where
   path accumulation can be truncated to a single element with no test failing
   (graph.py:129).

Medium:
3. Namespace unresolved external call targets (e.g. extern:contains) by checking
membership against the input symbols' own qualified names, so a bare unresolved name
can't become a collision hub across unrelated symbols (graph.py:61-67) — this is the
bug reproduced above. Add a test with two unrelated callers of the same unresolved
name, asserting neither is reachable from the other via ("calls","called_by").
Alternative if you'd rather keep this PR narrower: document the limitation at
graph.py:61-67 and file a follow-up issue instead of fixing it here — your call.
4. Fix the stale Edge.source docstring at graph.py:35 (says "symbol_id or a synthetic
node id"; nodes are actually keyed by qualified_name), and note the known limitation
that two Symbols sharing a qualified_name would silently merge onto one node.

Low:
5. STEP 4's __main__ block: also print is_shared_gated_kind's own called_by[]
alongside the reachable() result, per the plan's own done-when
(launchpad/plans/2026-08-18-issue-207-project-graph.md:43-44).
6. EdgeFieldsTest.test_constructs_at_least_four_distinct_edge_types should assert
source/target/evidence on every edge in the list, not just edges[0]
(test_graph.py:29-32).
7. Drop the f prefix on the three placeholder-free print strings at graph.py:158,166,174
(ruff F541).

Waiting for the go-ahead before implementing any of this.

---

🤖 Plan drafted by Claude Code (claude-sonnet-5) for @serina-mcfall — verification methods
noted per item above; not implemented pending her review.

[serina-mcfall]

Findings 3–7 fixed in ce30f6c

Per go-ahead — findings 1 (base retarget) and 2 (4-of-8 edge-type scope) are
left untouched, as planned; they're decisions, not code.

• prd-01 — upstream intelligence: Buzz keeps the cohort aware of upstream #3 (collision hub): unresolved external call targets (e.g. contains)
  are now namespaced extern:NAME, and the inverse called_by edge is no
  longer added for them — a synthetic external node has no real Symbol behind
  it, so it can't meaningfully "call back". Regression test added
  (test_unresolved_call_targets_do_not_create_a_false_reachability_hub):
  constructs two unrelated symbols calling the same unresolved name, asserts
  neither is reachable from the other via ("calls", "called_by"). Confirmed
  this fails without the fix (that's the live repro I posted in the plan) and
  passes with it.
• prd 02 — the knowledge crate: help in Settings, readable by humans and agents #4 (stale docstring): Edge.source's comment now says qualified_name,
  not symbol_id, and notes the known same-qualified-name-merges-nodes
  limitation.
• # prd-03 — reproducible and hardened Buzz deployment: rebuild the cohort server from a bare Ubuntu host #5 (STEP 4 demo): __main__ now prints is_shared_gated_kind's own
  flat Symbol.called_by[] alongside the reachable() result, per the
  plan's done-when. Verified live against buzz-core.
• handbook A — repo, MkDocs scaffold and Pages publishing #6 (EdgeFieldsTest): now asserts source/target/edge_type/
  evidence on every edge in the list, not just edges[0].
• handbook B — the page contract: frontmatter, claim rule, origin prefixes #7 (ruff F541): dropped the f prefix on the three placeholder-free
  print strings.

python3 -m unittest test_symbol test_indexer test_graph → 22/22 pass (was
21; +1 for the new regression test). Live python3 graph.py buzz-core rerun
and output checked by hand.

---

🤖 Fixes implemented by Claude Code (claude-sonnet-5) for @serina-mcfall, per her go-ahead on findings 3-7 only.

[tucktuck101]

Review: request changes

The graph construction and traversal are correct at head — BFS handles cycles and self-references (visited seeded with the start node), synthetic config:/doc:/extern: nodes can't collide with real qualified names, extern: nodes are pure sinks so the false-reachability hub is gone, and negative max_hops is rejected. The edge-direction convention is coherent across all four types and genuinely pinned by EdgeDirectionTest. Good work, and the review-response discipline on this PR has been excellent.

But three things need to happen before merge:

1. Two High-priority panel findings were dropped in a numbering slip

The fix-plan comment listed the panel's findings 3 (edge_types filter unpinned) and 4 (Reachable.path never asserted) first, as "High — pin invariants #207's DoD names by number". The follow-up commit ce30f6c then said "findings 3–7 fixed" — but its list maps to the panel's 5–9. The two High items were never implemented. Re-verified against head just now, both mutations still pass all 13 tests:

• Replacing the filter in edges_from() (graph.py:112-116) with return list(edges) → suite green. "Filtered by edge type" is the DoD's own words and is currently unprotected, because no fixture node has two outgoing edge types.
• Replacing new_path = path + (edge.target,) (graph.py:151) with new_path = (edge.target,) → suite green. No test reads .path; the STEP 4 demo would print a wrong path with no test failing — exactly the "right node, wrong provenance" bug class EdgeDirectionTest exists to prevent.

Both fixes are the ones already sketched in the fix plan: a fixture with mixed outgoing edge types asserting a filtered traversal reaches only the matching target, and asserting the full expected path tuple in the 1-hop and 2-hop ReachableTest cases.

2. Base branch (known, restating as the merge gate)

Base was task/206-project-indexer. Now that #213 has merged, make sure this retargets to launchpad (GitHub should have retargeted automatically when the head branch was deleted — please verify) so #207 gets its closing link. The existing approval predates the panel review and ce30f6c and itself says "do not merge as-is", so the green APPROVED badge is not clearance.

3. The 4-of-8 edge-type scope call is still open

#207's Objective names eight edge types; EdgeType declares all nine literal strings (graph.py:21-31) while only four can ever be materialized. The author escalated this correctly instead of deciding silently — a maintainer should now either narrow #207 with a written scope note + follow-up issue (per the #193 lefthook precedent) or state that the checkbox DoD governs. Cheap optional cleanup once decided: a comment on EdgeType marking which members are materialized vs. reserved.

Non-blocking observations

• CI is green but hollow for this change: only path-detection, ADR-boundary, and PR-body checks ran; nothing in CI executes the project-intelligence Python suite. Worth a tiny workflow step so these 22 tests run on PRs touching launchpad/project-intelligence/** — otherwise the mutation gaps above can regress invisibly.
• qualified_name-keyed nodes merging same-named symbols is documented (graph.py:35-38) and is the right key given calls[] holds qualified names — fine as a known limitation.
• Performance is appropriate for the stated single-crate scale (O(V+E) build and BFS); the "unverified beyond 453 symbols" caveat in the PR body is honest and acceptable for this task.

Happy to re-review once the two missing tests land and the retarget is confirmed.

The base branch was changed.

[serina-mcfall]

review-final findings fixed — ready for re-review

Fixed the two dropped High findings and documented the scope question, in 5f8b957b9:

1. edges_from()'s edge-type filter, unprotected. Every existing fixture gave a node only one outgoing edge type, so the filter ([e for e in edges if e.edge_type in edge_types]) could be deleted entirely and all 13 tests still passed. Added a mixed-type node and asserted the filtered call excludes the non-matching type. Confirmed by mutation-testing before writing the fix: with the filter removed, the new test fails exactly as expected; with it restored, it passes.

2. Reachable.path, never asserted. Nothing read .path anywhere, so truncating new_path = path + (edge.target,) to just (edge.target,) also passed every test. Asserted the full path tuple in the 1-hop and 2-hop ReachableTest cases. Same mutation-testing confirmation.

3. The 4-vs-8 edge-type scope call. Left EdgeType as all 9 literals (not trimmed), with an inline comment marking which 4 (imports, deployed_by, owns, depends_on) are reserved for the design doc's full graph rather than materialized by this task. #207's own DoD checkbox reads "edge types are explicit and directional as specified" — the materialized set satisfies that without claiming the other 4 are built. This is my recommendation, not a decision — if you'd rather narrow the type and file a follow-up issue instead (the other option review-final offered), that's a one-line change away.

Base branch: confirmed already retargeted to launchpad (not the deleted task/206 branch) via gh pr view --json baseRefName — no action was needed there.

Full test suite: 23/23 pass (python3 -m unittest discover -p "test_*.py" from launchpad/project-intelligence/).

@tucktuck101 — ready for another look when you have a chance.