@praneeth_54/agentdoctor 2.0.0 → 2.1.0

package/README.md

@@ -1,266 +1,442 @@
 # AgentDoctor
 
-**Codebase intelligence for developers, agents, and engineering teams.**
+## Engineering assurance for AI coding agents.
 
-Local-first tooling that helps you understand a repository, keep AI coding agents safer, and query evidence-backed project knowledge — without requiring a cloud account or API key.
+Understand your codebase, assess the impact of changes, govern engineering knowledge, enforce safety policies, and attach inspectable evidence to AI-driven changes.
 
 [![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 [![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
 [![License](https://img.shields.io/github/license/pranee54/AgentDoctor)](LICENSE)
 
-**Published package:** `@praneeth_54/agentdoctor@`**2.0.0**
+**Published:** [`@praneeth_54/agentdoctor@2.1.0`](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
+**Release notes:** [docs/RELEASE_2_1_0.md](docs/RELEASE_2_1_0.md) · Prior assurance cut: [docs/2.0.1/README.md](docs/2.0.1/README.md)
 
-[Documentation index](docs/README.md) · [AgentDoctor 2.0 docs](docs/2.0/README.md) · [Known limitations](docs/2.0/overview/known-limitations.md) · [Readiness matrix](docs/2.0/overview/readiness-matrix.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
+[Install](#install) · [Quickstart](#quickstart) · [Change assurance](#change-assurance) · [Project AI (2.1)](#project-ai-agent-21) · [Documentation](docs/2.0.1/README.md) · [MCP](#mcp) · [GitHub Action](#github-action) · [Architecture](#architecture)
 
 ---
 
-## What AgentDoctor does
+## What AgentDoctor is
 
-AgentDoctor combines three complementary layers:
+AgentDoctor sits between developers / AI coding agents and the repository’s engineering reality.
 
-1. **Safety** — audit and safely fix AI coding-agent configuration (scan → fix → verify → policy → CI).
-2. **Repository Brain** — evidence-backed claims, proposals, human review, and Project Brain MCP tools.
-3. **Codebase intelligence** — TypeScript/JavaScript AST graphs, git hotspots, impact analysis, knowledge governance, evaluate-only policy, and a combined MCP server.
+AI agents can write code quickly. The harder engineering problem is knowing whether a change is **correct, safe, compatible, explainable, and consistent** with the rest of the repository.
 
-It is **not** an autonomous coding agent, chatbot, or IDE process interceptor. It does **not** block Cursor/Claude/Codex unless you deliberately run commands through AgentDoctor’s controlled runner.
+AgentDoctor collects repository signals — source structure, graphs, Git history, policies, knowledge, and verification evidence — so humans and agents can reason about changes with fewer unsupported assumptions.
 
----
+**Who it is for**
 
-## Install
+| Audience               | How AgentDoctor helps                                                         |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| Manual developers      | Scan / fix / verify, change impact, evidence, architecture and policy checks  |
+| Students               | `learn` — explain project, viva, docs; **BUILD_WITH_ME** after approval       |
+| AI-assisted developers | Optional Project Chat (`ask` / `chat`) with evidence and truth labels         |
+| AI coding agents       | MCP + controlled tools; AgentDoctor owns context, execution, and verification |
 
-```bash
-npm install -g @praneeth_54/agentdoctor
-# or
-npx @praneeth_54/agentdoctor --help
+It is **not** a generic chatbot, IDE interceptor, or claim of full autonomy. Optional Project AI (2.1) is **opt-in** and still subject to approvals, path/runner controls, and verification. It does **not** guarantee correctness. It produces **evidence and controls** you can inspect.
+
+**Architecture (when AI is enabled):**
+
+```text
+THE MODEL REASONS.
+AGENTDOCTOR PROVIDES PROJECT CONTEXT.
+AGENTDOCTOR CONTROLS TOOLS.
+AGENTDOCTOR VERIFIES RESULTS.
 ```
 
-Requires **Node.js 20+**. The runtime depends on the TypeScript compiler API for AST analysis.
+**Short description:** Engineering assurance for AI coding agents — repository intelligence, change evidence, safety controls, MCP tools, and an optional Project AI Agent.
 
 ---
 
-## Quick start
+## Why AgentDoctor?
+
+Modern AI coding agents can:
+
+- read individual files
+- generate and edit code
+- run tests when asked
+
+Repository-level context is usually fragmented across:
+
+| Signal             | Typical location               |
+| ------------------ | ------------------------------ |
+| Source structure   | AST / imports / modules        |
+| Dependencies       | manifests / lockfiles          |
+| History            | Git                            |
+| Architecture       | docs / conventions / inference |
+| Tests              | test trees / naming heuristics |
+| Policy             | CI rules / allowlists          |
+| Decisions          | ADRs / RFCs / tribal knowledge |
+| Secrets / exposure | config files / ignore rules    |
+
+AgentDoctor brings those signals into one local toolchain around an AI-driven engineering change:
+
+```text
+Developer / AI Agent
+        │
+        ▼
+   AgentDoctor
+        │
+┌───────────────────────────────┐
+│ Repository Intelligence       │
+│ AST / Graph / Git / Impact    │
+├───────────────────────────────┤
+│ Engineering Knowledge         │
+│ Brain / Decisions / Provenance│
+├───────────────────────────────┤
+│ Safety & Policy               │
+│ Scan / Fix / Enforce / Secrets│
+├───────────────────────────────┤
+│ Verification                  │
+│ Tests / Reports / Evidence    │
+└───────────────────────────────┘
+        │
+        ▼
+Safer, explainable engineering decisions
+```
 
-```bash
-# Safety loop
-agentdoctor scan
-agentdoctor fix --dry-run
-agentdoctor verify --baseline agentdoctor-report.json
+---
 
-# Repository Brain proposals (never auto-approved)
-agentdoctor init --name "My App" --domain "payments"
-agentdoctor brain proposals
-agentdoctor brain review --artifact <id> --decision approved
+## Capability map
 
-# Intelligence
-agentdoctor graph --mode auto --json
-agentdoctor health --json
-agentdoctor c4 --json
-agentdoctor impact --json
-agentdoctor refactor-impact --symbol MySymbol --json
+Status labels: **SUPPORTED** · **PARTIAL** · **EXPERIMENTAL** · **NOT YET SUPPORTED**
 
-# Knowledge (draft → human approve)
-agentdoctor knowledge-create --title "Standard" --content "…"
-agentdoctor knowledge-approve --id <id> --decision approved
+Details and evidence: [docs/2.0/overview/capabilities.md](docs/2.0/overview/capabilities.md) · [readiness matrix](docs/2.0/overview/readiness-matrix.md)
 
-# Policy (evaluate-only by default)
-agentdoctor enforce --command "npm test" --json
+### Repository intelligence
 
-# MCP (Brain tools preserved; combined server adds intelligence tools)
-agentdoctor brain-mcp --root /ABS/PATH/TO/REPO
-agentdoctor mcp --root /ABS/PATH/TO/REPO
+| Capability                                           | Status       |
+| ---------------------------------------------------- | ------------ |
+| TypeScript / JavaScript AST graph (+ regex fallback) | PARTIAL      |
+| Import / inferred call relationships                 | PARTIAL      |
+| Git hotspot / engineering intelligence               | PARTIAL      |
+| Change / test / refactor impact                      | PARTIAL      |
+| C4-style architecture views                          | EXPERIMENTAL |
 
-# Local dashboard (loopback)
-agentdoctor dashboard
-```
+### Engineering knowledge
+
+| Capability                                                    | Status    |
+| ------------------------------------------------------------- | --------- |
+| Project Brain store + evidence-backed claims                  | SUPPORTED |
+| Repository Brain init / proposal review (never auto-approved) | PARTIAL   |
+| Governed knowledge + abstention on retrieve                   | PARTIAL   |
+| Provenance envelopes on Brain MCP tools                       | SUPPORTED |
+
+### Agent interfaces
+
+| Capability                                                                        | Status    |
+| --------------------------------------------------------------------------------- | --------- |
+| Brain MCP (`brain_*` tools, STDIO)                                                | SUPPORTED |
+| Combined MCP (Brain + intelligence tools)                                         | PARTIAL   |
+| Agent MCP (`project_ask`, path-safe file tools, plan, change verify) — 2.1        | PARTIAL   |
+| Optional Project Chat / coding agent CLI (`chat`, `ask`, `agent`, `learn`) — 2.1  | PARTIAL   |
+| Agent adapters (Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, Aider) | SUPPORTED |
+| Local dashboard + `/api/v2/*` + ask-only `/api/chat` — 2.1                        | PARTIAL   |
+| Programmatic API (`scan`, Fix, Brain helpers)                                     | SUPPORTED |
+
+### Safety & governance
+
+| Capability                                               | Status                |
+| -------------------------------------------------------- | --------------------- |
+| Scan → Safe Fix → Verify                                 | SUPPORTED             |
+| Policy gates (`--min-score`, severity, rule, verify-new) | SUPPORTED             |
+| Evaluate-only policy / controlled enforcement runner     | PARTIAL               |
+| Secret scan (redacted findings) + export redaction       | PARTIAL               |
+| Path-safety for MCP / dashboard                          | PARTIAL               |
+| Local-dev team auth (scrypt)                             | PARTIAL — **not SSO** |
+
+### Verification
+
+| Capability                                              | Status                     |
+| ------------------------------------------------------- | -------------------------- |
+| Change assurance assessment + evidence bundles          | PARTIAL                    |
+| Evidence hash verify (`verified` = integrity only)      | SUPPORTED                  |
+| Unit / integration / MCP STDIO tests (`npm run verify`) | SUPPORTED                  |
+| Packed CLI clean-install smoke                          | SUPPORTED                  |
+| Reproducible AST perf harness                           | PARTIAL (synthetic sample) |
 
 ---
 
-## Capability status (honest)
+## How AgentDoctor is different
+
+Most engineering tools optimize one layer: static analysis, search, docs generation, dashboards, security scanners, or AI chat.
 
-Classifications match [docs/2.0/overview/readiness-matrix.md](docs/2.0/overview/readiness-matrix.md). **No blanket 5/5 claims.**
+AgentDoctor is designed around the **lifecycle of an AI-driven change**:
 
-### Fully verified (shipped & regression-tested core)
+```text
+Repository
+    → Understand
+    → Impact
+    → Knowledge
+    → Policy
+    → Change
+    → Verification
+    → Evidence
+```
 
-| Capability                                                                        | Notes                                                      |
-| --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| Safety scan / Safe Fix / verify / policy gates                                    | Exit codes and CI Action preserved                         |
-| Agent adapters (Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, Aider) | Detect + rules; Safe Fix where official ignore/deny exists |
-| Project Brain store + Brain MCP tool names (`brain_*`)                            | STDIO MCP; `--root` required                               |
+That combination is the product direction. It does not mean every layer is equally mature — see the capability map and limitations.
 
-### Partially validated (implemented, tested; accuracy/perf not independently certified)
+---
 
-| Capability                                      | Entry points                                |
-| ----------------------------------------------- | ------------------------------------------- |
-| Repository Brain init / proposal review         | `init`, `brain review`, `brain proposals`   |
-| TS/JS AST intelligence graph (+ regex fallback) | `graph`                                     |
-| Git hotspots / bus-factor style metrics         | `health` (method disclosed per metric)      |
-| Impact / test-impact / refactor-impact          | `impact`, `test-impact`, `refactor-impact`  |
-| Knowledge governance + abstention               | `knowledge*`; MCP `knowledge_retrieve`      |
-| Policy packs + controlled enforcement runner    | `enforce`, `platform policy-check`          |
-| Combined MCP (`agentdoctor mcp`)                | Brain + intelligence tools                  |
-| Dashboard + `/api/v2/*`                         | `dashboard` (loopback default)              |
-| Local-dev team auth (scrypt)                    | `team-register`, `team-login` — **not SSO** |
+## Architecture
+
+```text
+AgentDoctor
+│
+├── Repository Intelligence
+│   ├── AST (TS/JS)
+│   ├── Graph
+│   ├── Git
+│   └── Impact
+│
+├── Engineering Knowledge
+│   ├── Brain
+│   ├── Governance
+│   └── Provenance
+│
+├── Safety
+│   ├── Scanner
+│   ├── Safe Fix
+│   ├── Secrets
+│   └── Policies
+│
+├── Agent Interface
+│   ├── MCP (brain-mcp / mcp)
+│   ├── CLI
+│   ├── API / dashboard
+│   └── Adapters
+│
+└── Verification
+    ├── Tests
+    ├── Reports
+    └── Release validation
+```
 
-### Experimental
+Code layout: `src/{intelligence,knowledge,core,mcp,platform,enforcement,cli}/`
 
-| Capability     | Notes                                                                             |
-| -------------- | --------------------------------------------------------------------------------- |
-| C4-style views | `c4` — **inferred/proposed** from graph evidence, not approved architecture truth |
+Canonical docs: [docs/2.0/overview/architecture.md](docs/2.0/overview/architecture.md)
+
+---
 
-### Unsupported / not claimed
+## Engineering principles
 
-| Topic                                            | Status                                             |
-| ------------------------------------------------ | -------------------------------------------------- |
-| Enterprise SSO / IdP                             | Not bundled                                        |
-| Production SQLite / Postgres / vector search     | Flags off / stub only                              |
-| Full multi-language AST (Python, Go, …)          | Unsupported                                        |
-| Direct IDE interception / agent process blocking | Unsupported                                        |
-| Coverage-backed test selection as ground truth   | Not bundled (test-impact is heuristic/graph-based) |
+1. Evidence over assumptions
+2. Explicit limitations over inflated claims
+3. Safety before automation
+4. Repository context over isolated files
+5. Human approval for governed decisions
+6. Backwards compatibility where documented
+7. Reproducible verification
+8. Explainable agent actions
+9. Least privilege
+10. Secure defaults
 
 ---
 
-## Safety (preserved)
+## Install
 
-Scan agent configs and repository hygiene; apply Safe Fix where supported; verify against a baseline; fail CI on severity/score gates.
+Requires **Node.js 20+**.
 
 ```bash
-agentdoctor scan --json
-agentdoctor fix -y
-agentdoctor verify --baseline agentdoctor-report.json
+npm install -g @praneeth_54/agentdoctor@2.1.0
+# or:
+npx @praneeth_54/agentdoctor@2.1.0 --help
 ```
 
-GitHub Action: pin `pranee54/AgentDoctor@v2.0.0` (default npm version input is `2.0.0`). Surfaces matrix: [docs/reference/surfaces-and-adapters.md](docs/reference/surfaces-and-adapters.md).
+From source:
 
-```yaml
-- uses: pranee54/AgentDoctor@v2.0.0
-  with:
-    path: .
-    version: "2.0.0"
+```bash
+git clone https://github.com/pranee54/AgentDoctor.git
+cd AgentDoctor
+npm install
+npm run verify
 ```
 
 ---
 
-## Repository Brain
-
-`agentdoctor init` writes **PROPOSED** artifacts under `.agentdoctor/repository-brain/proposals/`. They are **not** facts until a human reviews them.
+## Quickstart
 
 ```bash
-agentdoctor brain init
-agentdoctor brain snapshot
-agentdoctor brain review --artifact prop_… --decision approved|rejected
+agentdoctor --version          # 2.1.0
+agentdoctor scan .
+agentdoctor scan . --json
+agentdoctor fix --dry-run
+agentdoctor verify --baseline agentdoctor-report.json
+
+# Repository Brain proposals (not auto-approved)
+agentdoctor init --name "My App" --domain "payments"
+agentdoctor brain proposals
+
+# Intelligence
+agentdoctor graph --mode auto --json
+agentdoctor impact --json
+agentdoctor c4 --json
+
+# Change assurance
+agentdoctor change analyze
+agentdoctor change verify
+agentdoctor change explain|diff|status
+agentdoctor evidence inspect <id>
+agentdoctor evidence verify <id>
+agentdoctor proof build|inspect|verify|export <id>
+
+# Architecture / policy / controlled run
+agentdoctor architecture init|check|explain
+agentdoctor policy check|explain --command "npm test"
+agentdoctor run explain --command "npm test"
+agentdoctor workspace create|add|list|status|remove
+
+# MCP (absolute --root required)
+agentdoctor brain-mcp --root /ABS/PATH/TO/REPO
+agentdoctor mcp --root /ABS/PATH/TO/REPO
 ```
 
-Guide: [docs/2.0/guides/repository-brain.md](docs/2.0/guides/repository-brain.md).
+### Project AI Agent (2.1 — optional; local RC)
 
----
+Requires an explicit provider (`AGENTDOCTOR_AI_PROVIDER=mock` or openai-compatible / ollama). Default `none` fails closed for chat.
 
-## Codebase intelligence
+```bash
+agentdoctor ask "How does login work?" .
+agentdoctor chat .
+agentdoctor learn .
+agentdoctor learn --viva
+agentdoctor plan "Add registration"
+# Writes require --approve; model cannot self-approve
+agentdoctor agent --goal "Add registration" --approve --apply --apply-ops '[...]' .
+```
 
-- **AST graph** — TypeScript/JavaScript via the TypeScript compiler API; regex fallback when needed (`graph --mode auto|typescript-ast|regex`).
-- **Git intelligence** — recent-window hotspots / co-change heuristics with method disclosure (`health`).
-- **C4 views** — inferred diagrams (`c4`); label them proposed/inferred.
-- **Impact** — change/test/refactor blast-radius helpers (`impact`, `refactor-impact`).
+Details: [docs/RELEASE_2_1_0.md](docs/RELEASE_2_1_0.md) · [docs/AI_AGENT.md](docs/AI_AGENT.md) · [docs/SECURITY_AGENT.md](docs/SECURITY_AGENT.md)
 
-Limitations: call resolution is best-effort; non-TS languages are not deeply analyzed.
+CLI reference: [docs/2.0/guides/cli.md](docs/2.0/guides/cli.md) · Change assurance: [docs/2.0.1/change-assurance.md](docs/2.0.1/change-assurance.md)
 
 ---
 
-## Knowledge governance
+## Project AI Agent (2.1)
+
+Optional Project AI on top of the 2.0.1 assurance substrate. See [docs/RELEASE_2_1_0.md](docs/RELEASE_2_1_0.md).
 
-Draft → pending-review → approved/rejected. Retrieval **abstains** when no approved record matches.
+| Piece     | Behavior                                                                  |
+| --------- | ------------------------------------------------------------------------- |
+| Context   | Project evidence with truth labels; repository text is untrusted DATA     |
+| Tools     | Path-safe read/write; commands only via controlled runner (`shell=false`) |
+| Approvals | Human/caller `--approve` required for writes; LEARN mode cannot write     |
+| Verify    | Change / evidence / proof signals; `ENGINEERING_CORRECTNESS_NOT_CLAIMED`  |
+| Limits    | Tool calls, iterations, wall time, files modified, context size           |
 
-Guide: [docs/2.0/guides/knowledge-governance.md](docs/2.0/guides/knowledge-governance.md).
+Limitations: not an OS sandbox; native Anthropic/Gemini SDKs not implemented; MCP `approved=true` is trusted-caller input (not cryptographic identity); correctness never guaranteed.
 
 ---
 
-## Policy evaluation and controlled enforcement
+## Change assurance
+
+Structured assessment, evidence bundles, and Change Proof **integrity** (not engineering correctness). Optional `--coverage` for coverage-backed / hybrid test impact. See [docs/2.0.1/FINAL_COMPLETION_AUDIT.md](docs/2.0.1/FINAL_COMPLETION_AUDIT.md).
 
-| Mode                                                               | Behavior                                                                                  |
-| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| Policy evaluation (`platform policy-check`, MCP `policy_evaluate`) | Verdict only; `executionResult: "not-executed"`                                           |
-| Controlled runner (`enforce`)                                      | Can report `blocked-by-enforcement` when **AgentDoctor** refuses to run a blocked command |
-| Third-party IDEs                                                   | **Not** intercepted                                                                       |
+```bash
+agentdoctor change analyze              # ChangeAssessment (verificationStatus: not-run)
+agentdoctor change verify               # write .agentdoctor/evidence/<id>/ (evidence-produced)
+agentdoctor change explain|diff|status
+agentdoctor evidence inspect <id>       # list artifacts + manifest
+agentdoctor evidence verify <id>        # SHA-256 check; verified only if all hashes match
+agentdoctor proof inspect|verify <id>   # integrity; correctnessStatus always NOT_CLAIMED
+```
 
-Trust boundaries: [docs/2.0/overview/trust-boundaries.md](docs/2.0/overview/trust-boundaries.md).
+`verified` means artifact integrity against the manifest — not that the change is correct or safe. Details: [docs/2.0.1/change-assurance.md](docs/2.0.1/change-assurance.md) · [docs/2.0.1/evidence.md](docs/2.0.1/evidence.md)
 
 ---
 
 ## MCP
 
-| Command                               | Server     | Tools                      |
-| ------------------------------------- | ---------- | -------------------------- |
-| `agentdoctor brain-mcp --root <path>` | Brain only | Stable `brain_*` names     |
-| `agentdoctor mcp --root <path>`       | Combined   | Brain + intelligence tools |
+AgentDoctor exposes local **STDIO** MCP servers (no API key).
 
-MCP docs: [docs/2.0/guides/mcp.md](docs/2.0/guides/mcp.md) · legacy detail: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md).
+| Server       | Command                              | Tools                                                                                                                                                               |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Brain MCP    | `agentdoctor brain-mcp --root <abs>` | `brain_overview`, `brain_query`, `brain_explain`, `brain_trace`, `brain_claims`, `brain_evidence`, `brain_ownership`, `brain_risk`, `brain_delta`, `brain_snapshot` |
+| Combined MCP | `agentdoctor mcp --root <abs>`       | All `brain_*` tools **plus** intelligence tools below                                                                                                               |
+
+Intelligence tools (combined MCP):
+`repo_overview`, `codebase_search`, `symbol_lookup`, `dependency_lookup`, `call_graph_lookup`, `test_impact`, `refactor_impact`, `code_health`, `architecture_info`, `architecture_check`, `knowledge_retrieve`, `policy_evaluate`, `change_analyze`, `proof_inspect`, `evidence_inspect`, `graph_query`
+
+Guide: [docs/2.0/guides/mcp.md](docs/2.0/guides/mcp.md) · Deep Brain MCP: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)
 
 ---
 
-## CLI / API / dashboard
+## GitHub Action
 
-- CLI index: [docs/2.0/guides/cli.md](docs/2.0/guides/cli.md)
-- HTTP API (local dashboard): [docs/2.0/guides/api.md](docs/2.0/guides/api.md)
-- Dashboard defaults to `127.0.0.1`; `?user=` role selection is **not** authentication
+Use AgentDoctor Safety in CI for scan / verify gates. Default npm version input is **`2.1.0`**.
 
-```bash
-agentdoctor dashboard
-agentdoctor doctor --json
+```yaml
+- uses: pranee54/AgentDoctor@v2.1.0
+  with:
+    path: .
+    version: "2.1.0"
+    fail-on-severity: critical
 ```
 
+For repository CI against the checked-out build: `version: workspace` (requires `dist/` from `npm run build`).
+
+Guide: [docs/2.0/guides/github-action.md](docs/2.0/guides/github-action.md) · Action metadata: [`action.yml`](action.yml)
+
+Marketplace listing: confirm in the GitHub UI if you need Marketplace discovery beyond the Action in this repository.
+
 ---
 
-## Local-development team authentication
+## Security model
 
-```bash
-agentdoctor team-register --username alice --password '………'
-agentdoctor team-login --username alice --password '………'
-```
+| Control     | Behavior                                                                   |
+| ----------- | -------------------------------------------------------------------------- |
+| Path safety | MCP / dashboard reject traversal, encoded escapes, hostile URLs            |
+| Safe Fix    | Preflight targets; refuse symlink write-through / non-allowlisted paths    |
+| Secrets     | Opt-in scan; findings and exports redact sensitive patterns                |
+| Policy      | Evaluate-only by default (`executionResult: "not-executed"`)               |
+| Enforcement | Controlled runner blocks; does **not** claim IDE interception              |
+| Dashboard   | Loopback by default; non-loopback requires explicit opt-in                 |
+| Team auth   | Local-dev scrypt + optional OIDC JWT validation — **not** full browser SSO |
 
-This is **local-dev scrypt auth**, clearly labeled — **not** enterprise SSO.
+Threat model: [docs/2.0/overview/security-threat-model.md](docs/2.0/overview/security-threat-model.md) · Trust boundaries: [docs/2.0/overview/trust-boundaries.md](docs/2.0/overview/trust-boundaries.md)
 
 ---
 
-## Important limitations (read before adopting)
+## What AgentDoctor does not do
 
-1. AST depth is **TypeScript/JavaScript**-oriented.
-2. Test-impact is **heuristic / graph-based**, not coverage-oracle accurate.
-3. C4 views are **inferred**, not approved architecture.
-4. Firewall is **evaluate-only** unless you use AgentDoctor’s controlled runner.
-5. Team auth is **local-dev**, not SSO.
-6. No IDE interception.
-7. No production SQLite/Postgres/vector backend in this package.
-8. No complete multi-language AST.
-9. Deep 2.0 audits and readiness reports live on GitHub under [docs/2.0/](docs/2.0/README.md) (not inside the npm tarball — packaging Option B).
+- Full browser OAuth / production IdP login UX (JWT validation library path exists; redirect flow is experimental)
+- Complete multi-language AST (Java / Kotlin / Rust / Dart / Go extractors external or unsupported)
+- Coverage as universal ground truth without a coverage file / test map
+- IDE / agent process interception (external host APIs)
+- Production multi-tenant cloud / managed hosting in this package
+- Guaranteed autonomous command execution of “allowed” policies
+- Treating inferred C4 / heuristic impact as approved architecture truth
+- Shipping full `docs/2.0.1/` inside the npm tarball (Option B: README + GitHub docs)
 
-Full list: [docs/2.0/overview/known-limitations.md](docs/2.0/overview/known-limitations.md).
+Full list: [docs/2.0.1/limitations.md](docs/2.0.1/limitations.md) · [docs/2.0/overview/known-limitations.md](docs/2.0/overview/known-limitations.md)
 
 ---
 
-## Compatibility
+## Roadmap note: Change Proof
+
+Change assessment, evidence, and proof **integrity** shipped in 2.0.1. `correctnessStatus` is always `ENGINEERING_CORRECTNESS_NOT_CLAIMED`. Broader compliance / team-scale proof UX remains planned.
 
-- Safety CLI exit codes and Brain MCP tool names are preserved.
-- Additive 2.0 commands do not remove 1.x workflows.
-- Migration notes: [docs/2.0/guides/migration.md](docs/2.0/guides/migration.md).
+See [ROADMAP.md](ROADMAP.md) · [docs/2.0.1/limitations.md](docs/2.0.1/limitations.md) · [docs/2.0.1/FINAL_COMPLETION_AUDIT.md](docs/2.0.1/FINAL_COMPLETION_AUDIT.md).
 
 ---
 
 ## Documentation map
 
-| Area             | Link                                                                       |
-| ---------------- | -------------------------------------------------------------------------- |
-| 2.0 index        | [docs/2.0/README.md](docs/2.0/README.md)                                   |
-| CLI / MCP / API  | [docs/2.0/guides/](docs/2.0/guides/)                                       |
-| Release blockers | [docs/2.0/audits/release-blockers.md](docs/2.0/audits/release-blockers.md) |
-| Docs hub         | [docs/README.md](docs/README.md)                                           |
-| Changelog        | [CHANGELOG.md](CHANGELOG.md)                                               |
-| Contributing     | [CONTRIBUTING.md](CONTRIBUTING.md)                                         |
+| Audience                               | Start here                                                                                                                |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Product / 2.0.1                        | [docs/2.0.1/README.md](docs/2.0.1/README.md)                                                                              |
+| Product / 2.0                          | [docs/2.0/README.md](docs/2.0/README.md)                                                                                  |
+| Capabilities / readiness               | [capabilities](docs/2.0/overview/capabilities.md) · [readiness](docs/2.0/overview/readiness-matrix.md)                    |
+| Guides                                 | [docs/2.0/guides/](docs/2.0/guides/)                                                                                      |
+| Reference (rules, scoring, exit codes) | [docs/reference/](docs/reference/)                                                                                        |
+| Contributing                           | [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/development/development.md](docs/development/development.md)                   |
+| Changelog                              | [CHANGELOG.md](CHANGELOG.md)                                                                                              |
+| Release evidence                       | [FINAL_RELEASE_AUDIT](docs/2.0.1/FINAL_RELEASE_AUDIT.md) · [FINAL_COMPLETION_AUDIT](docs/2.0.1/FINAL_COMPLETION_AUDIT.md) |
 
 ---
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/development/development.md](docs/development/development.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). Prefer evidence-backed PRs, honest status labels, and no inflated capability claims.
 
 ---
 

package/dist/agent/approvals.d.ts

@@ -0,0 +1,24 @@
+import type { AgentRiskLevel, AgentToolName } from "./tools/types.js";
+export type ApprovalDecision = "allow" | "deny" | "require-approval";
+export interface ApprovalRequest {
+    action: string;
+    risk: AgentRiskLevel;
+    toolName?: AgentToolName;
+    detail?: string;
+}
+export interface ApprovalResult {
+    decision: ApprovalDecision;
+    risk: AgentRiskLevel;
+    reason: string;
+    /** True when a human must confirm before continuing */
+    needsHumanApproval: boolean;
+}
+/**
+ * Risk-based approval gate. The model cannot approve its own actions.
+ * Human approval is represented by an explicit `approvedByHuman` flag from CLI/UI.
+ */
+export declare function evaluateApproval(request: ApprovalRequest, options?: {
+    approvedByHuman?: boolean;
+    allowAutoLow?: boolean;
+}): ApprovalResult;
+export declare function formatApprovalPrompt(request: ApprovalRequest, result: ApprovalResult): string;