codegraph-brain 0.28.0__tar.gz → 0.29.0__tar.gz

codegraph_brain-0.29.0/.github/test-count-baseline

@@ -0,0 +1 @@
+3095

codegraph_brain-0.29.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.29.0"
+}

{codegraph_brain-0.28.0 → codegraph_brain-0.29.0}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.29.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.28.0...codegraph-brain-v0.29.0) (2026-10-14)
+
+
+### Features
+
+* **bench:** cgis-narrow arm — the cgis arm with three tools listed ([#586](https://github.com/zaebee/codegraph-brain/issues/586)) ([5a5c836](https://github.com/zaebee/codegraph-brain/commit/5a5c836e2fda1f41e6420e0d1160a56a0859ef94))
+* **mcp:** agent-sized cgis_analyze_impact — no test callers, files as dead ends, node budget ([#563](https://github.com/zaebee/codegraph-brain/issues/563)) ([d173d57](https://github.com/zaebee/codegraph-brain/commit/d173d5791e30983b58e7cbe7fb91cac8c7059154))
+* **mcp:** output_format="text" for traversals; trace_flow gets impact's node budget and test screen ([#581](https://github.com/zaebee/codegraph-brain/issues/581)) ([a1dd2b8](https://github.com/zaebee/codegraph-brain/commit/a1dd2b871d34c22e29f25103b9ee349a004ea28a))
+* **mcp:** server instructions in initialize, CGIS_MCP_TOOLS allowlist ([#565](https://github.com/zaebee/codegraph-brain/issues/565)) ([3c37874](https://github.com/zaebee/codegraph-brain/commit/3c37874f78e4a3d439be153641afe1fc19a32f03))
+* **query:** resolve an FQN given with the directories above the graph ([#571](https://github.com/zaebee/codegraph-brain/issues/571)) ([ea43ba9](https://github.com/zaebee/codegraph-brain/commit/ea43ba9f5451e0ee55575570eb8a5341eb906115))
+* **resolver:** DISPATCHES edges from a base-class method to each override ([#575](https://github.com/zaebee/codegraph-brain/issues/575)) ([827143e](https://github.com/zaebee/codegraph-brain/commit/827143ee2a13866602daaea84f1142106c69d49d))
+* **resolver:** type a parameter annotated with an Annotated[T, Depends(...)] alias as T ([#572](https://github.com/zaebee/codegraph-brain/issues/572)) ([fc33b20](https://github.com/zaebee/codegraph-brain/commit/fc33b202b607aecda9d3b317edc1d16f2ba350c6))
+* **workspaces:** read pnpm-workspace.yaml above the ingest root ([#591](https://github.com/zaebee/codegraph-brain/issues/591)) ([b0d67f8](https://github.com/zaebee/codegraph-brain/commit/b0d67f8124da3c414b852f045f6127ab2eec5c3e))
+
+
+### Bug Fixes
+
+* **bench:** agent A/B runner survives a failed session and continues run numbers ([#578](https://github.com/zaebee/codegraph-brain/issues/578)) ([bc303eb](https://github.com/zaebee/codegraph-brain/commit/bc303eb82e3ef25c01093452c2d68e8c3a53d1d9))
+* **bench:** guard — no false refusal on a grep for an import, no bypass through env/newline/prefix ([#590](https://github.com/zaebee/codegraph-brain/issues/590)) ([73ee4e2](https://github.com/zaebee/codegraph-brain/commit/73ee4e260cf3a65a31630f4cc6a46b618872ce7f))
+* **ingest:** read the tsconfig.json and package.json above a sub-directory ingest root ([#560](https://github.com/zaebee/codegraph-brain/issues/560)) ([9722f8c](https://github.com/zaebee/codegraph-brain/commit/9722f8c18da97cba20400cbd109fd8fea684a5e3))
+* **query:** one effective_prefix rule for every FQN-prefix entry point ([#585](https://github.com/zaebee/codegraph-brain/issues/585)) ([b5f10b3](https://github.com/zaebee/codegraph-brain/commit/b5f10b360ab021ba2dcd8dd9a211b222c989e183))
+* **resolver:** TypeScript imports of declared npm packages are EXTERNAL ([#557](https://github.com/zaebee/codegraph-brain/issues/557)) ([73d380a](https://github.com/zaebee/codegraph-brain/commit/73d380acb915671e9597fc01eaf509ba29e78a8b))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#558](https://github.com/zaebee/codegraph-brain/issues/558)) ([ee275a4](https://github.com/zaebee/codegraph-brain/commit/ee275a412b9af8b2d900e16b84335a343f68a7fa))
+* auto-sync architecture graph and MCP reference ([#564](https://github.com/zaebee/codegraph-brain/issues/564)) ([50637b3](https://github.com/zaebee/codegraph-brain/commit/50637b3b8d01cb4be01cbae3710f21a1cb5f1b02))
+* auto-sync architecture graph and MCP reference ([#573](https://github.com/zaebee/codegraph-brain/issues/573)) ([225499d](https://github.com/zaebee/codegraph-brain/commit/225499dd1a17163160e270b9dbeb73a7ad376b7d))
+* **bench:** agent A/B after [#568](https://github.com/zaebee/codegraph-brain/issues/568) and [#550](https://github.com/zaebee/codegraph-brain/issues/550) — cgis-forced at $0.184 against control $0.298 ([#574](https://github.com/zaebee/codegraph-brain/issues/574)) ([8e0ef37](https://github.com/zaebee/codegraph-brain/commit/8e0ef37b76fffc01e32338c67325535f8cb501f4))
+* **bench:** agent A/B on a task no fix was tuned on (occupied_window) ([#576](https://github.com/zaebee/codegraph-brain/issues/576)) ([a6eb679](https://github.com/zaebee/codegraph-brain/commit/a6eb679b51ae7fd3f52c73eb2da005857f2e6126))
+* **bench:** agent A/B on three deep-chain cgis tasks — impact pays, trace_flow's 32k answer does not ([#579](https://github.com/zaebee/codegraph-brain/issues/579)) ([eb7e951](https://github.com/zaebee/codegraph-brain/commit/eb7e9516a8e952fdbd2266c43accfee1a16109e7))
+* **bench:** agent A/B results for owner-impact-credit-wallet after [#563](https://github.com/zaebee/codegraph-brain/issues/563) and [#565](https://github.com/zaebee/codegraph-brain/issues/565) ([#570](https://github.com/zaebee/codegraph-brain/issues/570)) ([ae84feb](https://github.com/zaebee/codegraph-brain/commit/ae84febcc2621a92d00233e81e994171b6b14cd8))
+* **bench:** flow A/B after [#581](https://github.com/zaebee/codegraph-brain/issues/581) — text cut the answer 4x and the cost by a third; precision unchanged ([#583](https://github.com/zaebee/codegraph-brain/issues/583)) ([e36c850](https://github.com/zaebee/codegraph-brain/commit/e36c85099a85300f46a9b6fa28d375fa68f67227))
+* **bench:** unprompted agents do not call cgis — a short menu changes nothing, one instruction line 2 of 6 ([#587](https://github.com/zaebee/codegraph-brain/issues/587)) ([6534f74](https://github.com/zaebee/codegraph-brain/commit/6534f74f23fcd3d1193bda2201bbf598959cac8e))
+
 ## [0.28.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.27.0...codegraph-brain-v0.28.0) (2026-10-02)
 
 

{codegraph_brain-0.28.0 → codegraph_brain-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.28.0
+Version: 0.29.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain

{codegraph_brain-0.28.0 → codegraph_brain-0.29.0}/benchmarks/agent_ab/README.md

@@ -40,9 +40,17 @@ resolver gets wrong. Each task's `notes` say how it was checked.
 |---|---|---|---|---|
 | `control` | none (`--strict-mcp-config`, empty config) | no | all deleted | no |
 | `cgis` | this checkout's `cgis-mcp` | yes (the plugin minus its `.mcp.json`) | `graph.db` built before the clock starts | no |
+| `cgis-narrow` | as `cgis`, listing only `analyze_impact`, `find_symbol`, `trace_flow` (`CGIS_MCP_TOOLS`) | as `cgis` | as `cgis` | no |
 | `cgis-instructed` | as `cgis` | as `cgis` | as `cgis` | one line: query cgis first |
 | `cgis-forced` | as `cgis` | as `cgis` | as `cgis` | as `cgis-instructed`, and the guard refuses Read/Grep/Glob/Bash until one cgis call |
 
+`cgis-narrow` asks whether a short tool menu gets an unprompted agent to call the
+graph (#542). The server instructions and the plugin skill still name all fifteen
+tools, so it measures a short menu with a longer guide beside it. Each results line
+records `cgis_tools`, the number of `mcp__cgis__*` tools the session was offered,
+so an `env` the client ignored would show as 15. With no `--arm` a run now covers
+five arms.
+
 `cgis-instructed` exists because the first pilot's `cgis` arm made no cgis call in
 12 of 12 sessions: with the server connected and the skill loaded, Sonnet still
 went straight to Grep. It stands in for #542's MCP server instructions. It barely moved the agent (2 cgis
@@ -75,8 +83,19 @@ uv run python scripts/agent_ab.py report
 
 `--model` defaults to `claude-sonnet-5-5`; `--max-budget-usd` (default 2.00)
 caps each session. Every non-dry run is a paid session, so this never runs in
-CI. Transcripts are written to `transcripts/` (git-ignored); `results.jsonl`
-gets one line per (task, arm, run) and is meant to be committed with the write-up.
+CI. Transcripts are written to `transcripts/<task>/<arm>-<sha7>-<run>.jsonl`, with
+the first 7 characters of the cgis commit (git-ignored); `results.jsonl` gets one
+line per (task, arm, cgis commit, run) and is meant to be committed with the
+write-up.
+
+Run numbers continue from the highest one already in `--results` for the same
+task, arm and cgis commit, so a second invocation that finishes an interrupted
+batch adds runs instead of reusing them. A session that fails is written as a
+line with `failed` set to the reason, and the batch goes on: an ingest or
+worktree that raises gives a line with no metrics, and a `claude -p` that exits
+non-zero keeps its scored metrics and cost but is marked failed too. `run` exits
+1 at the end if any session failed; `report` counts failed sessions in their own
+column and leaves them out of the medians. A dry run writes nothing.
 
 ## Tasks
 

codegraph_brain-0.29.0/benchmarks/agent_ab/RESULTS.md

@@ -0,0 +1,177 @@
+# Agent A/B results
+
+One section per run, newest first. The raw lines are in `results.jsonl`; the
+transcripts they point at are git-ignored and stay on the machine that ran them.
+
+## 2026-10-14: does one instruction line get the agent to call cgis?
+
+cgis at 5a5c836, `cgis-instructed` — the `cgis` arm plus one appended system-prompt
+line, "query cgis first, then read source only to confirm", the nearest stand-in for
+a line in a project's CLAUDE.md. Same two impact tasks, 3 runs each, about $0.8.
+
+| task | cgis calls per run | cost per run |
+|---|---|---|
+| `cgis-impact-drift-same-name` | 0, 0, **1** | 0.184, 0.148, **0.075** |
+| `cgis-impact-transitive-tsconfig` | **1**, 0, 0 | **0.099**, 0.154, 0.153 |
+
+- **The line moves the agent a little: 2 of 6 sessions called the graph**, against 0
+  of 18 without it. Both made one call, and both were the cheapest runs of the
+  six, at the level of `cgis-forced` (0.085 / 0.091). The other four ignored the
+  line and cost more than plain `cgis` (median 0.150 against 0.126–0.138).
+- So an instruction is a coin toss weighted against the graph; the hook that refuses
+  Read/Grep/Bash until one cgis call (`cgis-forced`) is what delivers the saving
+  reliably. A project wanting the gain needs that hook, not a sentence.
+- One run is marked `contaminated` with no cgis CLI call in it: on a task in this
+  repository every path contains `cgis/`, and the guard's predicate took the agent's
+  own `grep`/`sed` over `src/cgis/...` for one. A harness false positive, kept out of
+  the medians by the report as usual.
+
+## 2026-10-14: does a short tool menu get an unprompted agent to call cgis? (#542 item 3)
+
+cgis at dbf3de9 (the `cgis-narrow` arm of #586), Sonnet 5.5, 3 runs per arm, 0 failed,
+0 contaminated, about $1.6. One probe session confirmed the narrowing reached the
+client: the `init` event listed exactly `mcp__cgis__cgis_analyze_impact`,
+`mcp__cgis__cgis_find_symbol`, `mcp__cgis__cgis_trace_flow`.
+
+| task | arm | cgis calls | recall | precision | median $ |
+|---|---|---|---|---|---|
+| `cgis-impact-drift-same-name` | cgis (15 tools) | 0, 0, 0 | 1.00 | 1.00 | 0.126 |
+| | cgis-narrow (3 tools) | 0, 0, 0 | 1.00 | 1.00 | 0.125 |
+| `cgis-impact-transitive-tsconfig` | cgis | 0, 0, 0 | 1.00 | 1.00 | 0.138 |
+| | cgis-narrow | 0, 0, 0 | 1.00 | 1.00 | 0.154 |
+
+- **Refuted.** Three tools instead of fifteen changed nothing: no unprompted
+  session called the graph, here or in any of the six `cgis` sessions before it —
+  0 of 18 today, across four tasks. The server instructions (#542 item 1) did not
+  move it either. Item 3's smaller default set has no evidence behind it.
+- These are the two tasks where `cgis-forced` was about 30% cheaper than control
+  (#579), so the graph would have paid; the agent never looked.
+- A likely reason sits in the client: Claude Code defers MCP tools, listing names
+  only, so a first call needs a ToolSearch to load the schema — every forced
+  session made one. An agent holding Grep and Bash, with a task grep finishes in
+  7–13 calls, does not take that step unasked.
+- Confound, as the README notes: the instructions and the plugin skill still name
+  all fifteen tools beside the three offered.
+
+## 2026-10-14: `cgis-flow-ingest-to-sqlite` after #581 (text format, trace budget)
+
+cgis at a1dd2b8, Sonnet 5.5, 3 runs per arm, 0 failed, 0 contaminated, about $0.6.
+
+| arm | recall | precision | median $ | trace answer |
+|---|---|---|---|---|
+| control | 1.00 | 0.94 | **0.101** | — |
+| cgis-forced, before (#579) | 1.00 | 0.52 | 0.167 | 32,637 chars of json |
+| cgis-forced, now | 1.00 | 0.58 | 0.112 | 6.3–8.9k chars of text |
+
+- **Size: fixed.** All three sessions asked for `output_format="text"` on their
+  own (the server instructions now say to), and the answer shrank about 4×.
+  Cost fell by a third, to 11% above control.
+- **Precision: not fixed.** Given every node the root reaches, the agent still
+  lists most of them (17–21 outside the key: `_compute_hash`,
+  `_is_noop_incremental`, `ResolverEngine` helpers). Control reads the code and
+  names the spine. The format no longer costs the agent; deciding which
+  branches are the main path is the part the graph does not do.
+- Two sessions first called `cgis_find_symbol(query="ingest", fqn_prefix="src.cgis")`
+  and got nothing: #568 taught `resolve_fqn` to drop a directory above the
+  graph, but `find_symbol`'s `fqn_prefix` filter was not given the same rule.
+
+## 2026-10-14: three cgis tasks with a deep chain
+
+cgis at bc303eb, Sonnet 5.5, 3 runs per arm, 0 failed, 0 contaminated, about $2.3.
+None of these tasks was used to find the recent fixes.
+
+| task | arm | recall | precision | median $ | median tool calls | cgis calls |
+|---|---|---|---|---|---|---|
+| `cgis-impact-drift-same-name` | control | 1.00 | 1.00 | 0.124 | 9 | — |
+| | cgis-forced | 1.00 | 1.00 | **0.085** | 3 | 1, 1, 1 |
+| `cgis-impact-transitive-tsconfig` | control | 1.00 | 1.00 | 0.126 | 7 | — |
+| | cgis-forced | 1.00 | 1.00 | **0.091** | 4 | 1, 2, 1 |
+| `cgis-flow-ingest-to-sqlite` | control | 1.00 | 0.86 | **0.112** | 5 | — |
+| | cgis-forced | 1.00 | 0.52 | 0.167 | 4 | 2, 2, 2 |
+
+- **Impact across several hops pays:** about 30% cheaper on both impact tasks,
+  with one cgis call doing what took control 7–9 greps and reads. Together with
+  `credit_wallet`, that makes three impact tasks out of three where the graph
+  wins once the question needs more than one hop.
+- **Flow does not, and the cause is the answer's size.** Every forced session
+  called `cgis_trace_flow(cgis.cli.ingest, depth=3, json)` and got **32,637
+  characters**, the bloat #551 fixed for impact only: trace has no node budget
+  and no test filter. Given everything downstream, the agent cannot tell the
+  main path from side branches and names them all (precision 0.52, 20 extra
+  symbols such as every `ResolverEngine._resolved_*_edge`).
+- `occupied_window` (above) and these together say where cgis earns its place:
+  multi-hop impact. A one-hop caller list and a "main path" flow question are
+  not where it helps today.
+
+## 2026-10-14: `owner-impact-occupied-window-same-name`, a task no fix was tuned on
+
+cgis at 827143e (after #551, #568, #550, #545), Sonnet 5.5, 0 contaminated. The
+three fixes before this were all found in `credit_wallet` transcripts and measured
+there; this task checks whether the gain carries to a question they never saw.
+
+| arm | runs | recall | precision | median $ | median tool calls | cgis calls per run |
+|---|---|---|---|---|---|---|
+| control | 3 | 1.00 | 1.00 | **0.130** | 2 | — |
+| cgis | 3 | 1.00 | 1.00 | 0.145 | 4 | 0, 0, 0 |
+| cgis-forced | 2 | 1.00 | 1.00 | 0.135 | 3.5 | 2, 1 |
+
+- **It does not carry.** On "list the direct callers", with a same-named
+  function in another module as the trap, control answered with one grep and
+  one look at the imports, and was the cheapest arm. The graph names the four
+  callers exactly (`impact depth=1`, 2.5k characters), but there is nothing
+  for it to save on a one-hop question that grep plus the imports already
+  answer.
+- The `credit_wallet` gain came from a deep transitive chain through DI. That
+  is where the graph pays, so the question for #542's default tool set is
+  which kinds of question agents ask, not whether cgis is cheaper in general.
+- `cgis` made no graph call again: 0 in 6 sessions across the two tasks.
+- `cgis-forced` has 2 runs, not 3. The host ran out of memory, and earlyoom
+  sent SIGTERM to the third session's `cgis ingest`, which aborted the runner
+  twice. Not a cgis failure. The runner stops at the first failed ingest
+  instead of recording it and going on.
+
+## 2026-10-14: `owner-impact-credit-wallet`, after #568 and #550
+
+cgis at fc33b20, Sonnet 5.5, 3 runs per arm, 0 contaminated, about $1.5 in total.
+`cgis` was not re-run: it made no cgis call on this task in the run below.
+
+| arm | recall | precision | median $ | median tool calls | cgis calls per run |
+|---|---|---|---|---|---|
+| control | 1.00 | 1.00 | 0.298 | 7 | — |
+| cgis-forced | 1.00 | 1.00 | **0.184** | 5 | 2, 5, 1 |
+
+- `cgis-forced` went from $0.235 to $0.184 median and is now about 38% cheaper
+  than control. Control was unchanged ($0.30 to $0.298).
+- **#568.** Two of the three sessions opened with
+  `app.domains.finance.service.credit_wallet` again, and this time it resolved:
+  the first answer was the full chain (6,746 characters), with no not-found
+  first. The third tried the bare `credit_wallet`, which is still ambiguous.
+- **#550.** That first answer now includes both routes, `get_top_up` and
+  `stripe_webhook`. One session finished on a single cgis call. The greps that
+  remain are the agent confirming that `FinanceService.top_up` and the worker
+  tasks have no further callers, not looking for missing ones.
+
+## 2026-10-13: `owner-impact-credit-wallet`, after #563 and #565
+
+cgis at 3c37874, Sonnet 5.5, 3 runs per arm, 0 contaminated, about $2.5 in total.
+
+| arm | recall | precision | median $ | median tool calls | cgis calls per run |
+|---|---|---|---|---|---|
+| control | 1.00 | 1.00 | 0.30 | 7 | — |
+| cgis | 1.00 | 1.00 | 0.30 | 6 | 0, 0, 0 |
+| cgis-forced | 1.00 | 1.00 | 0.235 | 8 | 3, 11, 3 |
+
+- **#551.** The call that returned 51,624 characters in the first pilot,
+  `cgis_analyze_impact(domains.finance.service.credit_wallet, depth=8, json)`,
+  returned 6,136 here. `cgis-forced` went from more expensive than control
+  ($0.207 vs $0.195) to cheaper. Control ranged from $0.198 to $0.327 across
+  three runs, so this shows the direction, not the size.
+- **#542.** The `cgis` arm now gets server instructions in `initialize`, and its
+  server reported `connected` every time. It still made no cgis call: the task
+  is solvable by grep in about seven calls, and the agent took that route.
+- **#568.** Every forced session's first call was
+  `app.domains.finance.service.credit_wallet`, built from the file path, which
+  is not found because the graph is ingested from `ownima-backend/app`. That
+  cost one or two calls per session before the agent found the real FQN.
+- Every arm recovered the two routes the graph misses at this sha
+  (`get_top_up`, `stripe_webhook`) by grepping for them.