loki-mode 11.4.2 → 11.6.0

package/docs/enterprise/security.md

@@ -6,153 +6,9 @@
 
 Loki Mode's security model follows a defense-in-depth approach. All security features are opt-in via environment variables, with sensible defaults that prioritize safety. When enterprise auth is not configured, the system operates in local-only mode with no network exposure.
 
-## Authentication
+## Authentication and Authorization
 
-### Token Authentication
-
-The primary authentication method uses bearer tokens prefixed with `loki_`.
-
-**Configuration:**
-
-```bash
-# Enable token auth for the dashboard/control plane API
-export LOKI_ENTERPRISE_AUTH=true
-```
-
-**Token Lifecycle:**
-
-```bash
-# Create a new API key
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "ci-pipeline", "role": "operator"}'
-
-# Rotate a key with 24-hour grace period
-curl -X POST http://localhost:57374/api/keys/ci-pipeline/rotate \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"grace_period_hours": 24}'
-
-# Revoke a key
-curl -X DELETE http://localhost:57374/api/keys/ci-pipeline \
-  -H "Authorization: Bearer $ADMIN_TOKEN"
-```
-
-**SDK Usage:**
-
-Python:
-```python
-from loki_mode_sdk import AutonomiClient
-
-client = AutonomiClient(
-    base_url="http://localhost:57374",
-    token="loki_your_token_here"
-)
-```
-
-TypeScript:
-```typescript
-import { AutonomiClient } from 'loki-mode-sdk';
-
-const client = new AutonomiClient({
-  baseUrl: 'http://localhost:57374',
-  token: 'loki_your_token_here'
-});
-```
-
-### OIDC / SSO Integration
-
-For organizations using identity providers (Okta, Auth0, Azure AD), Loki Mode supports OIDC-based authentication.
-
-**Configuration:**
-
-```bash
-export LOKI_OIDC_ISSUER="https://your-idp.okta.com/oauth2/default"
-export LOKI_OIDC_CLIENT_ID="your-client-id"
-# Optional: audience override (defaults to LOKI_OIDC_CLIENT_ID)
-export LOKI_OIDC_AUDIENCE="your-api-audience"
-```
-
-The system validates OIDC bearer tokens (presented as `Authorization: Bearer <jwt>`)
-against the issuer's JWKS endpoint. When PyJWT + cryptography are installed, the
-JWT signature is cryptographically verified (RS256/RS384/RS512) along with the
-issuer, audience, and expiry. Without PyJWT, tokens are rejected unless
-`LOKI_OIDC_SKIP_SIGNATURE_VERIFY=true` is set explicitly (insecure, local testing
-only).
-
-**Claims-to-roles mapping:**
-
-On a valid token, role/group claims are mapped to the four built-in Loki roles
-(`admin`, `operator`, `viewer`, `auditor`). The resolved role's scopes are then
-enforced through the same scope hierarchy used for API tokens. OIDC users are
-NOT granted full access by default.
-
-Recognized claim sources (case-insensitive; values may be a string,
-space-separated string, or list):
-
-| Claim | Provider |
-|-------|----------|
-| value of `LOKI_OIDC_ROLES_CLAIM` (supports dotted paths, e.g. `realm_access.roles`) | configurable |
-| `roles` | generic |
-| `groups` | generic |
-| `realm_access.roles` | Keycloak |
-| `cognito:groups` | AWS Cognito |
-
-Only claim values that exactly match a built-in role name (`admin`, `operator`,
-`viewer`, `auditor`) grant that role. Arbitrary group names (common in `groups`
-or `cognito:groups`) do not map to a role and fall through to the default.
-
-When multiple recognized roles are present, the highest-privilege match wins
-(precedence: `admin` > `operator` > `auditor` > `viewer`).
-
-**Default role (when no recognized role claim is present):**
-
-```bash
-# Defaults to the least-privileged role (viewer). Never admin.
-export LOKI_OIDC_DEFAULT_ROLE="viewer"
-```
-
-If `LOKI_OIDC_DEFAULT_ROLE` is unset or set to an unrecognized value, it falls
-back to `viewer`. The default is never `admin` / full access.
-
-## Authorization
-
-### Role-Based Access Control
-
-Four built-in roles provide scoped access:
-
-| Role | Scope | Permissions |
-|------|-------|-------------|
-| `admin` | Full control | Create/delete tenants, manage API keys, configure policies, all operator/viewer/auditor permissions |
-| `operator` | Execution | Start/cancel runs, create/update projects and tasks, read all resources |
-| `viewer` | Read-only | Read projects, runs, tasks, status. No write or delete operations |
-| `auditor` | Audit access | Read audit logs, verify chain integrity, generate compliance reports. No execution permissions |
-
-**Scope Hierarchy:**
-
-```
-admin > operator > viewer
-admin > auditor
-```
-
-Admin inherits all permissions. Operator inherits viewer permissions. Auditor is a separate branch with read-only access to audit data.
-
-**API Key Scopes:**
-
-API keys are created with a role assignment:
-
-```bash
-# Create a viewer key for monitoring dashboards
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -d '{"name": "grafana-reader", "role": "viewer"}'
-
-# Create an operator key for CI pipelines
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -d '{"name": "github-actions", "role": "operator"}'
-```
+Token auth (`LOKI_ENTERPRISE_AUTH`), key rotation with a 24-hour grace period, OIDC/SSO claim mapping and the default viewer role are documented in [authentication.md](../authentication.md). Roles (`admin`, `operator`, `viewer`, `auditor`), scope hierarchy and API key scopes are in [authorization.md](../authorization.md).
 
 ## API Security
 
@@ -221,94 +77,7 @@ This is a deliberate fail-closed design. Invalid or missing signatures always re
 
 ## Audit Logging
 
-### Hash-Chained Audit Logs
-
-Audit logs use SHA-256 hash chains for tamper evidence. Each entry's hash depends on the previous entry's hash, creating an immutable chain from the genesis record.
-
-**JavaScript Audit (Agent Actions):**
-
-```
-.loki/audit/audit.jsonl
-```
-
-Each entry:
-```json
-{
-  "seq": 42,
-  "timestamp": "2026-02-21T10:00:00.000Z",
-  "who": "agent-1",
-  "what": "file_write",
-  "where": "src/app.js",
-  "why": "implement feature",
-  "previousHash": "abc123...",
-  "hash": "def456..."
-}
-```
-
-**Python Audit (Dashboard API):**
-
-```
-~/.loki/dashboard/audit/audit-2026-02-21.jsonl
-```
-
-Each entry:
-```json
-{
-  "timestamp": "2026-02-21T10:00:00.000Z",
-  "action": "create",
-  "resource_type": "project",
-  "resource_id": "proj-1",
-  "user_id": "admin",
-  "success": true,
-  "_integrity_hash": "abc123..."
-}
-```
-
-### Chain Verification
-
-JavaScript:
-```javascript
-const audit = require('./src/audit');
-audit.init('/path/to/project');
-const result = audit.verifyChain();
-// { valid: true, entries: 1542, brokenAt: null, error: null }
-```
-
-Python:
-```python
-from dashboard.audit import verify_log_integrity
-result = verify_log_integrity("/path/to/audit-2026-02-21.jsonl")
-# {"valid": True, "entries_checked": 1542, "first_tampered_line": None}
-```
-
-API:
-```bash
-curl http://localhost:57374/api/audit/verify \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-### Syslog Forwarding
-
-Forward audit events to a centralized syslog server for SIEM integration:
-
-```bash
-export LOKI_AUDIT_SYSLOG_HOST="syslog.company.com"
-export LOKI_AUDIT_SYSLOG_PORT="514"          # default
-export LOKI_AUDIT_SYSLOG_PROTO="udp"         # or "tcp"
-```
-
-Security-relevant actions (`delete`, `kill`, `stop`, `login`, `logout`, `create_token`, `revoke_token`) are logged at `WARNING` level. All other actions are logged at `INFO` level.
-
-Syslog forwarding is fire-and-forget -- failures never block the main audit write path.
-
-### Log Rotation
-
-```bash
-export LOKI_AUDIT_MAX_SIZE_MB="10"    # Rotate when file exceeds this size
-export LOKI_AUDIT_MAX_FILES="10"      # Keep this many rotated files
-```
-
-Date-based log files (`audit-YYYY-MM-DD.jsonl`) are automatically rotated when they exceed the size limit. Old files are removed when the count exceeds the maximum.
+Hash-chained audit logs, chain verification, syslog forwarding (`LOKI_AUDIT_SYSLOG_*`) and rotation (`LOKI_AUDIT_MAX_SIZE_MB`, `LOKI_AUDIT_MAX_FILES`) are documented in [audit-logging.md](../audit-logging.md).
 
 ## Data Residency
 

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.