@orangepro/orangepro-mcp 0.1.0

package/docs/agent-workflow.md

@@ -0,0 +1,167 @@
+# Coding Agent Workflow
+
+OrangePro builds the local evidence graph. Your coding agent writes files, runs
+tests, and reports results.
+
+## Setup
+
+For Codex, prefer the plugin when it is available:
+
+```bash
+codex plugin add orangepro
+```
+
+Until OrangePro is accepted into a default marketplace, add this repo as a Codex marketplace:
+
+```bash
+codex plugin marketplace add OrangeproAI/orangepro-mcp --sparse .agents/plugins --sparse plugins/orangepro
+codex plugin add orangepro@orangepro
+```
+
+For maintainer-local development before npm publishing:
+
+```bash
+codex plugin add orangepro@personal
+```
+
+For Claude Code, add this repo as a Claude plugin marketplace and install the bundled MCP plugin:
+
+```text
+/plugin marketplace add OrangeproAI/orangepro-mcp
+/plugin install orangepro@orangepro
+/reload-plugins
+```
+
+For Cursor, install OrangePro from the Cursor Marketplace when available. Until then, use the bundled plugin directory at `plugins/orangepro` for local testing, or add the MCP server manually from the Cursor doc.
+
+## Publishing Checklist
+
+Before public plugin launch:
+
+1. Publish `@orangepro/orangepro-mcp` to npm so plugin MCP configs can run `npx -y -p @orangepro/orangepro-mcp@latest opro mcp`.
+2. Create and verify the fresh-history public export; do not publish a repo with private history.
+3. Codex: ship `.agents/plugins/marketplace.json` and `plugins/orangepro`; bare `codex plugin add orangepro` needs a configured/default marketplace listing.
+4. Claude Code: ship `.claude-plugin/marketplace.json` and `plugins/orangepro`; directory discovery is a separate marketplace/listing step.
+5. Cursor: submit `plugins/orangepro` to the Cursor Marketplace when ready; local testing uses that same directory.
+6. OpenCode / VS Code: keep the MCP snippets current until they expose a plugin marketplace path for this style of local server.
+7. Smoke every path in a clean checkout and verify no config pins a model or commits a provider key.
+
+Build the CLI and print a client-ready MCP block:
+
+```bash
+npm run build
+opro
+opro agent --client claude-code
+opro agent --client cursor
+opro agent --client codex
+opro agent --client opencode
+```
+
+Use `--json` if your setup script wants structured output:
+
+```bash
+opro agent --client generic --json
+```
+
+The generated MCP config points at the local `opro mcp` server and intentionally
+does not pin a model. If your MCP client does not inherit shell environment
+variables, add provider keys/model defaults to that client's local config, or
+place provider values in a local `.env.provider.local` file in the
+repo/workspace. Do not commit client config files or env files that contain keys.
+
+## Agent Instruction
+
+Use this as the short instruction for Codex, Claude Code, Cursor, OpenCode, Windsurf, or
+any MCP-capable coding agent:
+
+```text
+Use OrangePro before writing tests.
+
+Start:
+1. Call orangepro_start for the local checkout.
+2. If it reports a large-repo scope breakdown, prefer the suggested focused scope for AI/generation; full deterministic analysis is still allowed.
+3. Use its graph_html_path, rtm path, and next_actions as the test plan.
+4. If AI grounding is skipped, continue with the deterministic graph instead of asking the user for extra commands.
+
+For PR work:
+1. Call orangepro_generate_tests with base_ref=main.
+2. Use the changed behaviors returned by orangepro_start as context.
+3. Use only generated tests that include run_hints.
+4. Write each body to its suggested_path.
+5. Run the run_command from the owning package directory.
+6. After a pass, call the returned prove_run args to attempt public Proven; use record_run only for static diagnostics.
+7. Report pass/fail with stack traces and exact setup problems.
+
+For baseline work:
+1. Call orangepro_find_test_gaps.
+2. Pick one high-priority gap.
+3. Call orangepro_generate_tests for that target.
+4. Write, run, and report only runnable tests.
+5. After a pass, call the returned prove_run args to attempt public Proven; use record_run only for static diagnostics.
+
+Do not treat drafts as runnable tests. Drafts are context.
+Do not claim coverage changed unless OrangePro reports Proven, Reproven, Runtime-covered, Associated signal, or No integration signal changed.
+```
+
+## CLI Fallback
+
+If the agent has shell access but no MCP client, use the CLI:
+
+```bash
+opro
+opro start . --generate-coverage
+opro gaps --limit 10
+opro generate --base main --single --limit 3
+opro generate --target <target-id> --single --limit 1
+opro explain <generated-test-id>
+opro export --format graph-html --out .orangepro/graph.html
+```
+
+`generate --base main` is read-only: it uses `git diff` and does not check out a
+PR. `generate --pr <n>` is the mutating escape hatch and should only be used when
+the developer explicitly allows the working tree to switch.
+
+## What Counts
+
+- **Runnable**: the generated test has `run_hints`, the agent writes it to
+  `suggested_path`, and the repo's test runner executes it.
+- **Draft**: grounded context with no run command. Useful for a developer, but
+  not a runnable-test claim.
+- **Proven**: dynamic targeted-proof ledger certificate closed for the behavior; no LLM judgment or static-only match is involved.
+- **Reproven**: this run produced the dynamic proof certificate. Older static re-analysis records are associated diagnostics until that certificate exists.
+- **Runtime-covered**: the repo's own coverage tool executed the code; this is runtime observation, not assertion-level proof.
+- **Associated signal**: OrangePro found a name, path, import, or structural test signal, but not semantic proof.
+- **No integration signal**: no static test signal was found.
+
+Generated-test promotion numbers should count only tests that run in the target
+repo, reference real product symbols, and contain non-vacuous assertions.
+
+## AGENTS.md Snippet
+
+For repos that use an `AGENTS.md`, keep the OrangePro instruction short:
+
+```markdown
+## OrangePro Test Workflow
+
+- Run `opro` before adding tests. It writes graph, RTM, optional AI weak grounding when configured, and next actions.
+- For PR work, run `opro generate --base main --single --limit 3`.
+- For baseline gaps, run `opro gaps --limit 10`, pick one target, then run
+  `opro generate --target <target-id> --single --limit 1`.
+- Write only tests that include `run_hints`; drafts are context, not runnable claims.
+- Write each generated body to `suggested_path`, run `run_command`, call the returned `prove_run` args after a pass to attempt public Proven. Use `record_run` only for static diagnostics.
+- Report coverage status as Proven / Reproven / Runtime-covered / Associated signal / No integration signal. Do not promote Associated signal or AI links to Proven.
+```
+
+## Verification Loop
+
+After the agent writes a passing test:
+
+```bash
+opro
+opro start . --generate-coverage
+opro status
+opro gaps --limit 10
+```
+
+Report what changed. If nothing moved from No integration signal or Associated signal to Proven, say so
+plainly.

package/docs/agents/claude-code.md

@@ -0,0 +1,43 @@
+# OrangePro With Claude Code
+
+## Install
+
+```bash
+npm install -g @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
+
+`opro` prepares the behavior report, RTM, and agent next actions. If your shell has a model key, weak AI grounding and AI-suggested candidate flows run automatically. AI lanes are suggestions only; Proven remains dynamic targeted proof only.
+
+## Claude Plugin
+
+Install the bundled plugin from this repo marketplace:
+
+```text
+/plugin marketplace add OrangeproAI/orangepro-mcp
+/plugin install orangepro@orangepro
+/reload-plugins
+```
+
+The plugin starts the `orangepro-local` MCP server automatically and exposes the `/orangepro:opro` skill. It does not pin a model; OrangePro uses provider/model values from the environment, `.env.provider.local`, `.env.local`, `.env`, or `opro setup`.
+
+## MCP Setup
+
+Print the Claude Code config:
+
+```bash
+opro agent --client claude-code
+```
+
+Paste the printed `mcpServers.orangepro-local` block into the project `.mcp.json` or your Claude Code MCP config. If Claude Code does not inherit shell variables, add the provider key to that local config, or keep it in a repo-local `.env.provider.local` file that is not committed.
+
+The printed config intentionally does not pin a model. OrangePro uses the provider/model configured in the process environment, `.env.provider.local`, `.env.local`, `.env`, or `opro setup`.
+
+If your Claude Code setup supports custom slash commands, map `/opro` to: call `orangepro_start` for the current checkout, then follow the returned `next_actions`. The command should call the MCP tool; it should not run a separate source-writing script.
+
+## Agent Prompt
+
+```text
+Use OrangePro first. Call orangepro_start, then use orangepro_generate_tests for the returned PR or gap target. Write each runnable test to suggested_path, run run_command, and call prove_run with the result for public Proven. Use record_run only for static diagnostics. Do not treat drafts as runnable tests.
+```

package/docs/agents/codex.md

@@ -0,0 +1,52 @@
+# OrangePro With Codex
+
+## Install
+
+```bash
+npm install -g @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
+
+`opro` writes `.orangepro/behavior-coverage.html` and `.orangepro/rtm.md`. If a model key is available in the environment, it also applies weak AI grounding and AI-suggested candidate flows automatically. Proven coverage still comes only from dynamic targeted proof.
+
+## Codex Plugin
+
+When OrangePro is available in your configured Codex marketplace, install it like any other plugin:
+
+```bash
+codex plugin add orangepro
+```
+
+Until OrangePro is accepted into a default marketplace, add this repo as a Codex marketplace and install from it:
+
+```bash
+codex plugin marketplace add OrangeproAI/orangepro-mcp --sparse .agents/plugins --sparse plugins/orangepro
+codex plugin add orangepro@orangepro
+```
+
+For maintainer-local development before npm publishing, install the personal marketplace plugin:
+
+```bash
+codex plugin add orangepro@personal
+```
+
+The plugin starts the `orangepro-local` MCP server. It does not pin an LLM model; OrangePro uses the provider/model configured in your environment, `.env.provider.local`, `.env.local`, `.env`, or `opro setup`.
+
+## MCP Setup
+
+Print a Codex-ready config block:
+
+```bash
+opro agent --client codex
+```
+
+Add the printed `mcpServers.orangepro-local` block to the MCP settings your Codex environment uses. The printed config intentionally omits model settings. If Codex does not inherit your shell environment, put `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OLLAMA_BASE_URL` in the local client config, or keep them in a repo-local `.env.provider.local` file that is not committed.
+
+If your Codex build supports plugin/shortcut commands, map `$opro` (or `/opro`) to: call `orangepro_start` for the current checkout, then follow the returned `next_actions`. The MCP tool is the source of truth; the shortcut is just a convenience wrapper.
+
+## Agent Prompt
+
+```text
+Use OrangePro first. Call orangepro_start for this checkout, inspect the returned next_actions, then generate tests only through orangepro_generate_tests. Write only runnable tests with run_hints. After running them, call prove_run with the provided args for public Proven. Use record_run only for static diagnostics.
+```

package/docs/agents/cursor.md

@@ -0,0 +1,39 @@
+# OrangePro With Cursor
+
+## Install
+
+```bash
+npm install -g @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
+
+The first `opro` run creates `.orangepro/behavior-coverage.html`, `.orangepro/rtm.md`, and an agent-ready plan. With a configured model key, weak AI grounding and AI-suggested candidate flows are applied automatically and stay out of Proven coverage.
+
+## Cursor Plugin
+
+Install OrangePro from the Cursor Marketplace when it is listed. Until then, use the bundled plugin directory for local testing:
+
+```text
+plugins/orangepro
+```
+
+The plugin starts the `orangepro-local` MCP server through `npx -y -p @orangepro/orangepro-mcp@latest opro mcp` and applies OrangePro rules for gap/test workflows. It does not pin a model; provider keys and model defaults come from your environment, `.env.provider.local`, `.env.local`, `.env`, or `opro setup`.
+
+## MCP Setup
+
+Print the Cursor MCP block:
+
+```bash
+opro agent --client cursor
+```
+
+Paste the printed block into Cursor Settings -> MCP or `~/.cursor/mcp.json`. If Cursor does not inherit your shell environment, add the provider key to the local MCP config, or keep it in a repo-local `.env.provider.local` file that is not committed.
+
+If your Cursor setup supports custom commands, map `/opro` to: call `orangepro_start` for the current checkout, then follow the returned `next_actions`. The shortcut should use the MCP tool so Proven / Associated signal / No integration signal semantics stay intact.
+
+## Agent Prompt
+
+```text
+Use OrangePro first. Call orangepro_start in this repo, then follow its next_actions. Generate tests with orangepro_generate_tests, write only runnable outputs with run_hints, run the suggested command, and call prove_run after a passing run for public Proven. Use record_run only for static diagnostics.
+```

package/docs/agents/opencode.md

@@ -0,0 +1,43 @@
+# OrangePro With OpenCode
+
+## Install
+
+```bash
+npm install -g @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
+
+`opro` is the one-command preparation step: behavior report, RTM, optional weak AI grounding and AI-suggested candidate flows when a provider key is configured, and next actions for the agent.
+
+## MCP Setup
+
+Print the OpenCode MCP block:
+
+```bash
+opro agent --client opencode
+```
+
+Add the printed `mcpServers.orangepro-local` block to your OpenCode MCP settings. If OpenCode does not inherit your shell environment, put the model provider key in the local MCP config, or keep it in a repo-local `.env.provider.local` file that is not committed.
+
+For a direct OpenCode config, add this server under `mcp`:
+
+```jsonc
+{
+  "mcp": {
+    "orangepro-local": {
+      "enabled": true,
+      "command": "npx",
+      "args": ["-y", "-p", "@orangepro/orangepro-mcp@latest", "opro", "mcp"]
+    }
+  }
+}
+```
+
+If your OpenCode setup supports slash or dollar commands, map `/opro` or `$opro` to: call `orangepro_start` for the current checkout, then follow the returned `next_actions`. The shortcut should call the MCP tool; it is not a separate graph builder.
+
+## Agent Prompt
+
+```text
+Use OrangePro first. Call orangepro_start, generate tests only through orangepro_generate_tests, write runnable tests with run_hints, run the command, and call prove_run after a pass for public Proven. Use record_run only for static diagnostics. Report setup failures plainly.
+```

package/docs/agents/vscode.md

@@ -0,0 +1,34 @@
+# OrangePro With VS Code / Copilot
+
+## Install
+
+```bash
+npm install -g @orangepro/orangepro-mcp
+cd /path/to/your/repo
+opro
+```
+
+`opro` writes `.orangepro/behavior-coverage.html`, `.orangepro/rtm.md`, and next actions. With a configured provider key, weak AI grounding and AI-suggested candidate flows run automatically and stay out of Proven coverage.
+
+## MCP Setup
+
+Add OrangePro as an MCP server in your user or workspace MCP config:
+
+```json
+{
+  "servers": {
+    "orangepro-local": {
+      "command": "npx",
+      "args": ["-y", "-p", "@orangepro/orangepro-mcp@latest", "opro", "mcp"]
+    }
+  }
+}
+```
+
+Do not hardcode provider keys in a committed workspace config. Prefer your shell environment, `.env.provider.local`, `.env.local`, `.env`, or `opro setup`.
+
+## Agent Prompt
+
+```text
+Use OrangePro first. Call orangepro_start for this repo, then follow next_actions. Generate tests with orangepro_generate_tests, write only runnable outputs with run_hints, run the suggested command, and call prove_run after a pass for public Proven. Use record_run only for static diagnostics.
+```

package/docs/local-proof-kit.md

@@ -0,0 +1,269 @@
+# OrangePro (`opro`)
+
+Try graph-grounded test generation **on your own machine, before creating a tenant
+or granting repo access.** OrangePro builds an evidence graph from a
+local checkout, scores its readiness, generates a few grounded tests with **your own
+model key**, and exports a portable evidence pack you can inspect — and later promote
+into a hosted OrangePro tenant.
+
+## Privacy first
+
+- **No stored source.** Source is read in-process. When model generation is enabled,
+  redacted source excerpts may be sent to your configured BYOK provider; OrangePro does
+  not upload repos to an OrangePro tenant and does not store raw source in local artifacts.
+- **Metadata-only artifacts.** `metadata_only` means **no source code** in the graph,
+  manifest, or evidence pack — only file paths, names, hashes, frameworks, and provenance.
+  Source files are read in-process only to ground generation, and obvious secrets are
+  redacted first. **Generated test bodies are model output kept in the local graph; the
+  exported pack and graph HTML exclude them by default — embed bodies in the pack only with
+  `--include-generated-bodies`.** *Text you explicitly supply via a CSV/Markdown template* (requirement
+  titles, descriptions, acceptance criteria) **is** included in the pack — that text is the
+  reviewed evidence you chose to provide, so keep templates to releasable business metadata.
+- **Your keys stay yours.** Model API keys are read from the environment at call time
+  and are never written into the graph, config, or pack.
+- **Local only.** All workspace-local writes live under `.orangepro/`; no source or test files in your repo are written. Add
+  `.orangeproignore` (same spirit as `.gitignore`) to exclude paths from analysis.
+
+## Install
+
+```bash
+npm ci && npm run build
+npm link   # one-time: exposes the short `opro` command on your PATH
+# CLI is then available as: opro …  (equivalently node dist/local/cli.js …, or `npm run local -- …` in dev)
+```
+
+## Demo (one reproducible run)
+
+```bash
+node scripts/demo-local-proof-kit.mjs --repo /path/to/repo --provider deterministic
+```
+
+Runs analyze → score → doctor → gaps → generate (Local KG vs raw prompt) → export
+end-to-end in a throwaway workspace and prints a readable report when running from a
+source checkout. npm users can run the CLI commands below directly.
+
+## CLI
+
+```bash
+opro                            # one-command start: analyze, optional AI weak links, graph, RTM, next actions
+opro init                       # create the .orangepro/ workspace
+opro analyze .                  # build the local evidence graph + write .orangepro/graph.html (scan-all by default)
+opro status                     # fresh / stale / missing + score + privacy
+opro doctor                     # smallest next source that improves test quality
+opro score                      # readiness score + breakdown + "why not higher"
+opro gaps --limit 10            # behaviors with weak/missing test evidence
+opro generate --target REQ-001 --framework playwright --limit 3   # default: A/B (prompt-only vs Local KG), scored + report
+opro generate --single --limit 3   # one arm only — persists the tests to the graph
+opro generate --base main       # PR-scoped: target only behaviors the diff vs main touches
+opro generate --pr 123          # advanced: checks out PR #123 (changes your working tree), re-analyzes, targets its diff
+opro generate --base main --background   # PR-scoped + detached; poll with `opro jobs`
+opro jobs [<id>]                # list background jobs, or show one (status + outputs + log)
+opro explain <generated_test_id># which evidence anchors grounded a test
+opro update                     # incremental, non-destructive refresh
+opro changed --base main        # changed files + affected behaviors/tests
+opro export --out orangepro-evidence-pack.json
+opro analyze . --no-graph-html  # skip the explorer (it is written by default)
+opro export --format graph-html # write just the explorer (orangepro-graph.html)
+opro mcp                        # run the MCP server (stdio)
+```
+
+Report commands default to `.orangepro/`. When you are collecting a public
+validation bundle, pass an explicit local path such as
+`opro rtm --format json --out /tmp/orangepro-run/rtm.json`.
+
+Runnable Python and Go generation uses local syntax validators before OrangePro
+returns a run command: `python3` for pytest bodies and `gofmt` for Go bodies. If
+the toolchain is missing or the generated body is not valid for that language,
+the test is returned as a grounded draft with no run hint.
+
+Scan-all is the default: `analyze` no longer caps inferred behavior anchors at a low
+number (lower it with `ORANGEPRO_MAX_FLOWS` / `ORANGEPRO_MAX_FILES` only to bound a
+huge run), and it prints `files scanned: N` plus any cap that was hit.
+
+### Evidence graph explorer
+
+`analyze` writes a **self-contained, offline** HTML explorer to `.orangepro/graph.html`
+**by default** (`--no-graph-html` to skip; or `export --format graph-html` for a
+standalone copy) — no CDN, no network, metadata-only (never source, bodies, or prompts).
+It opens
+score-first, shows a *summarized* evidence layer (not a 3k-node hairball), and lets you
+search a symbol (e.g. `useScaledAmount`), click it, and see the connected files, tests,
+behaviors, and provenance — the visual half of "here's *why* the generated tests are
+grounded." Tabs: Overview · Coverage (behavior → test → file/symbol) · Gaps. Deep-link with
+`?select=<id|label>&view=<overview|coverage|gaps>`.
+
+Add `--json` to any read command for machine-readable output. Optional enrichers:
+point `analyze` at a small CSV requirements template or Markdown docs to raise the
+score and test specificity (`analyze . --paths payments-template.csv`).
+
+## BYOK (bring your own model key)
+
+Provider adapters, auto-detected in order **OpenAI-compatible → Ollama → Anthropic**:
+
+| Provider | Env |
+|---|---|
+| OpenAI-compatible | `OPENAI_API_KEY`, optional `OPENAI_BASE_URL`, `OPENAI_MODEL` |
+| Ollama (local) | `OLLAMA_BASE_URL`, optional `OLLAMA_MODEL` |
+| Anthropic | `ANTHROPIC_API_KEY`, optional `ANTHROPIC_MODEL` |
+
+With **no model key set, no tests are generated** — `generate` returns setup guidance
+instead (the BYOK contract never silently degrades to a non-model output). To run fully
+offline, opt in explicitly with `--provider deterministic` (CLI) or
+`ORANGEPRO_ALLOW_DETERMINISTIC=1`, which uses a clearly-labeled deterministic stand-in.
+Static analysis, scoring, gaps, and pack export never need a model.
+
+## Scenario buckets (generation diversity)
+
+`generate` is **target-focused**: it picks the top-gap behavior (or your `--target`)
+and produces up to `--limit` tests for that one behavior, each covering a different
+lightweight **local scenario bucket** when the evidence supports it:
+
+`happy_path` · `validation_error` · `edge_case` · `integration_flow` · `security_privacy` · `regression`
+
+Buckets are chosen from the behavior's own evidence (acceptance criteria, code
+context, related tests, weak/candidate edges) and are **never padded** — an
+unjustified bucket is skipped rather than filled with a generic smoke test. Each
+generated test reports its bucket, cites the evidence anchors it used, and discloses
+any weak evidence. Passing several `--target` ids splits the budget across them (each
+gets a test when the budget allows, in priority order). Total caps are unchanged
+(default 3, max 5).
+These are the local kit's own categories — the hosted platform owns full bucket
+orchestration, caps, and lifecycle coverage.
+
+## MCP (any agent: Cursor, Codex, Claude, Copilot, …)
+
+Run `opro agent --client claude-code|cursor|codex|opencode` to print a client-ready MCP
+config plus the write/run/report loop. The shipped guide is
+[agent-workflow.md](agent-workflow.md), with per-agent setup notes for
+[Codex](agents/codex.md), [Claude Code](agents/claude-code.md),
+[Cursor](agents/cursor.md), and [OpenCode](agents/opencode.md).
+
+```json
+{
+  "mcpServers": {
+    "orangepro-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/orangepro-mcp/dist/local/cli.js", "mcp"],
+      "env": { "OPENAI_API_KEY": "<your local key>" }
+    }
+  }
+}
+```
+
+First-slice MCP tools (same behavior as the CLI, same core): `orangepro_start`, `orangepro_analyze_sources`,
+`orangepro_graph_score`, `orangepro_status`, `orangepro_doctor`, `orangepro_find_test_gaps`,
+`orangepro_record_run`, `orangepro_prove`, `orangepro_stats`, `orangepro_rtm`, `orangepro_update_graph`,
+`orangepro_changed_impact`, `orangepro_ai_links`, `orangepro_ai_flows`, `orangepro_generate_tests`,
+`orangepro_explain_test`, `orangepro_export_evidence_pack`. **No upload or repo-write tools.**
+
+### Tool modes (baseline vs diff/PR)
+
+Two explicit classes, so an agent never fabricates PR analysis when there is no PR:
+
+- **Baseline tools** — the *"try OrangePro on any repo"* entry point. They run on the
+  current local graph/checkout and need **no diff or PR**: `orangepro_start`,
+  `orangepro_analyze_sources`, `orangepro_status`, `orangepro_graph_score`,
+  `orangepro_doctor`, `orangepro_find_test_gaps`, `orangepro_rtm`,
+  `orangepro_generate_tests`, `orangepro_record_run`, `orangepro_prove`, `orangepro_stats`,
+  `orangepro_explain_test`, `orangepro_export_evidence_pack`.
+- **Diff/PR tools** — only for **real code-review situations**. They require a git repo
+  and a real diff vs a base ref (default `main`). Today: `orangepro_changed_impact`
+  (future helpers may split risk and test-plan output, but they are not separate MCP
+  tools today). When there is nothing to
+  analyze they return a structured `status` + `guidance` instead of fabricated output:
+  - `not_a_git_repo` — the checkout is not a git repository.
+  - `missing_base_ref` — the base ref does not exist; pass an existing `base_ref`.
+  - `no_diff` — no changed files; run on a feature branch, pass `base_ref`, or use
+    `orangepro_find_test_gaps` for baseline opportunities.
+
+  Still no source/test file writes and no repo upload to an OrangePro tenant — and no hallucinated impact when there is no diff.
+
+## The evidence graph
+
+OrangePro-shaped, test-generation-oriented — **not** a generic code graph. Every node and
+edge carries an **evidence strength** (`hard` / `reviewed` / `candidate` / `weak`) and
+**provenance**. Explicit source refs, exact ids/paths, and reviewed template rows are hard
+evidence; LLM/similarity inference is candidate-only and never counts as proof. Generated
+tests link back to the graph evidence that grounded them, and disclose any weak evidence used.
+
+For coverage scoring, OrangePro uses one public glossary:
+
+- **Dynamically Proven** (labeled "Dynamically Proven" in the report/CLI/RTM) means a dynamic
+  targeted-proof ledger certificate closed for the behavior: baseline green, target mutated, same
+  test failed at an assertion, and the target was not mocked. The static map covers the whole repo;
+  the dynamic pass proves only the top few eligible behaviors per run (default 5, `--auto-limit` to raise).
+- **Runtime-covered** means the repo's own coverage tool executed the code, but not that an
+  assertion checked the behavior.
+- **Associated signal** means name, path, import, or structural matches suggest a useful link,
+  but not semantic proof.
+- **No integration signal** means no direct static test signal was found yet. It does not mean “untested.”
+
+The HTML report presents these as four display tiers: **Dynamically Proven**, **Statically Linked**
+(the report's label for an Associated signal — a test file appears to import or call the behavior,
+not dynamically verified), **Reachable Untested** (a behavior that appears in a static flow from an
+entry point but has no test signal), and **No Signal** (no test or static-flow signal yet). These are
+presentation labels over the same statuses above; they change no classification, count, or ledger record.
+
+LLM, similarity inference, and static hard TESTED_BY/COVERS edges are candidate or
+associated signals until a dynamic targeted proof closes.
+
+### Dynamic proof is TS/JS-only today (language-profiled)
+
+Dynamic targeted proof currently runs for **TypeScript/JavaScript only** — the oracle drives
+`vitest`/`jest`, and only TS/JS files are eligible for a proof target. The static map is
+multi-language: **Java, Go, Rust, and Python monorepos still get the full static picture today**
+(behaviors, flows, Statically Linked, Reachable Untested, and any ingested runtime coverage).
+
+Monorepo-aware dynamic proof is delivered as per-ecosystem **profiles**. The **`ts_js` profile**
+(handling `tsconfig` `extends`/`paths` monorepos) is the first and currently the only implemented
+profile — the M-1/M-2 sandboxing work improves TS/JS monorepo proof only. Dynamic proof for
+Java/Go/Rust/Python is future work: each needs its own test runner plus a workspace-config profile.
+Until a language's profile exists, dynamic proof does **not** pretend the TS/JS fixes apply — it
+reports "not supported for this language/ecosystem yet" or a precise `<lang>_workspace_config_missing`
+reason, and those behaviors simply stay in their static tiers.
+
+The local ledger is a trusted local artifact, not a cryptographic attestation. A
+hosted/product proof path must bind each dynamic certificate to witnessed run artifacts
+before accepting it from an untrusted client or edited checkout.
+
+Runtime coverage is reported separately when local coverage-tool artifacts are present. The
+local kit ingests Go coverprofiles, JS/TS `lcov.info`, Python coverage.py XML, and Java JaCoCo
+XML. These artifacts show executed lines inside symbols; they are not assertion-level proof and
+never promote Associated signal or No integration signal rows to Proven.
+
+## Readiness score
+
+A 0–100 **readiness** signal (not a proof of lift), in bands: `thin` (0–39),
+`usable` (40–59), `good` (60–74), `strong` (75+). The report always explains *why the
+score is not higher* — that is the trust feature. Exact weights and the formula stay
+internal; only the per-dimension breakdown, band, and missing-evidence are exposed.
+
+## Evidence pack
+
+`export` writes a JSON pack (validated against `orangepro.local_evidence_pack.v0`) plus a
+Markdown summary. The pack includes facts, provenance, evidence strength, generated outputs,
+and high-level score metadata. It **excludes** prompts, prompt templates, ranking traces,
+hidden weights, traversal traces, and raw source — promotion-ready, not
+reverse-engineering-ready. The strict schema validator enforces this boundary.
+
+## Validation
+
+Before release, the local kit is checked against representative real repositories for
+broken graph edges, parser downgrades, symbol truncation, and source-leak regressions.
+The public contract is simple: graph construction is deterministic and local; generated
+tests cite the file paths, symbols, tests, and evidence labels that grounded them.
+
+### Why graph grounding helps
+
+The headline claim is not "a graph beats a weak prompt." The useful comparison is:
+same selected model, same target behavior, but one run receives concrete graph evidence
+and the other does not. The graph-grounded run can cite real symbols, nearby tests,
+imports, and evidence strength, so it is less likely to invent modules and easier for a
+developer to verify.
+
+## What's deferred (hosted/premium or later phases)
+
+Hosted upload/promotion, Docker, watch mode, PDF/DOCX, Jira/Confluence/TestRail/OpenAPI
+enrichers, repo file writing (safe patch workflow), continuous coverage intelligence, and
+third-party graph import. The hosted KG remains the system of record; this kit is the local
+adoption surface.