codegraph-brain 0.7.3__tar.gz → 0.7.5__tar.gz

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/.github/workflows/autodoc.yml

@@ -28,15 +28,15 @@ jobs:
           enable-cache: true
 
       - name: Install CGIS
-        run: uv sync
+        run: uv sync --frozen
 
       - name: Self-ingest core engine
-        run: uv run cgis ingest ./src --output /tmp/self_graph.db
+        run: uv run --frozen cgis ingest ./src --output /tmp/self_graph.db
 
       - name: Generate pipeline flow diagram
         run: |
           mkdir -p docs/architecture/diagrams
-          uv run cgis trace "cgis.pipeline.IngestionPipeline.run" \
+          uv run --frozen cgis trace "cgis.pipeline.IngestionPipeline.run" \
             --db /tmp/self_graph.db \
             --depth 1 \
             --format mermaid \
@@ -44,21 +44,21 @@ jobs:
             > docs/architecture/diagrams/pipeline_flow.mermaid
 
       - name: Compute graph health badge
-        run: uv run python scripts/generate_health.py --db /tmp/self_graph.db
+        run: uv run --frozen python scripts/generate_health.py --db /tmp/self_graph.db
 
       - name: Inject graph into README.md
         run: |
-          uv run python scripts/inject_readme_graph.py \
+          uv run --frozen python scripts/inject_readme_graph.py \
             --db /tmp/self_graph.db \
             --fqn "cgis.pipeline.IngestionPipeline.run" \
             --depth 1 \
             --path-prefix "src/"
 
       - name: Generate MCP reference manual
-        run: uv run python scripts/generate_mcp_ref.py
+        run: uv run --frozen python scripts/generate_mcp_ref.py
 
       - name: Sync schema docs from source
-        run: uv run python scripts/generate_schema_docs.py
+        run: uv run --frozen python scripts/generate_schema_docs.py
 
       - name: Open PR with generated docs
         uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676  # v7

codegraph_brain-0.7.5/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+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.
+        run: uv run --frozen pytest --cov=cgis --cov-report=term-missing --cov-report=xml
+
+      - 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.
+          args: >
+            -Dsonar.projectKey=zaebee_codegraph-brain
+            -Dsonar.organization=zaebee
+            -Dsonar.sources=src,scripts
+            -Dsonar.tests=tests
+            -Dsonar.python.version=3.12
+            -Dsonar.python.coverage.reportPaths=coverage.xml

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/.github/workflows/guardian.yml

@@ -67,10 +67,10 @@ jobs:
         uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
 
       - name: Install dependencies
-        run: uv sync --extra guardian
+        run: uv sync --frozen --extra guardian
 
       - name: Build code graph
-        run: uv run cgis ingest ./src --output graph.db
+        run: uv run --frozen cgis ingest ./src --output graph.db
 
       - name: Restore metrics from data branch
         run: |
@@ -91,7 +91,7 @@ jobs:
           GUARDIAN_SKEPTIC: ${{ vars.GUARDIAN_SKEPTIC }}
           GUARDIAN_SKEPTIC_MODEL: ${{ vars.GUARDIAN_SKEPTIC_MODEL }}
         run: |
-          uv run python scripts/guardian_review.py \
+          uv run --frozen python scripts/guardian_review.py \
             --output guardian_report.md \
             --db graph.db \
             --pr "$PR_NUMBER" \
@@ -219,7 +219,7 @@ jobs:
           git show origin/data/guardian-metrics:guardian_metrics.jsonl \
             > guardian_metrics.jsonl
 
-          uv run cgis guardian-rate "$PR_NUMBER" "$APPLIED" \
+          uv run --frozen cgis guardian-rate "$PR_NUMBER" "$APPLIED" \
             --metrics guardian_metrics.jsonl
 
           if git ls-remote --exit-code origin data/guardian-metrics > /dev/null 2>&1; then

codegraph_brain-0.7.5/.github/workflows/pr-title.yml

@@ -0,0 +1,51 @@
+name: PR Title
+
+# The repository squash-merges, so the PR title becomes the commit subject that
+# release-please parses. A title it does not recognise is dropped from the
+# changelog silently — no warning, no failure. That has now happened twice:
+# #297 ("drift trust batch: …", a descriptive title) and #313
+# ("security(mcp): …", a type that does not exist), the second of which would
+# have shipped a security fix invisibly.
+on:
+  pull_request:
+    branches: [ main ]
+    # `edited` matters: without it, fixing a rejected title would not re-run
+    # the check. Kept in a separate workflow from ci.yml so retitling does not
+    # replay the whole test suite.
+    types: [ opened, edited, reopened, synchronize ]
+
+permissions: {}
+
+jobs:
+  conventional-title:
+    name: Conventional commit title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the title release-please will parse
+        env:
+          # Never interpolate an untrusted title straight into `run:` — it is
+          # attacker-controlled text. Through the environment it is just data.
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+          # Types release-please understands. Anything else is dropped from the
+          # changelog without complaint, which is the failure being prevented.
+          TYPES='feat|fix|docs|chore|style|refactor|perf|test|build|ci|revert'
+          if printf '%s' "$PR_TITLE" | grep -qE "^($TYPES)(\([a-z0-9._/-]+\))?!?: .+"; then
+            printf '::notice::PR title is a conventional commit.\n'
+            exit 0
+          fi
+          printf '::error::PR title is not a conventional commit: %s\n' "$PR_TITLE"
+          cat >&2 <<'MSG'
+
+          This repository squash-merges, so the PR title becomes the commit
+          subject release-please reads. An unrecognised type is dropped from the
+          CHANGELOG silently.
+
+          Expected:  <type>(<optional scope>): <description>
+          Types:     feat fix docs chore style refactor perf test build ci revert
+
+          Note there is no `security` type — use `fix` with a scope:
+              fix(mcp): validate db_path before cgis_ingest creates a database
+          MSG
+          exit 1

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

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

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.7.5](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.4...codegraph-brain-v0.7.5) (2026-08-01)
+
+
+### Documentation
+
+* **spec:** record what changed for [#258](https://github.com/zaebee/codegraph-brain/issues/258) — fixture, second lever, pre-registered gate ([#322](https://github.com/zaebee/codegraph-brain/issues/322)) ([fca8da8](https://github.com/zaebee/codegraph-brain/commit/fca8da8120a7542a71c875d9a960df615f59594e))
+
+## [0.7.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.3...codegraph-brain-v0.7.4) (2026-08-01)
+
+
+### Bug Fixes
+
+* **mcp:** validate db_path before cgis_ingest creates a database ([#313](https://github.com/zaebee/codegraph-brain/issues/313)) ([2c5499b](https://github.com/zaebee/codegraph-brain/commit/2c5499b8fb7f0d40a03144417c3210900371d499)), closes [#312](https://github.com/zaebee/codegraph-brain/issues/312)
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#314](https://github.com/zaebee/codegraph-brain/issues/314)) ([7d5b666](https://github.com/zaebee/codegraph-brain/commit/7d5b66669f9dfa40e2fc86dd59a4baf492a9342e))
+
 ## [0.7.3](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.2...codegraph-brain-v0.7.3) (2026-07-31)
 
 

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.7.3
+Version: 0.7.5
 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.7.3 → codegraph_brain-0.7.5}/benchmarks/guardian/CURATION.md

@@ -206,3 +206,69 @@ Fixed later by human-directed review as #283 (`b2ae97b`), which is the
 Precision is unaffected: `matched` stays 0, so the entry still scores `0/10`. The
 addition supplies a recall signal — a real **0/1** where the empty ground truth
 gave a vacuous 1.0.
+
+## pr-313 (added 2026-08-01, #315) — first security fixture
+
+`security(mcp): validate db_path before cgis_ingest creates a database`.
+
+Provenance is stronger than the rest of the corpus: neither entry was mined from
+review dialogue. Both were **reproduced by execution** on the pre-fix code and
+re-run after the fix.
+
+- `dangling-symlink-write-primitive` (110-121, major, **security**, `fix-commit`
+  `8bcda77`). A `.db` symlink whose target does not exist passes every check —
+  `is_file()` is False for a dangling link, so the magic-byte test never runs —
+  and SQLite then follows it and creates the target. Demonstrated by writing a
+  SQLite header into a non-existent `.ssh/authorized_keys`; refused afterwards.
+- `oserror-escapes-the-tool` (114-124, minor, `logic`, `fix-commit` `72c34eb`).
+  The guard runs before `cgis_ingest`'s own try/except and `Path.is_dir()`,
+  `.stat()`, `.open()` propagate `OSError`, so a `PermissionError` on the parent
+  crashes the MCP tool. Demonstrated with a `chmod 000` parent.
+
+### Why `head` is `2d79671` and not the final pull head
+
+Standard policy, restated because this PR has four commits: `2d79671` is the
+snapshot the first review ran on and the only one where **both** findings are
+present. The later three are the fixes.
+
+### Overlapping ranges are deliberate
+
+The two ranges overlap on 114-121. A reviewer can legitimately anchor the
+symlink bypass either at the unresolved `Path(db_path)` (110) or at the
+`is_file()` test where it slips through (121), and the OSError leak sits across
+the whole probe block. Matching is greedy per entry, so one prediction still
+consumes only one entry.
+
+### Scoring the historical runs would be unfair
+
+Three reviews ran over this PR, but on **different commits** — guardian started
+at 23:38:58, after `72c34eb` had already fixed the OSError defect, so it never
+had a shot at that entry:
+
+| reviewer | commit reviewed | findings | GT available | GT hit |
+|---|---|---|---|---|
+| gemini (1st) | `2d79671` | 1 | 2 | 1 (OSError) |
+| guardian | `72c34eb` | 5 | 1 | 0 |
+| gemini (2nd) | `c90bbf8` | 2 | 1 | 1 (symlink) |
+
+A replay at `head` gives every reviewer both findings, which is the point of
+pinning the review head. The table above must not be read as guardian missing
+two.
+
+### A refuted claim that is deliberately absent
+
+Guardian's `multi-dot suffix` finding on this PR was a false positive — it
+asserted `graph.tar.db` should be rejected, when ending in `.db` is exactly the
+stated policy, and its suggested `path.suffixes` fix would have broken a
+legitimate `my.project.db`. Per the policy above, refuted claims are omitted
+from ground truth entirely rather than filed as `ambiguous`, so that precision
+failures stay observable. Recorded here because the cross-family skeptic
+**confirmed** it (`Verified by gemini-2.5-flash`) — the cleanest example yet of
+a skeptic passing a systematic reasoning error (#246).
+
+### `category: security`
+
+New value, added with this fixture (`findings.py`). The finder prompt does not
+yet offer it — teaching the finder to emit it is #258 and needs bench
+validation. Scoring is unaffected: `_entry_accepts` compares file and line
+range, never category.

codegraph_brain-0.7.5/benchmarks/guardian/pr-313.yaml

@@ -0,0 +1,43 @@
+# PR 313 — security(mcp): validate db_path before cgis_ingest creates a database.
+# See CURATION.md. First security fixture in the corpus (#315, taxonomy gap #258).
+#
+# Provenance is unusually strong: both findings were REPRODUCED BY EXECUTION on
+# the pre-fix code and re-run after the fix, not mined from review dialogue.
+#
+# head = review head (the snapshot the first review ran on). The three later
+# commits on that branch are the fixes, so replaying the final pull head would
+# make both findings unfindable — CURATION.md erratum on spec §3.1.
+#
+# The two ranges overlap on 114-121. That is inherent rather than sloppy: a
+# reviewer can legitimately anchor the symlink bypass either at the unresolved
+# `Path(db_path)` (110) or at the `is_file()` test where it slips through (121),
+# and the OSError leak sits across the whole probe block. Matching is greedy per
+# entry, so one prediction still consumes only one entry.
+pr: 313
+base: 411f8c5894b6
+head: 2d79671547d4
+findings:
+  - id: dangling-symlink-write-primitive
+    file: src/cgis/api/mcp_server.py
+    lines: [110, 121]
+    severity: major
+    category: security
+    summary: >
+      db_path is validated unresolved, so a `.db` symlink whose target does not
+      exist passes every check — is_file() is False for a dangling link, so the
+      magic-byte test never runs — and SQLite then follows it and creates the
+      target. Demonstrated: a symlink to a non-existent .ssh/authorized_keys was
+      created as a SQLite database (header b'SQLite format 3\x00').
+    source: fix-commit
+  - id: oserror-escapes-the-tool
+    file: src/cgis/api/mcp_server.py
+    lines: [114, 124]
+    severity: minor
+    category: logic
+    summary: >
+      The guard runs before cgis_ingest's own try/except, and Path.is_dir(),
+      .stat() and .open() all propagate OSError, so a PermissionError on the
+      parent directory escapes the MCP tool as a crash instead of a message the
+      agent can act on. Demonstrated with a chmod 000 parent directory.
+    source: fix-commit
+ambiguous: []

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/docs/how-to/MCP_REFERENCE.md

@@ -176,9 +176,14 @@ Show the structural layout (CONTAINS/DECLARES) of a module or class.
 Scan a local directory, extract all symbols, resolve links, and build the graph DB.
 
     Use this to initialise or refresh the code knowledge graph for a project.
-    Paths are normalised relative to the workspace root so the database is
+    Node FQNs are normalised relative to the workspace root so the graph is
     portable across machines.
 
+    ``db_path`` must name a database — it has to end in ``.db``, ``.sqlite`` or
+    ``.sqlite3``, live in a directory that already exists, and not point at an
+    existing file that is not a SQLite database. cgis will not create parent
+    directories.
+
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
     whole-graph total. Set ``full_rebuild=True`` to re-scan every file and

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/docs/specs/2026-07-31-finder-bug-class-taxonomy.md

@@ -153,3 +153,93 @@ Steps 2–4 need a provider key, which is why they are not done here.
   instructions (we have no such capability in the finder).
 - Copying rule text verbatim — the source is Apache-2.0 Go/agentic tooling for a
   different stack; #258 asks for the taxonomy only.
+
+---
+
+# Addendum — 2026-08-01: the experiment is now runnable, and a second intervention appeared
+
+Three things changed after this document was written. None of them changes the
+conclusion above (**still nothing shipped to `prompts.py`**), but two of them
+change what the deciding experiment should measure.
+
+## 1. The top gap now has a fixture
+
+When the table above was written, the Security-Sensitive Code row was **absent**
+with no ground truth to test it against; only Resource Management (pr-278) had
+one. `benchmarks/guardian/pr-313.yaml` (#315) now carries a real security defect:
+
+    dangling-symlink-write-primitive   (major, category: security)
+
+A `.db` symlink whose target does not exist defeats a path guard —
+`is_file()` is False for a dangling link, so the magic-byte check never runs and
+SQLite creates the target. Reproduced by execution, not mined from dialogue.
+
+`category: security` was added to `Category` with that fixture. The finder prompt
+does **not** offer it — that is this document's subject and still unshipped.
+Scoring is unaffected: `_entry_accepts` compares file and line range, never
+category.
+
+So the experiment can now measure both evidenced gaps rather than one.
+
+## 2. A second, better-evidenced intervention: exculpating guards
+
+Production runs on 2026-07-31 produced a failure mode this document does not
+consider, because it is not a missing class — it is a defect in the classes that
+already exist.
+
+On PR #297 the finder returned **12** "Unvalidated dictionary access" findings
+against code that validates with `isinstance` one line above the use. On #313 it
+returned "floating-point comparison may be flaky" on a line carrying an explicit
+`+ 1e-9`. Both trace to focus-area wording that names a *shape* and never names
+the guard that makes an instance a non-finding:
+
+> **Unvalidated external data** — … used as a `dict`/… **without first checking
+> its type or presence**
+
+The finder matches the shape and does not check whether the guard is present.
+
+This matters for sequencing: **adding classes to a checklist that already
+over-fires multiplies noise.** The precision fix should be measured first, or at
+least separately — otherwise a recall gain from new classes and a noise change
+from the rewrite arrive in the same number and neither can be attributed.
+
+It is also the cheaper experiment. It needs no new fixture: if adding an
+exculpating clause to each existing focus area lowers `noise` without lowering
+`matched` on the current corpus, that is the whole result.
+
+## 3. Replay already exists
+
+This document says steps 2–4 "need a provider key". True, but worth stating
+plainly for whoever picks this up: the *machinery* is not missing.
+`uv run --frozen python scripts/guardian_bench.py --replay-finder <recording.json>`
+freezes a finder set and judges it, and `load_finder_recording` strips prior
+verdicts on read so arms stay comparable.
+(#302 was filed claiming this was absent and has been closed as redundant.)
+
+The only blocker is credentials.
+
+## Pre-registered gate
+
+Writing pass/fail criteria before spending money is what made the chunked-review
+no-go mechanical rather than motivated (#160). Same discipline here.
+
+**Arm A — exculpating-guard rewrite** (no new classes):
+1. mean `noise` per PR drops by ≥ 25% against the frozen baseline
+2. `matched` does not drop on any PR
+3. pr-141, the noise probe, does not regress
+
+**Arm B — class checklist** (security, concurrency, resource, error-handling;
+compact named classes, no per-class few-shot, per #247):
+1. pr-278 `gemini-client-never-closed` OR pr-313 `dangling-symlink-write-primitive`
+   is matched at least once in three runs — the hypothesis must show where it matters
+2. no PR drops more than 0.05 below its baseline recall
+3. mean noise does not exceed the Arm A result
+
+Ship each arm only on its own gate. If Arm B passes only with Arm A applied,
+say so explicitly rather than reporting the combined delta.
+
+## Still out of scope
+
+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.

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.7.3"
+version = "0.7.5"
 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.7.3 → codegraph_brain-0.7.5}/src/cgis/api/mcp_server.py

@@ -85,20 +85,92 @@ def _render_subgraph(
     return f"❌ Unknown format '{output_format}'. Use 'mermaid' or 'json'."
 
 
+#: Names cgis will create a database under. Everything else is refused, so an
+#: agent cannot be talked into materialising `~/.ssh/authorized_keys` (#312).
+_DB_SUFFIXES = frozenset({".db", ".sqlite", ".sqlite3"})
+
+#: First 16 bytes of any SQLite file.
+_SQLITE_MAGIC = b"SQLite format 3\x00"
+
+
+def _reject_db_path(db_path: str) -> str | None:
+    """Return a refusal message for an unusable ``db_path``, or None if it is fine.
+
+    ``cgis_ingest`` is the only MCP tool that creates its database — the other
+    twelve refuse a path that does not already exist, which is guard enough for
+    them. It needs a different one: it reads untrusted repository content and is
+    then told by the same agent where to write, so ``db_path`` is attacker-
+    reachable in a way the read-only tools' paths are not.
+
+    Refuses an unexpected suffix, a missing parent directory (creating a tree is
+    never wanted), a directory target, and an existing file that is not a
+    database. The last is belt-and-braces — SQLite already declines to open a
+    non-database — but it fails with a message that says why.
+
+    Everything is judged on the **resolved** path. A dangling symlink is the
+    bypass this guard exists to stop: ``attack.db`` pointing at a target that
+    does not exist yet makes ``is_file()`` return False, every check passes, and
+    SQLite creates the target. Resolving first means the suffix rule applies to
+    where the write actually lands. (A symlink to an *existing* non-database was
+    already refused by the magic-byte check.)
+
+    The filesystem probes are wrapped: this runs *before* ``cgis_ingest``'s own
+    try/except, and ``Path.resolve()``, ``Path.is_dir()`` and friends propagate
+    ``OSError`` (a ``PermissionError`` on the parent, or a symlink loop), which
+    would escape the tool as a crash instead of a message the agent can act on.
+    """
+    try:
+        path = Path(db_path).resolve()
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    # Case-insensitive: `.DB` carries the same intent, and on a case-insensitive
+    # filesystem it is literally the same file.
+    if path.suffix.lower() not in _DB_SUFFIXES:
+        allowed = ", ".join(sorted(_DB_SUFFIXES))
+        return f"❌ Refusing db_path '{db_path}': name must end in one of {allowed}."
+    try:
+        if path.is_dir():
+            return f"❌ Refusing db_path '{db_path}': it is a directory."
+        if not path.parent.is_dir():
+            return (
+                f"❌ Refusing db_path '{db_path}': parent directory does not exist. "
+                "cgis will not create one."
+            )
+        if path.is_file() and path.stat().st_size > 0:
+            with path.open("rb") as fh:
+                if fh.read(len(_SQLITE_MAGIC)) != _SQLITE_MAGIC:
+                    return (
+                        f"❌ Refusing db_path '{db_path}': existing file is not a SQLite database."
+                    )
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    return None
+
+
 @mcp.tool()
 def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: bool = False) -> str:
     """Scan a local directory, extract all symbols, resolve links, and build the graph DB.
 
     Use this to initialise or refresh the code knowledge graph for a project.
-    Paths are normalised relative to the workspace root so the database is
+    Node FQNs are normalised relative to the workspace root so the graph is
     portable across machines.
 
+    ``db_path`` must name a database — it has to end in ``.db``, ``.sqlite`` or
+    ``.sqlite3``, live in a directory that already exists, and not point at an
+    existing file that is not a SQLite database. cgis will not create parent
+    directories.
+
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
     whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
     overwrite the database from scratch — use this to drop nodes for files that
     were deleted or renamed, which an incremental run leaves behind.
     """
+    refusal = _reject_db_path(db_path)
+    if refusal is not None:
+        logger.warning("MCP ingest refused db_path", db=db_path)
+        return refusal
+
     pipeline = IngestionPipeline(_EXTRACTORS)
     try:
         with SQLiteStore(db_path) as store:

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/src/cgis/guardian/findings.py

@@ -5,7 +5,11 @@ from typing import Literal
 from pydantic import BaseModel, Field
 
 Severity = Literal["critical", "major", "minor"]
-Category = Literal["logic", "contract", "tests", "types", "ontology"]
+# "security" exists so curated ground truth can name an exploitable defect (#315).
+# The finder prompt does not yet offer it as a choice — teaching the finder to
+# emit it is #258, and needs bench validation. Scoring is unaffected either way:
+# bench matching compares file and line range, never category.
+Category = Literal["logic", "contract", "tests", "types", "ontology", "security"]
 Verdict = Literal["confirmed", "refuted", "uncertain"]
 
 

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/src/cgis/guardian/render.py

@@ -11,6 +11,7 @@ _CATEGORY_LABEL = {
     "tests": "Test Coverage",
     "types": "Type Safety",
     "ontology": "Ontology",
+    "security": "Security",
 }
 
 

{codegraph_brain-0.7.3 → codegraph_brain-0.7.5}/src/cgis/resolver/engine.py

@@ -126,7 +126,7 @@ class ResolverEngine:
 
     def _ensure_virtual_node(self, target: str, virtual_nodes: dict[str, Node]) -> None:
         """Create a virtual boundary node for target if it is not already in the graph."""
-        if target not in self._index.nodes and target not in virtual_nodes:
+        if not self._index.has_node(target) and target not in virtual_nodes:
             virtual_nodes[target] = self._make_virtual_node(
                 target, self._index.classify_fqn(target)
             )