codegraph-ir 0.2.1__tar.gz → 0.4.0__tar.gz

codegraph_ir-0.4.0/.pre-commit-hooks.yaml

@@ -0,0 +1,19 @@
+# CGIR contract seatbelt for the pre-commit framework (https://pre-commit.com).
+# In your repo's .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/asonkiya/llm-semantic-compilers
+#       rev: v0.2.1
+#       hooks:
+#         - id: cgir-contract-check
+#
+- id: cgir-contract-check
+  name: cgir contract seatbelt
+  description: >-
+    Block commits that alter component contracts: effect gain/loss on
+    net/fs/db, pin violations (cgir: pure / stable-signature / frozen),
+    and referenced type-shape drift.
+  entry: cgir hook run
+  language: python
+  pass_filenames: false
+  types_or: [python, ts, tsx, go]

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/Code-IR.md

@@ -60,7 +60,9 @@ H --> I[LLM regenerate / test / trace]
 "trace":{"type":"array","items":{"type":"string"}}}}
 ```
 
-`pins` are developer-declared invariants extracted from `cgir:` comment
+`lexical_effects` marks the subset of `effects` backed only by lexical
+(suffix/receiver-name) evidence — lower confidence, reported but not
+build-failing by default. `pins` are developer-declared invariants extracted from `cgir:` comment
 pragmas (`pure`, `no-<tag>`, `stable-signature`, `frozen`): state pins hold on
 every scan; change pins hold across scan pairs and are always enforced.
 

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-ir
-Version: 0.2.1
+Version: 0.4.0
 Summary: The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls.
 Project-URL: Homepage, https://github.com/asonkiya/llm-semantic-compilers
 Project-URL: Repository, https://github.com/asonkiya/llm-semantic-compilers
@@ -43,8 +43,9 @@ Requires-Python: >=3.11
 Requires-Dist: jsonschema>=4.21
 Requires-Dist: networkx>=3.2
 Requires-Dist: pydantic>=2.6
-Requires-Dist: tree-sitter-go<0.25,>=0.23
+Requires-Dist: tree-sitter-go<0.24,>=0.23
 Requires-Dist: tree-sitter-python<0.24,>=0.23
+Requires-Dist: tree-sitter-rust<0.23.3,>=0.23
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter<0.25,>=0.23
 Requires-Dist: typer>=0.12
@@ -61,6 +62,8 @@ Requires-Dist: ruff>=0.5; extra == 'dev'
 Requires-Dist: types-jsonschema; extra == 'dev'
 Provides-Extra: llm
 Requires-Dist: anthropic>=0.40; extra == 'llm'
+Provides-Extra: lsp
+Requires-Dist: pygls>=1.3; extra == 'lsp'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2; extra == 'mcp'
 Description-Content-Type: text/markdown
@@ -90,13 +93,14 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go, Rust)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests
 cgir impact app.service.charge --candidate new.py --repo .   # radius narrowed by the real delta
 cgir verify app.service.charge --candidate new.py --repo .   # contract-check an edit
 cgir hook install                    # pre-commit seatbelt: block contract-breaking commits
+cgir lsp                             # editor squiggles for pin violations + drift (cgir[lsp])
 ```
 
 `pack` → edit → `impact` → `verify` → `hook`, with `watch` keeping the index
@@ -127,6 +131,30 @@ change touches, and `verify` / `impact_of_change` to contract-check its own
 edit before proposing it. See [`examples/`](./examples) for a worked
 agent-PR case study.
 
+Setup guide for agents (MCP config + CLAUDE.md snippet): [`docs/agents.md`](./docs/agents.md).
+Or via the [pre-commit framework](https://pre-commit.com): hook id `cgir-contract-check`.
+
+## How it compares (honestly)
+
+| | **CGIR** | CodeGraph-style MCP graphs | Greptile / CodeRabbit | import-linter / ArchUnit | oasdiff / Pact |
+|---|---|---|---|---|---|
+| Effects & purity contracts per function | ✅ | ❌ | ❌ LLM judgment | ❌ | ❌ |
+| Invariants declared in source (`# cgir: pure`) & enforced | ✅ | ❌ | ❌ | imports only | API boundary only |
+| Deterministic (same input → same verdict, zero LLM) | ✅ | ✅ structure only | ❌ | ✅ | ✅ |
+| Catches "service silently stopped calling the backend" | ✅ | ❌ | sometimes | ❌ | at spec boundaries |
+| Blast radius + coverage-grounded test selection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Agent context over MCP | ✅ contract packs | ✅ broader retrieval | ❌ | ❌ | ❌ |
+| Finds logic bugs | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Languages | 4 builtin + [plugin API](./docs/languages.md) | 30+ | most | per-tool | spec-level |
+| Cycle / layer rules | ✅ | ❌ | ❌ | ✅ mature | ❌ |
+| Cost | free, local | mostly free | ~$24–30/user/mo | free | free |
+
+Where CGIR loses, we say so: it does **not** find logic bugs (a subtly wrong
+algorithm with unchanged effects passes the gate — pair it with tests or a
+reviewer), supports 3 languages not 38, and its effect detection is static
+analysis with [documented, measured limits](./docs/gate-noise.md) — every
+tag carries a confidence tier so you know which claims are verified.
+
 ## Docs
 
 - [`docs/strategy.md`](./docs/strategy.md) — positioning: the deterministic contract layer

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/README.md

@@ -23,13 +23,14 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go, Rust)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests
 cgir impact app.service.charge --candidate new.py --repo .   # radius narrowed by the real delta
 cgir verify app.service.charge --candidate new.py --repo .   # contract-check an edit
 cgir hook install                    # pre-commit seatbelt: block contract-breaking commits
+cgir lsp                             # editor squiggles for pin violations + drift (cgir[lsp])
 ```
 
 `pack` → edit → `impact` → `verify` → `hook`, with `watch` keeping the index
@@ -60,6 +61,30 @@ change touches, and `verify` / `impact_of_change` to contract-check its own
 edit before proposing it. See [`examples/`](./examples) for a worked
 agent-PR case study.
 
+Setup guide for agents (MCP config + CLAUDE.md snippet): [`docs/agents.md`](./docs/agents.md).
+Or via the [pre-commit framework](https://pre-commit.com): hook id `cgir-contract-check`.
+
+## How it compares (honestly)
+
+| | **CGIR** | CodeGraph-style MCP graphs | Greptile / CodeRabbit | import-linter / ArchUnit | oasdiff / Pact |
+|---|---|---|---|---|---|
+| Effects & purity contracts per function | ✅ | ❌ | ❌ LLM judgment | ❌ | ❌ |
+| Invariants declared in source (`# cgir: pure`) & enforced | ✅ | ❌ | ❌ | imports only | API boundary only |
+| Deterministic (same input → same verdict, zero LLM) | ✅ | ✅ structure only | ❌ | ✅ | ✅ |
+| Catches "service silently stopped calling the backend" | ✅ | ❌ | sometimes | ❌ | at spec boundaries |
+| Blast radius + coverage-grounded test selection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Agent context over MCP | ✅ contract packs | ✅ broader retrieval | ❌ | ❌ | ❌ |
+| Finds logic bugs | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Languages | 4 builtin + [plugin API](./docs/languages.md) | 30+ | most | per-tool | spec-level |
+| Cycle / layer rules | ✅ | ❌ | ❌ | ✅ mature | ❌ |
+| Cost | free, local | mostly free | ~$24–30/user/mo | free | free |
+
+Where CGIR loses, we say so: it does **not** find logic bugs (a subtly wrong
+algorithm with unchanged effects passes the gate — pair it with tests or a
+reviewer), supports 3 languages not 38, and its effect detection is static
+analysis with [documented, measured limits](./docs/gate-noise.md) — every
+tag carries a confidence tier so you know which claims are verified.
+
 ## Docs
 
 - [`docs/strategy.md`](./docs/strategy.md) — positioning: the deterministic contract layer

codegraph_ir-0.4.0/docs/agents.md

@@ -0,0 +1,70 @@
+# CGIR for agents — setup and protocol
+
+Agents are CGIR's first-class users: instead of grepping and reading whole
+files, an agent queries the semantic index and contract-checks its own edits
+before proposing them.
+
+## 1. Serve the index over MCP
+
+Scan once (or run `cgir watch` to keep it live), then register the server:
+
+```jsonc
+// .mcp.json at the repo root (Claude Code picks this up automatically)
+{
+  "mcpServers": {
+    "cgir": {
+      "command": "cgir",
+      "args": ["mcp", "--index", ".cgir"]
+    }
+  }
+}
+```
+
+Requires `cgir` on PATH with the mcp extra (`uv tool install "codegraph-ir[mcp]"`
+or `uv pip install "codegraph-ir[mcp]"`).
+
+## 2. Teach the agent the protocol (CLAUDE.md / AGENTS.md snippet)
+
+Paste into the repo's agent instructions:
+
+```markdown
+## Semantic index (CGIR)
+
+This repo has a semantic contract index served over MCP (server: `cgir`).
+Prefer it over grepping:
+
+- **Finding code**: `search(query)` — ranked free terms + contract
+  predicates: `kind:pure`, `effects:net`, `effects:none`, `lexical:false`,
+  `callers:>3`, `pins:pure`, `entrypoint:HTTP`, `lang:go`, `covered:false`.
+  E.g. "effects:net lexical:false callers:>2" = verified network code with
+  real fan-in — queries grep and vector search cannot answer.
+- **Loading context to edit a component**: `pack(component_id)` — the
+  minimal contract bundle (signature, effects, pins, callee interfaces,
+  linked tests). Do NOT read whole files for context first.
+- **Before changing a component**: `impact(component_id)` — blast radius:
+  affected callers, entrypoints at risk, exactly which tests to run.
+- **After drafting an edit**: `impact_of_change(repo, component_id,
+  candidate)` — the radius narrowed by your edit's real contract delta;
+  `verify(repo, component_id, candidate)` — contract-check before proposing.
+
+Respect `Pinned:` lines in packs — they are hard invariants (`pure`,
+`no-net`, `stable-signature`, `frozen`), enforced by the pre-commit hook
+and CI. A rewrite that violates a pin will be rejected; don't attempt it.
+```
+
+## 3. What the agent gets out of it
+
+- **Fewer tokens, better context**: a pack is ~60–800 tokens vs ~400–20,000
+  for raw files, and benchmarks show it *beats* whole-file context as
+  rewrite input (`docs/experiment-log.md`).
+- **Fewer rejected edits**: `verify`/`impact_of_change` catch contract
+  drift before the human (or the hook, or CI) does.
+- **No hallucinated wiring**: packs name DI receivers (`self.svc.method` /
+  `this.svc.method`), the exact field names an edit must use.
+
+## 4. The enforcement backstop
+
+The same contracts the agent consults are enforced deterministically:
+`cgir hook install` (pre-commit), the [GitHub Action](./github-action.md)
+(per-PR), and `cgir: ` pins in source. The agent can't drift from what the
+index says without something noticing — that's the point.

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/docs/architecture-rules.md

@@ -58,3 +58,23 @@ component id (`aspen.zones.*` matches `aspen.zones.contains.point_in_polygon`).
 - **Kind-aware**: "handlers must be orchestrators, not effect adapters."
 - **Call-target-aware**: layer boundaries over *resolved calls*, catching
   a cross-layer call even when the import is indirect.
+
+## Cycles and layers
+
+```toml
+[[rule]]
+name = "core is acyclic"
+in = "app.*"
+forbid-cycle = true          # Tarjan SCCs over resolved CALLS; self-recursion OK
+
+[[rule]]
+name = "layered architecture"
+layers = ["app.api.*", "app.core.*", "app.db.*"]   # top -> bottom
+```
+
+`forbid-cycle` fires once per strongly-connected component (size >= 2),
+naming the cycle. `layers` requires dependencies to point *downward*:
+a `db` component calling an `api` component is a violation; same-layer and
+layer-skipping downward calls are fine; components matching no layer are
+ignored. Unlike import linters, these run over the resolved *call* graph —
+and the same index tells you whether the violating edge also carries `net`.

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/docs/gate-noise.md

@@ -88,7 +88,15 @@ the `io` / `nondeterm` effect tags (a `print`/timestamp shouldn't fail CI).
    Trade-off (documented in `diff.violations`): a true removal paired with a
    new unrelated effectful call is masked — the loss stays visible in the
    diff report, it just doesn't fail the build.
-2. **Import-resolution stability** — kind/purity flipping on stub-vs-real
+2. **Confidence tiers** *(landed 0.3.0)* — every effect tag now carries
+   provenance: `high` (exact/prefix table match) vs `lexical` (bare-suffix /
+   receiver-name heuristics — `self.now()`, `db.query()`). Gate rules fire
+   on high-confidence tags by default; `:any` opts in
+   (`effect-gain:db:any`). Measured on camera-tracking: fs evidence is 89%
+   lexical, and 48% of the `calls_effectful` taint tree rests on lexical
+   evidence — all still *reported*, no longer build-failing. Lexical means
+   unverified, not wrong.
+3. **Import-resolution stability** — kind/purity flipping on stub-vs-real
    imports is the dominant `kind-change`/`purity-drop` noise source. A
    scan run compares two checkouts in one environment (CI does this), so it
    only bites when the stub *source itself* changes — but it's worth

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/docs/languages.md

@@ -28,6 +28,7 @@ full test suite green.
 | 3 | ingest structural dispatch + attr extraction (normalized `Declaration`s) | ✅ done |
 | 4 | `TypeScriptAdapter` + per-file language dispatch | ✅ done |
 | 5 | `GoAdapter` (package=directory merge, struct-field DI, panic≙raise) | ✅ done |
+| 6 | `RustAdapter` (agent-written from the docs, reviewed & promoted; structs/impl, use-trees, match CFG) | ✅ done |
 
 **Two languages ship (Python, TypeScript); a mixed repo scans both.**
 Zero grammar node-type strings remain outside `cgir/languages/`. The CFG builder is pure topology over statement
@@ -66,3 +67,46 @@ closure, symbol-table resolution, slicing, and all seven product surfaces.
 Register it in `cgir/languages/__init__.py:ADAPTERS`. The effect *taxonomy*
 (`io`/`net`/`fs`/`db`/`nondeterm`/`raise`) is language-neutral and fixed in
 `analyses/effects.py`; the adapter only decides which calls map to which tag.
+
+**Full authoring guide: [`writing-an-adapter.md`](./writing-an-adapter.md)** — self-contained; written so an implementer (human or agent) needs no other source.
+
+## Packaging a language plugin
+
+Adapters are discovered via the ``cgir.languages`` entry-point group — no
+fork needed. A minimal plugin package:
+
+```toml
+# pyproject.toml of cgir-rust
+[project]
+name = "cgir-rust"
+dependencies = ["codegraph-ir", "tree-sitter-rust"]
+
+[project.entry-points."cgir.languages"]
+rust = "cgir_rust:RustAdapter"
+```
+
+```python
+# cgir_rust/__init__.py
+from cgir.languages.base import ADAPTER_API_VERSION, LanguageAdapter
+
+class RustAdapter(LanguageAdapter):
+    name = "rust"
+    file_extensions = (".rs",)
+    api_version = ADAPTER_API_VERSION
+    # implement: parse, locate_function, direct_effects, call_sites,
+    # function_body, block_statements, describe_statement,
+    # module_declarations — see GoAdapter for the most recent template.
+    # Optional (defaults provided): direct_effects_confidence,
+    # global_declared_names.
+```
+
+`pip install cgir-rust` and `cgir languages` shows it. Safety rules:
+builtins win extension conflicts; a plugin that fails to load, isn't a
+`LanguageAdapter`, or reuses a language name is skipped with a warning —
+a broken plugin never crashes cgir. An `api_version` mismatch warns but
+loads (new adapter methods get base-class defaults, so older plugins
+usually keep working).
+
+Start from `src/cgir/languages/go.py` — the newest adapter and the best
+template — and mirror `tests/unit/test_go_adapter.py` for the expected
+pipeline-level test coverage.

codegraph_ir-0.4.0/docs/lsp.md

@@ -0,0 +1,40 @@
+# LSP diagnostics — contract drift in your editor
+
+`cgir lsp` is a diagnostics-only language server: on every save it rescans
+the repo and publishes
+
+- **errors** for pin violations (`# cgir: pure` that isn't) — visible the
+  moment you open the workspace;
+- **warnings** for contract drift vs your previous save (the default
+  low-noise gate rules: effect gain/loss on net/fs/db, change pins).
+
+Side effect worth having: every refresh rewrites `.cgir`, so MCP, `pack`,
+and `impact` stay fresh while you edit.
+
+```bash
+uv tool install "codegraph-ir[lsp]"    # or add the lsp extra to your env
+```
+
+## Neovim
+
+```lua
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = { "python", "typescript", "go" },
+  callback = function()
+    vim.lsp.start({ name = "cgir", cmd = { "cgir", "lsp" },
+                    root_dir = vim.fs.root(0, ".cgir") or vim.fn.getcwd() })
+  end,
+})
+```
+
+## VS Code
+
+Use any generic LSP client extension (e.g. "LSP Proxy"/"Generic LSP
+Client") with command `cgir lsp`, or wire it into an existing extension's
+`serverCommand` setting. A dedicated extension is on the roadmap.
+
+## Latency honesty
+
+Each save triggers a full rescan (~0.5s small repos, ~3–5s large ones).
+Diagnostics update when the scan lands; per-component incremental analysis
+(docs/plan-0.3.md) is the planned fix.

codegraph_ir-0.4.0/docs/plan-0.3.md

@@ -0,0 +1,109 @@
+# Plan: 0.3 and beyond — trust, reach, and the developer loop
+
+Written 2026-07-12 as a durable handoff: any session (any model) should be
+able to pick up any thread from here. Prior art: `plan-0.2-0.4.md` (all
+landed), `gate-noise.md` (measured rule noise), `experiment-log.md`
+(benchmarks), `status.md` (what runs).
+
+## Shipped in the 0.3 cook (see git log 2026-07-12)
+
+1. **Hook UX** — blocked-commit message explains the staged-state trap
+   (`git restore -S -W <file>`), found dogfooding.
+2. **pre-commit framework integration** — `.pre-commit-hooks.yaml` so
+   `repo: llm-semantic-compilers` works in anyone's `.pre-commit-config.yaml`.
+3. **Agent onboarding** — `docs/agents.md`: the MCP config + CLAUDE.md/
+   AGENTS.md snippet teaching agents the protocol (search → pack → edit →
+   impact_of_change → verify).
+4. **go.mod cross-package resolution** — ingest reads the `module` directive
+   and stashes it on the Repository node; symbols strips the prefix from Go
+   import targets and binds the alias to the target *package directory*
+   (any module in it — the directory merge exposes all package members).
+5. **Confidence tiers on effects** — every effect tag carries provenance:
+   `high` (exact/prefix table match, import-alias verified) vs `lexical`
+   (bare suffix / receiver-name heuristics: `.now`, db-receiver gating).
+   New spec field `lexical_effects` (subset of `effects`). Gate rules
+   (`effect-gain`/`effect-loss`) fire on high-confidence tags by default;
+   `:any` suffix opts into lexical (e.g. `effect-gain:db:any`). This is the
+   systematic fix for the `self.now()` false-positive class measured in
+   gate-noise.md.
+
+## In flight: market-driven quick strikes (designed 2026-07-12)
+
+**A. Ranked, structured search** (`report/search.py`, pure over specs; MCP
+`search` delegates; new `cgir search` CLI command).
+
+- Free terms rank: exact name (100) > name-word (50) > id substring (20) >
+  entrypoint (15) > doc (5); sum across terms, sort desc, cap 25.
+- Structured predicates (colon syntax, AND-combined, mixable with terms):
+  `kind:pure_function` (alias `kind:pure`), `effects:net`, `effects:none`,
+  `lexical:true|false`, `callers:>3|0`, `calls:>5`, `pins:pure`,
+  `pinned:true`, `lang:go`, `entrypoint:true|HTTP`, `covered:false`.
+  Caller counts computed from the spec set (reverse of `calls`).
+- The moat angle: contract predicates no vector index can answer
+  ("effects:net lexical:false callers:>3").
+
+**B. Cycles + layers in `cgir lint`** (existing `[[rule]]` config).
+
+- `forbid-cycle = true` (+ `in` scope glob): Tarjan SCCs over the spec-level
+  call graph within scope; every SCC of size ≥2 is a violation naming the
+  cycle. Self-recursion (size-1) is NOT a violation — recursion is normal.
+- `layers = ["app.api.*", "app.core.*", "app.db.*"]` (top→bottom): a
+  component in a lower layer calling one in a higher layer is a violation
+  (dependencies must point down; same-layer calls fine; unmatched
+  components ignored).
+- Neutralizes the import-linter/ArchUnit objection using graph data we
+  already have — and our violations can say the edge *also* carries `net`.
+
+**C. Coverage-grounded test linkage** *(landed)* — `.coverage` (sqlite,
+numbits decoded via stdlib) / `coverage.json --show-contexts` per-test
+contexts mapped onto component spans, unioned with static linkage. On CGIR
+itself (pytest-cov --cov-context=test): components with test linkage went
+48 → 345 of 389 (12% → 89%). Hot components link many tests (integration
+tests execute the pipeline — accurate); pack embeds at most 5 test sources,
+impact --run keeps the full set. Staleness limit: an old .coverage may
+reference moved lines; static linkage is the floor.
+
+## Not built — next up, in value order
+
+1. **Per-component incremental analysis** (the latency lever). Watch/hook
+   re-scan everything (~0.5–4.5s). Design sketch: content-hash manifest
+   identifies changed files → re-ingest only those modules → recompute
+   analyses for changed components + their upstream closure
+   (`compute_typed_impact` IS the scoping machinery) → splice into the
+   cached graph. Correctness traps: effect closure is global (a leaf change
+   can flip distant orchestrators — the closure must be re-run over the
+   merged spec set, which is cheap since it's pure over specs); symbol
+   tables must be rebuilt when imports/decls change, else only call-graph
+   edges from changed files. Validate: randomized edit-replay equivalence
+   (incremental result == full-scan result on N random historical edits).
+2. **vitest/jest execution for `impact --run`** — runner detection from
+   package.json; currently prints the command for TS.
+3. **Go: struct-in-one-file/methods-in-another field DI** — the class-stub
+   merge (registry of package-level types before method attachment).
+4. **Data-shape v1.1** — full type text for Python fields (needs a second,
+   non-DI fields channel), literal-key fingerprints for un-annotated dict
+   returns, base-class field inheritance.
+5. **LSP diagnostics** — watch already computes live drift; publish as
+   editor diagnostics (pygls; diagnostics-only server, no completion).
+6. **`cgir decompose`** — the spec's long-term flagship (PDG-sliced
+   functional-core/imperative-shell suggestions + verify loop).
+7. **Marketplace listing** for the Action; badges; a demo GIF in README.
+
+## The developer loop (what "useful for me" means, concretely)
+
+The user's repos and their CGIR state:
+- **camera-tracking** (Py+TS): pins live on branch `cgir-pins`; pre-commit
+  hook INSTALLED on the repo (uses PATH cgir = uv tool). `.mcp.json` +
+  CLAUDE.md snippet added in this cook so agents use the semantic index.
+- **Indra** (Go): scans clean (301 components). Candidate for pins next.
+- **novel-chrome-extension** (TS/Angular): benchmark corpus, index at
+  ~/.cgir-indexes/novel-frontend.
+
+Daily loop: `cgir watch` in a terminal (live drift), agents route through
+MCP (`pack`/`impact`/`verify` instead of grep), the hook gates commits, CI
+gates PRs (Action), pins encode the invariants worth keeping.
+
+## Release discipline
+
+Tag-triggered trusted publishing (RELEASING.md). Bump BOTH version spots.
+The maintainer pushes tags — releases are a human decision.

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/docs/roadmap.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-**Active plan: [`plan-0.2-0.4.md`](./plan-0.2-0.4.md)** — pins/init/impact-run (0.2.0), data-shape contracts (0.3.0), Go adapter (0.4.0).
+**Active plan: [`plan-0.3.md`](./plan-0.3.md)** — trust (confidence tiers), reach (go.mod resolution, pre-commit, agents), and the incremental-analysis design. `plan-0.2-0.4.md` is fully landed.
 
 Forward-looking sequencing. The grouping mirrors `Code-IR.md` §Architecture: **P0** is "you can produce a `ComponentSpec`," **P1** is "you can trust it," **P2** is "you can scale it." Within each tier the order below reflects current dependencies, not strict chronology — feel free to interleave when dependencies allow.
 

{codegraph_ir-0.2.1 → codegraph_ir-0.4.0}/docs/status.md

@@ -71,6 +71,17 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 | `cgir impact --run` (execute the blast-radius tests via pytest node-ids) | done | `report/impact.py:runnable_selectors` |
 | Data-shape contracts (`types` diff section + opt-in `shape-change` rule; TS interfaces/type-aliases, Py TypedDict/dataclass) | done | `report/diff.py:_type_shape_changes`, `json_export.read_types` |
 | Go adapter (package=dir symbol merge, struct-field DI, panic≙raise, effects tables) | done | `src/cgir/languages/go.py` |
+| Go cross-package resolution (go.mod module-prefix strip; unique dir-suffix fallback) | done | `analyses/symbols.py:_resolve_go_package` |
+| Confidence tiers (`lexical_effects`; gates fire high-confidence by default, `:any` opts in; pack marks `tag?`) | done | `analyses/effects.py:classify_with_confidence` |
+| Global/nonlocal rebinding as mutation (`global_declared_names` hook) | done | `languages/base.py`, `analyses/cfg.py` |
+| pre-commit framework hook (`cgir-contract-check`) + agents guide | done | `.pre-commit-hooks.yaml`, `docs/agents.md` |
+| Ranked/structured search (`cgir search`, MCP `search`): term ranking + contract predicates (kind/effects/lexical/callers/pins/entrypoint/lang/covered) | done | `src/cgir/report/search.py` |
+| `forbid-cycle` (Tarjan SCCs) + `layers` rules in lint | done | `report/lint.py:_cycle_violations`, `_layer_violations` |
+| Coverage-grounded test linkage (.coverage/coverage.json contexts ∪ static; pack test sources capped) | done | `analyses/coverage_link.py` |
+| LSP diagnostics (`cgir lsp`, `cgir[lsp]` extra): pin violations as errors, gate drift as warnings, on save | done | `src/cgir/api/lsp_server.py`, `docs/lsp.md` |
+| Language plugin registry (`cgir.languages` entry points, `cgir languages`, ADAPTER_API_VERSION; builtins win conflicts, broken plugins degrade to warnings) | done | `languages/registry.py:discover_adapters` |
+| Adapter authoring guide, validated by a docs-only agent experiment (Rust adapter, 36/36, 9/9 bar; gaps folded back; PinIndex line_comment fix) | done | `docs/writing-an-adapter.md`, `examples/rust-adapter/` |
+| Rust adapter (structs+impl methods w/ field DI, use-tree imports, match/loop CFG, effect tiers; agent-written, reviewed+promoted) | done | `src/cgir/languages/rust.py` |
 | Entrypoint recognition (HTTP/CLI/task decorators) | done | `src/cgir/analyses/entrypoints.py` |
 | Context packer (`cgir pack`, budget-aware, type closure + docstrings + raises) | done | `src/cgir/report/pack.py` |
 | Docstring / raises / module-variable extraction | done | `tree_sitter_source._docstring_text`, `_raised_names`, `_add_module_variables` |
@@ -90,7 +101,7 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 
 ## Test coverage
 
-`pytest -q` runs 444 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
+`pytest -q` runs 541 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
 
 | File | Covers |
 |---|---|