devcouncil 0.3.0 → 0.4.0

package/README.md

@@ -12,23 +12,21 @@
 
 DevCouncil is a high-integrity command-line orchestration platform for AI-assisted software development. It turns AI implementation from a black-box generation task into a gated engineering workflow where every change is authorized, verified, and traceable back to a requirement.
 
-DevCouncil does not replace coding agents. It sits beside tools like Codex CLI, Gemini CLI, Claude Code, OpenCode, Google Antigravity CLI, Warp/Oz, Cursor, Aider, and bring-your-own prompt-taking CLIs, then owns the plan, task scope, verification loop, repair prompts, and evidence trail.
+DevCouncil does not replace coding agents. Its primary native path is Claude Code, followed by Codex CLI; it also works beside OpenCode, Google Antigravity CLI, Warp/Oz, Cursor, Aider, and bring-your-own prompt-taking CLIs. It owns the plan, task scope, verification loop, repair prompts, and evidence trail.
 
 ## Documentation
 
 - [Quickstart](docs/quickstart.md): shortest install-to-first-task path.
-- [Daily workflow](docs/workflow.md): manual sidecar loop, verification, repair, and rollback.
-- [Coding CLI integration](docs/coding-cli-integration.md): Codex, Gemini, Claude Code, OpenCode, Antigravity, Cursor, Aider, MCP, hooks, and automated executors.
-- [Integration tiers](docs/integration-tiers.md): headless executor vs MCP-only vs sidecar definitions.
+- [Daily workflow](docs/workflow.md): manual sidecar loop, verification, repair, rollback, and `dev watch`.
+- [Coding CLI integration](docs/coding-cli-integration.md): tiers, Claude Code, Codex, OpenCode, Antigravity, Cursor, Grok Build, Aider, MCP, hooks, stop gate / claim checks, and automated executors (Gemini deprecated).
 - [CLI command reference](docs/cli-reference.md): available `dev` commands.
-- [Architecture](docs/architecture.md): components, artifact graph, state machine, and gated execution.
-- [Executor adapters](docs/executor-adapters.md): manual, coding CLI, native-preview, Mini-SWE, and OpenHands execution paths.
-- [Live review](docs/live-review.md): `dev watch` session review, cards, signals, and blocking behavior.
+- [Repo map & code graph](docs/code-graph.md): `dev map` / `dev graph` — navigation, dead code, blast radius, PDG (opt-in), HTML visualizer.
+- [Corpus side index](docs/corpus.md): `dev corpus` for docs/PDFs/images and optional verify gates.
+- [Hero loop](docs/hero-loop.md): certified Claude Code + MCP closed loop, leases, rigor, and `dev check --verify` on-ramp.
+- [Architecture](docs/architecture.md): components, artifact graph, state machine, gating policy, and gated execution.
 - [Model routing](docs/model-routing.md): provider selection, role models, OpenRouter, Vertex AI, Doubleword, and Ollama (local) setup.
-- [Knowledge formats](docs/knowledge-formats.md): Open Knowledge Format (OKF) export/ingest/browse (`dev okf html` renders a bundle as a self-contained static HTML site) and design.md design-system lint/export plus `dev design check` (a CI-friendly gate that fails on hardcoded color/spacing/typography literals bypassing the tokens), injected as planning and coding context, plus the bidirectional OKF <-> engineering-skills bridge (`dev okf export --skills` / `dev okf ingest`).
 - [Security model](docs/security.md): redaction, permissions, allowlists, and local state.
-- [Project status](docs/project-status.md): current maturity by subsystem.
-- [Roadmap](docs/roadmap.md): planned work.
+- [Project status](docs/project-status.md): current maturity by subsystem and near-term focus.
 
 ## Why DevCouncil Exists
 
@@ -73,6 +71,8 @@ Start the first gated workflow from your target repository:
 cd path/to/your/project
 dev setup
 dev plan "Describe the implementation goal"
+dev status                   # if AWAITING_USER_DECISIONS, run dev approve next
+dev approve                  # when planning raised advisory gaps
 dev tasks
 dev run TASK-001 --executor manual
 dev prompt TASK-001
@@ -151,45 +151,51 @@ DevCouncil is an application layer around coding agents. It does not just emit p
 
 ### Workflow Features
 
-- **Repository onboarding:** `dev setup` initializes `.devcouncil/`, generates the repo map + `AGENTS.md`/`CLAUDE.md` guides, scaffolds applicable engineering skills, runs environment checks, offers integration setup, and prints the next useful commands. Use `--skip-map` / `--skip-skills` to opt out, or `--scaffold-ci` to also write a starter GitHub Actions workflow.
-- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are now inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree — so the map (and the structural context it feeds into prompts) is meaningful outside DevCouncil's own tree, not just within it. The map records the git HEAD and tracked-file fingerprint it was built from; when prompts reuse a map that has fallen behind the current code, they flag it as stale (run `dev map` to refresh) rather than silently feeding wrong structure. The map is also generated automatically on first init.
+- **Repository onboarding:** `dev setup` initializes `.devcouncil/`, generates the repo map + `AGENTS.md`/`CLAUDE.md` guides, scaffolds applicable engineering skills, runs environment checks, offers integration setup, and prints the next useful commands. Use `--skip-map` / `--skip-skills` to opt out, or `--scaffold-ci` to also write a starter GitHub Actions workflow. **`dev boot "goal"`** chains setup, `dev integrate --apply`, optional CI scaffold flags, and `dev go` in one command (see [quickstart](docs/quickstart.md)).
+- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json` and a symbol-level `.devcouncil/graph/code_graph.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree. Freshness uses git HEAD, tracked-file hash, and a content fingerprint so plain edits mark the map stale; a **missing map is stale** (fail-closed on hard rigor). Post-tool-use hooks and `dev map --watch` refresh incrementally. Unified analyze entry: `dev graph ingest`. Query with `dev graph query|trace|dead|search|cypher|html`. Liveness lists are capped at 5000 per list and 256 dependents per file (truncation metadata when hit). The map is also generated automatically on first init.
 - **Engineering skills:** `dev skills` lists the bundled skills and shows which apply to the repository; `dev skills scaffold` writes them into `.claude/skills/<name>/SKILL.md`. A merged always-on `core-engineering` skill (think-before-coding, simplicity, surgical changes, goal-driven execution, evidence-grounded communication) plus domain skills (Android, iOS, Windows, web, AI training) that brief the agent on current SDKs, deprecations, and tooling before coding. Applicable skills are also embedded into `dev prompt` output.
-- **CI scaffolding:** `dev scaffold-ci` writes a starter `.github/workflows/devcouncil.yml` derived from the configured test/lint/typecheck commands, filtered to the detected language stack; it never overwrites existing CI unless `--force`.
-- **Planning council:** `dev plan` turns a goal into requirements, acceptance criteria, assumptions, critique findings, and executable tasks.
-- **Task graph:** `dev tasks` and `dev show TASK-001` expose requirement links, acceptance-criterion links, planned files, expected tests, allowed commands, forbidden changes, dependencies, and status. Tasks can declare `depends_on`; the plan gate rejects unknown dependencies and cycles, and `dev go`/`dev e2e` run tasks in topological order and skip a task whose prerequisites didn't complete (rather than letting it fail spuriously and burn its repair budget).
+- **CI scaffolding:** `dev scaffold-ci` writes a starter `.github/workflows/devcouncil.yml` derived from the configured test/lint/typecheck commands, filtered to the detected language stack; it never overwrites existing CI unless `--force`. Run `dev scaffold-ci --evidence` to generate `.github/workflows/devcouncil-evidence.yml` which automates verifying PRs and uploading evidence JSON and HTML reports.
+- **Planning council:** `dev plan` turns a goal into requirements, acceptance criteria, assumptions, critique findings, and executable tasks. When advisory gaps remain, the project stays in `AWAITING_USER_DECISIONS` until you run `dev approve` (or `dev e2e`/`dev go --force`).
+- **Task graph:** `dev tasks` and `dev show TASK-001` expose requirement links, acceptance-criterion links, planned files, expected tests, allowed commands, forbidden changes, dependencies, status, and active **lease** owners. Tasks can declare `depends_on`; the plan gate rejects unknown dependencies and cycles, and `dev go`/`dev e2e` run tasks in topological order and skip a task whose prerequisites didn't complete (rather than letting it fail spuriously and burn its repair budget). `dev tasks cancel`, `dev tasks edit`, and `dev tasks reprioritize` manage the live task graph without replanning.
+- **Gap and requirements surfaces:** `dev gaps` lists blocking and advisory verification gaps project-wide; `dev requirements` summarizes requirement coverage and derived status; `dev export` writes a portable JSON snapshot of requirements, tasks, and gaps.
 - **Scoped task prompts:** `dev prompt TASK-001` creates a constrained implementation prompt for sidecar agents, including file scope, verification expectations, and forbidden changes. The prompt now embeds the current (secret-redacted) contents of each planned file with a top-level symbol outline, structural orientation (from the code-review graph when available, otherwise the generated `repo_map.json`), and a **dependents (blast-radius) list** — the files that import each file being changed, from the map's precomputed reverse-import index — so the agent edits in place and keeps call sites working instead of starting blind. A central prompt budget keeps the core (goal/scope/instructions) always present and fits the optional context sections in priority order (file contents > structural > dependents > skills), dropping the lowest-priority ones with an explicit marker rather than overflowing silently.
 - **Execution:** `dev run TASK-001` supports manual sidecar mode, built-in coding CLI executors, external executors, and registered custom CLI agents.
 - **One-command flow:** `dev e2e "goal"` and `dev go "goal"` can initialize state, plan, run approved tasks, verify the diff, and generate a report. With an automated executor the run is now a **closed loop**: a task that fails verification is re-driven through a bounded self-repair loop (a correction manifest is written and the executor re-run) until it verifies or the `execution.max_repair_attempts` budget is spent, with no-progress detection that stops early when the same blocking gaps reappear.
 - **Verification:** `dev verify TASK-001` captures the diff, runs expected evidence commands, checks planned-file compliance, detects orphan changes, flags unplanned dependency edits, scans for secrets, and links evidence to acceptance criteria. An **empty diff can no longer pass** a task that declares files to create or modify (work that committed earlier is still recognized via the task checkpoint), and the result reports the rigor it ran at (`verification_mode` compiled vs coarse, `diff_empty`, `coverage_measured`/`coverage_skipped_reason`) plus a distinct `advisory_actions` list so an agent never mistakes "passed" for "proven." `dev verify` exits non-zero when a task is blocked so shell-driven agents can gate on `$?`.
+- **Lite check:** `dev check --verify` runs the same deterministic evidence gate against the current working tree without planning or provider keys — useful for CI and quick audits. `dev check` without `--verify` performs an LLM audit of current changes. Run `dev check --watch` to start a fast, incremental check loop that selects and re-runs only the stack gates affected by changed files using an input-content hash cache.
 - **Repair:** `dev repair` converts blocking gaps into focused follow-up work instead of leaving failures as vague test output.
 - **Rollback:** `dev rollback TASK-001` uses task checkpoints to revert scoped work when a task needs to be backed out.
-- **Reporting:** `dev report` emits a requirements coverage table, evidence summary, blocking gaps, and live-review blockers; JSON and PR-comment paths are available for automation.
+- **Codebase wiki:** `dev wiki update` generates and maintains an agent-facing wiki of the repository as an Open Knowledge Format bundle under `.devcouncil/knowledge/okf/wiki/` — an index, one cross-linked page per subsystem (entry points, roles, neighbors, handoff paths), a development guide, and a `log.md` change history. Pages are built deterministically from `repo_map.json` and, when a model is configured, enriched with LLM-written prose (overview, key flows, agent guidance) by the `wiki_writer` role; enrichment degrades cleanly to the skeleton. Updates are incremental (per-page fingerprints preserve prior enrichment), `dev map` refreshes stale skeletons automatically, `dev wiki status` reports freshness, and `dev wiki install-action` adds a GitHub Action that keeps the wiki current via automated PRs. Because the bundle lives under the knowledge directory, wiki pages are selected into planning/task prompts like any other OKF knowledge — tagged by subsystem so goals pull the right page.
+- **Run supervision (Preview):** every automated run is a reversible object (Shepherd-style): `dev runs timeline <run-or-task>` joins the run manifest, trace events, and git checkpoints into one inspectable timeline; `dev runs diff` shows exactly what the run changed; `dev runs revert` reverses it from its checkpoints (and records the revert in the trace); and `dev runs supervise` asks a supervisor meta-agent (the `run_supervisor` role, with deterministic heuristics as fallback) for a keep/revert/repair verdict — add `--apply` on the CLI to act on a revert verdict. Over MCP, `devcouncil_run_timeline` and `devcouncil_run_supervise` expose the same inspection and verdict surfaces; MCP supervise is verdict-only (no workspace modify — use `dev runs revert` or CLI `--apply` separately).
+- **Reporting:** `dev report` emits a requirements coverage table, evidence summary, blocking gaps, and live-review blockers; JSON, PR-comment, and interactive HTML report (`dev report --evidence-html PATH`) formats are available for automation.
 
 ### App Surfaces
 
 - **CLI:** `dev` and `devcouncil` expose the same Typer command surface for local terminal workflows.
+- **Multi-agent campaigns:** `dev campaign run` executes a planned task graph as a parallel, dependency-aware multi-agent campaign (Director → Coordinator → Worker pool + Reviewer QC) with automatic file-overlap serialization, cost budgeting, ntfy push notifications, and a markdown progress dashboard at `.devcouncil/campaign/dashboard.md`. Roster and mailbox commands (`dev campaign roster` / `dev campaign inbox`) expose the role hierarchy and on-disk message bus.
 - **Agent hub:** `dev agents` lists built-in and custom agents, `dev agents add` registers prompt-taking CLIs, `dev agents doctor` checks wiring, `dev agents run` executes a task through a named agent/profile, and `dev agents optimize` uses GEPA to tune profile preambles from offline eval examples.
-- **Integration hub:** `dev integrate all --apply` configures supported coding CLI and MCP integrations; targeted setup exists for Codex, Gemini, Claude Code, OpenCode, Antigravity, Cursor, Warp/Oz, hooks, and custom CLI agents. `dev integrate check` now reports each client's **enforcement posture** — `pre-action` (a native hook blocks unauthorized writes before they happen) vs `verify-only` (forbidden changes are caught only after the fact by verification) — so the containment guarantee isn't overstated for clients without a pre-action gate.
-- **MCP server:** `dev mcp-server` exposes DevCouncil context and workflow tools over stdio for MCP-capable clients. `devcouncil_verify_task` now runs DevCouncil's strong compiled per-criterion checks when a provider key is configured (falling back to a clearly-labeled `coarse` mode otherwise), refuses to pass on an empty diff, and returns `verification_mode`, `diff_empty`, `coverage_measured`/`coverage_skipped_reason`, and an `advisory_actions` array alongside the blocking `next_actions`. Cheap, re-verify-free read tools — `devcouncil_get_gaps` and `devcouncil_get_next_actions` — let a reconnecting agent resume outstanding work from persisted gaps (which now carry `file`/`line`/`suggested_command`/`acceptance_criterion_id`). Task leases expire on a config-driven TTL so a crashed agent's task frees itself, with `devcouncil_renew_lease` and `devcouncil_list_leases` for long runs and fleet supervision; a partial-unique DB index enforces a single active lease per task, so concurrent checkouts can't both win the writer slot. A pure-MCP agent can now make the change itself through lease-gated write tools — `devcouncil_write_file` and `devcouncil_apply_patch` — which policy-check every target path *before* it lands (out-of-scope, protected, or escaping paths are rejected; a patch with any out-of-scope target is rejected whole, never partially applied), write atomically, and record a `FileChangeEvent` for provenance. The corpus is also browsable as MCP **resources** (`devcouncil://report`, `devcouncil://tasks`, `devcouncil://gaps`, `devcouncil://cards`, `devcouncil://task/{id}`) so a host can read project state without a tool call. `devcouncil_get_task_provenance` then exposes that audit trail — gated file changes, verification runs, diff-coverage evidence, and the latest correction manifest — so what happened on disk is inspectable. The diff↔coverage proof is now also retained across graph reloads (it was previously dropped), so reports and `dev status` reflect whether the changed lines were actually exercised.
+- **Integration hub:** `dev integrate all --apply` configures supported coding CLI and MCP integrations in Claude-first, Codex-second order. `dev integrate check` reports each client's **enforcement posture**: `pre-action`, `advisory+verify`, or `verify-only`, so a client API that cannot natively deny PreToolUse is never presented as blocking.
+- **MCP server:** `dev mcp-server` exposes DevCouncil context and workflow tools over stdio for MCP-capable clients. Native graph tools include `devcouncil_graph_ingest`, `devcouncil_graph_cypher`, `devcouncil_pdg_query`, and `devcouncil_explain` alongside repo-map and symbol-query surfaces. `devcouncil_verify_task` now runs DevCouncil's strong compiled per-criterion checks when a provider key is configured (falling back to a clearly-labeled `coarse` mode otherwise), refuses to pass on an empty diff, and returns `verification_mode`, `diff_empty`, `coverage_measured`/`coverage_skipped_reason`, and an `advisory_actions` array alongside the blocking `next_actions`. Cheap, re-verify-free read tools — `devcouncil_get_gaps` and `devcouncil_get_next_actions` — let a reconnecting agent resume outstanding work from persisted gaps (which now carry `file`/`line`/`suggested_command`/`acceptance_criterion_id`). Task leases expire on a config-driven TTL so a crashed agent's task frees itself, with `devcouncil_renew_lease` and `devcouncil_list_leases` for long runs and fleet supervision; a partial-unique DB index enforces a single active lease per task, so concurrent checkouts can't both win the writer slot. A pure-MCP agent can now make the change itself through lease-gated write tools — `devcouncil_write_file` and `devcouncil_apply_patch` — which policy-check every target path *before* it lands (out-of-scope, protected, or escaping paths are rejected; a patch with any out-of-scope target is rejected whole, never partially applied), write atomically, and record a `FileChangeEvent` for provenance. The corpus is also browsable as MCP **resources** (`devcouncil://report`, `devcouncil://tasks`, `devcouncil://gaps`, `devcouncil://cards`, `devcouncil://task/{id}`) so a host can read project state without a tool call. `devcouncil_get_task_provenance` then exposes that audit trail — gated file changes, verification runs, diff-coverage evidence, and the latest correction manifest — so what happened on disk is inspectable. The diff↔coverage proof is now also retained across graph reloads (it was previously dropped), so reports and `dev status` reflect whether the changed lines were actually exercised.
 - **Live review:** `dev watch` tracks review cards, signals, blocking feedback, and repair guidance while a session is active.
 - **Trace viewer:** `dev trace tail --follow` streams local DevCouncil trace events for execution, verification, and agent handoff.
-- **Dashboard:** `dev dashboard --open` serves a local status dashboard and opens it in the default browser for project state and live workflow visibility.
+- **Cost and runs:** `dev cost show` reports estimated model-call cost from the local ledger; `dev runs list` and `dev runs show` inspect coding-agent run manifests under `.devcouncil/runs/`, and `dev runs timeline`/`diff`/`revert`/`supervise` treat each run as a reversible, supervisable trace. Over MCP, `devcouncil_wiki_page` exposes the codebase wiki; run supervision tools are documented in [coding-cli-integration.md](docs/coding-cli-integration.md#run-supervision) (`devcouncil_run_timeline`, `devcouncil_run_supervise`).
+- **Live Dashboard (Stable local UI):** `dev dashboard --open` serves a local-only status dashboard (blocking-first **gaps** table, recent runs, integration diagnostics) and opens it in the default browser. Apply controls are loopback + token-guarded.
 - **Agent-consumable CLI:** machine output for shell-driven agents — `dev prompt --json` (`{ok, task_id, prompt}`), `dev handoff --json` (`{ok, manifest_path, run_id, next_command}` to chain `dev run`), `dev verify` exits non-zero when blocked, and `dev status`/`dev report` accept `--fail-on-blocking` to exit non-zero on outstanding blocking gaps so a loop can gate on `$?`.
-- **Config editor:** `dev config` and `dev config models` inspect/update provider, model, executor, and command configuration.
+- **Config editor:** `dev config`, `dev config show`, `dev config set`, and `dev config models` inspect/update provider, model, executor, and command configuration.
 - **Artifact tools:** `dev artifacts validate` checks stored graph integrity.
-- **Code intelligence:** `dev lsp inspect` checks optional language-server readiness, and `dev ast match` searches code structurally.
-- **Doctor:** `dev doctor` validates local dependencies, commands, and environment prerequisites before a workflow fails deeper in execution.
+- **Code intelligence:** `dev lsp inspect` (with `--json` for automation) checks optional language-server readiness, and `dev ast match` searches code structurally.
+- **Doctor:** `dev doctor` validates local dependencies, configures coverage floor checks (`[tool.coverage.report] fail_under`), checks mypy status, and runs environment prerequisites before a workflow fails; it includes a subsystem maturity table aligned with `docs/project-status.md`.
 
 ### Agent And Executor Support
 
 DevCouncil works with human-in-the-loop sidecar sessions and automated prompt handoff:
 
 - **Manual sidecar:** paste `dev prompt TASK-001` into any agent, then run `dev verify TASK-001`.
-- **Built-in coding CLI adapters:** `codex`, `gemini`, `claude`, `opencode`, `antigravity`, `warp`, `cursor`, `aider`, and aliases such as `codex-cli`, `gemini-cli`, `claude-code`, `opencode-cli`, `antigravity-cli`, `agy`, `agy-cli`, `warp-cli`, `oz`, `cursor-agent`, and `cursor-cli`.
+- **Built-in coding CLI adapters:** `codex`, `claude`, `opencode`, `antigravity`, `warp`, `cursor`, `grok`, `aider`, `copilot`, `goose`, `amp`, `qwen`, `crush`, and aliases such as `codex-cli`, `claude-code`, `opencode-cli`, `antigravity-cli`, `agy`, `agy-cli`, `warp-cli`, `oz`, `cursor-agent`, `cursor-cli`, `grok-build`, `grok-cli`, `gork`, `xai-grok`, `copilot-cli`, `github-copilot`, `goose-cli`, `amp-cli`, `qwen-code`, and `crush-cli`. **`gemini` / `gemini-cli` remain as deprecated compat only** — prefer Antigravity.
 - **Custom CLI agents:** register any prompt-taking command with stdin, argument, or prompt-file handoff.
 - **Execution profiles:** custom agents can use profiles such as `default`, `yolo`, and `prod` to adjust prompt constraints while DevCouncil still verifies the final diff.
-- **External automated adapters:** `mini`, `openhands`, `native-preview`, and `native` are available when the corresponding local executor is configured.
-- **Hook-aware clients:** `dev integrate hooks --apply` installs write/shell hooks for Codex, Gemini, Claude, Cursor, and OpenCode so DevCouncil policy can block unauthorized actions before verification. The post-task hook can run deterministic verification of the active task and record gaps (enable `execution.verify_on_post_task`; off by default to keep hooks fast). File-write policy uses one shared path normalizer across the hook and task-policy paths that resolves every target and **denies anything outside the project root** (so the path that's checked is the path that's enforced), and the pre-tool-use hook is fail-closed: an unparseable or error payload is surfaced (and blocked under `--strict`/`DEVCOUNCIL_HOOK_STRICT`) rather than silently allowed.
+- **External automated adapters:** `mini`, `openhands`, `native-preview`, and `native` are available when the corresponding local executor is configured. The **native executor** (`NativeAgent`) is in Preview status and supports lease-gated writes (gated by the same safety path as MCP) and a bounded self-repair closed loop.
+- **Hook-aware clients:** `dev integrate hooks --apply` installs native lifecycle hooks. Claude Code can enforce the opt-in blocking write gate; Codex currently accepts advisory `systemMessage` output for PreToolUse and uses its native sandbox plus deterministic post-run verification for containment. Codex Stop/SubagentStop uses the supported `continue`/`stopReason` schema. File-write policy resolves every target and denies anything outside the project root.
 
 ### Gates And Evidence
 
@@ -198,6 +204,7 @@ DevCouncil blocks completion on concrete gaps rather than model confidence:
 - **Plan approval gates:** requirements must have acceptance criteria, acceptance criteria need verification methods, tasks must map to known requirements and acceptance criteria, high-impact assumptions must be resolved, and high/critical critique findings must be closed.
 - **Task readiness gates:** the working tree must be clean for the task, planned files must be declared, and each task needs allowed commands plus expected verification evidence.
 - **Diff gates:** verification detects files changed outside the planned task scope, dependency-file edits made without authorization, deleted/added files, and untracked file diffs.
+- **Architecture/subsystem boundary gates:** flags edits that cross non-neighbor subsystems without plan coverage, preventing unauthorized architecture drift. **Write policy** also soft-blocks paths outside `planned_files` unless the target shares a subsystem or a map `neighbors` area (widen via `dev scope update`).
 - **Evidence gates:** passing evidence commands are linked back to acceptance criteria; missing passing evidence becomes a blocking gap.
 - **Security gates:** secret scanning runs over captured diffs, and command output is redacted before it is written to logs.
 - **Live-review gates:** unresolved critical review cards can block task verification and appear in reports.
@@ -208,7 +215,7 @@ DevCouncil blocks completion on concrete gaps rather than model confidence:
 - **Role models:** planner, critic, arbiter, reviewer, and repair roles can share one model or use per-role overrides.
 - **Structured repair:** model routing includes JSON repair paths for structured planning and review outputs.
 - **Model defaults:** packaged YAML defaults ship with the tool so installed CLI environments do not depend on source-tree-only files.
-- **Telemetry:** local trace and cost data feed `dev status`, reports, and dashboard surfaces.
+- **Telemetry:** local trace and cost data feed `dev status`, `dev cost show`, reports, and dashboard surfaces.
 
 ### Reports And Automation Outputs
 
@@ -225,11 +232,13 @@ DevCouncil stores local workflow state in the target repository:
 - `.devcouncil/config.yaml`: provider, executor, command, integration, and workflow settings.
 - `.devcouncil/secrets.env`: local provider secrets such as API keys or Vertex AI project/location values. Git-ignored; copy `.devcouncil/secrets.env.example` and fill in real values. Environment variables take precedence over this file.
 - `.devcouncil/repo_map.json`: generated repository map and subsystem navigation index.
+- `.devcouncil/graph/code_graph.json`: symbol-level knowledge graph (imports, calls, dead-code tiers); visualize with `dev graph html`.
 - `.devcouncil/state.sqlite`: SQLite state for requirements, assumptions, tasks, evidence, gaps, critique findings, and project phase history.
 - `.devcouncil/checkpoints/`: task snapshots used by verification and rollback.
 - `.devcouncil/logs/`: the durable run log (`devcouncil.log`, rotating, DEBUG-level) plus redacted stdout/stderr from verification commands.
 - `.devcouncil/runs/<run-id>/run.log`: the full per-run log isolated to a single executor run.
 - `.devcouncil/runs/<run-id>/agent-run.json`: prompt, executor, profile, exit status, and run metadata for automated agent executions.
+- `.devcouncil/knowledge/okf/wiki/`: the generated codebase wiki (OKF bundle) — the one part of `.devcouncil/` meant to be committed and shared, maintained by `dev wiki update`.
 - `.devcouncil/reports/latest.json`: optional machine-readable report generated by `dev e2e --agent`.
 - `.devcouncil/integrations/` and `.agents/`: generated integration files such as Warp/Oz MCP JSON and Antigravity MCP config.
 
@@ -244,7 +253,7 @@ Every command logs each stage and step. The full DEBUG trail always lands in `.d
 
 ### Maturity
 
-The stable daily workflow is planning, manual sidecar execution, verification, repair, rollback, and reporting. Coding CLI executors, MCP, live review, dashboard, PR comments, LSP/AST tools, and GitHub check surfaces are preview features. Native autonomous execution is experimental and still requires DevCouncil verification before work is considered complete.
+The stable daily workflow is planning, manual sidecar execution, verification, the deterministic repair loop in `dev go`/`dev e2e`, rollback, reporting, repo map/code graph (`dev map` / `dev graph`), and the local Live Dashboard (`dev dashboard --open`). The **certified Claude Code MCP closed loop** (checkout → write → verify → repair → release) is **Stable** (see [hero-loop.md](docs/hero-loop.md#certified-path-stable)). Coding CLI executors and hooks (including stop-gate claim checks), `dev boot` onboarding, CI scaffolding, multi-agent campaigns, watch mode, live review, PR comments, LSP/AST tools, corpus side index, opt-in PDG, and GitHub check surfaces are preview features. Optional LLM repair inference remains preview and is not required for the deterministic loop. The native autonomous executor is **Preview** (lease-gated writes + shared verify loop) and still requires DevCouncil verification before work is considered complete.
 
 ## Core Flow
 
@@ -315,11 +324,15 @@ uv run dev --help
 For a global install from this repository:
 
 ```bash
-uv tool install --force .
+uv tool install --force --reinstall --editable .
 dev --help
 devcouncil --help
 ```
 
+`--editable` keeps `~/.local/bin/dev` pointed at this checkout so map/graph and other WIP features stay current without reinstalling after every edit. Use `uv tool install --force .` (without `--editable`) for a frozen snapshot of the tree at install time.
+
+See [docs/code-graph.md](docs/code-graph.md) for `dev map` / `dev graph` usage (dead code, blast radius, HTML visualizer).
+
 ## Project Shape
 
 DevCouncil implements a 7-phase software-team workflow:
@@ -345,8 +358,11 @@ Project ideas and execution patterns come from the open-source ecosystem:
 - [OpenHands](https://github.com/All-Hands-AI/OpenHands): for workspace-aware agent execution patterns.
 - [mini-SWE-agent](https://github.com/SWE-agent/mini-swe-agent): for lightweight execution loop inspiration.
 - [SWE-agent](https://github.com/SWE-agent/SWE-agent): for full-spectrum autonomous SWE-style tasking patterns.
-- [GitNexus](https://github.com/abhigyanpatwari/GitNexus): for structural codebase awareness.
-- [graphify](https://github.com/safishamsi/graphify): for knowledge-graph-based coordination concepts.
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus): structural codebase awareness concepts (native `dev map` / `dev graph` — no runtime integration).
+- [graphify](https://github.com/safishamsi/graphify): knowledge-graph / corpus coordination concepts (native `dev corpus` + optional verify gates — no runtime integration).
+- [Claude-oversight](https://github.com/sabarishraja/Claude-oversight): claim-to-evidence stop-gate semantics (native stop gate + claim mapper).
+- [Claude-hindsight](https://github.com/sabarishraja/Claude-hindsight): session continuity / statusline briefing patterns (native SessionStart briefing).
+- [Shepherd](https://github.com/shepherd-agents/shepherd): reversible run traces and meta-agent supervision (`dev runs timeline` / `diff` / `revert` / `supervise`).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcouncil",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Gated orchestrator for AI-assisted software development",
   "license": "Apache-2.0",
   "homepage": "https://github.com/bharathvbcr/DevCouncil#readme",
@@ -31,13 +31,17 @@
     "src/**/*.svg",
     "src/**/*.yaml",
     "src/**/*.mjs",
+    "src/**/*.js",
+    "packages/codeintel-grammars/pyproject.toml",
+    "packages/codeintel-grammars/hatch_build.py",
+    "packages/codeintel-grammars/src/devcouncil_codeintel_grammars/__init__.py",
     "pyproject.toml",
     "uv.lock",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "install:dev": "uv tool install --force .",
+    "install:dev": "uv tool install --force '.[codeintel-full]'",
     "install:editable": "uv pip install -e .",
     "dev": "uv run devcouncil",
     "pack:check": "npm pack --dry-run",

package/packages/codeintel-grammars/hatch_build.py

@@ -0,0 +1,43 @@
+"""Mark grammar artifacts as platform-specific without tying them to one ABI."""
+
+import hashlib
+import json
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from packaging.tags import sys_tags
+
+__all__ = ["CustomBuildHook"]
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        del version
+        assets = Path(self.root) / "src" / "devcouncil_codeintel_grammars" / "assets"
+        manifest_path = assets / "manifest.json"
+        if not manifest_path.is_file():
+            raise RuntimeError(
+                "grammar assets are not staged; run scripts/build-codeintel-grammar-wheel.py first"
+            )
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        checksums = dict(manifest.get("sha256") or {})
+        required = set(manifest.get("required_grammars") or [])
+        available = set(manifest.get("languages") or [])
+        missing = sorted(required - available)
+        failed = [
+            rel
+            for rel, digest in checksums.items()
+            if not (assets / rel).is_file()
+            or hashlib.sha256((assets / rel).read_bytes()).hexdigest() != digest
+        ]
+        if not checksums or not required or missing or failed:
+            raise RuntimeError(
+                "invalid grammar assets: "
+                f"missing={missing}, failed_checksums={failed}, asset_count={len(checksums)}"
+            )
+        platform_tag = next(sys_tags()).platform
+        build_data["tag"] = f"py3-none-{platform_tag}"
+        build_data["pure_python"] = False
+        build_data.setdefault("force_include", {})[str(assets)] = (
+            "devcouncil_codeintel_grammars/assets"
+        )

package/packages/codeintel-grammars/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "devcouncil-codeintel-grammars"
+version = "0.4.0"
+description = "Platform-specific Tree-sitter grammar assets for DevCouncil code intelligence"
+requires-python = ">=3.12"
+dependencies = ["tree-sitter-language-pack>=1.12.5"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/devcouncil_codeintel_grammars"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

package/packages/codeintel-grammars/src/devcouncil_codeintel_grammars/__init__.py

@@ -0,0 +1,93 @@
+"""Activate the packaged, offline Tree-sitter grammar cache."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+_ACTIVATION_LOCK = threading.Lock()
+_ACTIVATION_STATUS: dict[str, Any] | None = None
+
+
+def asset_root() -> Path:
+    return Path(str(files("devcouncil_codeintel_grammars").joinpath("assets")))
+
+
+def verify() -> dict[str, Any]:
+    root = asset_root()
+    manifest_path = root / "manifest.json"
+    if not manifest_path.is_file():
+        return {"ok": False, "error": "grammar manifest missing", "assets": str(root)}
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        return {
+            "ok": False,
+            "error": f"invalid grammar manifest: {exc}",
+            "assets": str(root),
+        }
+    checksums = dict(manifest.get("sha256") or {})
+    languages = sorted(set(manifest.get("languages") or []))
+    required = sorted(set(manifest.get("required_grammars") or []))
+    failures: list[str] = []
+    for rel, digest in checksums.items():
+        path = (root / rel).resolve()
+        if root.resolve() not in path.parents:
+            failures.append(rel)
+            continue
+        if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+            failures.append(rel)
+    missing = sorted(set(required) - set(languages))
+    error = ""
+    if not checksums:
+        error = "grammar manifest contains no checksummed assets"
+    elif not required:
+        error = "grammar manifest contains no required grammar list"
+    elif missing:
+        error = f"grammar wheel is missing required assets: {', '.join(missing)}"
+    return {
+        "ok": not failures and not error,
+        "assets": str(root),
+        "pack_version": manifest.get("pack_version"),
+        "platform": manifest.get("platform"),
+        "languages": languages,
+        "required_grammars": required,
+        "missing_grammars": missing,
+        "failed_checksums": failures,
+        "error": error,
+    }
+
+
+def activate() -> dict[str, Any]:
+    global _ACTIVATION_STATUS
+    with _ACTIVATION_LOCK:
+        if _ACTIVATION_STATUS is not None:
+            return dict(_ACTIVATION_STATUS)
+        status = verify()
+        if not status["ok"]:
+            _ACTIVATION_STATUS = {**status, "activated": False}
+            return dict(_ACTIVATION_STATUS)
+        import tree_sitter_language_pack as pack
+
+        pack.configure(pack.PackConfig(cache_dir=str(asset_root() / "cache")))
+        available = set(pack.available_languages())
+        missing = sorted(set(status["required_grammars"]) - available)
+        _ACTIVATION_STATUS = {
+            **status,
+            "ok": not missing,
+            "activated": not missing,
+            "missing_grammars": missing,
+            "error": (
+                f"pack could not activate required grammars: {', '.join(missing)}"
+                if missing
+                else ""
+            ),
+        }
+        return dict(_ACTIVATION_STATUS)
+
+
+__all__ = ["activate", "asset_root", "verify"]

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcouncil"
-version = "0.3.0"
+version = "0.4.0"
 description = "Gated orchestrator for AI-assisted software development"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,19 +12,28 @@ dependencies = [
     "sqlmodel>=0.0.19",
     "httpx>=0.27.0",
     "gitpython>=3.1.49",
-    "mcp>=1.27.0",
+    "mcp>=1.27.2",
     "gepa>=0.1.1",
     "watchdog>=4.0.0",
+    "tree-sitter>=0.23.0",
+    "tree-sitter-language-pack>=1.12.5",
+    "networkx>=3.3",
 ]
 
+[project.optional-dependencies]
+# Platform wheel containing the complete, checksum-manifested Tree-sitter cache.
+# The core package remains useful with locally installed grammars; release builds
+# install this extra to guarantee the full code-intelligence language matrix.
+codeintel-full = ["devcouncil-codeintel-grammars==0.4.0"]
+
 [project.urls]
 Homepage = "https://github.com/bharathvbcr/DevCouncil"
 Repository = "https://github.com/bharathvbcr/DevCouncil.git"
 Issues = "https://github.com/bharathvbcr/DevCouncil/issues"
 
 [project.scripts]
-dev = "devcouncil.cli.main:app"
-devcouncil = "devcouncil.cli.main:app"
+dev = "devcouncil.cli.main:run_cli"
+devcouncil = "devcouncil.cli.main:run_cli"
 
 [dependency-groups]
 dev = [
@@ -35,6 +44,19 @@ dev = [
     # Used only to exercise the diff↔coverage path end-to-end in tests. DevCouncil
     # never requires coverage at runtime — it uses whatever the target repo provides.
     "coverage>=7.4",
+    # Required for semantic_layer unit tests (cache FAISS backend).
+    "faiss-cpu>=1.8.0",
+    "numpy>=1.26.0",
+]
+platform-test = [
+    # Required only by the real Debug Adapter Protocol integration matrix.
+    "debugpy>=1.8.0",
+]
+semantic = [
+    "sentence-transformers>=3.0.0",
+    "faiss-cpu>=1.8.0",
+    "numpy>=1.26.0",
+    "torch>=2.2.0",
 ]
 
 [tool.uv]
@@ -49,18 +71,91 @@ constraint-dependencies = [
     "python-multipart>=0.0.31",
     "pydantic-settings>=2.14.2",
     "idna>=3.15",
+    "setuptools>=83.0.0",
 ]
 
+[tool.uv.workspace]
+members = ["packages/codeintel-grammars"]
+
+[tool.uv.sources]
+devcouncil-codeintel-grammars = { workspace = true }
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["src/devcouncil"]
+branch = true
+# Gate focuses on stable units; large CLI/orchestration glue is exercised by CLI tests.
+omit = [
+    "*/cli/commands/graph_cmd.py",
+    "*/cli/commands/plan.py",
+    "*/cli/commands/map.py",
+    "*/cli/commands/doctor.py",
+    "*/cli/commands/hook.py",
+    "*/cli/commands/integrate.py",
+    "*/codeintel/sync/coordinator.py",
+    "*/codeintel/resolution/semantic.py",
+    "*/codeintel/debug/python_trace_runner.py",
+    "*/verification/verify_orchestration.py",
+    "*/verification/checks/liveness_ratchet.py",
+    "*/verification/checks/acceptance_corpus.py",
+    "*/verification/checks/corpus_stale.py",
+    "*/skills/registry.py",
+]
+
+[tool.coverage.report]
+fail_under = 90
+omit = [
+    "*/cli/commands/graph_cmd.py",
+    "*/cli/commands/plan.py",
+    "*/cli/commands/map.py",
+    "*/cli/commands/doctor.py",
+    "*/cli/commands/hook.py",
+    "*/cli/commands/integrate.py",
+    "*/codeintel/sync/coordinator.py",
+    "*/codeintel/resolution/semantic.py",
+    "*/codeintel/debug/python_trace_runner.py",
+    "*/verification/verify_orchestration.py",
+    "*/verification/checks/liveness_ratchet.py",
+    "*/verification/checks/acceptance_corpus.py",
+    "*/verification/checks/corpus_stale.py",
+    "*/skills/registry.py",
+]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.wheel]
+packages = ["src/devcouncil", "src/semantic_layer"]
+
 [tool.hatch.build.targets.wheel.force-include]
 "src/devcouncil/llm/model_defaults.yaml" = "devcouncil/llm/model_defaults.yaml"
 "src/devcouncil/telemetry/model_pricing.yaml" = "devcouncil/telemetry/model_pricing.yaml"
 "src/devcouncil/assets/devcouncil-logo.svg" = "devcouncil/assets/devcouncil-logo.svg"
 "src/devcouncil/assets/devcouncil_logo_premium.png" = "devcouncil/assets/devcouncil_logo_premium.png"
+"src/devcouncil/assets/vendor/force-graph.min.js" = "devcouncil/assets/vendor/force-graph.min.js"
 "src/devcouncil/integrations/opencode_devcouncil_plugin.mjs" = "devcouncil/integrations/opencode_devcouncil_plugin.mjs"
+"src/devcouncil/campaign/prompts/coordinator.md" = "devcouncil/campaign/prompts/coordinator.md"
+"src/devcouncil/campaign/prompts/director.md" = "devcouncil/campaign/prompts/director.md"
+"src/devcouncil/campaign/prompts/protocol.md" = "devcouncil/campaign/prompts/protocol.md"
+"src/devcouncil/campaign/prompts/reviewer.md" = "devcouncil/campaign/prompts/reviewer.md"
+"src/devcouncil/campaign/prompts/worker.md" = "devcouncil/campaign/prompts/worker.md"