agents-handoff 0.0.0-stage → 2.0.3

package/docs/INTEGRATION.md

@@ -0,0 +1,188 @@
+---
+title: Integrating agents-handoff
+---
+
+# Integrating agents-handoff
+
+The engine is a command-line program with a file contract. There is no daemon, no network
+call and no database. Integration means three things: getting a transcript into the canonical
+input shape, running the engine, and reading the artifacts it writes.
+
+- Put a transcript in the canonical shape: [Input contract](#input-contract).
+- Run it: [Build a handoff](#build-a-handoff) and [Exit codes](#exit-codes).
+- Read the result: [Output artifacts](#output-artifacts) and [Manifest fields](#manifest-fields).
+
+## Input contract
+
+Every input line is one JSON object (JSONL). Any program that can write JSONL can feed the
+engine; no client is required.
+
+```json
+{"seq":0,"ts":"1787669764492","harness":"dsh","source":"<origin path>",
+ "session":"<id>","thread":"<project/thread>","role":"user|assistant|system|tool",
+ "kind":"<free-form: reasoning|tool_use|text>","text":"<message body>"}
+```
+
+| Field | Used for | Notes |
+|---|---|---|
+| `seq` | ordering, watermark | Falls back to the line index when absent or non-numeric. |
+| `ts` | timeline ordering | `timestamp` is accepted as an alias. |
+| `role` | turn class | `user`, `assistant`, `system`, `tool`. |
+| `kind` | turn class refinement | `tool_use` → TOOL, `reasoning`/`thinking` → THOUGHT. |
+| `text` | the turn body | `content` and `parts[].text` are accepted as aliases. |
+| `session` | handoff id | Used when `--session` is not passed. |
+| `thread` | project inference | A `--tag--` inside the thread name is read as the project. |
+| `harness` | provenance | Not read from the line. Set it with `--harness`; otherwise it is `unknown`. |
+| `source` | provenance | Not read from the line. `source_paths` records the file given to `--source`. |
+
+`harness` and `source` are carried for whatever reads the file later. The engine itself reads
+`seq`, `ts`, `role`, `kind` and `text`, plus `session` and `thread` from the first line.
+
+Turn classification order (`classify()` in [handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs)):
+
+1. `kind` contains `tool`, or `role` is `tool` → **TOOL**
+2. `kind` contains `reason` or `think` → **THOUGHT**
+3. `role` is `user`, or `kind` is `human` → **USER**
+4. `role` is `assistant`, or `kind` is `ai` → **AGENT**
+5. anything else → **OTHER**
+
+A line whose body is empty after that mapping is skipped. A file whose name ends in `.jsonl`
+is parsed as JSONL; every other file is parsed as text, using role markers:
+
+```
+user: what needs to happen next
+assistant: the plan is in refs/plan.md
+```
+
+The marker is `user|human|assistant|ai|system|tool`, optionally prefixed by `#` and followed
+by `:` or `>`. Lines after a marker are appended to that turn until the next marker. A
+`system:` line becomes OTHER, so it stays in the record without appearing as dialogue.
+
+If no usable turn is parsed, the build fails with exit 4 rather than writing an empty handoff.
+
+## Build a handoff
+
+```bash
+node tools/handoff.mjs build --source transcript.jsonl \
+  --session my-session --harness claude-code --model <name> \
+  --project my-project --objective "what this session was for"
+```
+
+| Flag | Effect |
+|---|---|
+| `--source <file>` | The transcript to ingest. Required. |
+| `--session <id>` | Handoff id. Default: the `session` field, else the file name. |
+| `--harness <name>` | Provenance label. Default `unknown`; the engine reads no harness field. |
+| `--model <name>` | Provenance label. Stored, never invented. |
+| `--project <name>` | Project group. Default: config, then the `--tag--` in the thread, then the harness. |
+| `--objective <text>` | Overrides the objective taken from the transcript. |
+| `--force-harness` | Rewrite an existing harness value. Without it, a set value is kept. |
+| `--force-model` | Rewrite an existing model value. Without it, a set value is kept. |
+
+`node tools/handoff.mjs --handoff --source transcript.jsonl` is an alias of `build`.
+
+A rebuild of the same session is incremental: only turns above the manifest watermark are
+appended, and a source whose bytes and watermark are unchanged prints `up-to-date` and writes
+nothing.
+
+## Where handoffs are stored
+
+The root is resolved by one module, [tools/lib/handoff-root.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/lib/handoff-root.mjs),
+in this order:
+
+| # | Source | Detail |
+|---|---|---|
+| 1 | `HANDOFFS_ROOT` environment variable | Always wins. This is what makes a CI run hermetic. |
+| 2 | `handoff.config.json` | Found by walking up from the current directory. |
+| 3 | a `handoffs/` directory | Found by walking up from the current directory. |
+| 4 | the skill directory | Final fallback when nothing else exists. |
+
+Inside a config, `storage.path` beats `handoff_dir`, and a relative `handoff_dir` resolves
+against the config's own directory. The walk is bounded to ten levels. A config file that is
+present but invalid fails the run with exit 2 — it is never ignored, because falling back
+would write to a different store than the one configured.
+
+`node tools/handoff.mjs config` prints the resolved root, the source that decided it, the
+config path, the schema path, the project name and whether cross-linking is on.
+
+## Output artifacts
+
+```
+<root>/
+├── INDEX.json                        # rebuilt from every manifest
+├── projects/<project>/
+│   ├── PROJECT.md                    # project name, session list
+│   └── <session>/
+│       ├── HANDOFF.md                # the brief a human or agent reads
+│       ├── HANDOFF.summary.json      # compact payload (schema 2.0.0-summary)
+│       ├── HANDOFF.llm.json          # full payload (schema 2.0.0)
+│       ├── timeline.jsonl            # append-only, one turn per line
+│       ├── TOOLS.md                  # every tool call, verbatim
+│       └── manifest.json             # provenance and counters
+└── links/<other-project>.md          # cross-project relation notes
+```
+
+`TOOLS.md` is the fidelity tier: it carries each tool call in full. The table inside
+`HANDOFF.md` is a digest of the same turns.
+
+## Manifest fields
+
+| Field | Meaning |
+|---|---|
+| `session`, `project`, `harness`, `model` | Identity and provenance. |
+| `created_at`, `updated_at` | First write, last write. |
+| `source_paths` | Every source file ingested for this session. |
+| `watermark` | Highest ingested `seq`. Everything below it is already in the timeline. |
+| `raw_sha256` | Hash of the source bytes at the last build. |
+| `revisions` | Build count for this session. |
+| `turn_count` | Lines in `timeline.jsonl`. |
+| `counts` | Turn count per class: USER, AGENT, THOUGHT, TOOL. |
+| `manifest_sha256` | Hash of the manifest without this field. |
+
+## Verify a handoff
+
+```bash
+node tools/handoff.mjs list                 # all sessions
+node tools/handoff.mjs list <project>       # one project
+node tools/handoff.mjs show <id-prefix>     # print the brief
+node tools/handoff.mjs verify <id-prefix>   # manifest sha, turn count, payload parses
+```
+
+`verify` recomputes the manifest hash, compares the timeline line count against
+`turn_count`, and parses `HANDOFF.llm.json`. It prints `PASS <id> [...]` or fails with exit 1
+and the first broken check. See [PROVENANCE.md](PROVENANCE.md) for what the hash chain does
+and does not detect.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | Integrity failure: tampered manifest, unparsable manifest, unexpected error. |
+| 2 | Usage or configuration error: missing `--source`, missing argument, invalid config. |
+| 3 | Ambiguous id prefix — more than one session matched. |
+| 4 | No usable turns, no handoffs, or no session matching the prefix. |
+
+## CI recipe
+
+```yaml
+- name: Build and verify the handoff
+  env:
+    HANDOFFS_ROOT: ${{ github.workspace }}/.handoffs
+  run: |
+    node skills/agents-handoff/tools/handoff.mjs build \
+      --source exported-transcript.jsonl --project ci --harness generic
+    node skills/agents-handoff/tools/handoff.mjs verify "$(ls .handoffs/projects/ci | head -1)"
+```
+
+`HANDOFFS_ROOT` keeps the run off any configured store, and `verify` returns the exit code a
+pipeline can gate on.
+
+## Limits
+
+- Filesystem only: nothing is uploaded, and no network call is made.
+- No watcher: a build happens when it is invoked. See [LEVEL4.md](LEVEL4.md) for the layer
+  that probes for staleness and runs the build for you.
+- The engine reads whatever the transcript contains, including secrets. Redaction is the
+  caller's job. See [SECURITY.md](SECURITY.md).
+- Adapter routes for common session stores: [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).

package/docs/LEVEL4.md

@@ -0,0 +1,202 @@
+---
+title: Level 4 — the dynamic runtime layer
+---
+
+# Level 4 — the dynamic runtime layer
+
+The engine ([handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs)) is passive: something has to invoke it. The
+runtime layer is [tools/agents-handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/agents-handoff.mjs), which acts on the
+state of the store — it probes for staleness, checks a handoff against a contract, composes
+sessions, imports other stores and maintains the index.
+
+Every mutating command takes a lock, so two runs cannot capture or merge the same session at
+once. Locks live in `<root>/.locks/` and are named after a hash of the operation target.
+
+```bash
+node tools/agents-handoff.mjs <command> [args]
+```
+
+| Command | Purpose |
+|---|---|
+| `auto --source <file>` | Build only when the source is newer than the stored manifest. |
+| `verify-gate <id-prefix>` | Five checks: sha, counts, payload, contract, evidence. |
+| `promote <id-prefix>` | Stamp promotion metadata on a handoff's manifest. |
+| `merge <a> <b>` | Compose two sessions of one project into one handoff. |
+| `dispatch <id-prefix> --task <objective>` | Hand the continuation to a worker (Level 5). |
+| `federated-merge --from <root>` | Import sessions from another store root. |
+| `self-improve` | Collect brief shortfalls into a rules candidate file. |
+| `index` | Rebuild `INDEX.json` and report stale sessions. |
+
+An unknown command prints that list and exits 2.
+
+## `auto` — self-triggering capture
+
+```bash
+node tools/agents-handoff.mjs auto --source transcript.jsonl \
+  [--session <id>] [--harness <name>] [--project <name>] [--min-fresh-ms <n>]
+```
+
+`--source` is required. Two gates run before any build:
+
+1. **Freshness.** If the session's manifest exists and `source_mtime - manifest.updated_at`
+   is below `--min-fresh-ms` (default 60000), nothing is built and the command prints
+   `{"action":"skip-fresh"}`.
+2. **Lock.** A capture already in flight for the same project and session exits 3.
+
+It then runs the engine's `build` and prints `{"action":"captured",...}`. A missing source
+file exits 2.
+
+## `verify-gate` — the evidence gate
+
+```bash
+node tools/agents-handoff.mjs verify-gate <id-prefix>
+```
+
+| Check | Passes when |
+|---|---|
+| `sha` | `manifest_sha256` equals the hash of the manifest without that field. |
+| `counts` | Lines in `timeline.jsonl` equal `turn_count`. |
+| `payload` | `HANDOFF.llm.json` parses as JSON. |
+| `contract` | `HANDOFF.md` contains all seven contract fields, each at the start of a line. |
+| `evidence` | Not `RESULT: DONE` with no `EVIDENCE:` line. |
+
+The contract fields are `RESULT`, `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`,
+`RISKS`, `FOLLOW_UP`. The verdict is `VERIFIED` when every check is `PASS`, otherwise
+`REJECTED`, printed as JSON with the per-check table.
+
+**The command exits 0 in both cases.** A caller must read `ok` or `verdict` from the JSON —
+the exit code alone does not report a rejection. Only a bad prefix (exit 3) or a missing
+manifest is visible as a nonzero status.
+
+## `promote` — stamping verified work
+
+```bash
+node tools/agents-handoff.mjs promote <id-prefix>
+```
+
+The manifest is backed up to `manifest.json.bak`, the gate above is run and its verdict is
+printed, and the manifest is then stamped with `promoted_at` and `promoted_by` and re-hashed.
+
+Two honest caveats:
+
+- The gate result is **printed, not enforced**. The stamp is written even when the verdict is
+  `REJECTED`; a caller that wants a gate must run `verify-gate` and branch on `verdict`
+  before calling `promote`.
+- Promotion is local. It writes one flag pair into one manifest file; it contacts no external
+  system and publishes nothing.
+
+## `merge` — composing two sessions
+
+```bash
+node tools/agents-handoff.mjs merge <id-prefix-a> <id-prefix-b>
+```
+
+Timelines are concatenated and sorted by `ts`, and written to a new session directory named
+`<a>+merge+<b>` under the first project. The merged manifest records `harness: "merged"`,
+`merged_from: [a, b]` and a fresh `raw_sha256` over the joined timeline. A note is appended
+to `links/<project-b>.md` with a `<!-- merged:<id> -->` marker, so a re-run does not duplicate
+it.
+
+A merged session has no `HANDOFF.md`, no payload and no `TOOLS.md`, so it fails `verify-gate`
+on `contract` and `payload` until a brief is written for it, and `index` reports it as stale.
+
+## `federated-merge` — importing another store root
+
+```bash
+node tools/agents-handoff.mjs federated-merge --from <remote-root> [--from <root> ...] [--dry-run]
+```
+
+Each remote root is expected to have the same `projects/<project>/<session>/` layout. A
+session is imported when its `manifest_sha256` differs from the local copy, or when no local
+copy exists; identical sessions are counted as skipped, so re-running imports only what
+changed. `--dry-run` lists the actions without writing.
+
+On import: an existing local manifest is backed up to `manifest.json.bak-federated`, the
+session directory is copied, and `federated_from` and `federated_at` are stamped on the
+canonical manifest, which is then re-hashed. Every imported session is verified with the
+engine's `verify` afterwards, and the index is rebuilt. Per-session failures are listed in
+the `failed` array rather than aborting the run. A root without a `projects/` directory is
+recorded as failed, and a missing `--from` exits 2.
+
+## `self-improve` — brief shortfalls
+
+```bash
+node tools/agents-handoff.mjs self-improve
+```
+
+Every session is scanned, and a session with 40 or more USER+AGENT turns whose `HANDOFF.md`
+is shorter than 800 characters is reported as a candidate. The output is written to
+`docs/self-improve-candidates.json` inside the skill directory — deliberately skill-relative,
+so a configured store never collects rule candidates. The file lists counts, not content.
+
+## `index` — the store index
+
+```bash
+node tools/agents-handoff.mjs index
+```
+
+Rebuilds `<root>/INDEX.json` from the manifests, with one entry per session (`id`, `uuid`,
+`project`, `harness`, `turns`, `revisions`, `updated`, `manifest_sha256`), and reports
+sessions that have a manifest but no `HANDOFF.md`.
+
+## Bounded execution — `runtime-engine.mjs`
+
+[tools/runtime-engine.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/runtime-engine.mjs) is the command-execution half of the
+runtime: every operation is evaluated against `permission-policy.json` **before** it runs, and
+a denied operation is recorded but never executed.
+
+```bash
+node tools/runtime-engine.mjs evaluate --risk R0..R4 [--target <path>] [--json]
+node tools/runtime-engine.mjs run --risk R0|R1 --op read --target <path>
+node tools/runtime-engine.mjs run --risk R1 --op spawn --args "<node args>"
+node tools/runtime-engine.mjs policy
+node tools/runtime-engine.mjs job --session <s> --steps <n> [--fail-at <k>] [--json]
+node tools/runtime-engine.mjs resume --session <s> --steps <n> [--json]
+node tools/runtime-engine.mjs status --session <s> [--json]
+```
+
+| Verdict | Meaning |
+|---|---|
+| `ALLOWED` | The grant for the risk class's level is `allow`. |
+| `DENIED` | Refused: an explicit denial, a personal-data path, an unknown risk, or an unknown grant. |
+| `NEEDS_AUTH` | The grant is `needs_auth`; the operation waits for authorization and does not run. |
+
+Targets are classified in a fixed order: an explicit denial first, then the engine's own
+state directory, then the approved workspaces, then the broad personal-data roots, then
+system read-only roots, otherwise external. A personal-data or denied path is refused at any
+risk. A read-only level is allowed inside an approved workspace or a system path; every other
+level requires an approved workspace. Levels, risk classes and grants are documented in
+[PERMISSIONS.md](PERMISSIONS.md).
+
+The `spawn` operation is bounded: it runs the local node binary with the given arguments, the
+working directory pinned to the repository, a 15000 ms timeout, and the output captured and
+hashed rather than streamed. Each decision — allowed, refused or failed — is written to
+`<state>/executions/<id>.json` with `enforced_before_execution: true`.
+
+Checkpoints make a job resumable from disk alone: after each step, `<state>/checkpoints/<session>.json`
+is rewritten with a sha256 seal, and the step is appended to `<state>/jobs/<session>/work.log`.
+Each step is permission-gated at `R1`. `--fail-at <k>` simulates an abrupt kill before step
+`k` executes, leaving the durable state at `k-1`.
+
+The state directory is `<repo>/.agents-handoff`, or `AGENT_HANDOFF_STATE_DIR` when set.
+
+| Code | Meaning |
+|---|---|
+| 0 | Allowed, executed, or completed. |
+| 1 | Execution error, or the child produced no exit code. |
+| 2 | Usage or configuration error. |
+| 3 | Denied. |
+| 4 | Needs authorization, or no checkpoint to resume from. |
+| 5 | Checkpoint corrupt, or its integrity seal does not match. |
+| 137 | Simulated abrupt kill. |
+| other | The captured exit code of the spawned child. |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | A mutating command failed; the lock was released. |
+| 2 | Usage or configuration error, including an unresolvable store root. |
+| 3 | A lock is held, an id prefix is ambiguous, or a referenced path is missing. |
+| 4 | No session matches the prefix. |

package/docs/LEVEL5.md

@@ -0,0 +1,96 @@
+---
+title: Level 5 — collaborative dispatch
+---
+
+# Level 5 — collaborative dispatch
+
+A handoff normally ends as files on disk, and something reads it later. The dispatch command
+lets a handoff whose own record is complete hand its continuation to a worker through a local
+broker, instead of waiting for a reader.
+
+```bash
+node tools/agents-handoff.mjs dispatch <id-prefix> --task "<objective>" \
+  [--role <role>] [--parent <parentTaskId>] [--broker <broker-root>] [--live]
+```
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `<id-prefix>` | required | The handoff that is handing off its continuation. |
+| `--task <objective>` | required | What the worker is being asked to do. |
+| `--role <role>` | `implementation-agent` | The role the request is addressed to. |
+| `--parent <parentTaskId>` | `handoff:<id>` | The parent the request is attached to. |
+| `--broker <root>` | none | Root of the broker program. |
+| `--live` | off | Enqueue the request instead of printing it. |
+
+## The gate
+
+Dispatch refuses to hand over work from a handoff that is not internally complete. Before
+anything is built, `HANDOFF.md` is read and two things are required:
+
+1. all seven contract fields are present, each at the start of a line — `RESULT`,
+   `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`, `RISKS`, `FOLLOW_UP`;
+2. a record that says `RESULT: DONE` also carries an `EVIDENCE:` line.
+
+When either fails, the command prints the refusal and exits 1:
+
+```json
+{ "ok": false, "status": "GATE_REJECTED", "session": "<id>",
+  "reason": "handoff fails the evidence gate (missing contract fields: ...; DONE-without-EVIDENCE=true)" }
+```
+
+The gate reads `HANDOFF.md` only. It does not recompute the manifest hash, check the timeline
+count, or parse the payload — those are `verify-gate` checks. A handoff can therefore pass the
+dispatch gate while failing `verify-gate` on `sha`, `counts` or `payload`; run
+`verify-gate <id>` first when that matters.
+
+## The envelope
+
+| Field | Value |
+|---|---|
+| `from_handoff` | The session id the request came from. |
+| `project` | The project that session belongs to. |
+| `role` | `--role`. |
+| `parentTaskId` | `--parent`, by default `handoff:<id>`. |
+| `objective` | `--task`. |
+| `evidence` | The session's `manifest_sha256`, so the receiver can check what it was given. |
+| `evidenceRequirements` | `["verified-handoff"]`. |
+| `dispatchedAt` | Timestamp of the envelope. |
+| `broker_mode` | `live` or `dry-run`. |
+| `handoff_dir` | Absolute path of the session directory. |
+
+## States
+
+| State | When | Exit |
+|---|---|---|
+| `GATE_REJECTED` | The contract or evidence check failed. Nothing is sent. | 1 |
+| `DRY_RUN` | `--live` was not passed, or no broker root was given. The envelope is printed. | 0 |
+| `DISPATCHED` | `--live` and a broker root were given and the broker answered. | 0 |
+
+`DRY_RUN` is the default. It prints the envelope and one line of advice: either re-run with
+`--live`, or pass a broker root and `--live`. A dry run writes nothing and starts no process.
+
+## Live dispatch
+
+With both `--live` and a broker root, the command requires
+`<broker-root>/runtime/request-child-worker.mjs`; if that file is missing it exits 3 and
+sends nothing. It then runs:
+
+```
+node <broker-root>/runtime/request-child-worker.mjs <broker-root> <parentTaskId> <role> <task> handoff:<id>
+```
+
+The broker's stdout is parsed as JSON and returned as `broker_output` alongside the envelope.
+A broker that fails to start, or that prints something that is not JSON, exits 1.
+
+Two limits worth knowing:
+
+- **No dedupe and no lock.** Unlike `auto`, `merge` and `promote`, dispatch takes no lock and
+  keeps no record of a previous dispatch. Running a live dispatch twice enqueues the request
+  twice; a caller that needs once-only delivery must guard it.
+- **The broker is a separate program.** This skill builds the envelope, checks the gate and
+  invokes the broker entry point. What the broker does with the request — how it queues it,
+  which worker picks it up, whether it dedupes — is not implemented or verified here.
+
+The traceability chain that does exist: `parentTaskId` defaults to `handoff:<id>`, and
+`evidence` carries the handoff's manifest hash, so a request can be traced back to the session
+directory, its manifest, and the source transcripts recorded in `source_paths`.

package/docs/PERMISSIONS.md

@@ -0,0 +1,145 @@
+---
+title: Permissions
+---
+
+# Permissions
+
+The runtime layer evaluates a permission policy before it executes anything. The policy is a
+JSON file; the implementation is `tools/runtime-engine.mjs`.
+
+```
+node tools/runtime-engine.mjs run --risk R0 --op read --target tests/fixtures/minimal-transcript.jsonl
+```
+
+Every operation is evaluated first and executed only on an `ALLOWED` verdict. A `DENIED` or
+`NEEDS_AUTH` operation does not run, and its decision record is written with
+`enforced_before_execution: true`.
+
+## The policy file
+
+`permission-policy.json` in the skill root is the default. Every runtime verb accepts
+`--policy <path>`; a relative path resolves against the skill root.
+
+| Key | Shipped value |
+|---|---|
+| `approved_workspaces` | `.` (the skill root), `repo-upstream`, `.agents-handoff`, `.context` |
+| `system_read_only_roots` | `C:\Windows`, `C:\Program Files`, `C:\Program Files (x86)` |
+| `personal_data_roots` | `C:\Users` |
+| `denied_roots` | empty |
+| `grants` | `DISCOVERY_ONLY` allow, `READ_ONLY` allow, `WORKSPACE_WRITE` allow, `EXTERNAL_EFFECT` needs_auth, `DESTRUCTIVE` needs_auth, `IRREVERSIBLE` needs_auth |
+| `risk_to_level` | `R0` → `READ_ONLY`, `R1` → `WORKSPACE_WRITE`, `R2` → `EXTERNAL_EFFECT`, `R3` → `DESTRUCTIVE`, `R4` → `IRREVERSIBLE` |
+
+The shipped roots are Windows-shaped. On macOS and Linux they match no existing path, so
+anything outside `approved_workspaces` classifies as `EXTERNAL_PATH`. Set platform-appropriate
+roots before relying on classification outside the workspace.
+
+A policy that is missing, is not valid JSON, or lacks `grants` or `risk_to_level` is a
+configuration error: exit 2, nothing executed.
+
+## Levels and grants
+
+| Level | Grant in the shipped policy | Meaning |
+|---|---|---|
+| `DISCOVERY_ONLY` | allow | Read metadata, list, inspect. |
+| `READ_ONLY` | allow | Read files and state. |
+| `WORKSPACE_WRITE` | allow | Write inside an approved workspace. |
+| `EXTERNAL_EFFECT` | needs_auth | Network or external service. |
+| `DESTRUCTIVE` | needs_auth | Delete or overwrite. |
+| `IRREVERSIBLE` | needs_auth | Operations that cannot be undone. |
+
+A grant value of `allow` yields `ALLOWED`, `needs_auth` yields `NEEDS_AUTH`, and any other
+value yields `DENIED`. Unknown risk classes are denied, not allowed.
+
+Because grants are keyed by level rather than by operation, an operator can permit every
+`EXTERNAL_EFFECT` operation, or require authorization for every workspace write, with one
+edit.
+
+## Target classification
+
+`classify()` tests the target against the policy roots, most specific rule first:
+
+| Order | Class | Source |
+|---|---|---|
+| 1 | `DENIED_ROOT` | `denied_roots` |
+| 2 | `APPROVED_WORKSPACE` | the runtime's own state directory, wherever `AGENT_HANDOFF_STATE_DIR` points |
+| 3 | `APPROVED_WORKSPACE` | `approved_workspaces` |
+| 4 | `PERSONAL_DATA_PATH` | `personal_data_roots` |
+| 5 | `SYSTEM_PATH` | `system_read_only_roots` |
+| 6 | `EXTERNAL_PATH` | nothing matched |
+
+Rule 3 must precede rule 4. A globally installed skill lives under the user's home
+directory, which is normally inside a personal-data root; if the broad root won, every
+operation inside a real installation would be denied at any risk.
+
+## Verdicts
+
+| Target class | `READ_ONLY` / `DISCOVERY_ONLY` | `WORKSPACE_WRITE` and above |
+|---|---|---|
+| `APPROVED_WORKSPACE` | allowed | grant applies |
+| `SYSTEM_PATH` | allowed | denied |
+| `PERSONAL_DATA_PATH` | denied | denied |
+| `DENIED_ROOT` | denied | denied |
+| `EXTERNAL_PATH` | denied | denied |
+
+Personal data and explicitly denied roots are denied at every risk level. Writes and effects
+are allowed only inside an approved workspace.
+
+| Verdict | Exit code |
+|---|---|
+| `ALLOWED` | 0 |
+| `DENIED` | 3 |
+| `NEEDS_AUTH` | 4 |
+| usage or configuration error | 2 |
+
+## What the gateway covers
+
+| Operation | How it is gated |
+|---|---|
+| `run --op read --target <path>` | Evaluated against the target. On `ALLOWED` the file is read and the record carries `bytes` and `content_sha256`. |
+| `run --op spawn --args "<node args>"` | Evaluated against the workspace root. The child is the running Node binary with the given arguments, working directory pinned to the skill root, 15-second timeout, stdout and stderr digested into the record, child exit code propagated. |
+| `job` / `resume` steps | Each step is evaluated at `R1` against the job state directory before the work log is appended. |
+| `evaluate` | Decides and prints; executes nothing. |
+| `policy` | Prints the loaded policy and exits 0. |
+
+Every decision, allowed or denied, is written to
+`<state dir>/executions/<timestamp>-<pid>-<random>.json`. The state directory is
+`AGENT_HANDOFF_STATE_DIR` when set, and `<skill>/.agents-handoff` otherwise; it is treated as
+an approved workspace wherever it points.
+
+## Declared but not enforced
+
+- `DISCOVERY_ONLY` has a grant, but the shipped `risk_to_level` maps no risk to it, so no
+  `--risk` value reaches that level. It becomes reachable only if a policy maps a risk class
+  to it.
+- The policy gates the runtime engine only. `tools/handoff.mjs`, the capability registry and
+  the installer do not consult it: the handoff engine writes to its resolved store without a
+  permission decision, and the registry probes are classified by their own declarations.
+- There is no interactive approval prompt. `NEEDS_AUTH` reports that authorization is
+  required; granting it means changing the policy, and the decision is recorded either way.
+
+## Changing the policy
+
+1. Decide the level. Operations are keyed by risk class (`R0`–`R4`), which maps to a level.
+2. Edit `permission-policy.json`, or write a separate policy file and pass
+   `--policy <path>`.
+3. Change `grants` to move a whole level between allow, needs-auth and denial; change
+   `risk_to_level` to reclassify a risk class; add entries to `approved_workspaces`,
+   `personal_data_roots`, `system_read_only_roots` or `denied_roots` to move a path between
+   classes.
+4. Test one decision without executing it:
+
+```
+node tools/runtime-engine.mjs evaluate --risk R2 --target README.md --json
+```
+
+5. Confirm what the runtime actually loaded:
+
+```
+node tools/runtime-engine.mjs policy --json
+```
+
+A `denied_roots` entry outranks an approved workspace, so it is the switch to use when a
+path must be off limits regardless of any other rule.
+
+See [INTEGRATION.md](INTEGRATION.md) for wiring these commands into another system, and
+[LEVEL4.md](LEVEL4.md) for the runtime verbs as a whole.