docs: describe the system as of 2026-10-02 (ax plane, AI decision engine, PHP, v3)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

docs/architecture.md

@@ -0,0 +1,160 @@
+# Architecture
+
+How a scan works, how a finding earns its place, how severity and the project score are
+decided, and how the ruleset improves itself. State as of 2026-10-02; module paths are under
+`src/openultrasast/`.
+
+## The scan pipeline
+
+The CLI is thin; `HarnessRuntime` owns the lifecycle and writes an event trace for every stage
+(`trace/events.jsonl`). The stages a mode requests are `MODE_STAGES` in `stages.py`:
+`quick` runs STATIC, `standard` adds MAP, `deep` adds REGRESS.
+
+```
+policy_load ─▶ ruleset_load ─▶ policy_check            (fail loud on an ungoverned CWE)
+  ─▶ static_mapping (SARIF ingest) ─▶ preprocess ─▶ entry_point_mapping
+  ─▶ rank ─▶ calibrate (demote previously rejected scopes)
+  ─▶ findings   quick, deep: quick_findings (language-scoped pattern rules)
+  │             standard: hunter_pool (the same rules, scheduled per ranked target)
+  ─▶ verify ─▶ record_calibration ─▶ fusion (standard only, deterministic) ─▶ score
+  ─▶ MAP (standard, deep)
+  │     map          complexity map and hotspots
+  │     overlay      semantic overlay over the findings (tree-sitter with the `semantic` extra)
+  │     obligations  absence bugs: an obligated operation with no governing guard
+  │     model        one Joern CPG per repository; taint, dominance and configuration arbiters
+  │     tool hunter  only with `[models] hunter`
+  ─▶ REGRESS (deep)  sandboxed regression snippets ─▶ verdicts.json, worth-fixing
+  ─▶ report.md, report.sarif, manifest.json
+```
+
+**The model layer** (`model/`, `cpg/`) is the core of `standard`. It builds one code property
+graph per scan with Joern (`joern-parse`, then batched `joern --script` queries from
+`cpg/queries/*.sc`) and dispatches each question to the arbiter of its spec type: taint
+(source to sink with no discharging sanitizer), dominance (does a guard govern the obligated
+operation) and configuration (constant abstraction over a value). Taint facts ship for C,
+Java, JavaScript, PHP and Python (`ruleset/semantic/*.toml`). Without Joern the layer records
+`cpg_unavailable` and the scan is otherwise unchanged; the Docker image ships Joern and
+`php-cli` (which the PHP frontend needs).
+
+The model layer reports on a rung ladder:
+
+```
+execution_confirmed   a test or sandbox reproduced it
+model_entailed        the graph decided: a flow with no discharge, an obligation with no
+                      guard, a permissive value
+model_corroborated    the graph found the shape; a judge agreed on the residual question
+suspicion             proposed, nothing corroborated it
+```
+
+The LLM (`model/judge.py`) is asked only the residual question the graph cannot settle, for a
+flow the graph already found; it can confirm or contradict, never create a flow. Without a
+provider key only the `suspicion` band goes unasked.
+
+**REGRESS** (`regress/`, `sandbox/`) runs only when `docker info` succeeds. Each promoted
+candidate gets a small language recipe (Python, JavaScript, C) that loads the candidate's
+source inside a container with no network, a read-only `/workspace`, a non-root user and the
+`[sandbox]` limits. A structural deny-list rejects snippets mentioning sockets, curl, host
+networking or writes under `/workspace` before anything runs.
+
+## Evidence ladder: how a false positive is eliminated
+
+Evidence level is a state machine, not a label a model may assign. The verifier
+(`verification.py`) runs on independent context and enforces:
+
+```
+suspicion ─▶ static_corroboration ─▶ crash_reproduced ─▶ root_cause_explained
+          ─▶ exploit_demonstrated ─▶ patch_validated
+```
+
+- below `static_corroboration`: `NEEDS_EVIDENCE`;
+- `static_corroboration` with reachability unknown: `REJECTED`, with a tie-breaker demanding
+  call-graph, route, CLI, parser or dynamic evidence;
+- `static_corroboration` with function-level reachability: `ACCEPTED`.
+
+A rejected finding becomes a **scoped false-positive learning** (`calibration.py`) with a
+reason from a fixed taxonomy (`unreachable_path`, `missing_attacker_control`,
+`sanitizer_disproved`, `static_rule_mismatch`, `incorrect_model_assumption`, `duplicate`,
+`insufficient_impact`, `unsupported`, `contradicted`, `unverified`) and a scope. A rejection in
+`auth/` demotes only `auth/...`, never the whole class
+(`tests/test_calibration.py::test_scoped_false_positive_demotion_does_not_suppress_class_globally`).
+
+## How a false negative is surfaced
+
+Every expected vulnerability that no finding matched becomes a `BenchmarkCalibrationRecord` in
+`calibration_records.json`, with a `next_improvement_candidate` (a static rule, SARIF source,
+entry-point mapping, retrieval package, hunter prompt, dynamic reproducer or skill route).
+Once a miss is closed the detection gate keeps it closed in CI.
+
+## Central CWE policy and the project score
+
+**Policy** (`policy/verycode.py`): a vendored `CWE_Score.tsv` (verycode-policies) is the single
+source of truth. Each CWE carries a flaw category, a severity (0-5) and `static`/`dynamic` scope
+flags. A finding's severity comes only from policy, keyed on CWE. CWEs that are not `static`
+resolve to 0 and are report-only. `assert_rules_resolve` runs as the `policy_check` stage: an
+enabled rule naming an ungoverned CWE aborts the scan. Verycode has no CWE-120, so the C/C++
+buffer rules carry CWE-121.
+
+**Score** (`scoring/project_score.py`): each finding's penalty is
+`SEV_WEIGHT[severity] x REACH_MULT[reachability]`, and the score is `100 * e^(-total/k)` with
+`k = 60`.
+
+| Severity | Weight | | Reachability | Multiplier |
+| --- | --- | --- | --- | --- |
+| 5 | 50 | | `reachable` | 1.0 |
+| 4 | 25 | | `inferred-file-surface` | 0.6 |
+| 3 | 10 | | `unknown` | 0.4 |
+| 2 / 1 / 0 | 2 / 1 / 0 | | | |
+
+A confirmed false positive lowers a finding's reachability multiplier instead of deleting the
+rule. A severity-5 reachable finding always fails the score gate; `score < min_score`
+(default 80) fails it only with `[score] blocking = true`. The `score` stage writes
+`score.json` and merges it into `manifest.json`.
+
+## Self-improvement
+
+### Scoped calibration (every scan)
+
+```
+scan ─▶ verify ─▶ non-accepted findings ─▶ scoped learnings
+        (.openultrasast/calibration/false_positive_learnings.json)
+next scan ─▶ rank ─▶ calibrate (demote rejected scopes) ─▶ findings
+```
+
+`record_calibration` (after `verify`) merges this run's non-accepted outcomes into the ledger,
+de-duplicated by finding ID; `calibrate` (after `rank`) demotes the priority of every scope
+that produced a rejection and writes `applied_calibrations.json`. Demotion is scoped and
+reversible (`tests/test_pipeline_calibration.py`).
+
+### Rule-level loop: `ousast improve`
+
+Each round (`improve/evolve.py`): benchmark with the current ledger, per-rule signals
+(`rule_signals.json`), bounded proposals, validation (`improve/validator.py`), replay smoke,
+re-benchmark, and a hard gate. The levers are rule status (`enabled -> shadow` before
+`disabled`) and score constants; the loop can never edit pattern text
+or the authoritative CWE severity. A round is accepted only if recall >= 90%, FP < 10%, the
+project score did not regress and no matched finding was lost; otherwise the ledger is not
+written. With `--pair-catalog`, every round is also gated per provenance profile on the
+catalog's holdout pairs (`--no-pair-gate` skips this and is not for accepted ledgers). The same
+detection gate runs in CI (`python -m openultrasast.gate`).
+
+### Proposals from plane memory
+
+With `--memory [STORE]`, `ousast improve` also reads the rows plane runs stored per repository
+and pin (`improve/memory.py`). Two deterministic rules turn them into rule-status proposals: a
+rule whose alerts are repeatedly false across repositories is shadowed, and a shadow rule that
+keeps hitting agreed, declared vulnerable sites is re-enabled. Rows from holdout pairs, from the
+gated manifest's own cases and from any `--qualify-population` are dropped before any rule sees
+them. Each proposal records the rows it came from (`memory_proposals.jsonl` next to the
+journal) and goes through the same validator and gate.
+
+### The loop as a plane Run
+
+`ousast plane workspaces <population> --validation-set ... --loop` appends the improvement loop
+to a generated Run: `alerts` per case (the quick scan on the vulnerable and fixed pins), then
+the steps `snapshot` (task `memory-snapshot`), `measure`, `propose` and `improve` (`plane/tasks/loop.py`), each model-free
+with a zero budget. The snapshot applies the same train-on-test guard before any row leaves the
+store. A recorded live run: `benchmarks/measurements/2026-09-30-harnessx-removal-loop/`.
+
+For PHP, which quick mode covered with zero rules when that run was made, `ousast plane
+alerts-engine` produces a Run's `alerts` from the engine image on the host instead
+(`benchmarks/measurements/2026-09-30-php-engine-alerts/`).

docs/decision-engine.md

@@ -0,0 +1,85 @@
+# The learned decision engine (in development)
+
+**Status 2026-10-02: in development, not adopted.** No scan, pre-push check or report uses it;
+every user-facing path is today's deterministic one until a compiled program is adopted. The
+design is the `learned-decision-engine` specification (maintainer tooling); the code is in
+`src/openultrasast/learn/`.
+
+## Why
+
+Every detection gain so far was a hand edit made after a miss: a rule, a taint vocabulary entry,
+a guard, a prompt line, a tie-break. Each was tuned on the cases that exposed it, and engine
+tuning measured on population v1 did not transfer to v2 (see [evaluation.md](evaluation.md)).
+The engine replaces that with a decision learned from labelled outcomes and checked out of
+repository.
+
+## Design
+
+- **Signals, not verdicts.** Every instrument (quick rules, the Joern engine, model sink and
+  role classification, the plane's verify passes and agreement, repository facts such as
+  callers) contributes a feature record per candidate `(path, function, family)`, including an
+  explicit state when it did not run or failed. None decides alone.
+- **Labels from ground truth.** `ousast learn labels` derives labels only from sources on a
+  fail-closed allow-list (`learn/sources.toml`): the vulnerable and fixed sides of pairs, the
+  declared sites and fix ranges of spent populations, benign deltas and recorded adjudications.
+  "Rejected by the plane" is never a negative. Reserved populations (v3) are not on the list.
+- **An AI classifier with local memory, compiled in house in the DSPy style.** The program is an
+  instruction, a few demonstrations and up to six retrieved labelled examples, then the
+  candidate's code excerpt and signals; the model (`deepseek-flash`) answers
+  vulnerable / not vulnerable / unsure with a rationale, sampled `k` times, giving a score `s`.
+  Compilation bootstraps demonstrations and searches instructions on a compile split, scored by
+  a pre-registered balanced Brier score (`learn/compile.toml`).
+- **Retrieval** from the memory store: nearest neighbours by Gower distance on the signal
+  profile, re-ranked by cosine similarity of code embeddings (OpenAI `text-embedding-3-small`
+  through OpenRouter, cached by excerpt hash), under a label/family/repository balance rule. An
+  evaluation-boundary filter keeps a candidate's own repository group out of what it is shown.
+- **Repository-grouped evaluation.** The compile split (25% of repository groups) is never
+  evaluated. The rest is evaluated by outer grouped 5-fold cross-validation: the Platt
+  calibration map is cross-fitted on the other folds and the operating points are chosen on the
+  other folds (nested). One compile per profile, not one per fold. Intervals are 95%
+  repository-cluster bootstrap.
+- **Two operating points.** BLOCK is offered only when calibration holds (slope CI contains 1,
+  intercept CI contains 0, ECE <= 0.05) and a fold reaches the required precision; otherwise the
+  engine is ADVISORY only. An `unsure` answer can never BLOCK.
+
+## First measured slice (2026-10-01)
+
+Record: `benchmarks/measurements/2026-10-01-decision-engine-injection-slice/record.json` (counts
+only). Family **injection** only; memory of 724 static examples from all families; input profile
+v1 with the engine signals and function length withheld (a leak audit found them separating the
+sides of a pair by construction: `2026-10-01-decision-engine-leak-audit/`); framework priors off.
+
+| Measure | Value (95% repository-cluster CI) |
+| --- | --- |
+| Candidates evaluated | 110 in 29 repository groups, 58 positive |
+| ADVISORY recall | 0.90 (0.82 - 0.97) |
+| ADVISORY precision | 0.54 (0.44 - 0.65) |
+| AUC of the score `s` | 0.74 (0.65 - 0.85) |
+| Majority "vulnerable" verdict | precision 0.86 (0.72 - 1.0), recall 0.43 (0.29 - 0.62) |
+| BLOCK | not offered: ECE 0.064 > 0.05, and every fold reported `precision_unreachable` |
+| Compiled program | balanced Brier 0.128 on the validation split vs 0.199 for the baseline instruction |
+| Canary agreement on re-run | 0.83 (30 candidates) |
+| Spend | $0.91 metered at list price for DeepSeek, $0.0040 for embeddings; $0.0032 per evaluated candidate |
+
+The other evaluable families are not evaluated yet. Leave-one-source-out, leave-one-framework-out
+and learning curves, experiments, integration into scan and pre-push, adoption, and the one-time
+v3 check are still ahead.
+
+## Commands
+
+`ousast learn` is a maintainer command group over the engine's data. Paid steps take
+`--budget-usd`; `--replay-only` answers every call from the response cache at no cost.
+
+| Command | Does |
+| --- | --- |
+| `ousast learn labels` | labels from the allow-listed sources (host only); `--snapshot` writes the counts-only record |
+| `ousast learn memory build` | label + feature record + excerpt -> `example` rows (no model) |
+| `ousast learn memory embed` | embed the stored excerpts (OpenRouter, metered, cached) |
+| `ousast learn compile` | compile the program on the compile split |
+| `ousast learn evaluate --program ID` | outer-fold evaluation, cross-fitted calibration, nested operating points |
+| `ousast learn curve --program ID` | the metric over memory size on a fixed candidate subset |
+| `ousast learn audit-leaks` | how well each signal alone separates the sides of a pair (no model) |
+
+The memory store is the plane's (`OUSAST_MEMORY`; see [ops/ax/README.md](../ops/ax/README.md)).
+The harvest that produced the plane signals runs as plane Runs generated by
+`ousast plane harvest` (`benchmarks/measurements/2026-10-01-decision-engine-harvest/record.json`).

docs/evaluation.md

@@ -0,0 +1,84 @@
+# Evaluation
+
+What has been measured on code the tool was not tuned on, and how. State as of 2026-10-02.
+Every number below is quoted from a committed record; the path is given with it.
+
+## Instruments
+
+| Instrument | Measures | Where |
+| --- | --- | --- |
+| Detection gate | per-language recall/FP on the bundled cheat-sheet corpora (goal: >= 90% recall, < 10% FP) | `python -m openultrasast.gate`, `benchmarks/manifests/` |
+| Pair corpus | fire on the vulnerable function, stay silent on its fix | `ousast pairs`, `benchmarks/pairs/` |
+| Independent populations | real repositories at vulnerable, fixed and benign pins, scored under a pre-registered protocol | `benchmarks/independent/` |
+
+The detection gate and the local pairs are CI gates. They catch regressions; they do not
+estimate recall on real code, because the rules were written against them.
+
+## Pair corpora
+
+`benchmarks/pairs/catalog.toml` and the slice directories (`local`, `github`, `sast`, `vfc`,
+`vibe-py`, `vfc-js`, `agent-vfc`, `owasp`) are runnable with `ousast pairs --slice <name>`; each
+pair carries a provenance profile and a train/holdout split (`--profile`, `--split`). Pointer
+pairs are not vendored: `--pointers` fetches them into `~/.cache/openultrasast/pairs/`.
+`benchmarks/pairs/README.md` documents the schema and the review tiers.
+
+**`advisory-fixes`** (`benchmarks/pairs/advisory-fixes/`, 2026-10-01) holds 97 pointer pairs,
+one per repository: a public CVE/GHSA fix commit whose advisory-named function is declared on
+both sides and changed by the fix. It was assembled to give the decision engine real negatives
+for families the corpus had few of (access control, deserialization, output encoding, path,
+untrusted destination). It is a label source of the decision engine
+(`src/openultrasast/learn/sources.toml`), not an `ousast pairs` slice; the research log and
+every rejection are in `research-2026-10-01.md`.
+
+## Independent populations and the M4 gates
+
+The pre-push safety net's qualification milestone (M4) requires, together: at least 95%
+actionable precision, at least 90% supported recall, at least 95% supported-check completion,
+the runtime gates, and zero fixed-side or benign false alerts. A population is frozen before
+any of its cases is scanned, scored once under a pre-registered protocol, and then **spent**:
+it may inform changes, but it can no longer qualify anything.
+
+| Population | Status | Result | Record |
+| --- | --- | --- | --- |
+| v1 (11 cases) | spent | engine: recall 1/11, precision 1/12, 4 fixed-side and 1 benign false alert; every M4 gate failed. Eight of eleven cases completed no question at the vulnerable pin. | `benchmarks/independent/results-v1.json` |
+| v2 (17 cases) | spent | engine: recall 0/17, 3 benign alerts, completion 13,206 of 108,374. Tool hunter: recall 1/17, precision 2/14, 1 fixed-side and 16 benign alerts, $8.88. No M4 gate met by either. | `results-v2.json`, `results-v2-hunter.json` |
+| v2, model-driven pipeline | exploratory (v2 already spent) | stopped after 7 of 17 cases when the account emptied: recall 4/7; precision not adjudicated; no gate measurable | `results-v2-model-pipeline.json` |
+| v3 (PHP, 16 cases) | frozen, untouched | none: it is the one-time final check, run once under `protocol-v3.md` after a prediction is committed | `population-v3-php.toml`, `freeze-v3-php.json` |
+
+v3 is reserved: development and analysis work never reads its cases, and
+`tests/test_independent_population.py` fails when anything in the development tree (a recipe,
+catalog, manifest or measurement) names one of its repositories.
+
+## The plane increment
+
+The first increment of the agentic plane ran the model-driven pipeline's validation set (46
+candidates in 15 cases of v2, 20 declared vulnerable sites) on google/ax and compared it with
+the script pipeline on the same cases, candidates, pins and recorded triage. The pre-registered
+gate: at least 16 of 20 declared sites agreed, at a cost per candidate under $0.022.
+
+- **Increment 1** (2026-09-29, `benchmarks/independent/plane-increment-1.json`): 14 of 20
+  declared sites agreed against the reference's 16; $0.0194 per candidate with recorded triage.
+  **NOT MET** on recall.
+  *Correction (2026-09-30, in the record):* the first version read agree's
+  `declared_sites_matched` (coverage by candidates, 19) as "found in either pass" and concluded
+  detection was unchanged. Recounted from the agreed rows, the plane's passes flagged 17 of 20
+  declared sites in at least one pass against the reference's 19.
+- **Increment 2** (2026-09-30, `benchmarks/independent/plane-increment-2.json`): after the design
+  revisit, a tie-break pass c on the 10 disputed candidates with 2-of-3 agreement. 16 of 20
+  declared sites agreed (reference 16) at $0.0205 per candidate over 46 ($0.02195 over the 43
+  after triage, against the reference's $0.022). **MET**, with two caveats the record carries:
+  the tie-break was chosen after seeing the first measurement on the same validation set, so
+  this compares plane with script and qualifies nothing on an independent population; and the
+  plane's passes still flag fewer declared sites than the reference (17 vs 19). Precision is
+  not part of this gate and remains the open problem.
+
+## The decision engine
+
+The first measured slice of the learned decision engine (injection family, out-of-repository
+evaluation) is described with its numbers in [decision-engine.md](decision-engine.md).
+
+## Removal of the earlier agentic extra
+
+The removal of the earlier agentic extra (2026-09-30) was checked for byte-identical
+deterministic outputs (pair replay, quick benchmark, standard scan, `improve --dry-run`):
+`benchmarks/measurements/2026-09-30-harnessx-removal-baseline/` and `-equality/`.

docs/examples.md

@@ -13,7 +13,18 @@ jq . "$run/score.json"      # 0–100 project score + gate verdict
 "$run/report.sarif"         # SARIF for code-scanning / IDEs
 ```
 
-## 2. CI gate
+## 2. Standard scan with the engine (Docker)
+
+```bash
+source ops/shell/ousast.sh          # once per shell; builds the image on first use
+ousast scan . --mode standard       # Joern model layer, container network off: no model calls
+ousast-with-judge scan . --mode standard   # network on, so the model is asked (needs DEEPSEEK_API_KEY)
+```
+
+Without a key the graph still decides; only the `suspicion` band goes unasked, and the manifest
+records the degradation.
+
+## 3. CI gate
 
 ```bash
 # Fail the build on any evidence-verified finding:
@@ -23,23 +34,21 @@ uv run ousast scan . --mode quick --fail-on verified
 uv run python -m openultrasast.gate
 ```
 
-## 3. Benchmark a known-vulnerable corpus
+## 4. Benchmark a known-vulnerable corpus
 
 ```bash
 uv run ousast benchmark benchmarks/manifests/python-vulnerable.toml --mode quick
 # -> expected / matched / missed counts + a per-rule recommendation delta
 ```
 
-## 4. Vuln vs fixed pair eval (efficiency, not cheat-sheet recall)
+## 5. Vuln vs fixed pair eval (efficiency, not cheat-sheet recall)
 
 ```bash
 uv run ousast pairs                              # local fixtures + vendored GitHub VFCs
 uv run ousast pairs --slice github --json        # honesty dashboard as JSON
 uv run ousast pairs --slice sast                 # OWASP Benchmark + Juliet Youden (TPR-FPR)
 uv run ousast pairs --slice vibe-py --pointers   # nightly: pointer pairs via the local cache (network)
-uv run ousast mechanisms export --slice vibe-py   # maintainer: seed mechanism candidates from trusted pairs (offline)
-uv run ousast improve bench.toml --pair-catalog benchmarks/pairs/catalog.toml   # the mechanisms lever admits candidates the holdout pairs prove; the scan then searches them
-uv run ousast pairs --slice vibe-py --loo        # leave-one-out: the corpus's own detection rate (reports/loo.json)
+uv run ousast pairs --split holdout --profile human   # filter by declared split and provenance profile
 uv run python -m openultrasast.pair_gate         # CI: local pairs must all pass
 ```
 
@@ -48,7 +57,7 @@ Each case is two isolated trees (vuln file vs patched file, same relative path).
 fix. Misses and fix-side leaks become `miss`/`fp` signals for `ousast improve`.
 The catalog and public dataset pointers live in `benchmarks/pairs/`.
 
-## 5. Self-improve the ruleset from benchmark feedback
+## 6. Self-improve the ruleset from benchmark feedback
 
 ```bash
 uv run ousast improve benchmarks/manifests/java-spring-boot-vulnerable.toml --dry-run  # preview
@@ -57,16 +66,16 @@ uv run ousast improve benchmarks/manifests/java-spring-boot-vulnerable.toml
 # which the next scan/benchmark of that target loads automatically.
 ```
 
-## 6. Running the agentic plane
+## 7. Running the agentic plane
 
 Model work over whole repositories runs as a Run manifest on ax, one isolated actor
 per task (bring-up: [ops/ax/README.md](../ops/ax/README.md)). The provider key is
-read from the environment (or `.env`) by `ousast` and sent only in each task's start
-request.
+read from the environment (or `.env`, which never overrides an exported variable) by
+`ousast` and sent only in each task's start request.
 
 ```bash
 uv run ousast plane doctor                               # kind, Agent Substrate, ax controller, runner image
-uv run ousast plane run plane/runs/validation-46.yaml    # repo-facts, verify a/b(/c), agree, remember per case
+uv run ousast plane run plane/runs/validation-46.yaml    # per case: repo-facts, verify a/b/c, agree, final, features, remember
 uv run ousast plane status validation-46                 # per-task status and token attribution
 uv run ousast plane remember validation-46               # re-ingest the run's memory rows (OUSAST_MEMORY)
 
@@ -76,14 +85,14 @@ uv run ousast improve benchmarks/manifests/java-spring-boot-vulnerable.toml --dr
 
 Each task in the Run carries its own Model and `budget: {usd, calls}`; a task that
 reaches its ceiling stops as `unfinished` and resumes on a rerun with a larger
-budget. A local `ousast scan --mode standard` stays deterministic apart from the
-optional `[models] hunter` tool hunter.
+budget. `ousast plane status` prints the token attribution table: calls, prompt,
+cache-hit and output tokens and USD per task.
 
-## 7. Drive it from an MCP client (OpenCode / IDE)
+## 8. Drive it from an MCP client (OpenCode / IDE)
 
 ```jsonc
 { "command": "uv", "args": ["run", "ousast", "mcp"] }
 ```
 
 Then: `openultrasast.scan {path}` → `run_dir` → `openultrasast.findings {run_dir}` →
-`openultrasast.explain {run_dir, finding_id}`. See the README "MCP server" section.
+`openultrasast.explain {run_dir, finding_id}`. See the README section "Agent integrations".

docs/threat-model.md

@@ -5,18 +5,23 @@ it does not, and the controls that keep a scan safe to run in CI and safe to sha
 
 ## Trust boundaries
 
-- **Scanned code is untrusted input, never executed.** Quick and standard modes read
-  source as text (regex rules, evidence ladder, optional LLM review). They never import,
-  build, or run the target. Only `deep` mode would execute target-derived code, and only
-  inside the sandbox below — and deep mode is not yet implemented (it exits with a clear
-  message rather than running anything).
+- **Scanned code is untrusted input.** Quick and standard modes never import, build or run
+  the target: quick reads source as text, and standard additionally parses it into a code
+  property graph with Joern (`joern-parse`, a parser, not a build) and may send code excerpts
+  to the configured model. Only `deep` mode executes target-derived code: its REGRESS stage
+  loads promoted candidates inside the Docker sandbox below, and it runs only when `docker
+  info` succeeds (otherwise the stage is skipped and recorded as `sandbox_unavailable`).
 - **The ruleset and CWE policy are trusted, governed data.** They change only through
   reviewed commits or the bounded self-improvement loop (`ousast improve`), which can
   flip rule *status* and tune score constants but can never edit pattern text or the
-  authoritative 0–5 severity. See the self-improving cycle in the README.
-- **Provider credentials are the operator's.** The zero-dependency core makes no network
-  calls. A local scan calls a model only for the optional `[models] hunter` tool hunter
-  in standard mode. Agentic work runs on the plane (`ousast plane run`): `ousast` reads
+  authoritative 0–5 severity. See [architecture.md](architecture.md#self-improvement).
+- **Provider credentials are the operator's.** The core install (PyYAML only) makes no
+  network calls on its own. A local scan calls a model only in standard or deep mode, and
+  only when a key is available: the model layer asks the residual question the graph cannot
+  settle, and `[models] hunter` enables the tool hunter. LLM calls go to DeepSeek
+  (`DEEPSEEK_API_KEY`); OpenRouter (`OPENROUTER_API_KEY`) serves embeddings. Keys come from
+  the environment or a gitignored `.env`, which never overrides an exported variable. The
+  pre-push check calls a model only with an explicit `--model-config`. Agentic work runs on the plane (`ousast plane run`): `ousast` reads
   the variable a task's Model names (`secretKey.key`) from the operator's environment or
   `.env` and sends the key only in that task's start request, through Agent Substrate's
   router to that task's actor. It is not baked into an image or task template, and it is
@@ -54,7 +59,7 @@ LLM/embedding calls retry transient failures (HTTP 429/5xx, connection errors, t
 with exponential backoff; non-transient errors (e.g. 4xx, malformed JSON) fail fast.
 
 ### Visible degradation & determinism
-When an optional capability is missing (the extra, a model, a provider key), the scan
+When an optional capability is missing (Joern, Docker, a model, a provider key), the scan
 falls back to its deterministic equivalent and records a `degradations` entry in the
 manifest — it is never silently downgraded. Runs are reproducible: fixed config,
 artifact manifests, prompt hashes, and model identifiers are recorded.
@@ -63,18 +68,20 @@ artifact manifests, prompt hashes, and model identifiers are recorded.
 `ousast mcp` exposes only the ten narrow project tools. No tool runs arbitrary shell,
 Docker, or internal hunter tools, and no tool accepts a free-form command argument.
 
-## Sandbox limits (deep mode, when implemented)
+## Sandbox (deep mode)
 
-Dynamic analysis runs under the bounds in `[sandbox]` (`config.SandboxConfig`):
+The REGRESS stage (`regress/`, `sandbox/runner.py`) runs each snippet with `docker run`
+and never mounts the host Docker socket:
 
-| Control | Default |
+| Control | Setting |
 |---|---|
-| network | disabled (`network = false`) |
-| workspace | read-only (`workspace_readonly = true`) |
-| memory | 2048 MB (`memory_mb`) |
-| pids | 512 (`pids_limit`) |
-| timeout | 300 s (`timeout_seconds`) |
+| network | `--network none`, always; a host-network argument is refused |
+| source | the target bind-mounted read-only at `/workspace`; root filesystem `--read-only` |
+| scratch | a tmpfs at `/scratch` for the snippet |
+| user | non-root `65534:65534`, `--cap-drop ALL`, `no-new-privileges` |
+| memory | `[sandbox] memory_mb`, default 2048 MB |
+| pids | `[sandbox] pids_limit`, default 512 |
+| timeout | `[sandbox] timeout_seconds`, default 300 s |
 
-Dynamic probes additionally declare their network scope, log commands, and capture
-artifacts; a hardened runtime (e.g. gVisor) is used when available. Until deep mode
-ships, no target code is executed at all.
+Before anything runs, a structural deny-list (`regress/safety.py`) rejects a snippet that
+mentions sockets, curl, host networking or writes under `/workspace`.