devcouncil 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +112 -214
  2. package/package.json +17 -3
package/README.md CHANGED
@@ -1,4 +1,6 @@
1
- # DevCouncil: Components and Modules for AI Development
1
+ # DevCouncil
2
+
3
+ Code intelligence and verification components for AI development.
2
4
 
3
5
  [![Website](https://img.shields.io/badge/website-devcouncil.vbcr.dev-10B981?style=flat&logo=safari&logoColor=white)](https://devcouncil.vbcr.dev/)
4
6
  [![CI](https://github.com/bharathvbcr/DevCouncil/actions/workflows/ci.yml/badge.svg)](https://github.com/bharathvbcr/DevCouncil/actions/workflows/ci.yml)
@@ -29,7 +31,7 @@ DevCouncil's core runtime is a set of standalone, compiled native modules. Each
29
31
  | Binary | Language | Role & Ownership |
30
32
  |--------|----------|------------------|
31
33
  | `devcouncil` / `dev` | **Go** | Host orchestrator: Stdio MCP server (`mcp`), multi-host agent integration (`integrate`), engineering skills distribution (`skills`), task verification (`verify`), and devmap forwarding (`map`, `graph`, `ast`). |
32
- | `devmap` | **Rust** | Code intelligence engine: 36+ tree-sitter language extractors, symbol resolution, blast-radius calculation, dead-code analysis, workspace guides (`AGENTS.md`), and DevMap MCP server (`devmap mcp`). |
34
+ | `devmap` | **Rust** | Code intelligence engine: Language-aware tree-sitter extraction and explicit fallback/coverage reporting, symbol resolution, blast-radius calculation, dead-code analysis, workspace guides (`AGENTS.md`), and DevMap MCP server (`devmap mcp`). |
33
35
  | `dcstore` | **Rust** | State & lease store: SQLite-backed task repository, mutual-exclusion leases for concurrent agent building, evidence records, and gap tracking. |
34
36
  | `dcverify` | **Rust** | Deterministic verification: Unified-diff parsing, planned file scope classification, anti-laziness/stub gates, test coverage evaluation, and typed `next_actions` repair signals. |
35
37
  | `dcgrep` | **Rust** | Code search: Ripgrep-powered ignore-aware search engine with optional trigram indexing (`tgrep-core`). |
@@ -45,240 +47,136 @@ DevCouncil's core runtime is a set of standalone, compiled native modules. Each
45
47
 
46
48
  ---
47
49
 
48
- ## Installation
50
+ ## Benchmarks: DevMap vs Graphify, Gortex, GitNexus, CodeGraph, and codebase-memory-mcp
51
+
52
+ Six code-graph tools plus a ripgrep text baseline, measured on **four
53
+ repositories** (595 to 4,335 files, mixing Rust, Go, TypeScript, Python and
54
+ Swift) on one Apple M5 Pro. Every timing is a minimum or median from a
55
+ reproducible run with the raw evidence committed beside it — not a marketing
56
+ estimate. Head-to-head breakdown:
57
+ **[DevMap vs GitNexus, CodeGraph, Graphify, Gortex, and codebase-memory-mcp](docs/devmap/comparison.md)**.
58
+ Full method, caveats, and raw output:
59
+ **[benchmark report](benchmarks/results/competition/20260914-v0.2.2/REPORT.md)**.
60
+
61
+ **DevMap 0.2.2 was fastest on most of what was measured:** cold indexing and
62
+ unchanged refresh on **all four repositories**, the lowest median in **all six
63
+ symbol-query cells**, and **5/5** source-inspected caller pairs — matched only
64
+ by codebase-memory-mcp.
65
+
66
+ Detailed table on the 1,098-file DevCouncil corpus, where the correctness and
67
+ query campaign also ran:
68
+
69
+ | Tool | Cold index | Unchanged refresh | Single-file edit | Definition lookup | Peak RSS | Caller pairs found |
70
+ |---|---:|---:|---:|---:|---:|---:|
71
+ | **DevMap 0.2.2** | **2.012 s** | **0.089 s** | 0.816 s | **9.7 ms** | **678 MiB** | **5/5** |
72
+ | CodeGraph 1.6.0 | 3.294 s | 0.235 s | **0.512 s** | 101–106 ms | 2430 MiB | 3/5 |
73
+ | codebase-memory-mcp 0.10.8 | 9.357 s | 5.726 s | 8.894 s | ~3.94 s | — | **5/5** |
74
+ | Graphify 0.9.59 | 14.989 s | 5.080 s | 4.883 s | 557–572 ms | 3417 MiB | 3/5 |
75
+ | GitNexus 1.6.9 | 33.689 s | 0.699 s | 31.841 s | 792–808 ms | 3355 MiB | 3/5 |
76
+ | Gortex 0.64.3 | 16.5 s to query-ready | — | — | 92–104 ms | — | 4/5 |
77
+
78
+ **Where DevMap won.** Fastest cold index on all four corpora (**1.6–21×** the
79
+ competitors' time) and fastest unchanged refresh on all four (**2.2–107×**).
80
+ Lowest median in all six query cells — definition lookups at 9.7 ms, **~10×
81
+ faster than CodeGraph** and **~82× faster than GitNexus**. Lowest sampled peak
82
+ memory on three of four corpora. All five source-inspected caller pairs, and a
83
+ clean result on both index-staleness probes.
84
+
85
+ **Where DevMap lost.** CodeGraph re-indexes a single edited file faster **on
86
+ every corpus** — DevMap takes 1.08× its time on the smallest and **3.61×** on
87
+ GitPulse. That is the one stage where a competitor is consistently ahead.
88
+ DevMap's store is 1.6–2.0× CodeGraph's and 2.8–4.7× Graphify's, and Graphify
89
+ used **less memory than DevMap on the largest repository** (1,458 MB vs
90
+ 1,725 MB). Against v0.2.1, unchanged refresh regressed ~12% on the smallest
91
+ corpus.
92
+
93
+ **What these numbers are not.** Four repositories, one machine, three-to-five
94
+ repetitions, three symbols, and five inspected caller pairs. They do not
95
+ establish general graph accuracy, persistent-MCP latency, or coding-agent task
96
+ success. Tool output scopes differ, so equal latency is not equal analysis.
97
+ DevMap itself reports 106,217 unexplained call-attribution sites on this corpus.
98
+ The report states every limit explicitly and keeps the failures in — including
99
+ GitNexus serving a deleted symbol through two ordinary refreshes until a forced
100
+ rebuild.
49
101
 
50
- DevCouncil supports macOS, Linux, and Windows. Requires a Go toolchain (`>=1.22`), Rust/`cargo`, and Git.
102
+ ---
51
103
 
52
- ### 1. Build and Install Native Binaries
104
+ ## Get started
53
105
 
54
- From a clone of this repository:
106
+ Build just DevMap from source, then map a project:
55
107
 
56
108
  ```bash
57
- # macOS & Linux: builds Go host and all Rust analysis binaries into ~/.local/bin
58
- bash scripts/install.sh
59
-
60
- # Standalone DevMap (no Go host)
109
+ git clone https://github.com/bharathvbcr/DevCouncil.git
110
+ cd DevCouncil
61
111
  bash scripts/install.sh --only=devmap
62
-
63
- # Analysis suite only (devmap dcstore dcverify dcgrep)
64
- bash scripts/install.sh analysis
65
-
66
- # Windows (PowerShell):
67
- .\scripts\install.ps1
68
- .\scripts\install.ps1 -Components devmap
69
- ```
70
-
71
- To build and install the analysis components (`devmap`, `dcstore`, `dcverify`, `dcgrep`):
72
-
73
- ```bash
74
- # Build & install all analysis components to ~/.local/bin
75
- bash scripts/install-components.sh
76
-
77
- # Or install specific components
78
- bash scripts/install-components.sh devmap
79
- bash scripts/install-components.sh dcstore dcverify dcgrep
80
-
81
- # Build the Go host binary
82
- go -C backend/go_orchestrator build -o ~/.local/bin/devcouncil ./cmd/devcouncil
83
- ln -sf devcouncil ~/.local/bin/dev
84
- ```
85
-
86
- Ensure `~/.local/bin` is in your `PATH`:
87
-
88
- ```bash
89
112
  export PATH="$HOME/.local/bin:$PATH"
90
- ```
91
-
92
- ### 2. Optional Global npm Shim
93
113
 
94
- If you prefer to dispatch through npm, install the lightweight Node.js wrapper (Node 18+). The npm package ships a shim that resolves and executes the native binaries:
95
-
96
- ```bash
97
- npm install -g devcouncil
98
- ```
99
-
100
- ### 3. Verify Environment
101
-
102
- ```bash
103
- devcouncil --help
104
- dev --help
105
- devmap --version
106
- dcverify health
107
- dcstore --db .devcouncil/state.sqlite health
108
- dcgrep health
114
+ cd /path/to/your/project
115
+ devmap build --manifest --guides
116
+ devmap paths --json
117
+ devmap status --json
118
+ devmap explore MyFunction --json
109
119
  ```
110
120
 
111
- ---
112
-
113
- ## Core Capabilities & Workflows
121
+ Git and Rust/Cargo are required. To include the Go host and full analysis suite,
122
+ run `bash scripts/install.sh`; the host needs the toolchain declared in
123
+ [`go.mod`](backend/go_orchestrator/go.mod), currently Go 1.26.6. On Windows use
124
+ `.\scripts\install.ps1 -Components devmap`, or omit `-Components` for the suite.
125
+ The npm package is a lightweight launcher for native binaries, not a bundled
126
+ runtime. [Complete installation guide](docs/quickstart.md).
114
127
 
115
- ### 1. Coding Agent Integration (`devcouncil integrate`)
128
+ Use the paths returned by `devmap paths`: new repositories default to `.devmap`,
129
+ existing `.devcouncil` layouts remain supported, and explicit configuration can
130
+ override either. `--guides` requests managed workspace guides separately from
131
+ the map export. Check freshness, coverage gaps and result truncation before
132
+ using graph answers as evidence. If first-time guide creation leaves status
133
+ stale, run `devmap build --manifest` once more to index the new guides.
116
134
 
117
- Connect DevCouncil's MCP server to Cursor or Claude Code. `--write-gate` has been removed: it named a pre-tool-use gate that only the retired lifecycle hooks installed, and nothing enforced it. Use `dev hook status` to inspect old registrations and `dev hook disable --dry-run` to preview cleanup.
135
+ ## Connect an agent
118
136
 
119
137
  ```bash
120
- devcouncil integrate cursor --apply
121
- devcouncil integrate claude --apply
122
-
123
- # Stub receipt only — not a working installer:
124
- # devcouncil integrate antigravity --apply
125
-
126
- # Verify existing integration configuration
127
- devcouncil integrate cursor --check
138
+ devmap integrate cursor --dry-run
139
+ devmap integrate cursor
140
+ devmap integrate cursor --check
128
141
  ```
129
142
 
130
- ### 2. Engineering Skills Delivery (`devcouncil skills`)
131
-
132
- Deliver verified engineering practices and code-intelligence skills directly into agent skill folders (`.agents/skills`, `.claude/skills`, `.cursor/skills`):
133
-
134
- ```bash
135
- # List available skills embedded in the binary
136
- devcouncil skills list
137
-
138
- # Scaffold all applicable skills into the repository
139
- devcouncil skills scaffold
140
-
141
- # Scaffold a specific skill (e.g. core-engineering or devmap)
142
- devcouncil skills scaffold --skill core-engineering
143
- devcouncil skills scaffold --skill devmap
144
- ```
143
+ Substitute `claude`, `codex`, `antigravity`, `opencode` or `warp` for `cursor`.
144
+ Integration can update user-level MCP settings as well as project assets.
145
+ Inspect the receipt and complete host reload/trust steps. For task tooling,
146
+ add the Go-host integration described in
147
+ [coding CLI integration](docs/coding-cli-integration.md).
145
148
 
146
- ### 3. Repository Mapping & Code Intelligence (`devmap` / `dev map`)
149
+ ## Verification is opt-in
147
150
 
148
- Build and query deep semantic relationships across your codebase without an LLM:
151
+ For an existing task in an initialized `.devcouncil/state.sqlite`:
149
152
 
150
153
  ```bash
151
- # Build the repository map (.devcouncil/repo_map.json) and code graph
152
- devmap build --manifest
153
-
154
- # Shorthand via the Go host:
155
- dev map
156
-
157
- # Query symbol blast radius & reverse dependents before editing
158
- devmap impact path/to/file.go
159
-
160
- # Trace dependency paths between two symbols
161
- devmap trace SymbolA SymbolB
162
-
163
- # Find dead code with confidence tiers (extracted | inferred | ambiguous)
164
- devmap dead
165
-
166
- # Launch the interactive HTML visualizer
167
- devmap view
168
- ```
169
-
170
- ### 4. Task Leases & Gated Verification (`devcouncil verify`)
171
-
172
- Prevent multi-agent file trampling and verify diff correctness against deterministic criteria:
173
-
174
- ```bash
175
- # Run deterministic verification against a task's diff
176
- devcouncil verify TASK-001
177
-
178
- # Machine-readable output for agent loops
179
- devcouncil verify TASK-001 --json
180
-
181
- # Sandbox flag is recorded only; docker/nix do not isolate (TASK-P7-2)
182
- devcouncil verify TASK-001 --sandbox local
183
- ```
184
-
185
- Verification today (Go `verify.Run()`) enforces:
186
- - **Planned file scope:** Rejects unauthorized edits outside declared task boundaries.
187
- - **Orphan diffs / dependency-risk:** Flags files changed that were not planned.
188
- - **Expected tests / allowed commands:** Runs the task's command list via `/bin/sh -c` in the project root.
189
- - **Typed `next_actions`:** Structured repair instructions when those gates fail.
190
-
191
- Stub detection, secret scanning, and coverage intersection live in the **`dcverify`** binary. `devcouncil verify`, MCP `devcouncil_verify_task`, and **Manvi** `runRigor` all spawn it. When `dcverify` is not installed the report carries an empty `rigor_applied` **and** a `rigor_skipped_reason` naming what to install — never a silent clean pass. Diff↔coverage runs only when a profile is supplied (`devcouncil verify --coverage PATH`); otherwise `coverage_skipped_reason` says so.
192
-
193
- ### 5. MCP Servers for AI Agents
194
-
195
- DevCouncil provides two complementary Model Context Protocol (MCP) servers:
196
-
197
- - **Host MCP Server (`devcouncil mcp`)**: Eight tools — checkout / renew / release / next_task / get_diff / verify_task / get_gaps / policy_check_write. `verify_task` runs Go `verify.Run()`, which spawns `dcverify` for the stub and secret gates; diff↔coverage needs a profile this tool has no field for, so use `devcouncil verify --coverage PATH`.
198
- - **DevMap MCP Server (`devmap mcp`)**: Eleven query tools (status, search, dependencies, impact, trace, neighbors, dead_symbols, clones, preview, explore, affected_tests). Always pass `repo_path`.
199
-
200
- ---
201
-
202
- ## Architecture Flow
203
-
204
- ```mermaid
205
- flowchart TD
206
- subgraph Agents["Harnesses, hosts, and coding agents"]
207
- Claude["Claude Code"]
208
- Cursor["Cursor"]
209
- Codex["Codex"]
210
- AGY["Antigravity"]
211
- Warp["Warp"]
212
- Manvi["Manvi (wraps these components)"]
213
- GitPulse["GitPulse (selects modules)"]
214
- end
215
-
216
- subgraph Host["Go Host Orchestrator (devcouncil / dev)"]
217
- CLI["Host CLI\ncmd/devcouncil"]
218
- MCP["Host MCP Server\ndevcouncil mcp"]
219
- Integ["Integrator\ndevcouncil integrate"]
220
- Skills["Skills Engine\ndevcouncil skills"]
221
- VerifyCmd["Verify Command\ndevcouncil verify"]
222
- end
223
-
224
- subgraph RustAnalysis["Rust Analysis & State Suite"]
225
- DevMap["devmap\nCode Graph & 36+ Language ASTs"]
226
- DCStore["dcstore\nAtomic Task Leases & SQLite Store"]
227
- DCVerify["dcverify\nUnified Diff Parser & Rigor Gates"]
228
- DCGrep["dcgrep\nRipgrep Engine & Trigram Index"]
229
- end
230
-
231
- Agents <-->|MCP Protocol| MCP
232
- Agents <-->|Direct / Tool Calls| CLI
233
- Manvi -->|Wraps: imports Go, spawns binaries| Host
234
- Manvi -->|Spawns selected modules| RustAnalysis
235
- GitPulse -->|Vendors selected crates| DevMap
236
- GitPulse -->|manvi serve| Manvi
237
-
238
- CLI -->|Execs| DevMap
239
- CLI -->|Integrates| Integ
240
- CLI -->|Scaffolds| Skills
241
- VerifyCmd -->|Scope, orphan, expected tests| DCStore
242
- Manvi -->|Spawns dcverify rigor| DCVerify
243
-
244
- MCP -->|Leases and tasks| DCStore
245
- MCP -->|verify_task → Go Run| VerifyCmd
246
- ```
247
-
248
- ---
249
-
250
- ## Repository Layout
251
-
252
- ```
253
- DevCouncil/
254
- ├── backend/go_orchestrator/ # Go host orchestrator binary and packages
255
- │ ├── cmd/devcouncil/ # Main entrypoint for devcouncil and dev
256
- │ ├── devcouncil/ # MCP server, integrate, skills, verify implementations
257
- │ ├── dc/store/ # Interop client for dcstore binary
258
- │ └── policy/ # File-write containment & security policies
259
- ├── rust/ # Analysis and verification engine crates (dcstore, dcverify, dcgrep, devmap)
260
- ├── bin/ # Node.js npm shim (bin/devcouncil.js)
261
- ├── scripts/ # Platform installers (install.sh, install-components.sh)
262
- └── docs/ # Architecture, releases, and integration guides
154
+ devcouncil verify TASK-001 --mode enforce --json
263
155
  ```
264
156
 
265
- ---
157
+ Read gate mode, skipped reasons and coverage metadata. The Go host invokes
158
+ `dcverify` for rigor checks; changed-line coverage requires a profile supplied
159
+ through `--coverage PATH`. The default gate mode is `off`. Task leases and MCP
160
+ policy results coordinate participating clients; retired lifecycle hooks do
161
+ not intercept arbitrary shell commands or editor writes. The sandbox selector
162
+ does not implement Docker/Nix isolation. See the
163
+ [task loop contract](docs/hero-loop.md).
266
164
 
267
165
  ## Documentation
268
166
 
269
- - [Release Notes (v0.2.0)](docs/releases/v0.2.0.md): Native orchestration and analysis migration.
270
- - [Native cutover follow-ups](docs/TODO.md): Open wiring and honesty work after Phase 7.
271
- - [Architecture Decisions & Python Retirement](docs/PHASE7_LONG_TAIL.md): Background on the transition to native Go and Rust binaries.
272
- - [Archived ledgers](docs/archive/README.md): Pre-cutover DevMap plans, audits, and qualification dumps.
273
- - [Code Graph & DevMap Guide](docs/code-graph.md): Symbol resolution, dead code, and blast radius.
274
- - [DevMap competitor benchmarks](docs/devmap/README.md#benchmark-comparison): Measured strengths, weaknesses, speed, memory, storage, and correctness against Graphify, Gortex, GitNexus, CodeGraph, codebase-memory-mcp, and ripgrep, with scope limits and raw evidence.
275
- - [Hero Loop (MCP Closed Loop)](docs/hero-loop.md): Autonomous task loop with deterministic gates.
276
- - [Coding CLI Integration](docs/coding-cli-integration.md): Configuring Claude, Codex, Cursor, Warp, and Antigravity.
277
- - [Security Model](docs/security.md): Redaction, write isolation, and containment rules.
278
- - [Project Status](docs/project-status.md): Subsystem maturity ledger.
279
-
280
- ---
281
-
282
- ## License
283
-
284
- Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE) for details.
167
+ Start at the **[documentation index](docs/README.md)**.
168
+
169
+ | Topic | Guide |
170
+ |---|---|
171
+ | Installation and first query | [Quickstart](docs/quickstart.md) |
172
+ | Components and state ownership | [Architecture](docs/architecture.md) |
173
+ | Symbols, impact and evidence limits | [Code graph](docs/code-graph.md) |
174
+ | Editor setup and hooks | [Integration](docs/coding-cli-integration.md) |
175
+ | Commands and flags | [CLI reference](docs/cli-reference.md) |
176
+ | Task workflow | [Workflow](docs/workflow.md) and [MCP loop](docs/hero-loop.md) |
177
+ | Implementation and migration limits | [Project status](docs/project-status.md) |
178
+ | Native development | [Rust workspace](rust/README.md) |
179
+
180
+ [Apache 2.0](LICENSE). The Python CLI, its release lineage and its historical
181
+ workflow certifications are retired; current native source and installed
182
+ binary identities must be checked separately.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "devcouncil",
3
- "version": "0.2.1",
4
- "description": "Gated orchestrator for AI-assisted software development",
3
+ "version": "0.2.2",
4
+ "description": "Code intelligence and deterministic verification for AI coding agents: symbol-level code graph, blast radius, dead-code analysis, and MCP servers for Claude Code, Cursor, and Codex",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://github.com/bharathvbcr/DevCouncil#readme",
7
7
  "repository": {
@@ -17,7 +17,21 @@
17
17
  "coding-agent",
18
18
  "devtools",
19
19
  "orchestration",
20
- "verification"
20
+ "verification",
21
+ "code-graph",
22
+ "code-intelligence",
23
+ "codebase-context",
24
+ "mcp",
25
+ "mcp-server",
26
+ "model-context-protocol",
27
+ "claude-code",
28
+ "cursor",
29
+ "static-analysis",
30
+ "tree-sitter",
31
+ "dead-code",
32
+ "blast-radius",
33
+ "call-graph",
34
+ "repo-map"
21
35
  ],
22
36
  "bin": {
23
37
  "devcouncil": "bin/devcouncil.js",