codegraph-brain 0.11.0__tar.gz → 0.14.0__tar.gz

codegraph_brain-0.14.0/.gitattributes

@@ -0,0 +1,6 @@
+# The review fingerprint (#375) hashes file bytes, so a checkout that stores
+# CRLF would produce a different digest for identical code — and the measured
+# digest would disagree with the reconstructed one on the same commit. Pinned
+# rather than normalised at hash time, because a normaliser can only fail by
+# merging two reviewers that differ.
+*.py text eol=lf

{codegraph_brain-0.11.0 → codegraph_brain-0.14.0}/.github/workflows/ci.yml

@@ -115,6 +115,34 @@ jobs:
           # Deliberately scoped to scripts/. src/ keeps the rule — metrics.py:70
           # is library code and its instance deserves a real answer (#342).
           #
+          # pythonsecurity:S2083 ("do not construct the path from user-controlled
+          # data") is exempted for scripts/ too, but for a DIFFERENT reason than
+          # S8707 above, and the difference matters. S8707's argument is that
+          # confining these tools to a root would break legitimate ad-hoc runs.
+          # S2083 was raised against backfill_review_fingerprint.py, which does
+          # the opposite: `safe_corpus_path` resolves the argument, requires a
+          # .jsonl regular file, confines it under the repository root, raises
+          # otherwise, and returns the resolved path that `backfill()` then uses
+          # for every read and write — the original argument never reaches the
+          # filesystem again (#375).
+          #
+          # The finding survived that. It was reported first at the read, then at
+          # the write, unchanged by binding the check to the value used, because
+          # SonarCloud's Python taint engine does not model `Path.resolve()` plus
+          # `is_relative_to()` as a sanitiser. The remaining report is an engine
+          # limitation, not an unvalidated path. Verified rather than assumed:
+          # main carries no open S2083, and the one S8707 left in src/ is marked
+          # FALSE-POSITIVE by a human, so neither rule has a working precedent
+          # here to copy blindly.
+          #
+          # The alternative considered and rejected was taking a bare filename
+          # and building the path from a fixed base, which the engine would
+          # accept. It makes traversal inexpressible, but it changes a documented
+          # CLI to satisfy an analyser rather than to close a hole that is
+          # already closed. If a script ever takes a path it does NOT validate,
+          # this exemption hides it — that is the cost, and it is the reason the
+          # rule stays on for src/.
+          #
           # `sonar.newCode.referenceBranch` overrides the server-side new-code
           # definition for this analysis. The instance default is
           # `previous_version` (confirmed: sonar.leak.period=previous_version,
@@ -173,9 +201,11 @@ jobs:
             -Dsonar.tests=tests
             -Dsonar.python.version=3.12
             -Dsonar.python.coverage.reportPaths=coverage.xml
-            -Dsonar.issue.ignore.multicriteria=e1,e2,e3
+            -Dsonar.issue.ignore.multicriteria=e1,e2,e3,e4
             -Dsonar.issue.ignore.multicriteria.e1.ruleKey=pythonsecurity:S8707
             -Dsonar.issue.ignore.multicriteria.e1.resourceKey=scripts/**/*.py
+            -Dsonar.issue.ignore.multicriteria.e4.ruleKey=pythonsecurity:S2083
+            -Dsonar.issue.ignore.multicriteria.e4.resourceKey=scripts/**/*.py
             -Dsonar.issue.ignore.multicriteria.e2.ruleKey=githubactions:S8541
             -Dsonar.issue.ignore.multicriteria.e2.resourceKey=.github/workflows/*.yml
             -Dsonar.issue.ignore.multicriteria.e3.ruleKey=githubactions:S8544

codegraph_brain-0.14.0/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  - repo: local
+    hooks:
+      # SonarCloud's python:S5778, enforced before the push rather than after it.
+      # Sonar only decorates a pull request, so the loop was write -> push ->
+      # get told -> fix -> forget, five times over. `pass_filenames: false`
+      # because the check is a repo-wide ratchet (a stale baseline entry is a
+      # failure too), which a staged-files-only view cannot see.
+      #
+      # This hook is the fast half, not the gate: CI does not run pre-commit,
+      # so `tests/unit/test_check_pytest_raises.py` is what actually blocks a
+      # merge. Both call the same `check()`.
+      - id: pytest-raises-single-call
+        name: one throwing call per pytest.raises block (S5778)
+        entry: python scripts/check_pytest_raises.py
+        language: system
+        pass_filenames: false
+        files: ^tests/.*\.py$
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        args: [--config-file=pyproject.toml]
+        files: ^src/
+        additional_dependencies:
+          - httpx>=0.27  # imported directly by guardian/providers/base.py (#275)
+          - pydantic>=2.13.4
+          - structlog>=25.5.0
+          - types-pyyaml>=6.0.12.20260518
+          - rich>=15.0.0
+          - typer>=0.26.7
+          - tree-sitter>=0.25.2
+          - tree-sitter-python>=0.25.0
+          - tree-sitter-typescript>=0.23.2
+          - pytest>=9.0.3
+          - "mcp[cli]>=2"  # must match the pyproject bound
+          - duckdb>=1.1.0

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

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

{codegraph_brain-0.11.0 → codegraph_brain-0.14.0}/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [0.14.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.13.0...codegraph-brain-v0.14.0) (2026-08-16)
+
+
+### Features
+
+* **guardian:** give measured recall a reviewer it can name ([#390](https://github.com/zaebee/codegraph-brain/issues/390)) ([#391](https://github.com/zaebee/codegraph-brain/issues/391)) ([acc1887](https://github.com/zaebee/codegraph-brain/commit/acc18874b7ce67fa38b7dab41552838f9578516d))
+* **guardian:** say whether a temperature was chosen or inherited ([#393](https://github.com/zaebee/codegraph-brain/issues/393)) ([#395](https://github.com/zaebee/codegraph-brain/issues/395)) ([1b2c3c3](https://github.com/zaebee/codegraph-brain/commit/1b2c3c3f1619f00d20c36fb315eaca3dce5661d9))
+
+
+### Bug Fixes
+
+* **guardian:** close the deferred cleanups that could only narrow silently ([#385](https://github.com/zaebee/codegraph-brain/issues/385)) ([#386](https://github.com/zaebee/codegraph-brain/issues/386)) ([e7020ff](https://github.com/zaebee/codegraph-brain/commit/e7020ff237964a66728f0b437f13b70dc8bfe2f9))
+* **guardian:** refuse a model name carrying whitespace ([#382](https://github.com/zaebee/codegraph-brain/issues/382)) ([#389](https://github.com/zaebee/codegraph-brain/issues/389)) ([45fb110](https://github.com/zaebee/codegraph-brain/commit/45fb110d3e440e858f57c28cd3e343e61218697c))
+
+
+### Documentation
+
+* **bench:** a failed parse is not a draw ([#394](https://github.com/zaebee/codegraph-brain/issues/394)) ([a70b09b](https://github.com/zaebee/codegraph-brain/commit/a70b09bf1faf67ddefff2d7fdcf555aba51ced9f))
+* **bench:** repeated rows are samples, not corrections ([#392](https://github.com/zaebee/codegraph-brain/issues/392)) ([e1fcc3f](https://github.com/zaebee/codegraph-brain/commit/e1fcc3f4728e61363d06b022b14bc66f45f3a031))
+
+## [0.13.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.12.0...codegraph-brain-v0.13.0) (2026-08-15)
+
+
+### Features
+
+* **guardian:** an identity for a reviewer, that a commit does not fragment ([#375](https://github.com/zaebee/codegraph-brain/issues/375)) ([#383](https://github.com/zaebee/codegraph-brain/issues/383)) ([e339a38](https://github.com/zaebee/codegraph-brain/commit/e339a38743ddfdaac1e7c8f0724281844d5a8b38))
+
+## [0.12.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.11.0...codegraph-brain-v0.12.0) (2026-08-13)
+
+
+### Features
+
+* **guardian:** an ablation arm, because G5 cannot separate graph from language ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#366](https://github.com/zaebee/codegraph-brain/issues/366)) ([e2374a7](https://github.com/zaebee/codegraph-brain/commit/e2374a72016413414241e71d3cc37a7ce251c590))
+* **guardian:** bound the local finder's output, because it does not stop ([#246](https://github.com/zaebee/codegraph-brain/issues/246)) ([#381](https://github.com/zaebee/codegraph-brain/issues/381)) ([1e0b5e1](https://github.com/zaebee/codegraph-brain/commit/1e0b5e13332c697102a22838f90fed265c0fec67))
+* **guardian:** expose judge concurrency, because Mistral needs it at 1 ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#364](https://github.com/zaebee/codegraph-brain/issues/364)) ([47392e8](https://github.com/zaebee/codegraph-brain/commit/47392e829e8653e6d145533a637342e8a46b4982))
+* **guardian:** keep the valid prefix of a truncated finder response ([#248](https://github.com/zaebee/codegraph-brain/issues/248)) ([#377](https://github.com/zaebee/codegraph-brain/issues/377)) ([d34f01f](https://github.com/zaebee/codegraph-brain/commit/d34f01fa11208c0f8202579edc7e07dccb163ad4))
+* **guardian:** record what the judge spent, per row ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#378](https://github.com/zaebee/codegraph-brain/issues/378)) ([c4eea31](https://github.com/zaebee/codegraph-brain/commit/c4eea31b12492d90dafb92b3afacfbe9a942bab5))
+* **guardian:** refuse a review of a truncated prompt, and supply the missing visitor ([#248](https://github.com/zaebee/codegraph-brain/issues/248)) ([#371](https://github.com/zaebee/codegraph-brain/issues/371)) ([5f3e9b7](https://github.com/zaebee/codegraph-brain/commit/5f3e9b73bcc36aabe64d634e4aa95ea0f5bd7fb7))
+* **guardian:** review --slice, so the registered population is a command ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#373](https://github.com/zaebee/codegraph-brain/issues/373)) ([4d1fe6a](https://github.com/zaebee/codegraph-brain/commit/4d1fe6a8073641cdd46a9d9af24a3c31abd70764))
+* **guardian:** sampling reaches Ollama, instead of the chat template deciding ([#246](https://github.com/zaebee/codegraph-brain/issues/246)) ([#380](https://github.com/zaebee/codegraph-brain/issues/380)) ([14cb966](https://github.com/zaebee/codegraph-brain/commit/14cb9664f200aa9507f1f364f72dfb0de0981259))
+* **guardian:** send the registered temperature, and survive a 429 ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#372](https://github.com/zaebee/codegraph-brain/issues/372)) ([3d7efd8](https://github.com/zaebee/codegraph-brain/commit/3d7efd82efe750283a43eb0d5cb7941f7f67ddd1))
+* **guardian:** the union arm scores offline, and a unit bug made G8 unfailable ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#370](https://github.com/zaebee/codegraph-brain/issues/370)) ([dd290fe](https://github.com/zaebee/codegraph-brain/commit/dd290fef986ad0dcf0b62da9fa2824e0ace1b90d))
+
+
+### Bug Fixes
+
+* **guardian:** a dead judge is not a reviewer that found nothing ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#376](https://github.com/zaebee/codegraph-brain/issues/376)) ([2772c30](https://github.com/zaebee/codegraph-brain/commit/2772c305e9d7ca70c31bdfc2b12297392768330c))
+* **guardian:** a truncated review is not a review that found nothing ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#374](https://github.com/zaebee/codegraph-brain/issues/374)) ([9f86bb6](https://github.com/zaebee/codegraph-brain/commit/9f86bb63e297e2b8bdda6bf6214e5d1e1bbd9339))
+* **guardian:** the ablation must skip PRs with no graph to remove ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#367](https://github.com/zaebee/codegraph-brain/issues/367)) ([f9c36f5](https://github.com/zaebee/codegraph-brain/commit/f9c36f5cae503d83002ad03957eb7bf0cf31d263))
+
+
+### Documentation
+
+* **guardian:** bench a local model in a notebook, and retire a wrong lever ([#246](https://github.com/zaebee/codegraph-brain/issues/246)) ([#379](https://github.com/zaebee/codegraph-brain/issues/379)) ([419fcc1](https://github.com/zaebee/codegraph-brain/commit/419fcc1eb28fddd9a2c0cef814480d861e6d8c88))
+* **spec:** Phase 2 results — G5 fails at +9.5 pp against a 10 pp gate ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#362](https://github.com/zaebee/codegraph-brain/issues/362)) ([9481a54](https://github.com/zaebee/codegraph-brain/commit/9481a54c02b60786e14e6317d3a71c8a4cee12a0))
+* **spec:** Phase 3 registers the union arm, and the pilot says it is marginal ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#369](https://github.com/zaebee/codegraph-brain/issues/369)) ([bc9caf4](https://github.com/zaebee/codegraph-brain/commit/bc9caf43c16a2ce27a0075b14eb0766569ae8c2d))
+* **spec:** R5 — the noise floor equals the effect, so Phase 2 cannot answer its question ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#368](https://github.com/zaebee/codegraph-brain/issues/368)) ([8540bf1](https://github.com/zaebee/codegraph-brain/commit/8540bf1178a8535849bdd2fadfa5473f42040eb8))
+* **spec:** second judge — G5 fails under both, and the row becomes publishable ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#365](https://github.com/zaebee/codegraph-brain/issues/365)) ([62c49e4](https://github.com/zaebee/codegraph-brain/commit/62c49e4b36c0950df0c10cce26c09418674130eb))
+
 ## [0.11.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.10.0...codegraph-brain-v0.11.0) (2026-08-12)
 
 

{codegraph_brain-0.11.0 → codegraph_brain-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.11.0
+Version: 0.14.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
@@ -169,6 +169,8 @@ GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
   uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
 ```
 
+No GPU on hand? **[Benchmark it on a notebook GPU →](docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.
+
 ---
 
 ## 📈 Proof at Real Scale

{codegraph_brain-0.11.0 → codegraph_brain-0.14.0}/README.md

@@ -119,6 +119,8 @@ GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
   uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
 ```
 
+No GPU on hand? **[Benchmark it on a notebook GPU →](docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.
+
 ---
 
 ## 📈 Proof at Real Scale

{codegraph_brain-0.11.0 → codegraph_brain-0.14.0}/benchmarks/guardian/CURATION.md

@@ -54,6 +54,103 @@ carries `matched`, `noise` and `ambiguous_hits`, so either definition can be
 re-derived from it. (Contrast `calibration.jsonl`, which *was* rewritten — that
 was a scorer bug, wrong under its own stated algorithm, not a policy change.)
 
+## Repeated rows are samples, not corrections (2026-08-16, #390)
+
+**Do not deduplicate any corpus in this repository by "one row per subject,
+latest wins."** Every repeat here was paid for on purpose, and collapsing to the
+newest draw silently discards the experiment it belongs to.
+
+Written down because a downstream consumer adopted exactly that rule — reasoning
+that a re-run is a correction, so counting both would let a reviewer improve its
+record by re-running — and nothing in this repository contradicted it. The
+reasoning is sound for a corpus of corrections. It is wrong for these.
+
+### `benchmarks/martian-*.jsonl` — 115 review rows, 83 distinct subjects
+
+Keyed by subject and genome (`url`, `head_sha`, `review_fingerprint`,
+`finder_model`, `had_graph`), 32 of 115 rows are repeats. Every one of them
+comes from a registered sampling arm:
+
+| repeat group | count | source |
+|---|---|---|
+| `p3-run1` + `p3-run2` | 12 | Phase 3 union arm |
+| `p3-run1` + `p3-run2` + `p3-run3` | 7 | Phase 3 union arm |
+| `reviews` + `repeat-reviews` | 6 | R5 repeat probe |
+
+Phase 3 registered three runs at `temperature = 0.7` **because the runs must
+differ** — see the spec, "Configuration under test": at temperature 0 "the three
+runs collapse toward one and the union arm becomes identically equal to a single
+run." Gate G8 is defined as `F₂(union) > F₂(mean of the 3 runs)`; a mean over
+three draws is not computable from one of them.
+
+The variance is not theoretical. **21 of the 25 repeat groups disagree on how
+many findings the review produced**, with spreads including 8→14, 15→24, 26→38
+and one 0→25 — the same reviewer, the same commit, the same configuration. Keep
+one draw and the number you publish is a coin flip over that range.
+
+### `benchmarks/guardian/results.jsonl` — 118 scored rows, 53 distinct
+
+Repeats here carry an explicit `run` index (0/1/2) for the same reason. A row is
+identified by `pr` + `model` + `guardian_sha` + `run`, and dropping `run` averages
+away the per-PR sampling noise that R5 was written to measure.
+
+### `benchmarks/guardian/calibration.jsonl` — 236 rows, 118 subjects
+
+Exactly two rows per recorded review, one per judge (`gemini-2.5-flash` and
+`mistral-medium-latest`). The pair *is* the measurement — inter-judge agreement
+is the G3 statistic — so `row_key` alone is not a unique key here; `row_key` +
+`judge_model` is.
+
+### If you do need one row per reviewer
+
+Aggregate over the draws (mean, or union where the arm defines one); do not
+select among them. Selecting by recency is the one choice guaranteed to be
+uncorrelated with quality, and it deletes 28% of this corpus.
+
+**Aggregate over the subject's *draws*, which is not the same set as its rows.**
+Say what a draw is rather than which rows to exclude: an exclusion list is
+open-ended and the next entry arrives after it has already been believed, while
+a positive definition is closed.
+
+**A draw is a review that completed and whose output was parsed** — a row with
+`parse_failed: false`. That is the whole test; `error` is `None` on all 115 rows,
+because a run that failed outright never reached a record.
+
+**A `parse_failed` row is not a draw.** Its structured output could not be read,
+so it carries zero findings, and averaging it in charges the model for a harness
+failure. This is exactly the distinction #374 established ("a truncated review is
+not a review that found nothing"); before it, `parse_failed` was recorded and
+read by nothing.
+
+**A row with zero findings and `parse_failed: false` *is* a draw.** Three exist
+(PRs 6, 77754 and 107534, all gemini), and each spent real tokens — 106, 117 and
+124 completion tokens. The reviewer ran and said nothing, which is evidence about
+the reviewer. Same output shape as the parse failure, opposite meaning; keeping
+them and dropping the parse failure is the one combination that is right about
+both. The `arm` field exists for the mirror of this hazard: a failure and a
+controlled removal must not look alike in the record.
+
+There is exactly **one** parse-failed row in the review corpora:
+`martian-p3-run1.jsonl` for PR 11059 — the same row #374 was written about. One
+row out of 115 sounds ignorable and is not, because of how the averaging works:
+
+- PR 11059 has three rows. Dropping the parse-failed one leaves draws of `9/13`
+  and `8/8`, so the subject contributes mean `c = 8.5` over mean `n = 10.5` —
+  a rate of **81.0%**, which is *below* mistral/graph's pooled 86.6%.
+- Averaging the parse failure in as a third draw keeps that 81.0% but shrinks the
+  subject to `c = 5.667` over `n = 7.0`. Its **weight** falls, not its rate.
+- A below-average subject carrying less weight pulls the pooled figure **up**:
+  86.6% → **86.9%**.
+
+So including the harness failure makes the reviewer look better, which is the
+direction that makes this easy to leave in. That is how the gap was found — a
+downstream consumer computed 86.6%, this repository computed 86.9%, and the
+disagreement had exactly one cause.
+
+The same applies to the `error` rows in `results.jsonl`, for the same reason and
+by the same rule: they are already excluded there because `is_scored` requires
+`matched` and `precision`, which a failed run never gets.
+
 ## Curation policy
 
 - Style/idiom-only findings → `ambiguous` (guardian's PRECISION RULES forbid