codegraph-brain 0.9.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.14.0/.github/workflows/ci.yml

@@ -0,0 +1,212 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, dev, "feat/**", "fix/**", "docs/**" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  python-ci:
+    name: Python Verification
+    runs-on: ubuntu-latest
+    # Job level, not step level: a step's own `env` block is not reliably visible
+    # to that same step's `if`, and a condition that silently never fires is a
+    # gate that looks like protection and is not.
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          # Full history: the scanner computes new-code metrics by diffing against
+          # the base branch, and a depth-1 clone makes it log
+          #   WARN Could not find ref 'main' in refs/heads, refs/remotes…
+          # which silently degrades every new_* metric, new_coverage included.
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+
+      - name: Lockfile in step with pyproject
+        # This is the only step that validates the lockfile. `--frozen` below stops
+        # uv rewriting uv.lock, but it does not check that the lock is current —
+        # that is `--locked`. Keeping the check explicit gives a clearer failure
+        # than a sync error, and it still runs first so an unfrozen uv could never
+        # repair the lock ahead of it.
+        run: uv lock --check
+
+      - name: Install Dependencies
+        run: uv sync --frozen --group dev
+
+      - name: Ruff Format Check
+        run: uv run --frozen ruff format --check .
+
+      - name: Ruff Lint
+        run: uv run --frozen ruff check .
+
+      - name: Interrogate (≥90% docstring coverage)
+        run: uv run --frozen interrogate -v --fail-under 90 src/cgis
+
+      - name: Mypy (strict)
+        run: uv run --frozen mypy src
+
+      - name: Pytest
+        # xml alongside term-missing: the console form is for a human reading the
+        # log, the XML is the only form SonarCloud can import.
+        #
+        # `--cov=scripts` because `sonar.sources` below is `src,scripts`: Sonar
+        # counts every executable line in scripts/ as a line to cover whether or
+        # not the report mentions it, so omitting the directory does not exclude
+        # it from the coverage metric — it just reports all of it as uncovered.
+        # That alone put new-code coverage at 37.8% on a PR whose script was
+        # covered at 99% locally.
+        run: >
+          uv run --frozen pytest --cov=cgis --cov=scripts
+          --cov-report=term-missing --cov-report=xml
+
+      - name: Project version for Sonar
+        id: version
+        # Without this every analysis records the version as the literal string
+        # "not provided", which is both a lie in the history and, if the
+        # new-code period is "previous version", a baseline that can never move
+        # again — no VERSION event fires when the string never changes, so the
+        # window grows without bound and the gate quietly becomes a
+        # whole-project gate (#309).
+        #
+        # Validated before use: the value reaches the scanner's args, and a
+        # version string is not somewhere to discover that pyproject can carry
+        # arbitrary text.
+        if: env.SONAR_TOKEN != ''
+        run: |
+          version="$(uv version --short)"
+          case "$version" in
+            "" | *[!0-9A-Za-z.+-]* )
+              echo "Refusing unexpected project version: '$version'" >&2
+              exit 1 ;;
+          esac
+          echo "value=$version" >> "$GITHUB_OUTPUT"
+
+      - name: SonarQube Cloud scan
+        # Inert until SONAR_TOKEN exists, so this can land before the migration.
+        # Coverage cannot be imported by Automatic Analysis at all — see #317 —
+        # so the token must be added only AFTER Automatic Analysis is switched
+        # off in the SonarCloud UI, or the two modes conflict.
+        if: env.SONAR_TOKEN != ''
+        uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f  # v8.2.1
+        with:
+          # Passed as args rather than a committed sonar-project.properties:
+          # SonarCloud treats that file as a signal to disable Automatic
+          # Analysis, which would break the working setup the moment this
+          # merges rather than when the migration is actually performed.
+          # pythonsecurity:S8707 ("an LLM running this with faulty CLI arguments
+          # can escape file system restrictions") fires on any script that takes
+          # a path from argparse and reads or writes it. Every script here does,
+          # by definition — they are developer and CI tools whose arguments come
+          # from this repository's own workflows, not from untrusted input, and
+          # confining them to a root would break ad-hoc runs like
+          # `--out /tmp/scratch.jsonl`. main already carries four unresolved
+          # instances (guardian_bench.py, gen_ideal_graph.py x2, metrics.py) and
+          # has never acted on them; the gate only blocked once a PR made such
+          # lines *new*. This states that de-facto position explicitly.
+          #
+          # 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,
+          # parentOrigin=INSTANCE), and with the project version unset until
+          # #352 it had nothing to anchor to and collapsed to *everything* —
+          # `new_lines` on main read 39257, i.e. the whole codebase was "new".
+          # A gate measuring the whole project is not the gate anyone intended,
+          # and it fails the day one legacy file dips.
+          #
+          # Reference branch says what the gate actually means: do not make this
+          # worse than main. The known consequence, accepted rather than
+          # discovered: on main's own analysis the reference is main, so its new
+          # code is empty and its gate goes quiet. PR analyses are unaffected
+          # either way — SonarCloud always scopes a PR to its diff against the
+          # target branch (#309).
+          #
+          # `.github` is in sources because leaving it out did not mean "no
+          # findings there", it meant "nobody is looking". Automatic Analysis
+          # used to scan it and reported 34 workflow vulnerabilities; the moment
+          # this scanner took over with `src,scripts`, SonarCloud closed all 34
+          # as FIXED. Nothing had been fixed. Silent closure in the one
+          # directory where supply-chain surface actually matters is worse than
+          # a red count (#309).
+          #
+          # The two workflow rules are then exempted — on evidence, not
+          # preference, which is the difference between this and the silent
+          # closure above:
+          #
+          #   S8541 "omitting --no-build can execute setup scripts": the
+          #   remediation is impossible here, verified by running it. This
+          #   project installs itself as an editable distribution, so both
+          #   `uv sync --frozen --no-build` and `uv run --frozen --no-build`
+          #   exit with "Distribution `codegraph-brain==0.10.0 @ editable+.`
+          #   can't be installed because it is marked as `--no-build` but has no
+          #   binary distribution". Every third-party dependency ships a wheel,
+          #   so the only source distribution `uv sync` builds is ours — which
+          #   is not the untrusted code the rule is about. #309 called this
+          #   "mechanical, pattern already established"; the established pattern
+          #   (release-please.yml's `uvx --no-build --from twine==7.0.0`) works
+          #   only because uvx runs a *foreign* tool, and does not transplant.
+          #
+          #   S8544 "dependencies without locked resolved versions": untrue
+          #   here. Every invocation passes --frozen against a committed
+          #   uv.lock, and the "Lockfile in step with pyproject" step above
+          #   fails the build if that lock is stale.
+          #
+          # Residual risk, stated because the glob cannot be narrower: a future
+          # `uvx` invocation would go unchecked by S8541, where it WOULD be both
+          # applicable and fixable. Keep passing --no-build to uvx by hand.
+          args: >
+            -Dsonar.projectKey=zaebee_codegraph-brain
+            -Dsonar.organization=zaebee
+            -Dsonar.projectVersion=${{ steps.version.outputs.value }}
+            -Dsonar.newCode.referenceBranch=main
+            -Dsonar.sources=src,scripts,.github
+            -Dsonar.tests=tests
+            -Dsonar.python.version=3.12
+            -Dsonar.python.coverage.reportPaths=coverage.xml
+            -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
+            -Dsonar.issue.ignore.multicriteria.e3.resourceKey=.github/workflows/*.yml

{codegraph_brain-0.9.0 → codegraph_brain-0.14.0}/.gitignore

@@ -229,3 +229,4 @@ guardian_metrics.jsonl
 # SQLite WAL/SHM sidecars
 *.db-wal
 *.db-shm
+.martian-workspace/

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.9.0 → codegraph_brain-0.14.0}/CHANGELOG.md

@@ -1,5 +1,105 @@
 # 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)
+
+
+### Features
+
+* **collector:** collect TypeScript context via a language registry ([#344](https://github.com/zaebee/codegraph-brain/issues/344)) ([#349](https://github.com/zaebee/codegraph-brain/issues/349)) ([f40f22f](https://github.com/zaebee/codegraph-brain/commit/f40f22fcfae57602fff24ae183bfc8977f246473)), closes [#342](https://github.com/zaebee/codegraph-brain/issues/342)
+* **guardian:** Martian corpus layer, and the profiles are not what the spec said ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#355](https://github.com/zaebee/codegraph-brain/issues/355)) ([16f9640](https://github.com/zaebee/codegraph-brain/commit/16f96408e46bfe9d5544fa10dd4ea9d68b2e8f34))
+* **guardian:** Phase 1 calibration harness — score recorded reviews with Martian's judge ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#346](https://github.com/zaebee/codegraph-brain/issues/346)) ([6d7771a](https://github.com/zaebee/codegraph-brain/commit/6d7771aad9b7bb1bfc7b26a0ed2c9d56b2715466))
+* **guardian:** Phase 2 judge pass, and the first scored PR ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#359](https://github.com/zaebee/codegraph-brain/issues/359)) ([eaf6626](https://github.com/zaebee/codegraph-brain/commit/eaf6626ea473e0c0bd8f2468f4fc989d29a3decf))
+* **guardian:** Phase 2 planner — resolve slices before spending anything ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#356](https://github.com/zaebee/codegraph-brain/issues/356)) ([75a278d](https://github.com/zaebee/codegraph-brain/commit/75a278d5caad07e3865c1fa95ed79c5f63e64640))
+* **guardian:** Phase 2 report — G4/G5/G6, and G5 refuses a vacuous comparison ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#360](https://github.com/zaebee/codegraph-brain/issues/360)) ([14d0fc4](https://github.com/zaebee/codegraph-brain/commit/14d0fc4fb989c1ae0224e3367de30f1b202a701d))
+* **guardian:** Phase 2 review step, and the first paid run ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#358](https://github.com/zaebee/codegraph-brain/issues/358)) ([933c229](https://github.com/zaebee/codegraph-brain/commit/933c2298b1051962c6860a99ea584b8ca6f204e5))
+* **guardian:** Phase 2 workspace — prepare finds the bug that would have sunk G5 ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#357](https://github.com/zaebee/codegraph-brain/issues/357)) ([1ecd962](https://github.com/zaebee/codegraph-brain/commit/1ecd9629f46cab10b907dae285d0f58b0eef5e21))
+
+
+### Bug Fixes
+
+* **guardian:** an ambiguous hit is a false positive ([#345](https://github.com/zaebee/codegraph-brain/issues/345)) ([#348](https://github.com/zaebee/codegraph-brain/issues/348)) ([fa37624](https://github.com/zaebee/codegraph-brain/commit/fa37624721a3a58a8b33cb01af71b7a7cb0bd34c)), closes [#342](https://github.com/zaebee/codegraph-brain/issues/342)
+* **guardian:** give record_review a contract for the path it writes to ([#347](https://github.com/zaebee/codegraph-brain/issues/347)) ([#350](https://github.com/zaebee/codegraph-brain/issues/350)) ([af968b9](https://github.com/zaebee/codegraph-brain/commit/af968b90d931c8152b5c9372d343cec44c8281fe))
+
+
+### Documentation
+
+* **spec:** auto-evolution PoC — unit of selection, fitness, first mutation gate ([#335](https://github.com/zaebee/codegraph-brain/issues/335)) ([#336](https://github.com/zaebee/codegraph-brain/issues/336)) ([b7359a7](https://github.com/zaebee/codegraph-brain/commit/b7359a78b3734ff5f23131b28b6923de6bc37707))
+* **spec:** first live data falsifies two parts of the PoC gate ([#335](https://github.com/zaebee/codegraph-brain/issues/335)) ([#338](https://github.com/zaebee/codegraph-brain/issues/338)) ([a417e89](https://github.com/zaebee/codegraph-brain/commit/a417e8977505abd49ddf7c2642a7eeb5614d578a))
+* **spec:** Guardian vs Martian Code Review Bench — Phase 1 calibration results ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([7ca8434](https://github.com/zaebee/codegraph-brain/commit/7ca8434ff1363ef6c8c8d0cf97541e7e2039e098))
+* **spec:** Phase 2 corpus reconnaissance and the amended G5 ([#342](https://github.com/zaebee/codegraph-brain/issues/342)) ([#354](https://github.com/zaebee/codegraph-brain/issues/354)) ([e63ec24](https://github.com/zaebee/codegraph-brain/commit/e63ec244f61988048a915e9c7564e897ab68d6cf))
+
+## [0.10.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.9.0...codegraph-brain-v0.10.0) (2026-08-01)
+
+
+### Features
+
+* **guardian:** kinship-grouped axis batches behind GUARDIAN_FEATURES=axes_paired ([#334](https://github.com/zaebee/codegraph-brain/issues/334)) ([7951dcb](https://github.com/zaebee/codegraph-brain/commit/7951dcb60a2fff2f232b144af76043a9d06d3eee))
+* **guardian:** per-axis review fan-out behind GUARDIAN_FEATURES=axes ([#333](https://github.com/zaebee/codegraph-brain/issues/333)) ([ada3205](https://github.com/zaebee/codegraph-brain/commit/ada3205e54433356f3a1e9ef4944ed5475ed2d7c)), closes [#331](https://github.com/zaebee/codegraph-brain/issues/331)
+
+
+### Documentation
+
+* **spec:** record the Arm A result — fails its gate, and shows the mechanism ([#330](https://github.com/zaebee/codegraph-brain/issues/330)) ([af8d543](https://github.com/zaebee/codegraph-brain/commit/af8d543fb656af233a961ef081bc8fed5f4331a0))
+
 ## [0.9.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.8.0...codegraph-brain-v0.9.0) (2026-08-01)
 
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.9.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.9.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.9.0 → codegraph_brain-0.14.0}/benchmarks/guardian/CURATION.md

@@ -7,17 +7,166 @@ first review actually ran on; the final `refs/pull/N/head` contains the
 FIXES, so replaying it would make every fixed finding unfindable).
 Spec §3.1 erratum: `head` = review head, not final pull head.
 
+## What `ambiguous` does to the score (decided 2026-08-11, #345)
+
+**An `ambiguous` hit counts as a false positive.** It is recorded apart from
+`noise` — `MatchResult.ambiguous_hits`, `BenchScore.ambiguous_hits` — but that
+separation is curation diagnostics, not a scoring adjustment. Reported
+precision is `TP / (TP + noise + ambiguous_hits)`.
+
+It used to be exempt from the precision denominator. Two findings retired that.
+
+**It stopped the number describing the review.** The exemption was per *file*:
+one entry on `drift.py` exempted every prediction in `drift.py`. On pr-142
+every candidate landed on a file carrying one entry, the denominator emptied,
+and `score()` returned the vacuous `1.0` reserved for "nothing wrong was said".
+Two independent LLM judges scored those same reviews at 0.14 and 0.19. Ten of
+118 recorded reviews reported that vacuous 1.0, across three of the six PRs
+with runs — normal, not exceptional. pr-144 shows the reach: its entries cover
+`drift.py` and `triads.py`, the files carrying 3 of its 5 ground-truth
+findings.
+
+**And the exemption was never argued for.** The rule below routes style nits
+here to keep them from depressing **recall** — but omitting them from
+`findings` already does that, since recall divides by `len(findings)`. Removing
+them from the precision denominator as well came along with the mechanism, and
+it points the wrong way: guardian's precision rules forbid style nits, so
+emitting one *is* a precision failure, and the exemption hid exactly the
+failure those rules exist to catch.
+
+Measured over the same 118 reviews against two judges (#342 Phase 1), the new
+definition is also the one that tracks an independent scorer:
+
+| | old (exempt) | new (strict) |
+|---|---|---|
+| Spearman ρ vs judge, all reviews | +0.72 / +0.71 | **+0.92 / +0.92** |
+| ρ vs judge, non-empty reviews | +0.42 / +0.35 | **+0.76 / +0.72** |
+| mean \|difference from judge\| | 0.25 / 0.26 | **0.10 / 0.10** |
+
+What this costs, stated plainly: a genuinely debatable suggestion — pr-144's
+three declined clip proposals, which gemini raised and then agreed to drop —
+now counts against precision. That is the price of a number an external scorer
+can be compared to, and `ambiguous_hits` keeps the fact visible.
+
+`benchmarks/guardian/results.jsonl` is **not** rescored. Its `precision` was
+correct under the policy in force when each row was written, and every row
+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
-  style nits; penalizing recall for them would measure the wrong thing).
+  style nits; penalizing recall for them would measure the wrong thing —
+  keeping them out of GT `findings` is what achieves that, see above).
 - Review-dialogue resolutions (open questions answered during review) →
   `ambiguous` (not defects present in the diff).
 - Declined-with-reason suggestions → `ambiguous` (per spec §3.1).
 - Refuted claims → omitted from GT entirely, NOT `ambiguous`. A finding
-  disproved by execution (the code cannot behave as claimed) is noise, and
-  `ambiguous` exempts hits per FILE — filing errors there would make the suite
-  structurally unable to observe a precision failure (#279).
+  disproved by execution (the code cannot behave as claimed) is an error, not a
+  judgement call. The original reason was that `ambiguous` exempted hits per
+  file, so filing errors there made the suite structurally unable to observe a
+  precision failure (#279); since #345 removed the exemption the rule no longer
+  protects the score, but it still keeps `ambiguous_hits` meaning what it says —
+  "landed on ground we already marked debatable" — rather than becoming a
+  second name for noise.
 - `lines` required wherever the source provides line provenance (quality
   review I3: rangeless entries are gameable by file-level predictions).
 - Sonar quality-gate findings (cognitive complexity, float equality) stay in