loki-mode 11.4.2 → 11.5.1

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 Loki Mode, by [Autonomi](https://www.autonomi.dev/), turns a spec or an issue into a verified pull request with a receipt you can check. This page covers installing it, a first run, and the options around it.
 
-**Version:** v11.4.2
+**Version:** v11.5.1
 
 **Engine note:** `loki start` is the primary command. `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick` all run the Loki 10 engine, whatever the flag order or input form (PRD file, issue ref, task or one-word brief). The previous loop runs only on `--engine legacy`, `LOKI_ENGINE=legacy`, or for one call when a flag Loki 10 cannot honor is present. See the [user guide](v10/GUIDE.md) and the [5-minute quickstart](QUICKSTART.md).
 

package/docs/KNOWN-ISSUES.md

@@ -4,4 +4,13 @@ Issues in the current release that are known and not yet fixed. Report new ones
 
 ## Which engine runs
 
-From 11.4.0, `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine whatever the flag order or input form. The previous loop runs only on `--engine legacy`, `LOKI_ENGINE=legacy`, or for one call when a flag Loki 10 cannot honor is present (`--simple`, `--parallel`, `--sandbox`, ...). Check with `loki route start <args>`.
+From 11.4.0, `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine whatever the flag order or input form. The previous loop runs only on `--engine legacy`, `LOKI_ENGINE=legacy`, for a provider with no Loki 10 invoker, for a PRD over 100000 bytes, or for one call when a flag Loki 10 cannot honor is present (`--simple`, `--parallel`, `--sandbox`, ...). Check with `loki route start <args> --json`: it reports `engine`, `adapter`, `reason` and `capability_differences`. The full table is in the Routing contract section of `docs/exit-codes.md`.
+
+## Exit codes
+
+The exit code of every command is listed in `docs/exit-codes.md`. Two things are kept as they are for compatibility:
+
+- `loki run` (deprecated alias of `loki start <issue-ref>`) exits 1 on an unknown option, not 64.
+- `loki start` without `LOKI_DURABLE_STATE=1` has no finer run-outcome signal than 0 versus nonzero.
+
+An empty diff has a distinct exit code only for `loki verify` (3). `loki quick`, `loki start` and `loki run` do not define one.

package/docs/PROOF-PASSPORT.md

@@ -29,3 +29,117 @@ trust limitations, but no repository or machine-specific paths.
 Proof Passport does not currently sign the passport itself. Receipt signature
 status is reported separately and must not be interpreted as a passport
 signature.
+
+## Verification record
+
+Status: v1 (schema_version 1). Closes review finding LM-005: a passing outcome label could be misread when checks were not performed.
+
+Implementation: the verification-record section of `autonomy/lib/proof-verify.py` (CLI: `proof-verify.py <label|summary|json> <file>`). Both routes of `loki verify` and `loki proof show` use this one module, so the bash and Bun paths cannot drift.
+
+### Why three properties
+
+A single "verified" word hides three different questions. The record answers each one separately and never lets one stand in for another.
+
+1. **Integrity.** Is this record the one that was written, unaltered?
+2. **Execution validity.** Did the checks run against the code in front of you, and in what environment?
+3. **Requirement coverage.** Do the checks that ran actually cover what was asked for?
+
+A signature alone proves neither execution validity nor requirement coverage. A signed record can describe checks run on a different commit, on a dirty tree, or against only some of the requirements. The signature says the bytes are unchanged. It says nothing about whether the claims in those bytes are current or complete.
+
+### Property 1: integrity
+
+| status | meaning |
+| --- | --- |
+| `valid` | `verification.hash` matches the canonical bytes, gpg (when present) verifies, the recorded headline matches the headline re-derived from the facts, and the cost claim is coherent. |
+| `invalid` | Any of the above failed. The label becomes `NOT VERIFIED (integrity failed ...)` regardless of what the checks say. |
+| `not_recorded` | The record carries no hash. `.loki/verify/evidence.json` is always in this state: it is unhashed and unsigned. |
+| `unchecked` | The integrity code could not run. |
+
+The Ed25519 attestation is reported as present but is not verified inside the record. Use `loki proof verify --jwks` for that.
+
+### Property 2: execution validity
+
+Recorded with every receipt:
+
+- `git.head_sha` and `git.dirty` (dirty ignores `.loki/`), plus `git.tree_sha256` when the generator computed it.
+- `environment`: os, machine, python, node, bun and git versions, as found.
+
+Status:
+
+| status | meaning |
+| --- | --- |
+| `fresh` | Recorded HEAD equals live HEAD and the tree digest (or clean flag) still matches. |
+| `stale` | HEAD moved, or the working tree changed since the checks ran. Every previously passed check is reported as `stale`, and the label is `STALE (...)`. |
+| `unknown` | Not enough was recorded to compare (older receipts, no git tree). Unknown is never promoted to fresh. The label carries `revision freshness unknown`. |
+
+### Property 3: requirement coverage
+
+Read from `.loki/state/requirements-map.json`:
+
+```json
+{"requirements": [{"id": "R1", "text": "...", "checks": ["lint"], "status": "covered"}]}
+```
+
+| status | meaning |
+| --- | --- |
+| `recorded` | `total`, `covered`, `uncovered` and `uncovered_ids` are filled in. Uncovered requirements appear in the label. |
+| `not_recorded` | No map exists. Coverage is unknown, not zero. Counts are `null`. |
+| `unreadable` | The file exists but is not a valid map. Counts are `null`. |
+
+`covered_but_check_not_passed` lists covered requirements whose named check did not pass. Matching check ids to gate names is best effort.
+
+### Per-check status
+
+Every check is exactly one of: `passed`, `failed`, `skipped`, `not_run`, `stale`.
+
+Recorded words map as follows: pass-like words (`pass`, `passed`, `verified`, `ok`, `success`) become `passed`; fail-like words (`fail`, `failed`, `blocked`, `weakened`, `error`) become `failed`; `skipped` and `disabled` become `skipped`; `stale` stays `stale`. Everything else, including `inconclusive` and empty, becomes `not_run`. A check that did not reach a conclusion never reads as passed.
+
+### Label rules
+
+Evaluated in this order, first match wins:
+
+1. Integrity `invalid`: `NOT VERIFIED (integrity failed: ...)`.
+2. Any `failed` check: `NOT VERIFIED (failed: <ids>)`. A failed check never yields a passing label.
+3. Record has no facts or no base verdict: `INCOMPLETE (...)`.
+4. Base verdict is not `VERIFIED` or `VERIFIED WITH GAPS`: that verdict, unchanged.
+5. Execution `stale`: `STALE (...)`.
+6. Anything not run, recorded gaps, uncovered requirements, modified tests or unknown freshness: `VERIFIED (scoped: 5 of 7 checks ran; not run: lint, e2e)` with the applicable clauses.
+7. Otherwise `VERIFIED`.
+
+The bare word `VERIFIED` therefore means: integrity not failed, no failed checks, every check ran and passed, tree fresh, no uncovered requirements, no modified tests.
+
+### Modified tests
+
+`modified_tests` lists existing test files the change modified, deleted, renamed or type-changed, derived from `git diff --name-status` between the recorded base and head. Added test files are not listed. Status is `measured` or `unknown` (no base recorded or diff not computable). Modified tests appear in the label and in the summary because an implementer who edits the tests that judge the change weakens the evidence.
+
+### Record shape
+
+`loki proof show <id> --json` keeps the full proof. The verification record is produced by `proof-verify.py json`, embedded as `verification` in `.loki/verify/evidence.json`, and added as `verification` to the `loki proof verify` JSON. Fields are added, never renamed.
+
+```json
+{
+  "schema_version": 1,
+  "kind": "proof | evidence",
+  "label": "VERIFIED (scoped: ...)",
+  "base_verdict": "VERIFIED",
+  "integrity": {"status": "valid", "hash_ok": true, "signature": "none", "detail": "..."},
+  "execution": {"status": "fresh", "reason": "", "recorded": {}, "current": {}, "environment": {}},
+  "requirements": {"status": "recorded", "total": 3, "covered": 1, "uncovered": 2, "uncovered_ids": []},
+  "checks": [{"id": "lint", "status": "skipped", "detail": ""}],
+  "counts": {"passed": 1, "failed": 0, "skipped": 1, "not_run": 0, "stale": 0, "total": 2, "ran": 1},
+  "modified_tests": {"status": "measured", "files": [{"path": "tests/a.py", "change": "modified"}]},
+  "complete": true,
+  "record_path": ""
+}
+```
+
+### Human output
+
+`loki verify` (banner), `loki proof show <id>` and `loki proof verify <id> --human` print a compact summary of about 12 lines: the label, revision and freshness, environment, integrity, check counts with the checks that did not pass, requirement coverage, modified tests, and the signature caveat. Pass `--json` to `loki proof show` for the full record.
+
+### Compatibility
+
+- Exit codes are unchanged: `loki verify` keeps its verdict-based codes; `loki proof verify` keeps 0 clean, 1 tamper or drift, 2 unusable.
+- Existing JSON fields are untouched. `verification` is additive.
+- Receipts written before this contract lack `facts.environment` and `facts.git.dirty`. They report environment `not recorded` and may report freshness `unknown`.
+- `loki proof show <id>` used to print the raw JSON. Scripts that parsed it must now pass `--json`.

package/docs/alternative-installations.md

@@ -115,3 +115,106 @@ mv loki-mode-${VERSION} ~/.claude/skills/loki-mode
 ```
 
 **Best for:** Offline or air-gapped environments, pinned version deployments.
+
+---
+
+## Setup requirements (LM-001)
+
+This is the authoritative statement of what Loki Mode needs to run a first task. It is checked by tests against one shared table, `autonomy/lib/setup-requirements.json`. `loki doctor`, `loki doctor --requirements`, `loki doctor --json` (key `requirements`), `loki setup`, and the runtime "provider CLI missing" errors all read that table, so wording and fixes match.
+
+Normal repository build dependencies (the toolchain of the project you point Loki at) are not Loki overhead and are not listed.
+
+### How to read your machine
+
+```
+loki doctor --requirements   # per path: ready or not ready, each item required or optional, present or missing, one-line fix
+loki doctor --json           # same data under "requirements", plus "first_task_ready"
+```
+
+A first task is ready when every required "All paths" item is present and at least one execution path is ready. `first_task_ready` in the JSON reports exactly that. It checks presence on this machine; it does not prove that a provider login is valid or that an API key is accepted.
+
+### Execution paths
+
+- Claude Code CLI path: the default. `loki start` runs the `claude` binary you installed and logged in with `claude auth login`. `loki chat` (with the claude provider) and `loki edit` call the `claude` CLI directly.
+- Anthropic API-key path (Agent SDK, no `claude` CLI): opt-in. It needs `LOKI_SDK_MODE=full` (resolved to `LOKI_SDK_LOOP=1` by `bin/loki`), Anthropic credentials, the bundled `@anthropic-ai/claude-agent-sdk` platform binary, and Bun. It runs only on the Bun route of `loki start`; commands that stay on the bash route (for example `loki demo`, `loki quick`) still need a provider CLI on PATH. Without `LOKI_SDK_MODE=full`, an API key alone does not replace the `claude` CLI for the main loop.
+- Other provider CLIs: `codex` (degraded), `cline`, `aider`, `opencode`. Any one of them replaces the `claude` CLI for `loki start --provider <name>`. Loki never silently substitutes a different provider than the one requested.
+
+### Install methods
+
+| Install method | What it provides | What you still need |
+| --- | --- | --- |
+| `npm install -g loki-mode` | Loki, a bundled Bun binary and the Claude Agent SDK as npm optional dependencies | Node 20+, python3, jq, git, curl, and one execution path above |
+| `npm install -g loki-mode --omit=optional` (slim) | Loki only; no bundled Bun, no Agent SDK | Everything above, plus Bun from https://bun.sh for the Bun route. Without Bun, `bin/loki` falls back to the bash CLI. The API-key path is unavailable |
+| Homebrew (`brew install loki-mode`) | Loki | Same as npm, and install Bun yourself if you want the Bun route |
+| git clone | Loki sources | Same as npm; see the Git Clone section above for the clone steps |
+
+Supported platforms are the `os` entries in `package.json` (darwin, linux).
+
+### Requirements by path
+
+The tables below are generated from the shared source. Do not edit between the markers; run `UPDATE_CONTRACT=1 bun test tests/commands/doctor.test.ts` from `loki-ts` after editing the JSON, and the test fails if this block drifts.
+
+<!-- BEGIN GENERATED REQUIREMENTS (loki-ts/tests/commands/doctor.test.ts) -->
+
+### All paths
+
+Needed by every Loki command.
+
+| Requirement | Level | Check | Fix |
+| --- | --- | --- | --- |
+| Node.js 20 or newer | required | `node` on PATH, version 20.0 or newer | install Node 20+ from https://nodejs.org |
+| Python 3.8 or newer | required | `python3` on PATH, version 3.8 or newer | install python3 with your package manager (brew install python3) |
+| jq | required | `jq` on PATH | install jq with your package manager (brew install jq) |
+| git | required | `git` on PATH | install git with your package manager (brew install git) |
+| curl | required | `curl` on PATH | install curl with your package manager (brew install curl) |
+| bash 4.0 or newer | optional | `bash` on PATH, version 4.0 or newer | install a newer bash (brew install bash); macOS ships 3.2 |
+| Bun 1.3 or newer (bundled by npm install) | optional | `bun` on PATH, version 1.3 or newer | reinstall without --no-optional (npm bundles @oven/bun-*) or install from https://bun.sh; without it loki falls back to the slower bash CLI |
+
+### Claude Code CLI path (default, loki start)
+
+Loki drives the claude binary you installed and logged in.
+
+| Requirement | Level | Check | Fix |
+| --- | --- | --- | --- |
+| claude CLI on PATH (then log in: claude auth login) | required | `claude` on PATH | npm install -g @anthropic-ai/claude-code |
+
+### Anthropic API-key path (Agent SDK, no claude CLI)
+
+Opt-in with LOKI_SDK_MODE=full; the bundled Agent SDK runs the loop over HTTPS.
+
+| Requirement | Level | Check | Fix |
+| --- | --- | --- | --- |
+| SDK loop enabled (LOKI_SDK_MODE=full) | required | `LOKI_SDK_LOOP` is `1` or `true` | export LOKI_SDK_MODE=full |
+| Anthropic credentials (API key, auth token or gateway URL) | required | one of `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` is set | export ANTHROPIC_API_KEY=<your key> |
+| Claude Agent SDK platform binary (optional npm dependency) | required | executable `@anthropic-ai/claude-agent-sdk-<platform>/claude` in an installed node_modules | reinstall without --no-optional: npm install -g loki-mode (the SDK is an optionalDependency) |
+| Bun runtime (the SDK loop runs only on the Bun route) | required | `bun` on PATH, version 1.3 or newer | reinstall without --no-optional (npm bundles @oven/bun-*) or install from https://bun.sh |
+
+### Other provider CLIs
+
+codex (degraded), cline, aider, opencode: any one replaces the claude CLI.
+
+| Requirement | Level | Check | Fix |
+| --- | --- | --- | --- |
+| codex CLI | optional | `codex` on PATH | npm install -g @openai/codex |
+| cline CLI | optional | `cline` on PATH | npm install -g cline |
+| aider CLI | optional | `aider` on PATH | pip install aider-chat |
+| opencode CLI | optional | `opencode` on PATH | npm install -g opencode-ai |
+
+### When an optional dependency is missing
+
+| Missing | Effect |
+| --- | --- |
+| @anthropic-ai/claude-agent-sdk (or its platform binary) | The api-key-sdk path is unavailable and doctor reports it not ready. The claude-cli path and all other providers are unaffected. |
+| @oven/bun-* (Bun) | bin/loki falls back to the bash CLI (slower). The api-key-sdk path is unavailable because the SDK loop runs only on Bun. |
+
+<!-- END GENERATED REQUIREMENTS -->
+
+### Install smoke test
+
+`scripts/smoke-install.sh` packs the repository, installs the tarball into a temporary prefix, and runs `loki --version`, `loki doctor --json` and `loki route "add a health endpoint" --json`. It then repeats with Bun and the optional Agent SDK hidden. It is run by hand, is not part of CI, and writes a reproducible log. A run on one machine is evidence for that machine and OS only; it is not an OS matrix.
+
+### Known behaviors
+
+- Bun-less fallback: when Bun is absent, `loki doctor --json` runs a minimal bash evaluator (`loki_requirements_json` in `autonomy/provider-offer.sh`) over the same table. It checks presence only and does not compare versions, so the Node minimum is enforced only by the Bun doctor.
+- `first_task_ready` does not verify that `claude auth login` was done or that an API key is valid.
+- Observed once, with npm 11.17.0 on macOS arm64 and a local tarball: `npm install -g --omit=optional` still installed `@oven/bun-*` and the Claude Agent SDK packages. The smoke test removes them after install so the second case models a machine without them. This was not checked on other npm versions or from the registry.

package/docs/cost-controls.md

@@ -41,6 +41,127 @@ while spending almost nothing and completing no iteration, so neither of those
 breakers ever trips. The wall-clock cap is the one that catches it. We added it
 after a run burned $34 reaching an external timeout.
 
+## Budget contract
+
+The per-run spend cap: its default, how it is chosen, what it covers, where it is
+enforced, how far a run can overshoot, what happens when a price is missing, and
+what happens when a run is cancelled. The CLI help, the run-start line and this
+section must agree; tests pin them.
+
+### Default
+
+The default cap is **100 USD per run**.
+
+The number lives in one file, `loki-ts/data/model-pricing.json`
+(`default_max_cost_usd`). Both routes read it:
+
+- TypeScript: `loki-ts/src/e10ext/budget_cap.ts` (`DEFAULT_MAX_COST_USD`).
+- Bash: `autonomy/run.sh` (`BUDGET_LIMIT`) and the help text through
+  `loki_budget_default_usd` in `autonomy/loki`.
+
+`loki-ts/tests/engine10/budget_cap.test.ts` asserts that this document, the JSON
+file, the TypeScript constant, the bash default and the CLI help all state the same
+number. Change the JSON file and the document together.
+
+Where the default applies:
+
+| Route | Default applies | What the cap does |
+| --- | --- | --- |
+| engine10 (`loki "<task>"`, the Loki 10 engine) | Only when an API key is set (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`). A subscription run (no key) has no dollar cap. | Ends the run `BUDGET_STOP`, exit 3. |
+| Bash loop (`loki start`, `autonomy/run.sh`) | Always, key or not. | Pauses the run (writes `.loki/PAUSE` and `.loki/signals/BUDGET_EXCEEDED`); remove both to resume. |
+| Bun SDK loop (`LOKI_SDK_LOOP`) | No default. Opt in with `BUDGET_LIMIT`. | Stops the loop when the limit is reached. |
+
+The README and the engine guide have shown different figures in the past (100 and
+20). The figure above is the code's, and the two guides follow it.
+
+### Precedence
+
+Highest first. The first one set wins.
+
+1. `--max-cost USD` (engine10) or `--budget USD` (bash route). `loki start --budget`
+   is forwarded to engine10 as `--max-cost`.
+2. The environment variable `LOKI_BUDGET_LIMIT`. On the bash route an empty value
+   (`LOKI_BUDGET_LIMIT=`) means unlimited.
+3. Config file: `budgets.per_run` in `loki.yaml` (engine10), or the budget setting in
+   the settings file loaded by `autonomy/run.sh` (bash route).
+4. The default above (subject to the API-key rule for engine10).
+
+### Run-start line
+
+Every start prints the active cap and where it came from.
+
+- engine10: the start line ends the cap clause with `cap $X.XX (SOURCE)` where SOURCE
+  is `--max-cost`, `env`, `loki.yaml` or `default`, or `no dollar cap (subscription)`.
+  The default output stays within its 8-line limit.
+- bash route: `Budget limit set: $X.XX (source: flag|env|config|default)`.
+
+A cap set through the bash settings file is reported as `config`; the `--config`
+file loader exports the variable, so it reports as `env`.
+
+### Scope
+
+- **Per run.** The cap covers one run, not a day or a repository.
+- **Retries.** Every session counts, including retried stages and sessions started
+  after a provider failover. Each session writes its own cost record, and the run
+  total is the sum over every session started, so a retry adds to the total.
+- **Child work.** Subagents and tool calls made inside a provider session are part of
+  that session's reported cost. Sessions run in a temporary directory (the Wall stage)
+  have their cost record copied into the run before the directory is removed.
+- **Not counted.** The detached deep verify that may start after a PR opens is a
+  separate process and is not counted against the run cap. Sessions with no known
+  price are not counted either (see "Missing prices").
+
+### Enforcement point and overshoot
+
+engine10 checks the cap before each stage starts (`machine.ts`, `capReached`), using
+the cost events recorded so far. A stage that is already running is not interrupted by
+the dollar cap. The documented overshoot is therefore up to the cost of the stages in
+flight when the cap is crossed (the plan and wall stages can run together). Time caps
+and the per-session time limit still apply inside a stage.
+
+The bash route checks after each iteration (`check_budget_limit`), so the overshoot is
+up to one iteration.
+
+### Missing prices
+
+Cost is never reported as 0 when it was not measured.
+
+- A session with no dollar figure records `usd: null` in its cost event. Token counts
+  are kept when the provider reported them.
+- A model with no entry in the price table (`loki-ts/src/providers/price_table.ts`)
+  is not priced with a default guess. The cost record carries `total_cost_usd: null`,
+  `cost_basis: "unpriced"` and an `unmeasured_reason` naming the model.
+- The bash iteration record omits `cost_usd` and writes `cost_unmeasured_reason`
+  instead of `"cost_usd": 0`.
+- Unmeasured sessions never count toward the cap, so a run with unpriced models is not
+  stopped by a guess. The run summary says `not measured`, or `partial: $X for N of M
+  sessions` when only some sessions were priced. It never prints `$0.00` for a run
+  whose cost is unknown. The cap is only as good as the prices behind it: a run on a
+  model the table does not know is effectively uncapped, and the summary says so.
+
+### Cancellation
+
+SIGINT or SIGTERM during an engine10 run:
+
+1. The supervisor forwards SIGTERM to the worker process group and keeps reading its
+   output.
+2. The worker stops every live provider session. All providers share one spawn path
+   (`createSessionRunner`), so one rule covers them all: SIGTERM to the session's
+   process group, then SIGKILL after 2 seconds. No new session starts.
+3. Each stopped session records the usage measured so far, with its unmeasured flag
+   when no dollar figure exists (`usd: null`).
+4. If the worker has not exited after the cancel grace (10 seconds, set with
+   `LOKI_E10_CANCEL_GRACE_MS`), the supervisor SIGKILLs the group. A second signal
+   escalates immediately.
+5. The supervisor opens no PR and makes no backstop commit, restores the branch the
+   run started on, and appends `run.completed` with `cancelled: true`,
+   `outcome: "CANCELLED"` and the cost folded from the events. `loki status` shows the
+   run as `cancelled`, distinct from `FAILED`.
+6. The run summary is printed with `Outcome: CANCELLED` and the process exits **130**.
+
+The test `loki-ts/tests/engine10/supervisor_signal.test.ts` drives this with a stub
+provider that sleeps.
+
 ## Hitting a cap is a FAILURE, not a success
 
 This is the part that matters for anyone automating against us.
@@ -86,3 +207,21 @@ What we do instead:
 
 If a run cost more than you expected, `loki proof show <id>` tells you where it
 went.
+
+## Backend capability contract (LM-004)
+
+One table in `loki-ts/src/providers/provider_guard.ts` (`CAPABILITIES`) records what each provider guarantees on engine10. `loki provider matrix` prints it (all engines), `loki provider info <name> --json` prints one provider's rows with the source files each value was read from, and `loki start` prints one disclosure line before the run when the provider falls short of Claude. Claude prints nothing extra. On the legacy bash engine only the invocation and sandbox flags are confirmed from code; every other value there is `unknown`, which means not confirmed, not absent.
+
+- cost: `measured` = provider-reported; `estimated` = parsed or size-based and flagged estimated; `none` = reported as not measured.
+- budget kill: `post-iteration` = no further stage starts once priced cost reaches the cap; `none` = no cap applies.
+- cancel (pgroup): the session child is killed as a whole process group.
+- guard scan: `native` = the provider's own hooks gate each call; `post-iteration` = diff scan after each iteration, reverting destructive changes.
+- kill blocking: `native` = enforced; `none` = receipts list `kill blocking not enforced`.
+
+| provider | engine | cost | budget kill | cancel (pgroup) | sandbox flags | receipt | resume | guard scan | kill blocking |
+|---|---|---|---|---|---|---|---|---|---|
+| claude | engine10 | measured | post-iteration | yes | none | yes | yes | native | native |
+| codex | engine10 | estimated | post-iteration | yes | --sandbox workspace-write | yes | no | post-iteration | none |
+| cline | engine10 | estimated | post-iteration | yes | none | yes | no | post-iteration | none |
+| aider | engine10 | estimated | post-iteration | yes | --no-auto-commits | yes | no | post-iteration | none |
+| opencode | engine10 | none | none | yes | none | yes | no | post-iteration | none |

package/docs/environment-variables.md

@@ -49,6 +49,7 @@ interact and why hitting one is a failure rather than a success.
 | `LOKI_ENGINE` | unset | `legacy` forces the previous loop; the `--engine` flag wins over it. |
 | `LOKI_SUMMARY_JSON` | unset | `1` prints the end-of-run summary as one JSON line on the previous loop. |
 | `LOKI_TIER` | `oss` | **Not a model setting.** The open-core licensing seam. Leave it unset. |
+| `LOKI_REPO_BASELINE` | unset | `0` skips the intake repo profile and baseline test run (see docs/HARNESS-INTELLIGENCE-PLAN.md). |
 | `LOKI_ALLOW_CLAUDE_SIDECALLS` | unset | `1` (exactly) lets PRD enrichment, done recognition, the council voters, the USAGE.md refresh and the quickstart intent check prompt the `claude` CLI under a non-claude provider; `loki doctor --airgap` then reports that as required egress to Anthropic. |
 
 ### Picking a model without naming one
@@ -99,11 +100,46 @@ behaviour has a switch rather than a fork.
 | `LOKI_INJECT_FINDINGS` | on | Injects the previous iteration's reviewer findings, by severity and file:line. `0` makes the next iteration a blind retry. |
 | `LOKI_ITERATION_GRACE` | on | When the agent reports done and no gate is failing, grants ONE extra iteration past the cap to land the work. Granted at most once per run. `0` restores a pure counter. |
 | `LOKI_SCOPED_CHANGE` | auto | Forces the scoped-change profile on (`1`) or off (`0`). Auto-detected from an issue-sourced spec on a repository with real history. Never disables a trust gate; it skips phases irrelevant to a scoped fix. |
+| `LOKI_RISK_TIER` | computed | Raises the verification tier (`low`, `medium`, `high`) above the one computed from the diff. Lowering is ignored unless `LOKI_RISK_OVERRIDE_REASON` is also set. |
+| `LOKI_RISK_OVERRIDE_REASON` | unset | Recorded reason that lets `LOKI_RISK_TIER` lower the computed tier. Stored in the risk record and shown in the run summary. |
 
 `LOKI_INJECT_FINDINGS=0` is the one to think twice about. Without it the model
 is told to fix problems without being told which, so it re-derives them from
 scratch every iteration -- the slowest and least accurate way to converge.
 
+### Verification depth (risk tier)
+
+The v10 verify stage classifies risk on the diff (the artifact), never on the
+prompt, and records the result in `.loki/state/risk-tier.json`. The run
+summary prints its one-line `summary` (also `summary.risk` under `--json`; in
+default output only while the 8-line cap still holds). A record older than the
+run start is ignored, and a classification failure never fails verify.
+`loki review --risk` (`autonomy/lib/review_risk.py`) is a separate 0-100
+advisory score and is unchanged.
+
+- high: a sensitive path (auth, crypto, payments, migrations or `.sql`, CI config, lockfiles, infra, `.env`), a deleted test file, public API surface (openapi/swagger, `.proto`, `.d.ts`, `api/`, `routes/`, `public/`, index files), 15+ files, or 500+ changed lines.
+- medium: an existing test or test config modified, 4+ files, or 100+ changed lines.
+- low: everything else. Test files are never counted as sensitive.
+
+| Tier | Selected checks | Recorded as not run |
+|---|---|---|
+| low | targeted tests, lint of changed files | full test command, reviewer, council, security scan (skipped by design) |
+| medium | low plus full test command, one reviewer | one reviewer (and the full test command when no runner was detected) |
+| high | medium plus full suite, council, security scan | council, security scan (and the full test command and full suite when no runner was detected) |
+
+Targeted tests and lint always run. At medium and high, verify also runs the
+detected full test command (the `deep.ts` per-runner table); a full-test
+failure counts like any failing check, and a `not_run` result is added to
+`not_proven`. Reviewer, council and security scan are not run by fast verify at
+any tier, so they stay recorded as not run; nothing marks a skipped check as
+passing. Record shape: `{version, tier, computed, reasons[], stats{files, lines,
+sensitive[], tests_modified[], tests_deleted[], api[]}, checks_selected[],
+checks_deferred[], override?, override_ignored?, summary}`.
+
+Known gaps: the bash `run.sh` council triggers and the outcome record do not
+yet use this tier; public API detection is path-based, not a semantic diff of
+exports; a full-test failure that also fails on the base is not subtracted.
+
 ## Timeouts
 
 | Variable | Default | Effect |

package/docs/exit-codes.md

@@ -24,7 +24,9 @@ is the part most likely to surprise a script author.
 
 Usage errors are distinct from run outcomes: `loki start` with an unknown
 option exits 64, and `loki quick` with no task description exits 64 (they were
-1 and 2). A missing provider CLI still exits 2 before any spend. There is no
+1 and 2). A missing provider CLI still exits 2 before any spend, and so does a
+working directory that is not a git repository (`engine10: not inside a git
+repository`). A PRD path that does not exist also exits 2 (`PRD file not found`). There is no
 finer run-outcome signal. A gate that needs to tell "failed the quality gate"
 from "crashed" must opt into the durable contract below.
 
@@ -59,7 +61,8 @@ identically; a parity test asserts they agree status for status.
 |---|---|
 | 0 | The run completed and its diff did not weaken the tests |
 | 3 | The diff weakened the tests (a skip marker added in a test file, a test runner config changed, or an existing test file deleted or renamed). The receipt headline is NOT VERIFIED and names what was weakened, for example `NOT VERIFIED (tests weakened: skip added in sum.test.js)` |
-| 64 | Usage error: no task description |
+| 2 | Not a git repository (engine10 preflight, before any spend), or a missing provider CLI |
+| 64 | Usage error: no task description, or an unknown leading `--option` (from 11.5.0; before that it was taken as task text and started a paid run) |
 | other nonzero | The run itself failed; this code is passed through unchanged |
 
 `loki quick` has no `--json` flag; its structured result is `loki why --json`, schema: `schemas/why-result.schema.json` (`state.lastExitCode` carries the ladder above).
@@ -363,3 +366,100 @@ One provider pass, no loop.
 | 0 | Edit done (or nothing to change, or `--dry-run` plan printed) |
 | 1 | Provider pass failed, or `--verify` failed (nothing is committed) |
 | 2 | Usage or setup error (no change text, not a git repo, claude or python3 missing, unsupported provider) |
+
+## `loki run` (deprecated alias of `loki start <issue-ref>`)
+
+Not changed. `loki run` with an unknown option exits 1 (it predates the 64 usage
+contract and keeps its code); with no issue reference it exits 2. New scripts
+should call `loki start` instead. `loki route` input errors (a missing PRD file,
+or `--engine engine10` combined with a flag engine10 cannot honor) exit 2.
+
+## Contract cases
+
+Each row is executed against the real CLI by `tests/test-exit-codes-documented.sh`,
+which fails if an observed code differs from the Exit column. Every case stops
+before any provider spend. An empty diff is a distinct code only for `loki verify`
+(3). `loki edit` treats it as "nothing to change" (exit 0, see above); `loki quick`,
+`loki start` and `loki run` have no empty-diff exit code, and none is asserted.
+
+| Case | Command and setup | Exit | Meaning |
+|---|---|---|---|
+| `verify-empty-diff` | `loki verify` in a repo with no diff vs base | 3 | Verifier error: nothing to check is never a pass |
+| `verify-not-git` | `loki verify` outside a git repository | 2 | Could not check |
+| `verify-unknown-flag` | `loki verify --no-such-flag` | 64 | Usage error |
+| `run-unknown-flag` | `loki run --no-such-flag` | 1 | Legacy alias keeps its pre-64 code |
+| `run-no-issue-ref` | `loki run` with no argument | 2 | Issue reference required |
+| `quick-unknown-flag` | `loki quick --no-such-flag` | 64 | Usage error (from 11.5.0) |
+| `quick-no-task` | `loki quick` with no argument | 64 | Usage error |
+| `quick-not-git` | `loki quick fix the bug now` outside a git repository | 2 | engine10 preflight, before spend |
+| `edit-unknown-flag` | `loki edit --no-such-flag` | 2 | Usage error |
+| `edit-no-change` | `loki edit` with no change text | 2 | Usage error |
+| `edit-not-git` | `loki edit "change x"` outside a git repository | 2 | Setup error |
+| `start-unknown-flag` | `loki start --no-such-flag` | 64 | Usage error |
+| `start-missing-prd` | `loki start missing-prd.md` | 2 | PRD file not found |
+| `start-not-git` | `loki start fix the bug now` outside a git repository | 2 | engine10 preflight, before spend |
+
+Migration note (11.5.0): `loki quick --some-typo` used to run a paid task whose text
+was the flag. It now exits 64 before any spend. Task text that starts with `--` must
+be rephrased or put after other words.
+
+## Routing contract
+
+Authoritative contract for which engine and adapter `loki start` and `loki quick` use for each input form. Inspect any call without running it:
+
+```sh
+loki route start <args> --json
+loki route quick <args> --json
+loki --explain-route <flag-first args>
+```
+
+The JSON carries `engine`, `adapter`, `provider`, `model`, `input_type`, `input`, `reason` and `capability_differences`. `capability_differences` is an empty list only for the full Claude Code path on the Loki 10 engine. Any compatibility route (the legacy bash loop, or a provider other than Claude) lists at least one difference.
+
+### Rules
+
+- Argument order never changes the route: flags first or last, `--prd FILE` or a positional file, `--provider X` or `LOKI_PROVIDER=X`, `--engine X` or `LOKI_ENGINE=X` all resolve identically (the flag wins over the env var).
+- Default engine is `engine10` for a PRD file (`.md`, `.json`, `.yaml`), an issue reference (`owner/repo#N` or an issue URL), a multi-word task and a one-word brief.
+- The legacy engine runs only on `--engine legacy` or `LOKI_ENGINE=legacy`, for one call when a flag engine10 does not support is present (a notice is printed), for a provider with no engine10 invoker, or for a PRD larger than 100000 bytes.
+- `--engine engine10` with an unsupported flag is refused (exit 2) instead of rerouted.
+- A missing PRD file path is a usage error (exit 2).
+- Adapter is `<engine>:<provider>`, with the legacy engine written `legacy-bash:<provider>`.
+- Claude Code is the primary provider. The `loki chat` surface does not use this router; it is a separate interactive entry point.
+
+### Invocation table
+
+The table below is rendered from live `loki route --json` output by `tests/test-engine10-dispatch.sh`. The test fails if it drifts; regenerate with `bash tests/test-engine10-dispatch.sh --update-doc`.
+
+<!-- route-table:begin (generated by tests/test-engine10-dispatch.sh --update-doc) -->
+| Invocation (after `loki route`, unless it starts with `loki` or an env var) | Engine | Adapter | Capability differences | Reason |
+|---|---|---|---|---|
+| `start p.md` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start p.md --provider claude` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start --provider claude p.md` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start --prd p.md` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start p.json` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start p.yaml` | engine10 | engine10:claude | none | default: prd input runs on engine10 regardless of flag order |
+| `start "fix the bug"` | engine10 | engine10:claude | none | default: task input runs on engine10 regardless of flag order |
+| `start fix the bug` | engine10 | engine10:claude | none | default: task input runs on engine10 regardless of flag order |
+| `loki --explain-route --json "fix the bug"` | engine10 | engine10:claude | none | default: task input runs on engine10 regardless of flag order |
+| `quick "fix the bug"` | engine10 | engine10:claude | none | default: task input runs on engine10 regardless of flag order |
+| `quick fix the bug` | engine10 | engine10:claude | none | default: task input runs on engine10 regardless of flag order |
+| `start owner/repo#5` | engine10 | engine10:claude | none | default: issue input runs on engine10 regardless of flag order |
+| `start owner/repo#5 --provider claude` | engine10 | engine10:claude | none | default: issue input runs on engine10 regardless of flag order |
+| `start https://github.com/owner/repo/issues/5` | engine10 | engine10:claude | none | default: issue input runs on engine10 regardless of flag order |
+| `start hello` | engine10 | engine10:claude | none | default: brief input runs on engine10 regardless of flag order |
+| `start p.md --provider codex` | engine10 | engine10:codex | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `start --provider codex p.md` | engine10 | engine10:codex | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `LOKI_PROVIDER=codex start p.md` | engine10 | engine10:codex | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `start p.md --provider cline` | engine10 | engine10:cline | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `start p.md --provider aider` | engine10 | engine10:aider | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `start p.md --provider opencode` | engine10 | engine10:opencode | 1 listed | default: prd input runs on engine10 regardless of flag order |
+| `start p.md --provider gemini` | legacy | legacy-bash:gemini | 2 listed | provider gemini has no engine10 invoker (use claude, codex, cline, aider or opencode) |
+| `start p.md --engine legacy` | legacy | legacy-bash:claude | 1 listed | explicit: --engine legacy or LOKI_ENGINE=legacy |
+| `start --engine legacy p.md` | legacy | legacy-bash:claude | 1 listed | explicit: --engine legacy or LOKI_ENGINE=legacy |
+| `LOKI_ENGINE=legacy start p.md` | legacy | legacy-bash:claude | 1 listed | explicit: --engine legacy or LOKI_ENGINE=legacy |
+| `start p.md --engine engine10` | engine10 | engine10:claude | none | explicit: --engine engine10 |
+| `LOKI_ENGINE=engine10 start p.md` | engine10 | engine10:claude | none | explicit: --engine engine10 |
+| `start p.md --parallel` | legacy | legacy-bash:claude | 2 listed | flag --parallel is not supported by engine10 |
+| `start --parallel p.md` | legacy | legacy-bash:claude | 2 listed | flag --parallel is not supported by engine10 |
+| `start big.md` | legacy | legacy-bash:claude | 1 listed | PRD is larger than 100000 bytes (engine10 takes the task as one argument) |
+<!-- route-table:end -->

package/docs/spec-first-intent.md

@@ -26,3 +26,32 @@ A spec that does not parse exits 2 before any run state is created, naming the f
 ## Unchanged without the flags
 
 Without `--spec` or `--spec-first`, `loki plan` stays on its existing route, `loki start` behaves as before, and the plan and implement briefs are byte-identical (pinned by golden fixtures in `loki-ts/tests/engine10/fixtures`).
+
+## Requirement-to-check map (REQTRACE)
+
+File: `.loki/state/requirements-map.json`. Written after verification, before the run summary. Read-only view: `loki plan --requirements` (add `--json` for the raw file). Code: `loki-ts/src/features/contract.ts`; tests: `loki-ts/tests/features/contract.test.ts`.
+
+```json
+{"version":1,"revision":"<git sha at write time, or \"unknown\">","requirements":[
+  {"id":"R1","text":"...","checks":["<check id>"],"status":"covered","method":"explicit"}
+]}
+```
+
+- `status` is `covered` only when at least one check that actually ran and passed maps to the requirement. `checks` lists only those passing checks. A failed, flaky, not_run or pending check never covers.
+- `method` is `explicit` when the requirement carries its own link to checks, `heuristic` otherwise. An uncovered requirement with no link is `heuristic` with `checks: []`.
+- Ids `R1..Rn` are assigned in source order. At most 40 requirements are taken from PRD text.
+- The file is never written when there is no requirement source, and a write failure never fails a run.
+
+Requirements and checks come from existing extractors, with no second parser:
+
+| Run | Requirements | Checks that ran | Link |
+|---|---|---|---|
+| Bun runner (`loki start`, default) | `.loki/checklist/checklist.json` items | that item's `verification[]` entries, id `<item id>:<type>:<n>`; `passed === true` counts | explicit, by construction |
+| engine10 with `--spec` | acceptance criteria of the spec snapshot (`spec_file.ts` parseSpec) | `test.result` events of the run, id = check name (`runner:path`) | explicit if the criterion ends with `[check: id1, id2]`, else heuristic |
+| engine10 text or PRD task | units from `autonomy/lib/requirements_contract.py` `extract_bound_requirement_units`; needs 2 or more units | same `test.result` events | heuristic |
+
+Heuristic rule: a passing check matches when it shares at least 2 significant words (4 or more letters, minus a small stop list; all of them when the requirement has only one) with the check id plus command. It is a hint, not proof, which is why `method` is recorded.
+
+Surfaces: the run summary next-step line reads `N requirement(s) uncovered, see: loki plan --requirements` when `N > 0`, inside the 8-line cap (engine10 `withNextLine` / `formatRunSummary`, and `autonomy/lib/run-summary.sh` for the bash summary). The JSON summary adds `requirements_uncovered` only when `N > 0`.
+
+Known gaps: the legacy bash engine (`autonomy/run.sh` without Bun) does not write the map; its summary only reads one if present. Heuristic matching is word overlap only and can both miss and over-claim, so use explicit `[check: id]` links for requirements that matter.

package/docs/v10/CLI-MODERN.md

@@ -11,7 +11,7 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 - DROP-LEGACY: 32
 - DELETE: 14
 - Total rows: 137
-- Registry paths (commands and nested subcommands): 188
+- Registry paths (commands and nested subcommands): 190
 
 ## Commands
 
@@ -184,7 +184,7 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 - preview: 1
 - projects: 8
 - proof: 6
-- provider: 3
+- provider: 2
 - quick: 1
 - resume: 1
 - rollback: 2