codegraph-brain 0.9.0__tar.gz → 0.10.0__tar.gz

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

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

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [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.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.9.0
+Version: 0.10.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.9.0 → codegraph_brain-0.10.0}/docs/specs/2026-07-31-finder-bug-class-taxonomy.md

@@ -243,3 +243,214 @@ say so explicitly rather than reporting the combined delta.
 Unchanged from above, plus: do not run Arm B before Arm A has a number. The
 float few-shot regression happened because two effects were entangled in one
 measurement.
+
+---
+
+# Arm A result — 2026-08-01: fails its gate, and shows why
+
+Run with the prod pairing (finder `mistral-medium-latest`, skeptic
+`gemini-2.5-flash`), one run per fixture over all eight, baseline and treatment
+sweeps back to back.
+
+**Treatment:** each of five focus areas gained one clause naming what makes an
+instance *not* a finding — a guard that dominates the use, an existing tolerance
+compare, a test that already reaches the path, `Any` as the honest type of
+parsed data. No per-class few-shot, per #247.
+
+## The gate says no
+
+| PR | noise | matched |
+|---|---|---|
+| 122 | 11 → **19** | 4 → 4 |
+| 140 | 20 → 13 | 6 → **5** |
+| 141 | 7 → **8** | 0 → 0 |
+| 142 | 0 → 0 | 0 → 0 |
+| 143 | 6 → **14** | 4 → **3** |
+| 144 | 6 → 2 | 2 → 2 |
+| 278 | 7 → 7 | 1 → 1 |
+| **313** | 6 → 4 | **0 → 2** |
+
+```
+1. mean noise -25%          FAIL   7.88 -> 8.38  (+6%, wrong direction)
+2. matched drops nowhere    FAIL   pr-140, pr-143
+3. pr-141 does not regress  FAIL   7 -> 8
+```
+
+Three of three. The clauses do not ship.
+
+## The finding inside the failure
+
+**pr-313 went from recall 0.000 to 1.000** — the finder surfaced both ground-truth
+entries it had previously missed entirely. Precisely: one is categorised
+`security` (`dangling-symlink-write-primitive`) and one `logic`
+(`oserror-escapes-the-tool`), so this is one security-class hit plus one logic
+hit, not two security hits. That is the fixture added in #315 because the finder
+was blind to the class.
+
+And the total is unchanged: **matched 17 → 17**. Two lost on pr-140/143, two
+gained on pr-313. Attention moved; precision did not improve.
+
+That is the same mechanism that killed the float few-shot experiment: the model
+reallocates focus rather than applying an extra criterion. It is worth stating
+plainly because the naive reading of "noise went up, recall moved around" is
+"the change did nothing", and that is not what happened — it did something
+specific and undesired.
+
+## What this implies for Arm B
+
+It strengthens the case for testing Arm B rather than weakening it. If a clause
+that merely *mentions* guards can pull the finder onto a class it was blind to,
+an explicit named class is a more direct instrument for the same effect — and
+Arm B's gate is written around exactly that (pr-278 or pr-313 matched at least
+once in three runs).
+
+It also confirms the sequencing rule already in this document: these two effects
+must not be measured together. Had both shipped at once, the pr-313 gain and the
+pr-140/143 loss would have arrived as one number.
+
+## Honest limits
+
+- **n=1 per arm.** Finder variance on an unchanged diff has been measured at
+  6 → 46 → 36 findings. Criteria 2 and 3 turn on single-finding deltas and are
+  fragile at this sample size. Criterion 1 is the sturdier signal: noise moved
+  the wrong way, by +6% across eight fixtures.
+- Cost: ~1.1M tokens for the two sweeps.
+
+## Why the raw rows are not in results.jsonl
+
+Both arms carry the same `guardian_sha` — the treatment was a working-tree edit,
+never committed — so the rows would be indistinguishable once merged into the
+corpus. The aggregate above is the record. Anyone repeating this should either
+commit the prompt variant behind a flag first, or add an arm label to the
+metrics row.
+
+**Methodology note for whoever repeats this:** the first attempt was ruined by
+launching the sweep twice against one results file, after an empty (buffered)
+log was misread as a dead process. Check for a running bench by process name,
+not by looking at its log.
+
+`pgrep -f guardian_bench.py` is **not** enough — measured with the bench fully
+stopped it still returns 2, because the shell wrapper running the check carries
+the pattern in its own command line. pgrep excludes its own pid, not its
+parent's. Match on the process name instead:
+
+```sh
+ps -eo comm,cmd | awk '$1 ~ /^python/ && /guardian_bench\.py/' | wc -l
+```
+
+Returns 0 when nothing is running. A false positive here is not harmless: it
+fires the pre-launch guard and silently skips the sweep.
+
+---
+
+# Per-axis fan-out (#331) — measured 2026-08-01: the hypothesis holds, the cost does not
+
+Seven finder calls per PR, one per focus area, each seeing the whole diff.
+Stopped at four of eight fixtures: the verdict was already decided and the
+remaining four could not change it.
+
+| PR | noise | recall |
+|---|---|---|
+| 122 | 11 → **55** (5.0×) | 0.364 → 0.455 |
+| 140 | 20 → **70** (3.5×) | 0.400 → 0.533 |
+| 141 | 7 → **39** (5.6×) | 1.000 → 1.000 |
+| 142 | 0 → 0 | 0.000 → 0.000 |
+
+Mean noise **9.5 → 41.0, a 4.3× rise**. Gate criterion 1 fails by an order of
+magnitude, not a margin.
+
+## Both halves of the hypothesis were right
+
+**Separating axes does lift recall** — up on every fixture that had anything to
+find (+0.09, +0.13). Attention competition is real, and removing it works.
+
+**And it multiplies noise, exactly as chunking did.** pr-141 is the sharpest
+evidence: it is the noise probe, recall was already 1.000, there was nothing to
+gain — and noise still rose 5.6×. On that fixture the change bought only noise.
+
+Raw finding counts show the mechanism directly: 126, 139 and 94 findings per PR
+before dedup (82, 102, 60 after), against roughly 15 for the single prompt.
+Every extra call is another opportunity to invent something.
+
+## Why it stopped at four
+
+#331 pre-registered the rule: *"If noise inflates but per-axis recall improves,
+that is a result, not a partial pass — record it and stop, exactly as #160 did."*
+The multiplier was consistent across all four, so four more fixtures would have
+cost real money to confirm a verdict already in hand.
+
+## What the numbers say about the fix
+
+Noise scaled roughly **linearly with call count**: 7 calls, 4.3×. That predicts
+~1.8× at three calls and ~1.2× at two — the last of which would sit close enough
+to baseline to pass criterion 1 while keeping part of the recall.
+
+So the next variant is not "abandon fan-out", it is "fan out less". Shipped
+behind `GUARDIAN_FEATURES=axes_paired`: two calls, grouped by what a defect *is*
+rather than arbitrarily —
+
+- **correctness**: logic, unvalidated external data, float equality
+- **contracts**: type safety, library boundaries, ontology, test coverage
+
+Kin travel together because the two measured competitions (#247, #330) were both
+between *dissimilar* classes.
+
+A caveat for whoever runs it: there is no `security` axis to separate, since Arm
+B was never shipped. The recall gains above therefore came from separation in
+general, not from isolating a blind class — so this variant tests the cheaper
+half of the idea, and the blind-class question stays open in #258.
+
+## Paired grouping — measured the same day, on the same four fixtures
+
+Two calls instead of seven, batched by kinship.
+
+| PR | baseline | paired (2) | per-axis (7) |
+|---|---|---|---|
+| 122 | 11 / 0.364 | **21 / 0.545** | 55 / 0.455 |
+| 140 | 20 / 0.400 | 27 / **0.333** | 70 / 0.533 |
+| 141 | 7 / 1.000 | **9** / 1.000 | 39 / 1.000 |
+| 142 | 0 / 0.000 | 0 / 0.000 | 0 / 0.000 |
+
+```
+mean noise    9.50  ->  14.25 (1.5x)  ->  41.00 (4.3x)
+mean recall   0.441 ->  0.470          ->  0.497
+```
+
+### The linear model held, and the recall did too
+
+Noise was predicted at ~1.2× for two calls from the linear-in-call-count fit;
+the measurement is **1.5×**, against 4.3× at seven. The order of magnitude was
+right.
+
+The part that was **not** predicted: recall barely moved. Seven calls give
+0.497, two give 0.470 — **three times less noise for 0.027 of recall.** Most of
+the benefit of separation is already there at two calls.
+
+On pr-122 two calls beat seven on *both* axes — recall 0.545 against 0.455, at
+noise 21 against 55. More calls is not more recall: seven axes appear to
+fragment too far, leaving each call too little to reason with.
+
+### It still fails the gate
+
+- **Criterion 1** — noise must not exceed baseline. 1.5× does not pass.
+- **Criterion 3** — no PR more than 0.05 below baseline recall. pr-140 dropped
+  0.400 → 0.333.
+
+So this does not ship either. But it is a qualitatively different result from
+the seven-axis run: not "the hypothesis failed" but "the cost is down threefold
+and 1.5× remains".
+
+### Limits
+
+n=1 per variant across four fixtures, against a finder whose variance on an
+unchanged diff has been measured at 6 → 46 → 36 findings. The gap between 0.470
+and 0.497 is well inside that. The noise multipliers (1.5× vs 4.3×) are the
+sturdy part — they are large and consistent per fixture.
+
+### What it points at
+
+Since recall survives batching, the next thing worth testing is **one call that
+walks the axes in sequence** — separation of attention without a second call at
+all. Failing that, keep two calls and attack the residual noise from the skeptic
+side, which is currently tuned for single-prompt volume rather than for a merged
+union.

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.9.0"
+version = "0.10.0"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

codegraph_brain-0.10.0/src/cgis/guardian/axes.py

@@ -0,0 +1,130 @@
+"""Per-axis review: one finder call per focus area instead of one carrying all (#331).
+
+The finder appears to work against a roughly fixed attention budget spread over
+the axes named in a single prompt. Editing that prompt reallocates the budget
+rather than adding capacity — measured twice:
+
+- a targeted float few-shot cracked nothing and dropped pr-144 from 3/5 to 1/5,
+  pulling focus off the yaml class it had been catching (#247);
+- exculpating clauses took pr-313 from recall 0.000 to 1.000 while the corpus
+  total stayed at matched 17 -> 17, two lost elsewhere (#330).
+
+Axes cannot compete for attention if they are not in the same context window.
+Each call still sees the *whole* diff — only the question narrows, which is what
+separates this from chunked review (#154), where each call saw a fragment and
+part of the failure was dilution inside the chunk.
+
+The known risk is the one chunking failed on: every extra call is another
+opportunity to invent a false positive, and there noise grew superlinearly
+(#160). That is why this ships behind a flag and why the pre-registered gate in
+#331 puts noise first.
+"""
+
+import asyncio
+
+import structlog
+
+from cgis.guardian.collector import ContextCollector
+from cgis.guardian.core import finder_pass
+from cgis.guardian.findings import Finding, ReviewResult, dedup_findings
+from cgis.guardian.prompts import AXIS_GROUPS, PER_AXIS_GROUPS
+from cgis.guardian.providers.base import BaseProvider
+from cgis.guardian.skeptic import apply_judgements, judge_all, skeptic_status_for
+
+log = structlog.getLogger(__name__)
+
+
+async def _axis_pass(
+    provider: BaseProvider, context: dict[str, str], label: str, axes: tuple[str, ...]
+) -> ReviewResult | None:
+    """Run the finder for one axis; None when that axis's call fails.
+
+    A flaky call must cost one axis, not the review — the same guard the chunked
+    orchestrator puts around each chunk.
+    """
+    try:
+        return await finder_pass(provider, {**context, "focus_group": ",".join(axes)})
+    except Exception:
+        log.warning("Axis finder call failed; group skipped.", group=label, exc_info=True)
+        return None
+
+
+async def run_axis_review(
+    *,
+    provider: BaseProvider,
+    collector: ContextCollector,
+    skeptic_provider: BaseProvider | None,
+    concurrency: int = 4,
+) -> ReviewResult:
+    """Fan out over focus areas, merge, dedup, then one skeptic pass over the union.
+
+    One skeptic pass rather than one per axis: judging is already the larger half
+    of the token bill, and per-axis judging would multiply it for no expected
+    gain — the axes disagree about *what to look for*, not about whether a given
+    finding is real.
+    """
+    context = collector.collect_all()
+    # "axes" = one call per axis; "axes_paired" = kinship batches (#331 follow-up).
+    groups = AXIS_GROUPS if "axes_paired" in collector.features else PER_AXIS_GROUPS
+    axes = list(groups)
+
+    semaphore = asyncio.Semaphore(concurrency)
+
+    async def guarded(axis: str) -> ReviewResult | None:
+        async with semaphore:
+            return await _axis_pass(provider, context, axis, groups[axis])
+
+    results = await asyncio.gather(*(guarded(axis) for axis in axes))
+
+    findings: list[Finding] = []
+    summaries: list[str] = []
+    failed = 0
+    for axis, result in zip(axes, results, strict=True):
+        if result is None:
+            failed += 1
+            continue
+        if result.parse_failed:
+            # Unparseable output is not a finding-free axis; count it as failed so
+            # the summary cannot read as "this axis found nothing".
+            failed += 1
+            log.warning("Axis output did not parse; axis skipped.", axis=axis)
+            continue
+        findings.extend(result.findings)
+        summaries.append(f"- [{axis}]: {result.summary}")
+
+    if failed == len(axes):
+        return ReviewResult(
+            findings=[],
+            summary="Every axis pass failed; no review produced.",
+            parse_failed=True,
+        )
+
+    merged = ReviewResult(
+        findings=dedup_findings(findings),
+        summary="\n".join(summaries),
+    )
+    log.info(
+        "Axis fan-out complete.",
+        axes=len(axes),
+        failed=failed,
+        raw_findings=len(findings),
+        after_dedup=len(merged.findings),
+    )
+
+    if skeptic_provider is None or not merged.findings:
+        return merged
+
+    judgements = await judge_all(
+        skeptic_provider, merged.findings, context.get("diff", ""), concurrency
+    )
+    judged = sum(1 for j in judgements if j is not None)
+    if judged == 0:
+        log.warning("Every skeptic judgement failed; returning unverified findings.")
+    return merged.model_copy(
+        update={
+            "findings": apply_judgements(merged.findings, judgements),
+            "skeptic_status": skeptic_status_for(judged, len(judgements)),
+            "skeptic_judged": judged,
+            "skeptic_total": len(judgements),
+        }
+    )

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/src/cgis/guardian/chunked.py

@@ -8,10 +8,11 @@ complete world instead — its own diff, full files, and impact graph.
 import structlog
 from pydantic import BaseModel
 
+from cgis.guardian.axes import run_axis_review
 from cgis.guardian.chunker import Chunk, build_chunks, split_diff_by_file
 from cgis.guardian.collector import ContextCollector
 from cgis.guardian.core import GuardianReviewer, finder_pass
-from cgis.guardian.findings import Finding, ReviewResult
+from cgis.guardian.findings import Finding, ReviewResult, dedup_findings
 from cgis.guardian.providers.base import BaseProvider
 from cgis.guardian.skeptic import (
     apply_judgements,
@@ -85,25 +86,6 @@ def _chunk_survivors(chunk: Chunk, findings: list[Finding]) -> list[Finding]:
     return survivors
 
 
-def _dedup(findings: list[Finding]) -> list[Finding]:
-    """Drop duplicate (file, line, category) findings, keeping the higher confidence.
-
-    Cross-chunk duplicates are impossible after the per-chunk file filter
-    (chunks partition files) — this is insurance against intra-pass
-    duplicates. First-occurrence order is preserved.
-    """
-    best: dict[tuple[str, int | None, str], Finding] = {}
-    order: list[tuple[str, int | None, str]] = []
-    for finding in findings:
-        key = (finding.file, finding.line, finding.category)
-        if key not in best:
-            best[key] = finding
-            order.append(key)
-        elif finding.confidence > best[key].confidence:
-            best[key] = finding
-    return [best[k] for k in order]
-
-
 async def _single_pass(
     provider: BaseProvider,
     collector: ContextCollector,
@@ -187,7 +169,7 @@ async def run_chunked_review(
         bullets.append(f"- [{label}]: {result.summary}")
 
     merged = ReviewResult(
-        findings=_dedup(kept),
+        findings=dedup_findings(kept),
         summary="\n".join(bullets),
         parse_failed=failed == len(chunks),
     )
@@ -229,6 +211,17 @@ async def run_review_routed(
     degrade to all-isolated chunks = one API call per file with zero
     connectivity benefit — strictly worse than the status quo.
     """
+    if collector.features & {"axes", "axes_paired"}:
+        # Per-axis fan-out (#331) is checked first: it needs no graph DB, and
+        # combining it with chunked would multiply calls by axes x chunks while
+        # entangling two effects in one measurement — the mistake #330 recorded.
+        return RoutedReview(
+            result=await run_axis_review(
+                provider=provider, collector=collector, skeptic_provider=skeptic_provider
+            ),
+            chunk_count=None,
+        )
+
     chunked = "chunked" in collector.features
     if chunked and (collector.db_path is None or not collector.db_path.exists()):
         log.warning("chunked requested but no graph DB; falling back to single pass.")

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/src/cgis/guardian/collector.py

@@ -16,7 +16,7 @@ from cgis.storage.sqlite_store import SQLiteStore
 
 log = structlog.getLogger(__name__)
 
-VALID_FEATURES = frozenset({"full_files", "flow", "drift", "chunked"})
+VALID_FEATURES = frozenset({"full_files", "flow", "drift", "chunked", "axes", "axes_paired"})
 
 _MAX_FILE_LINES = 1200
 _MAX_TOTAL_CHARS = 120_000

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/src/cgis/guardian/findings.py

@@ -72,3 +72,23 @@ def extract_json(text: str) -> str:
     # No newline before the closing fence (e.g. `{...}```` on one line):
     # valid JSON never ends with backticks, so stripping the suffix is safe.
     return body.strip().removesuffix("```").strip()
+
+
+def dedup_findings(findings: list[Finding]) -> list[Finding]:
+    """Drop duplicate (file, line, category) findings, keeping the higher confidence.
+
+    Shared by every fan-out reviewer: chunked review partitions files so
+    cross-chunk duplicates cannot occur and this is insurance, but per-axis
+    review (#331) asks several axes about the same lines, where collisions are
+    expected rather than exceptional. First-occurrence order is preserved.
+    """
+    best: dict[tuple[str, int | None, str], Finding] = {}
+    order: list[tuple[str, int | None, str]] = []
+    for finding in findings:
+        key = (finding.file, finding.line, finding.category)
+        if key not in best:
+            best[key] = finding
+            order.append(key)
+        elif finding.confidence > best[key].confidence:
+            best[key] = finding
+    return [best[k] for k in order]

{codegraph_brain-0.9.0 → codegraph_brain-0.10.0}/src/cgis/guardian/prompts.py

@@ -1,5 +1,75 @@
 """Builds system and user prompts for the Guardian LLM reviewer."""
 
+#: The finder's focus areas, one entry per axis. A mapping rather than one blob
+#: so a review can ask about a single axis at a time (#331): axes sharing a
+#: context window compete for what looks like a fixed attention budget, measured
+#: twice (#247, #330). Joining every value reproduces the original prompt exactly.
+FOCUS_AREAS: dict[str, str] = {
+    "logic": """\
+**Logic bugs** — inputs that produce wrong output, division by zero, off-by-one errors,
+incorrect algorithm behaviour. Think: empty collections, None values, boundary conditions.""",
+    "external_data": """\
+**Unvalidated external data** — a value read from config/YAML/JSON, env, or a request is
+used as a `dict`/`list`/`set`/iterable (subscripted, iterated, passed to `set()`/`dict()`,
+`.items()`, `for x in value`) without first checking its type or presence. A YAML key the
+author expects to be a mapping can legally be a scalar or a list; a `value or {}` idiom
+catches `None` but lets a non-dict truthy value through to operations that then misbehave
+silently rather than erroring. Flag each such use that lacks a type/shape guard.""",
+    "float_equality": """\
+**Exact-equality on floats / money** — bare `==` or `!=` comparing floating-point or
+Decimal values, *including in test assertions* (`assert x == 0.3`). Floating-point
+rounding makes these flaky or wrong; they should use a tolerance compare. Check changed
+test files for this too.""",
+    "test_coverage": """\
+**Missing test coverage** — code paths in the diff that have no test. Focus on edge cases
+that could silently return wrong results (not just "coverage for coverage's sake").""",
+    "type_safety": """\
+**Type safety** — implicit `Any`, missing return type annotations, unsafe casts, Pydantic
+models constructed with wrong field types.""",
+    "library_contract": """\
+**Library boundary contracts** — for each call into a third-party library, verify that
+the data passed in matches the library's expected convention:
+  - Units and coordinate systems (e.g. center vs top-left, row/col vs x/y,
+    naive vs timezone-aware datetimes)
+  - Ordering assumptions (e.g. does array order affect rendering or sort stability?)
+  - Ownership and mutation (e.g. does the library mutate its input?)
+Trace the value from where it's produced to where it's consumed across the library call.
+If the producing code and consuming code have different assumptions, that's a bug.""",
+    "ontology": """\
+**Ontology compliance** — wrong NodeType/EdgeType assignments, FQNs not derived from file
+paths, unresolved calls not using `raw_call:` prefix.""",
+}
+
+
+#: How the axes are batched into finder calls. Per-axis measured 4.3x the
+#: single-prompt noise across four fixtures (#331) — the superlinear growth that
+#: killed chunked review (#160) — while recall rose on every fixture that had
+#: anything to find. Noise scaled roughly linearly with call count, so fewer,
+#: kinship-grouped calls should keep part of the recall and most of the quiet.
+#:
+#: The split is by what a defect *is*: "wrong answer" shapes in one call,
+#: "declared contract vs actual" in the other. Axes that competed in the two
+#: measured cases (#247, #330) were dissimilar ones, so kin travel together.
+AXIS_GROUPS: dict[str, tuple[str, ...]] = {
+    "correctness": ("logic", "external_data", "float_equality"),
+    "contracts": ("type_safety", "library_contract", "ontology", "test_coverage"),
+}
+
+#: One call per axis — the seven-way fan-out benched in #331.
+PER_AXIS_GROUPS: dict[str, tuple[str, ...]] = {name: (name,) for name in FOCUS_AREAS}
+
+
+def render_group(axes: tuple[str, ...]) -> str:
+    """Render the focus areas for one batch of axes."""
+    return "\n\n".join(FOCUS_AREAS[axis] for axis in axes)
+
+
+def render_focus_areas(axis: str | None = None) -> str:
+    """Return every focus area joined, or a single one when `axis` names it."""
+    if axis is not None:
+        return FOCUS_AREAS[axis]
+    return "\n\n".join(FOCUS_AREAS.values())
+
 
 class PromptBuilder:
     """Constructs the system and user prompts."""
@@ -82,6 +152,20 @@ observe-only — do NOT flag it.
 
 """
 
+        # `focus_axis` narrows the prompt to one axis (#331). Absent = every axis,
+        # which renders exactly the text this block replaced.
+        # `focus_group` carries the axes for this call, comma-separated. Absent =
+        # every axis, which renders exactly the text the inline block used to be.
+        group = context.get("focus_group")
+        # Whitespace-tolerant: the only producer joins without spaces, but this is
+        # a public context key and a stray space would surface as a KeyError deep
+        # inside prompt building rather than as anything a caller could act on.
+        focus_areas_section = (
+            render_group(tuple(part.strip() for part in group.split(",")))
+            if group
+            else render_focus_areas()
+        )
+
         return f"""Review the following Pull Request diff for real defects.
 
 {contributing_section}{ontology_section}### 3. CHANGES TO REVIEW (git diff)
@@ -126,38 +210,7 @@ observe-only — do NOT flag it.
 ---
 ### WHAT TO LOOK FOR (focus areas):
 
-**Logic bugs** — inputs that produce wrong output, division by zero, off-by-one errors,
-incorrect algorithm behaviour. Think: empty collections, None values, boundary conditions.
-
-**Unvalidated external data** — a value read from config/YAML/JSON, env, or a request is
-used as a `dict`/`list`/`set`/iterable (subscripted, iterated, passed to `set()`/`dict()`,
-`.items()`, `for x in value`) without first checking its type or presence. A YAML key the
-author expects to be a mapping can legally be a scalar or a list; a `value or {{}}` idiom
-catches `None` but lets a non-dict truthy value through to operations that then misbehave
-silently rather than erroring. Flag each such use that lacks a type/shape guard.
-
-**Exact-equality on floats / money** — bare `==` or `!=` comparing floating-point or
-Decimal values, *including in test assertions* (`assert x == 0.3`). Floating-point
-rounding makes these flaky or wrong; they should use a tolerance compare. Check changed
-test files for this too.
-
-**Missing test coverage** — code paths in the diff that have no test. Focus on edge cases
-that could silently return wrong results (not just "coverage for coverage's sake").
-
-**Type safety** — implicit `Any`, missing return type annotations, unsafe casts, Pydantic
-models constructed with wrong field types.
-
-**Library boundary contracts** — for each call into a third-party library, verify that
-the data passed in matches the library's expected convention:
-  - Units and coordinate systems (e.g. center vs top-left, row/col vs x/y,
-    naive vs timezone-aware datetimes)
-  - Ordering assumptions (e.g. does array order affect rendering or sort stability?)
-  - Ownership and mutation (e.g. does the library mutate its input?)
-Trace the value from where it's produced to where it's consumed across the library call.
-If the producing code and consuming code have different assumptions, that's a bug.
-
-**Ontology compliance** — wrong NodeType/EdgeType assignments, FQNs not derived from file
-paths, unresolved calls not using `raw_call:` prefix.
+{focus_areas_section}
 
 ---
 ### WORKED EXAMPLES (how the per-function walk turns into a finding):