devcouncil 0.2.1 → 0.2.3

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 +114 -214
  2. package/package.json +21 -4
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)
@@ -20,6 +22,8 @@ difference between unavailable evidence and a passing check.
20
22
 
21
23
  **Manvi wraps these components** into a coding-agent harness (turn loop, providers, policy, TUI, `manvi serve`). **GitPulse** uses Manvi for policy, workbench, and agent hosting, and DevCouncil components for code intelligence and related analysis. DevCouncil does not replace coding agents; it sits beside Claude Code, Codex, Cursor, and others as selectable modules.
22
24
 
25
+ ![DevMap interactive dependency map and symbol graph in GitPulse](docs/assets/DevMap.png)
26
+
23
27
  ---
24
28
 
25
29
  ## Architecture & Components
@@ -29,7 +33,7 @@ DevCouncil's core runtime is a set of standalone, compiled native modules. Each
29
33
  | Binary | Language | Role & Ownership |
30
34
  |--------|----------|------------------|
31
35
  | `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`). |
36
+ | `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
37
  | `dcstore` | **Rust** | State & lease store: SQLite-backed task repository, mutual-exclusion leases for concurrent agent building, evidence records, and gap tracking. |
34
38
  | `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
39
  | `dcgrep` | **Rust** | Code search: Ripgrep-powered ignore-aware search engine with optional trigram indexing (`tgrep-core`). |
@@ -45,240 +49,136 @@ DevCouncil's core runtime is a set of standalone, compiled native modules. Each
45
49
 
46
50
  ---
47
51
 
48
- ## Installation
52
+ ## Benchmarks: DevMap vs Graphify, Gortex, GitNexus, CodeGraph, and codebase-memory-mcp
53
+
54
+ Six code-graph tools plus a ripgrep text baseline, measured on **four
55
+ repositories** (595 to 4,335 files, mixing Rust, Go, TypeScript, Python and
56
+ Swift) on one Apple M5 Pro. Every timing is a minimum or median from a
57
+ reproducible run with the raw evidence committed beside it — not a marketing
58
+ estimate. Head-to-head breakdown:
59
+ **[DevMap vs GitNexus, CodeGraph, Graphify, Gortex, and codebase-memory-mcp](docs/devmap/comparison.md)**.
60
+ Full method, caveats, and raw output:
61
+ **[benchmark report](benchmarks/results/competition/20260914-v0.2.2/REPORT.md)**.
62
+
63
+ **DevMap 0.2.2 was fastest on most of what was measured:** cold indexing and
64
+ unchanged refresh on **all four repositories**, the lowest median in **all six
65
+ symbol-query cells**, and **5/5** source-inspected caller pairs — matched only
66
+ by codebase-memory-mcp.
67
+
68
+ Detailed table on the 1,098-file DevCouncil corpus, where the correctness and
69
+ query campaign also ran:
70
+
71
+ | Tool | Cold index | Unchanged refresh | Single-file edit | Definition lookup | Peak RSS | Caller pairs found |
72
+ |---|---:|---:|---:|---:|---:|---:|
73
+ | **DevMap 0.2.2** | **2.012 s** | **0.089 s** | 0.816 s | **9.7 ms** | **678 MiB** | **5/5** |
74
+ | CodeGraph 1.6.0 | 3.294 s | 0.235 s | **0.512 s** | 101–106 ms | 2430 MiB | 3/5 |
75
+ | codebase-memory-mcp 0.10.8 | 9.357 s | 5.726 s | 8.894 s | ~3.94 s | — | **5/5** |
76
+ | Graphify 0.9.59 | 14.989 s | 5.080 s | 4.883 s | 557–572 ms | 3417 MiB | 3/5 |
77
+ | GitNexus 1.6.9 | 33.689 s | 0.699 s | 31.841 s | 792–808 ms | 3355 MiB | 3/5 |
78
+ | Gortex 0.64.3 | 16.5 s to query-ready | — | — | 92–104 ms | — | 4/5 |
79
+
80
+ **Where DevMap won.** Fastest cold index on all four corpora (**1.6–21×** the
81
+ competitors' time) and fastest unchanged refresh on all four (**2.2–107×**).
82
+ Lowest median in all six query cells — definition lookups at 9.7 ms, **~10×
83
+ faster than CodeGraph** and **~82× faster than GitNexus**. Lowest sampled peak
84
+ memory on three of four corpora. All five source-inspected caller pairs, and a
85
+ clean result on both index-staleness probes.
86
+
87
+ **Where DevMap lost.** CodeGraph re-indexes a single edited file faster **on
88
+ every corpus** — DevMap takes 1.08× its time on the smallest and **3.61×** on
89
+ GitPulse. That is the one stage where a competitor is consistently ahead.
90
+ DevMap's store is 1.6–2.0× CodeGraph's and 2.8–4.7× Graphify's, and Graphify
91
+ used **less memory than DevMap on the largest repository** (1,458 MB vs
92
+ 1,725 MB). Against v0.2.1, unchanged refresh regressed ~12% on the smallest
93
+ corpus.
94
+
95
+ **What these numbers are not.** Four repositories, one machine, three-to-five
96
+ repetitions, three symbols, and five inspected caller pairs. They do not
97
+ establish general graph accuracy, persistent-MCP latency, or coding-agent task
98
+ success. Tool output scopes differ, so equal latency is not equal analysis.
99
+ DevMap itself reports 106,217 unexplained call-attribution sites on this corpus.
100
+ The report states every limit explicitly and keeps the failures in — including
101
+ GitNexus serving a deleted symbol through two ordinary refreshes until a forced
102
+ rebuild.
49
103
 
50
- DevCouncil supports macOS, Linux, and Windows. Requires a Go toolchain (`>=1.22`), Rust/`cargo`, and Git.
104
+ ---
51
105
 
52
- ### 1. Build and Install Native Binaries
106
+ ## Get started
53
107
 
54
- From a clone of this repository:
108
+ Build just DevMap from source, then map a project:
55
109
 
56
110
  ```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)
111
+ git clone https://github.com/bharathvbcr/DevCouncil.git
112
+ cd DevCouncil
61
113
  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
114
  export PATH="$HOME/.local/bin:$PATH"
90
- ```
91
115
 
92
- ### 2. Optional Global npm Shim
93
-
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
116
+ cd /path/to/your/project
117
+ devmap build --manifest --guides
118
+ devmap paths --json
119
+ devmap status --json
120
+ devmap explore MyFunction --json
109
121
  ```
110
122
 
111
- ---
112
-
113
- ## Core Capabilities & Workflows
114
-
115
- ### 1. Coding Agent Integration (`devcouncil integrate`)
116
-
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.
118
-
119
- ```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
128
- ```
123
+ Git and Rust/Cargo are required. To include the Go host and full analysis suite,
124
+ run `bash scripts/install.sh`; the host needs the toolchain declared in
125
+ [`go.mod`](backend/go_orchestrator/go.mod), currently Go 1.26.6. On Windows use
126
+ `.\scripts\install.ps1 -Components devmap`, or omit `-Components` for the suite.
127
+ The npm package is a lightweight launcher for native binaries, not a bundled
128
+ runtime. [Complete installation guide](docs/quickstart.md).
129
129
 
130
- ### 2. Engineering Skills Delivery (`devcouncil skills`)
130
+ Use the paths returned by `devmap paths`: new repositories default to `.devmap`,
131
+ existing `.devcouncil` layouts remain supported, and explicit configuration can
132
+ override either. `--guides` requests managed workspace guides separately from
133
+ the map export. Check freshness, coverage gaps and result truncation before
134
+ using graph answers as evidence. If first-time guide creation leaves status
135
+ stale, run `devmap build --manifest` once more to index the new guides.
131
136
 
132
- Deliver verified engineering practices and code-intelligence skills directly into agent skill folders (`.agents/skills`, `.claude/skills`, `.cursor/skills`):
137
+ ## Connect an agent
133
138
 
134
139
  ```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
140
+ devmap integrate cursor --dry-run
141
+ devmap integrate cursor
142
+ devmap integrate cursor --check
144
143
  ```
145
144
 
146
- ### 3. Repository Mapping & Code Intelligence (`devmap` / `dev map`)
147
-
148
- Build and query deep semantic relationships across your codebase without an LLM:
149
-
150
- ```bash
151
- # Build the repository map (.devcouncil/repo_map.json) and code graph
152
- devmap build --manifest
145
+ Substitute `claude`, `codex`, `antigravity`, `opencode` or `warp` for `cursor`.
146
+ Integration can update user-level MCP settings as well as project assets.
147
+ Inspect the receipt and complete host reload/trust steps. For task tooling,
148
+ add the Go-host integration described in
149
+ [coding CLI integration](docs/coding-cli-integration.md).
153
150
 
154
- # Shorthand via the Go host:
155
- dev map
151
+ ## Verification is opt-in
156
152
 
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:
153
+ For an existing task in an initialized `.devcouncil/state.sqlite`:
173
154
 
174
155
  ```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
156
+ devcouncil verify TASK-001 --mode enforce --json
183
157
  ```
184
158
 
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
263
- ```
264
-
265
- ---
159
+ Read gate mode, skipped reasons and coverage metadata. The Go host invokes
160
+ `dcverify` for rigor checks; changed-line coverage requires a profile supplied
161
+ through `--coverage PATH`. The default gate mode is `off`. Task leases and MCP
162
+ policy results coordinate participating clients; retired lifecycle hooks do
163
+ not intercept arbitrary shell commands or editor writes. The sandbox selector
164
+ does not implement Docker/Nix isolation. See the
165
+ [task loop contract](docs/hero-loop.md).
266
166
 
267
167
  ## Documentation
268
168
 
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.
169
+ Start at the **[documentation index](docs/README.md)**.
170
+
171
+ | Topic | Guide |
172
+ |---|---|
173
+ | Installation and first query | [Quickstart](docs/quickstart.md) |
174
+ | Components and state ownership | [Architecture](docs/architecture.md) |
175
+ | Symbols, impact and evidence limits | [Code graph](docs/code-graph.md) |
176
+ | Editor setup and hooks | [Integration](docs/coding-cli-integration.md) |
177
+ | Commands and flags | [CLI reference](docs/cli-reference.md) |
178
+ | Task workflow | [Workflow](docs/workflow.md) and [MCP loop](docs/hero-loop.md) |
179
+ | Implementation and migration limits | [Project status](docs/project-status.md) |
180
+ | Native development | [Rust workspace](rust/README.md) |
181
+
182
+ [Apache 2.0](LICENSE). The Python CLI, its release lineage and its historical
183
+ workflow certifications are retired; current native source and installed
184
+ 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.3",
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",
@@ -34,7 +48,10 @@
34
48
  "smoke:registry": "node scripts/npm-registry-smoke.mjs",
35
49
  "check:release": "node scripts/check-release.mjs",
36
50
  "check:workflows": "node scripts/check-workflows.mjs",
37
- "test:scripts": "node --test scripts/check-release.test.mjs scripts/check-workflows.test.mjs",
51
+ "agents:sync": "node scripts/sync-agent-defs.mjs",
52
+ "agents:check": "node scripts/sync-agent-defs.mjs --check",
53
+ "agents:prefixes": "node scripts/mcp-served-tools.mjs",
54
+ "test:scripts": "node --test scripts/check-release.test.mjs scripts/check-workflows.test.mjs scripts/sync-agent-defs.test.mjs",
38
55
  "ci:local": "node scripts/ci-local.mjs"
39
56
  },
40
57
  "engines": {