feat: import-graph test impact, git_error for diff_impact, agent-oriented docs

- BFS import closure for get_impacted_tests/suggest_tests; storage importers/imported
- tool_coupling: numeric cochange/import/effective scores; diff_impact catches git failures
- Risk breakdown: coverage_fraction; schemas/cli/next_steps updates; tests
- README/CLAUDE/ARCHITECTURE/COMPLETE_PROJECT_DOCUMENTATION: solo multi-agent focus
- wiki-local/spec-project.md and CONTRIBUTING aligned with MCP contracts

Made-with: Cursor

Author: IronAdamant

ARCHITECTURE.md

@@ -2,7 +2,9 @@
 
 **Version:** 0.6.3 | **Python:** >= 3.11 | **Dependencies:** zero (stdlib only)
 
-Test impact analysis and code intelligence for LLM agents. Maps tests to code, code to git history, and answers: "what to run, what's risky, who touched it."
+Test impact analysis and code intelligence **for LLM agents**. The design target is **solo-maintained repos** where **multiple agent sessions or processes** (MCP clients, terminals, CI) may run `analyze` / read tools concurrently — hence **ProcessLock**, **WAL SQLite**, and **normalized paths** as core mechanics, not optional extras.
+
+Questions Chisel answers for agents: **what tests matter for a change**, **where risk concentrates**, **what’s untested or stale**, and **git/blame context** when debugging — not headcount or org workflows.
 
 ## Core Data Model
 
@@ -54,10 +56,10 @@ ChiselEngine (engine.py) — main orchestrator
   │     ├── Ownership aggregation from blame blocks
   │     └── Co-change coupling detection
   ├── ImpactAnalyzer (impact.py)
-  │     ├── Impacted tests (direct + transitive via coupling)
+  │     ├── Impacted tests (direct + co-change + import-graph reachability)
   │     ├── Risk scoring (5-component weighted formula)
   │     ├── Stale test detection (orphaned edge refs)
-  │     └── Reviewer suggestions (commit-activity-based)
+  │     └── Commit-activity hints (who_reviews; heuristic, not team routing)
   ├── AST Utils (ast_utils.py)
   │     ├── Multi-language extraction (12 languages)
   │     ├── Pluggable extractor registry (tree-sitter/LSP hooks)

CLAUDE.md

@@ -2,6 +2,14 @@
 
 Test impact analysis and code intelligence for LLM agents. Zero external dependencies.
 
+## Audience (how to read this project)
+
+- **Primary user**: autonomous and semi-autonomous **coding agents** (MCP, CLI invoked by agents), not a stand-alone dashboard for engineering managers.
+- **Typical human**: **solo developer** orchestrating multiple agent sessions, parallel tasks, or long-running analyses — *not* “hand off to another engineer” workflows. Tools like `ownership` / `who_reviews` expose **git-derived context** (blame, commit activity) for debugging and risk heuristics; they are not org-chart features.
+- **Multi-agent safety** (see `project.py`, `ProcessLock`, `RWLock`) exists so **several processes** (agents, terminals, CI) can share one `.chisel/` database without corrupting reads/writes — treat this as a **first-class product requirement**, not an edge case.
+
+When editing behavior or docs, prefer: **structured tool results**, **explicit statuses** (`no_data`, `no_changes`, `git_error`), **import-graph + test edges** over relying on git co-change alone, and **clear hints** when MCP would otherwise time out or mis-resolve `project_dir`.
+
 ## Architecture
 
 ```
@@ -34,9 +42,9 @@ chisel/
 - **Blame caching**: Cached by file content hash, invalidated on change.
 - **Incremental updates**: File content hashes tracked in `file_hashes` table.
 - **Persistent connection**: Storage uses a single SQLite connection (`check_same_thread=False`) with RWLock for thread safety.
-- **Multi-agent safety**: `project.py` provides: (1) `detect_project_root()` canonicalizes via git common dir so worktrees share identity, (2) `normalize_path()` ensures consistent relative paths, (3) `resolve_storage_dir()` defaults to project-local `.chisel/` (priority: explicit > env > project-local > ~/.chisel/), (4) `ProcessLock` for cross-process coordination — shared locks for reads, exclusive for writes. Cross-platform: `fcntl.flock` on Unix, `LockFileEx` on Windows.
+- **Multi-agent / multi-process safety** (solo dev + parallel agents): `project.py` provides: (1) `detect_project_root()` canonicalizes via git common dir so worktrees share identity, (2) `normalize_path()` ensures consistent relative paths, (3) `resolve_storage_dir()` defaults to project-local `.chisel/` (priority: explicit > env > project-local > ~/.chisel/), (4) `ProcessLock` for cross-process coordination — shared locks for reads, exclusive for writes — so concurrent agent runs and CLI `analyze`/`update` do not interleave destructive storage operations. Cross-platform: `fcntl.flock` on Unix, `LockFileEx` on Windows.
 - **SQLite concurrency**: 30s `busy_timeout` + exponential-backoff retry on `_execute` for cross-process SQLITE_BUSY.
-- **Ownership vs Reviewers**: `ownership` = blame-based (who wrote the code, `role: "original_author"`). `who_reviews` = commit-activity-based (who maintains it, `role: "suggested_reviewer"`).
+- **Ownership vs Reviewers**: `ownership` = blame-based (`role: "original_author"`). `who_reviews` = commit-activity-based (`role: "suggested_reviewer"`). Both are **git-derived signals** for agents (lineage, hot spots); they are not substitutes for team assignment in a solo workflow.
 - **Shared constants**: `_SKIP_DIRS` and `_EXTENSION_MAP` live in `ast_utils.py`. `_CODE_EXTENSIONS` in `engine.py` is derived from `_EXTENSION_MAP`. `_SKIP_DIRS` includes `coverage`, `.next`, `.nuxt` to exclude build/test output artifacts.
 - **Shared dispatch**: `dispatch_tool()` in `mcp_server.py` is used by both HTTP and stdio servers. Tool schemas and dispatch tables live in `schemas.py`.
 - **Edge weighting**: Test edges carry a weight (0.4-1.0) based on file proximity. `_compute_proximity_weight()` in `test_mapper.py`.

COMPLETE_PROJECT_DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # Chisel -- Complete Project Documentation
 
-Test impact analysis and code intelligence for LLM agents. Zero external dependencies.
+Test impact analysis and code intelligence for **LLM agents** in **solo-maintainer** workflows, with **multi-process / multi-agent** safety (shared `.chisel/` storage, locks). Zero external dependencies.
 
 **Version:** 0.6.2
 **PyPI:** `chisel-test-impact`
@@ -35,7 +35,7 @@ Test impact analysis and code intelligence for LLM agents. Zero external depende
 | `chisel/metrics.py` | Pure computation: churn scoring, ownership aggregation, co-change detection | `collections`, `datetime`, `itertools` | [glossary: churn score](wiki-local/glossary.md) |
 | `chisel/test_mapper.py` | Test file discovery, framework detection (pytest/Jest/Go/Rust/Playwright), dependency extraction, test edge building | `ast`, `os`, `re`, `pathlib`, `chisel.ast_utils`, `chisel.project` | [glossary: test edge](wiki-local/glossary.md) |
 | `chisel/impact.py` | Impact analysis, risk scoring, stale test detection, ownership queries, reviewer suggestions | `collections`, `datetime`, `chisel.metrics`, `chisel.storage` (via constructor injection) | [glossary: risk score](wiki-local/glossary.md) |
-| `chisel/project.py` | Multi-agent safety: project root detection (worktree-aware), path normalization, storage dir resolution, cross-platform file lock (ProcessLock) | `os`, `subprocess`, `sys`, `contextlib`; Unix: `fcntl`; Windows: `ctypes`, `msvcrt` | -- |
+| `chisel/project.py` | Multi-process / multi-agent safety: project root detection (worktree-aware), path normalization, storage dir resolution, cross-platform file lock (ProcessLock) for concurrent agents and CLI | `os`, `subprocess`, `sys`, `contextlib`; Unix: `fcntl`; Windows: `ctypes`, `msvcrt` | -- |
 | `chisel/engine.py` | Orchestrator -- owns Storage, GitAnalyzer, TestMapper, ImpactAnalyzer, RWLock, ProcessLock; exposes `tool_*()` methods for all 15 MCP tools | `os`, `chisel.ast_utils`, `chisel.git_analyzer`, `chisel.impact`, `chisel.project`, `chisel.rwlock`, `chisel.storage`, `chisel.test_mapper` | [spec-project](wiki-local/spec-project.md) |
 | `chisel/cli.py` | argparse CLI with 17 subcommands, dispatch table, output formatting | `argparse`, `json`, `os`, `chisel.engine` | [spec-project: CLI](wiki-local/spec-project.md) |
 | `chisel/mcp_server.py` | HTTP MCP server (GET /tools, /health; POST /call), ThreadedHTTPServer, shared `dispatch_tool()` | `json`, `logging`, `threading`, `http.server`, `socketserver`, `chisel.engine`, `chisel.schemas` | [spec-project: MCP tools](wiki-local/spec-project.md) |

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing to Chisel
 
+Chisel is built for **LLM agents** and **solo developers** running **multiple agent sessions** on one repo. Contributions should preserve: **stdlib-only runtime**, **structured MCP responses** (status dicts, `next_steps` where applicable), **multi-process safety** (locks around storage), and **import-graph + test edges** as primary signals when git co-change is thin.
+
 ## Prerequisites
 
 - Python 3.11 or later
@@ -18,7 +20,7 @@ This installs Chisel in editable mode along with dev dependencies (pytest, pytes
 ## Running Tests
 
 ```bash
-pytest tests/ -v --tb=short     # full suite (567 tests)
+pytest tests/ -v --tb=short     # full suite
 pytest tests/test_engine.py     # single module
 pytest -k "test_risk"           # by name pattern
 ```
@@ -37,25 +39,26 @@ Configuration lives in `pyproject.toml` under `[tool.ruff]`.
 
 ## Architecture Overview
 
-See `CLAUDE.md` for the full module map and dependency graph, and `ARCHITECTURE.md` for detailed design documentation.
+See `CLAUDE.md` for the full module map and dependency graph, `ARCHITECTURE.md` for the data model, and `wiki-local/spec-project.md` for MCP tool contracts.
 
 The core modules are:
 
 | Module | Role |
 |---|---|
-| `engine.py` | Orchestrator; owns all subsystems |
+| `engine.py` | Orchestrator; owns all subsystems; `tool_*()` for MCP |
 | `storage.py` | SQLite persistence (WAL mode, single persistent connection, batch queries) |
 | `ast_utils.py` | Multi-language AST extraction (12 languages) + pluggable extractor registry |
 | `git_analyzer.py` | Git log/blame parsing via subprocess |
 | `metrics.py` | Pure computation: churn scoring, ownership, co-change detection |
 | `test_mapper.py` | Test discovery, framework detection, dependency extraction, edge building |
-| `impact.py` | Impact analysis, risk scoring, stale test detection, reviewer suggestions |
-| `project.py` | Project root detection, path normalization, cross-platform ProcessLock |
-| `schemas.py` | JSON Schema definitions for all 15 tools + dispatch table |
-| `cli.py` | argparse CLI (17 subcommands) |
-| `mcp_server.py` | HTTP MCP server |
+| `impact.py` | Impact analysis (direct + co-change + import-graph tests), risk scoring, stale tests, git-derived ownership/review hints |
+| `project.py` | Project root, path normalization, **ProcessLock** (multi-process / multi-agent) |
+| `schemas.py` | JSON Schema + dispatch for **22 MCP tools** (core + advisory file locks) |
+| `next_steps.py` | Contextual follow-up hints for agent clients |
+| `cli.py` | argparse CLI (core tools + serve + lock subcommands) |
+| `mcp_server.py` | HTTP MCP server (`dispatch_tool`, `next_steps`) |
 | `mcp_stdio.py` | stdio MCP server |
-| `rwlock.py` | Read-write lock for concurrent access |
+| `rwlock.py` | In-process read/write lock (pairs with ProcessLock) |
 
 ## Guidelines
 
@@ -82,12 +85,14 @@ Do not add runtime dependencies.
 
 ### Adding a New MCP Tool
 
-To add a new tool, wire it through four layers:
+To add a new tool, wire it through these layers:
+
+1. **Engine method**: Add `tool_<name>(self, ...)` in `engine.py`. Wrap with `self._process_lock.shared()` + `self.lock.read_lock()` for reads, or `exclusive()` + `write_lock()` for writes. Prefer **explicit statuses** (`no_data`, `git_error`, etc.) over ambiguous empty lists for agents.
+2. **Schema + dispatch**: Add the tool schema to `_TOOL_SCHEMAS` and the dispatch entry to `_TOOL_DISPATCH` in `schemas.py`. Use **prescriptive** descriptions (“Use when…”). Both HTTP and stdio servers import these automatically; HTTP responses include **`next_steps`** — add a handler in `next_steps.py` if the new tool should suggest follow-ups.
+3. **CLI handler**: Add a subcommand in `cli.py` when the tool should be human-invokable from the terminal (optional for agent-only tools).
+4. **Tests**: Add tests in `tests/` — at minimum an engine integration test; add CLI tests if you added a subcommand.
 
-1. **Engine method**: Add `tool_<name>(self, ...)` in `engine.py`. Wrap with `self._process_lock.shared()` + `self.lock.read_lock()` for reads, or `exclusive()` + `write_lock()` for writes.
-2. **Schema + dispatch**: Add the tool schema to `_TOOL_SCHEMAS` and the dispatch entry to `_TOOL_DISPATCH` in `schemas.py`. Both HTTP and stdio servers import these automatically.
-3. **CLI handler**: Add a subcommand in `cli.py` that calls the engine method and formats output.
-4. **Tests**: Add tests in `tests/` — at minimum an engine integration test and a CLI mock test.
+Keep **multi-agent safety** in mind: long-running writes (`analyze`, `update`) must stay under the process exclusive lock; readers should not block writers longer than necessary.
 
 ### Adding a Custom Extractor
 

LLM_Development.md

@@ -4,6 +4,16 @@ Chronological record of development activity on the Chisel project.
 
 ---
 
+## 2026-03-27 -- Product re-orientation (agentic + multi-agent solo)
+
+### Summary
+Re-oriented README, CLAUDE.md, ARCHITECTURE.md, and COMPLETE_PROJECT_DOCUMENTATION.md toward **LLM agents** and **solo developers** running **multiple agent sessions** — emphasizing MCP-first usage, multi-process safety (locks, shared storage), and reframing git-derived “ownership” / “reviewer” tools as audit/heuristic signals rather than team workflows. Updated ecosystem and coupling copy to center import-graph and structured tool results.
+
+### Follow-up
+Aligned **`wiki-local/spec-project.md`** (tool specs, 22 tools, import-graph impact, `triage`, locks, `next_steps`, `git_error`) and **`CONTRIBUTING.md`** (agent/solo preamble, architecture table, MCP/tool wiring guidance) to the same positioning.
+
+---
+
 ## v0.6.2 -- 2026-03-22 -- Scale Validation on Grafana (21k files)
 
 ### Summary

README.md

@@ -1,18 +1,24 @@
 # Chisel
 
-Test impact analysis and code intelligence for LLM agents.
+Test impact analysis and code intelligence **built for LLM agents** — especially when **several agents or sessions** touch the same repo (solo developer, multi-agent workflow).
 
-Chisel maps tests to code, code to git history, and answers: **"what to run, what's risky, who touched it."**
+Chisel maps tests to code, code to git history, and answers: **what to run, what’s risky, and where attention should go** — including blame-based lineage when you need audit context (not “team roster” features).
 
 ![Chisel analyzing a real project — risk map, churn, ownership, test gaps, and agent interpretation](docs/chisel-demo.png)
 
+## Who this is for
+
+- **Solo developers** using Cursor, Claude Code, or other MCP clients — not a substitute for human code review queues.
+- **Multi-agent usage**: parallel agent runs, background tasks, or sequential sessions that share one project. Chisel keeps **one consistent graph** (project-local `.chisel/` storage, cross-process locks) so agents don’t corrupt analysis mid-write.
+- **Primary interface**: MCP tools and structured responses (`next_steps`, diagnostic statuses), not dashboards for managers.
+
 ## The Problem
 
 An LLM agent changes `engine.py:store_document()`. It then either:
 - Runs **all** 287 tests (slow, wasteful), or
 - Guesses with `-k "test_store"` (misses regressions)
 
-When multiple agents (or agents + humans) work on the same codebase, changes in one area silently break another. Chisel gives agents the intelligence to understand the blast radius of their changes before they commit.
+When **multiple agent runs** (or agents plus you) work on the same codebase, changes in one area can break another. Chisel gives each agent **test impact, import-aware suggestions, and risk signals** so they narrow what to run and where regressions may hide — before you merge or ship.
 
 ## Install
 
@@ -51,7 +57,7 @@ Or run the HTTP server for any MCP-compatible client:
 chisel serve --port 8377
 ```
 
-Once connected, Claude Code can use all 15 tools directly — `analyze`, `diff_impact`, `suggest_tests`, `risk_map`, and more. Run `analyze` first to build the project graph, then `diff_impact` before each commit to know exactly which tests to run.
+Once connected, agents can call the full tool surface — `analyze`, `diff_impact`, `suggest_tests`, `risk_map`, `triage`, and more. Run `analyze` first to build the project graph, then `diff_impact` after edits to narrow which tests to run. For long analyses on large repos, prefer `chisel analyze` / `chisel update` in a terminal so MCP clients don’t time out.
 
 ## Use with Cursor / Other MCP Clients
 
@@ -109,25 +115,28 @@ chisel test-gaps
 chisel stats
 ```
 
-## 15 Tools
+## MCP tools (core)
+
+Core query and write tools below; the MCP server also exposes **advisory file-lock** helpers for multi-process coordination. See `schemas.py` / `chisel serve` for the full list.
 
 | Tool | What it does |
 |------|-------------|
 | `analyze` | Full project scan — code units, tests, git history, edges |
 | `update` | Incremental re-analysis of changed files only |
 | `impact` | Which tests cover these files/functions? |
 | `diff_impact` | Auto-detect changes from `git diff`, return impacted tests |
-| `suggest_tests` | Rank tests by relevance + historical failure rate |
+| `suggest_tests` | Rank tests by relevance (edges, co-change, import graph) + failure rate |
 | `churn` | How often does this file/function change? |
-| `ownership` | Who wrote this code? (blame-based) |
-| `who_reviews` | Who maintains this code? (commit-activity-based) |
-| `coupling` | What files always change together? |
+| `ownership` | Blame-based authors (useful for audit / “who wrote this line”) |
+| `who_reviews` | Recent commit activity on the file (heuristic “hot spots”, not org chart) |
+| `coupling` | Co-change partners + **import-graph** neighbors and numeric scores |
 | `risk_map` | Risk scores for all files (churn + coupling + coverage gaps) |
 | `stale_tests` | Tests pointing at code that no longer exists |
 | `test_gaps` | Code units with zero test coverage, sorted by risk |
 | `history` | Commit history for a specific file |
 | `record_result` | Record test pass/fail for future prioritization |
 | `stats` | Database summary counts |
+| `triage` | Composite: top risk + gaps + stale tests in one call |
 
 ## Features
 
@@ -142,19 +151,19 @@ chisel stats
 
 ## Ecosystem
 
-Chisel works standalone or alongside [Stele](https://github.com/IronAdamant/Stele) for multi-agent code coordination. Chisel handles test intelligence; Stele handles document-level context and conflict prevention.
+Chisel is designed to sit **in the agent loop** (MCP): impact → tests → record results → refresh analysis. It works standalone or alongside tools like [Stele](https://github.com/IronAdamant/Stele) for semantic code context — Chisel stays focused on **test graph, git signals, and static imports** for blast-radius reasoning.
 
 ## Design Notes
 
 ### Coupling: co-change vs. import-graph
 
-Chisel's `coupling` tool has two coupling sources:
+Chisel's `coupling` tool exposes two coupling sources:
 
-1. **Co-change coupling** (`co_change_partners`) — files that frequently appear in the same git commits. This signal requires **multiple agents or multiple human collaborators** making separate commits. In solo-agent workflows, there is no co-change signal and this returns 0.0.
+1. **Co-change coupling** (`co_change_partners`) — files that often appear in the same git commits. Stronger when **history has many small commits** (including a solo dev committing often, or multiple agents landing separate commits). Sparse history → thin co-change signal.
 
-2. **Import-graph coupling** (`import_partners`) — static `import`/`require` edges between source files. This works in any project and provides structural coupling data even when co-change is absent.
+2. **Import-graph coupling** (`import_partners`, plus numeric `import_coupling` / `effective_coupling`) — static `import`/`require` edges. **Always available** after analysis and is the main structural signal for single-author repos.
 
-When co-change is 0.0, import coupling still provides meaningful structural data. The `risk_map` tool uses the maximum of the two coupling sources.
+`risk_map` and impact tools combine both; import graph also powers **transitive test suggestions** (e.g. facade tests covering inner modules).
 
 ### Coverage Gap: Graduated Scoring