agents-handoff 0.0.0-stage → 2.0.3

package/docs/CLI.md

@@ -0,0 +1,299 @@
+---
+title: Command reference
+---
+
+# Command reference
+
+Every executable in this repository. Each one is a standalone Node script with zero
+dependencies; there is no build step and nothing to install to run them from a checkout.
+
+| Executable | Role | Invoked as |
+|---|---|---|
+| [`tools/handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs) | Capture engine: transcript in, handoff folder out. | `node tools/handoff.mjs <verb>`, or the published `agents-handoff` bin |
+| [`tools/agents-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agents-handoff.mjs) | Runtime layer: acts on the state of the store. | `node tools/agents-handoff.mjs <verb>` |
+| [`tools/agent-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs) | Compatibility forwarder: the runtime layer's pre-rename path, kept so older notes and hooks keep working. | `node tools/agent-handoff.mjs <verb>` (forwards to `tools/agents-handoff.mjs`) |
+| [`tools/runtime-engine.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/runtime-engine.mjs) | Bounded execution: evaluates an operation against the policy before running it. | `node tools/runtime-engine.mjs <verb>` |
+| [`tools/capability-registry.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/capability-registry.mjs) | Health probes for declared capabilities. | `node tools/capability-registry.mjs <verb>` |
+| [`install/install.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/install/install.mjs) | Installs, updates and removes the skill. | `npx agents-handoff <verb>` |
+
+Requires Node.js 18 or newer.
+
+## `tools/handoff.mjs` — capture engine
+
+Reads a transcript and writes a handoff directory. The source is never written; every
+output file is a render of it. The folder layout, the manifest fields and the provenance
+chain are in [FORMAT.md](FORMAT.md).
+
+| Verb | Effect |
+|---|---|
+| `build --source <file>` | Build or update a handoff from a transcript. |
+| `--handoff --source <file>` | Alias of `build`. |
+| `list [project-or-prefix]` | List sessions, newest first. |
+| `show <id-prefix>` | Print the rendered brief. |
+| `verify <id-prefix>` | Re-check the provenance chain and the file set. |
+| `rename <id-prefix> <new-project>` | Move a session to another project. |
+| `retitle <id-prefix> <new-name>` | Give a session a readable directory name. |
+| `config` | Report the resolved store root, the rule that chose it, the config file, the schema path and the configured project. |
+
+### `build` flags
+
+| Flag | Meaning |
+|---|---|
+| `--source <file>` | Required. A `.jsonl` file is read line by line; any other extension is read as text. |
+| `--session <id>` | Session id. Defaults to the `session` field on the first JSONL line, else the source file name without its extension. |
+| `--harness <name>` | Harness name recorded in the manifest. Defaults to the source's own field, else `unknown`. |
+| `--model <name>` | Model recorded in the manifest. Defaults to the source's own field, else empty. |
+| `--project <name>` | Project slug. The session directory is created under `projects/<project>/`. |
+| `--objective <text>` | Objective line for the brief. |
+
+`build` is incremental. It appends the turns with `seq` above the manifest's `watermark`,
+sets the watermark to the highest `seq` seen, and increments `revisions`. `timeline.jsonl`
+is append-only; the renders are rewritten. A rebuild with no new turns and an unchanged
+source hash writes nothing and prints `handoff: up-to-date`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. For `verify`, all checks passed. |
+| 1 | `verify` failed: the manifest hash, the timeline line count or the LLM payload does not match. |
+| 2 | Usage error, for example `build` without `--source`. |
+| 3 | The id prefix matched more than one session, or none. |
+| 4 | No match for `show`/`verify`/`rename`/`retitle`; also `build` when no turn could be parsed from the source. |
+
+## `tools/agents-handoff.mjs` — runtime layer
+
+Acts on the state of the store rather than being invoked per file. Every mutating command
+takes a lock in `<root>/.locks/`, so two runs cannot capture or merge the same session at
+once. Behaviour per command is described in [LEVEL4.md](LEVEL4.md).
+
+| Verb | Effect |
+|---|---|
+| `auto --source <file>` | Build only when the source is newer than the stored manifest; skip within `--min-fresh-ms` (default 60000). |
+| `verify-gate <id-prefix>` | Five checks: `sha`, `counts`, `payload`, `contract`, `evidence`. |
+| `promote <id-prefix>` | Stamp `promoted_at` and `promoted_by` on the manifest. |
+| `merge <a> <b>` | Compose two sessions of one project into `<a>+merge+<b>`. |
+| `dispatch <id-prefix> --task <objective>` | Hand the continuation to a worker. See [LEVEL5.md](LEVEL5.md). |
+| `federated-merge --from <root> [--from <root> …] [--dry-run]` | Import sessions from another store root. |
+| `self-improve` | Scan for brief shortfalls and write a rules candidate file. |
+| `index` | Rebuild `INDEX.json` and report sessions with no `HANDOFF.md`. |
+
+`tools/agent-handoff.mjs` is a forwarder, not a second implementation: it spawns
+`tools/agents-handoff.mjs`, passes every argument through, and exits with the same code. Its
+stdout and stderr are the runtime's own. Use the new path in anything you write today; the
+old one exists only so a command that already names it does not break.
+
+`auto` flags: `--source` (required), `--session`, `--harness`, `--project`, `--min-fresh-ms`.
+`dispatch` flags: `--task` (required), `--role` (default `implementation-agent`), `--parent`
+(default `handoff:<id>`), `--broker <root>`, `--live`.
+
+`verify-gate` exits 0 for both `VERIFIED` and `REJECTED`. Read `ok` or `verdict` from the
+JSON; the exit code alone does not report a rejection. `promote` prints the gate result but
+does not enforce it — run `verify-gate` and branch on the verdict first.
+
+### 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 missing, or a referenced path is missing. |
+| 4 | No session matches the prefix. |
+
+## `tools/runtime-engine.mjs` — bounded execution
+
+Evaluates every operation against [permission-policy.json](https://github.com/Alot1z/agent-handoff/blob/main/permission-policy.json)
+before it runs, and records the decision whether it was allowed, refused or failed. Levels,
+risk classes and grants are in [PERMISSIONS.md](PERMISSIONS.md).
+
+| Verb | Effect |
+|---|---|
+| `evaluate --risk R0..R4 [--target <path>] [--json]` | Classify the target and return the verdict without running anything. |
+| `run --risk R0\|R1 --op read --target <path>` | Evaluate, then read the file when allowed. |
+| `run --risk R1 --op spawn --args "<node args>"` | Evaluate, then run the local node binary with a 15000 ms timeout. |
+| `job --session <s> --steps <n> [--fail-at <k>] [--json]` | Run a checkpointed job of `n` steps, gated at `R1`. |
+| `resume --session <s> --steps <n> [--json]` | Continue from the last sealed checkpoint. |
+| `status --session <s> [--json]` | Report the durable state of a session's job. |
+| `policy` | Print the loaded policy. |
+
+Verdicts are `ALLOWED`, `DENIED` and `NEEDS_AUTH`. A denied or personal-data target is
+refused at any risk class and is never executed.
+
+| 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 (`--fail-at`). |
+| other | The captured exit code of the spawned child. |
+
+## `tools/capability-registry.mjs` — capability probes
+
+Runs a real probe per declared capability and reports what it observed. An unknown probe
+kind, a probe error and an unreadable target are reported as `unknown` or `unhealthy` with
+the evidence — never interpreted into a passing verdict.
+
+| Verb | Effect |
+|---|---|
+| `check [--registry <file>] [--json] [<id>]` | Probe every capability, or one by id; write the state file. |
+| `list [--registry <file>] [--json]` | Show declared capabilities with the verdict from the last check. |
+
+Probe kinds: `file-exists`, `dir-writable`, `command` (with `command` and `args`; the token
+`<node>` means the running node binary).
+
+| Code | Meaning |
+|---|---|
+| 0 | Every required capability is `healthy`. |
+| 1 | A required capability is `unhealthy` or `unknown` — `unknown` is never accepted as healthy. |
+| 2 | The registry file is missing, not valid JSON, or has no `capabilities` array. |
+| 4 | Unknown capability id, or a usage error. |
+
+State is written to `<state>/capability-state.json`, where `<state>` is
+`AGENT_HANDOFF_STATE_DIR` or `.agents-handoff/`.
+
+## `install/install.mjs` — installer
+
+Published as `agents-handoff`. Location resolution is documented in
+[INSTALL.md](INSTALL.md).
+
+A bare verb and its flag form are the same command: `npx agents-handoff update` and
+`npx agents-handoff --update` behave identically.
+
+| Verb | Flag form | Effect |
+|---|---|---|
+| `install` (default), `i` | `--install` | Install the skill into every selected target. |
+| `update`, `u` | `--update` | Update to the latest or a named version. |
+| `remove`, `rm` | `--remove` | Remove the installation, keeping everything that is not the installer's. |
+| `verify`, `v` | `--verify` | Verify each installation against the record written when it was installed. |
+| `verify-package`, `vp` | `--verify-package` | Verify each installation against the tarball npm publishes for its version. |
+| `list`, `ls` | `--list` | List every installed location, with its provenance state. |
+| `where` | — | Show the resolved global root and why it was chosen. |
+| `doctor` | `--doctor` | Report which harnesses exist here, what is installed where, and whether each installation still matches its record. Read-only: it never installs. |
+| `help` | `--help`, `-h` | Print the usage block. |
+
+Harness targets. With no harness flag the installer keeps its historical single target
+(`--location` / `--path`); any of these switches to named targets, and several may be combined
+in one run — each target gets its own copy and its own install record.
+
+| Flag | Target |
+|---|---|
+| `--claude` | `~/.claude/skills/` — Claude Code personal skills. |
+| `--codex` | `~/.codex/skills/` — Codex CLI personal skills. |
+| `--agents` | `~/.agents/skills/` — the harness-neutral store. |
+| `--harness <a,b>` | Named harnesses, comma separated; repeatable. |
+| `--all` | Every harness whose directory exists on this machine. |
+| `--skills-dir <dir>` | Any other stack, exactly; repeatable. |
+| `--project` | Use the per-repository form of the harness directories (`./.claude/skills`, `./.codex/skills`). |
+
+| Flag | Meaning |
+|---|---|
+| `--location global\|local\|project` | Target location. Default `global`. |
+| `--path <dir>` | Install to an exact directory. |
+| `--version latest\|<v>` | Version to install. Default `latest`. |
+| `--force`, `-f` | Skip confirmations and overwrite. |
+| `--provenance` | With `verify`: print the install record the check was run against. |
+| `--record` | With `verify-package`: store the fetched tarball hashes in the install record. |
+
+### `update` and `verify` with no harness flag
+
+A machine can hold the same skill in several places at once — `~/.claude/skills` for Claude
+Code, `~/.agents/skills` for a neutral store, an account-skill store a desktop client reads.
+With no harness flag, `update` and `verify` act on **every** installation they can find rather
+than on the single target the resolver happens to pick, because updating only the resolved one
+is how a second harness keeps an old engine without anyone noticing.
+
+The search covers the resolved global root, `./local/skills`, `./skills`, `~/.claude/skills`,
+`~/.codex/skills`, `~/.agents/skills`, each harness's per-repository form, and every
+account-skill root discovered under the platform's application-data directories. `update`
+reports one line per installation, with the version before and after; `verify` fails the run
+when any copy fails. Neither touches a store, `handoff.config.json` or any file the install
+manifest does not name.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The command ran and everything it checked passed. |
+| 1 | Any failure: a usage error, nothing installed to act on, a verification that did not match, or a `verify-package` mismatch. |
+
+### The install record
+
+Every install writes `.agents-handoff-install.json` into the copy it just made. [FORMAT.md](FORMAT.md)
+lists the fields and [PROVENANCE.md](PROVENANCE.md) states what the record does and does not prove.
+
+| Field | Contents |
+|---|---|
+| `schema_version` | `1.0-install-provenance`. |
+| `product`, `version` | `agents-handoff`, and the version read back out of the installed `SKILL.md`. |
+| `installer_version` | The installer package's own version. |
+| `installed_at` | ISO timestamp of the write. |
+| `harness` | The harness the copy went into, or `null` for the resolved single target. |
+| `target` | Absolute install directory. |
+| `source` | What the copy was made from: `{kind: "tree", path}` for a checkout or release archive, or `{kind: "archive", ref, label, archive_url, archive_sha256}` for a fetched tag archive. |
+| `package` | The npm identity this install should match: `name`, `version`, `registry`, `tarball`, `sha256`, `sha512`, `integrity`, `shasum`, `verified_at`. The hashes are `null` until `verify-package --record` fills them, because a copy made from a tree is not the published tarball. |
+| `file_count`, `manifest_entries` | Files present, and entries in the installer's manifest. |
+| `files_sha256` | One sha256 folded over every manifest path together with that file's own hash. |
+| `files` | Per-path sha256, or `missing` for a path this version does not have. |
+
+### What `verify` compares
+
+For each installation: that every manifest file exists (a path the version never had is
+reported as not part of that version rather than failed), that `SKILL.md` carries a name and a
+version, that the engine actually runs — `tools/handoff.mjs config` must exit 0 with its
+resolved-root marker, which also proves the import graph resolves — and that a recomputed
+`files_sha256` equals the recorded one. An installation made before this record existed is
+reported as having none, never silently passed.
+
+### What `verify-package` checks, and in what order
+
+Each step makes the next one meaningful:
+
+1. **The registry's own hashes.** The tarball is downloaded for the installed version and must
+   match the `integrity` (sha512) and `shasum` (sha1) the registry declares for it; otherwise
+   "the published package" is just whatever the network handed over.
+2. **Per-file identity.** The manifest is compared file by file against the extracted tarball,
+   and every difference is named (`not installed`, `not in the published package`, or
+   `content differs`).
+3. **The recorded hash.** When the install record already holds a package `sha256`, it must
+   match too.
+
+Without `--record` nothing is written; with it, the fetched `sha256`, `sha512`, `integrity`
+and `shasum` are stored in `package`. A version that is not on the registry cannot pass this
+check, and it says so rather than reporting success.
+
+### What `remove` deletes
+
+`remove` deletes what the install manifest owns, plus the record it wrote itself and the
+`private` `package.json` stub it created — and nothing else. Store directories, notes, a
+`handoff.config.json`, and any file a later version treats as user data survive by default,
+and every entry that was left is printed under `Kept — not the installer's to delete:`.
+
+## Environment variables
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `HANDOFFS_ROOT` | capture engine, runtime layer | Store root. Always wins over every other rule. |
+| `AGENT_HANDOFF_STATE_DIR` | runtime engine, capability registry | State directory for executions, checkpoints, jobs and capability state. Default `<repo>/.agents-handoff`. |
+| `AGENT_HANDOFF_GLOBAL_DIR` | installer | Overrides the resolved global install root. |
+
+## Files written
+
+| Path | Written by |
+|---|---|
+| `<root>/INDEX.json` | `build`, `index` |
+| `<root>/projects/<project>/<session>/` | `build`, `merge`, `federated-merge`, `retitle`, `rename` |
+| `<root>/links/<project>.md` | `merge` |
+| `<root>/.locks/<hash>.lock` | every mutating runtime command |
+| `<state>/executions/<id>.json` | `runtime-engine run`, `job` |
+| `<state>/checkpoints/<session>.json` | `runtime-engine job`, `resume` |
+| `<state>/jobs/<session>/work.log` | `runtime-engine job` |
+| `<state>/capability-state.json` | `capability-registry check` |
+| `<skill>/docs/self-improve-candidates.json` | `self-improve` |
+| `<install>/.agents-handoff-install.json` | `install`, `update`, `verify-package --record` |
+
+`self-improve` writes inside the skill directory on purpose: the candidate file describes the
+skill's brief rules, so a configured store never collects rule candidates.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,124 @@
+---
+title: Compatibility
+---
+
+# Compatibility
+
+## Platforms
+
+| Platform | Level | Notes |
+|---|---|---|
+| Windows 10 / 11 | SUPPORTED | Primary development platform |
+| macOS 12+ | SUPPORTED | Uses only portable Node APIs |
+| Linux | SUPPORTED | Uses only portable Node APIs |
+
+## Runtime
+
+| Requirement | Version | Why |
+|---|---|---|
+| Node.js | 18.0.0 or newer | ES modules and `node:` built-ins |
+| npm | 9.0.0 or newer | Only if you install from the registry |
+
+The engine and the runtime install no packages at run time. `package.json` declares no
+dependencies.
+
+## Architectures
+
+| Architecture | Level | Notes |
+|---|---|---|
+| x64 | SUPPORTED | Primary |
+| arm64 (Apple silicon) | TESTED | macOS |
+| arm64 (Linux) | UNTESTED | Expected to work; no CI runner exercises it |
+
+## Node version matrix
+
+| Version | Level |
+|---|---|
+| 18.x | SUPPORTED (minimum) |
+| 20.x | SUPPORTED |
+| 22.x | SUPPORTED |
+| < 18 | UNSUPPORTED |
+
+## Input formats the engine parses
+
+| Format | How it is detected | Fields read |
+|---|---|---|
+| JSONL | `.jsonl` extension | `seq`, `ts`/`timestamp`, `role`, `kind`, and the text from `text`, `content`, or `parts[].text` |
+| Plain text | Any other extension | A line opening with `user:`, `human:`, `assistant:`, `ai:`, `system:` or `tool:` (or `>` instead of `:`); following lines are appended to that turn |
+
+Turn classification, in this order: `kind` containing `tool`, or `role: "tool"`, becomes `TOOL`;
+`kind` containing `reason` or `think` becomes `THOUGHT`; `role: "user"` (or `kind: "human"`) becomes
+`USER`; `role: "assistant"` (or `kind: "ai"`) becomes `AGENT`; everything else becomes `OTHER`.
+Malformed JSONL lines and turns with empty text are skipped.
+
+## Session sources
+
+Harness stores are read by adapters that normalise a store into the canonical JSONL shape; the
+engine has no harness-specific code. See [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
+
+| Source shape | Route |
+|---|---|
+| JSONL session directory | Adapter projects each session file to canonical JSONL |
+| SQLite session database | Adapter reads the database read-only and projects rows to canonical JSONL |
+| Exported JSONL | Passed directly to `build --source` |
+| Plain text or Markdown log | Role-marker parser built into the engine |
+
+## Filesystem
+
+| Feature | Windows | macOS | Linux |
+|---|---|---|---|
+| Path separators | `\` and `/` | `/` | `/` |
+| Case sensitivity | Insensitive (typical) | Sensitive | Sensitive |
+| Symlinks | Limited | Full | Full |
+| Permissions | ACLs | POSIX | POSIX |
+
+Path handling goes through `node:path`; no path is hard-coded in the engine.
+
+## Environment variables
+
+| Variable | Required | Effect |
+|---|---|---|
+| `HANDOFFS_ROOT` | No | Sets the store root and takes precedence over every other rule |
+
+## Configuration
+
+`handoff.config.json` is optional. It is discovered by walking up from the current directory, a
+maximum of 10 levels, and validated against `handoff.config.schema.json`. The keys the engine acts
+on are `storage.path`, `handoff_dir`, `project_name` and `linking.enabled`. A relative
+`handoff_dir` resolves against the directory that holds the config.
+
+Root resolution order, first match wins: `HANDOFFS_ROOT`, then a config-declared directory, then a
+`handoffs/` directory found by the same upward walk, then the skill directory itself. Run
+`node tools/handoff.mjs config` to see which rule applied.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Integrity failure (manifest mismatch, corrupted manifest) or an unexpected error |
+| 2 | Usage error, missing source file, or an invalid config |
+| 3 | Ambiguous session-id prefix |
+| 4 | No parsable turns, no handoffs, or no match for the prefix |
+
+## CI
+
+The suite is `node tools/handoff.test.mjs`. It needs no install step, so a CI job is checkout plus
+Node 18/20/22. GitHub Actions workflows are under `.github/workflows/`.
+
+| Platform | Level | Notes |
+|---|---|---|
+| GitHub Actions | SUPPORTED | Workflows included |
+| GitLab CI, Azure DevOps, Jenkins | UNTESTED | Any runner with Node 18+ works |
+
+## Offline use
+
+The engine makes no network requests. The installer is the one component that reaches the
+network: run from a checkout or an unpacked archive it copies the files beside it, and run as the
+published package it downloads that version's archive from this repository. Either way the
+network is needed once, while installing; after that the installed skill is offline.
+
+## MCP
+
+The engine is a CLI with text and JSON output, so an MCP server can wrap it. No MCP server ships
+with this repository.

package/docs/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+---
+title: Contributing
+---
+
+# Contributing
+
+## Requirements
+
+Node.js 18 or newer. The tools import `node:*` only, so there is no runtime dependency to
+install and no lockfile to keep in sync.
+
+## Run the suite
+
+```
+node tools/handoff.test.mjs
+```
+
+`npm test` runs the same command. The suite uses `node:test` and `node:assert` only, and
+drives the real CLIs through `spawnSync`. It is hermetic: every test builds into a temporary
+`HANDOFFS_ROOT`, batch runtime state goes to a temporary `AGENT_HANDOFF_STATE_DIR`, and both
+are removed afterwards. A bare run leaves no files behind.
+
+| Area | Asserted |
+|---|---|
+| Engine: build, verify, list | Build from the shipped fixture, `verify` prints `PASS` and exits 0, a tampered manifest fails `verify` with exit 1, `list` shows the session under its project, a malformed source exits 4, a missing source exits 2, usage errors exit 2, a rebuild of identical input stays up to date without a new revision. |
+| Capability registry | Required capabilities probe healthy, an unknown capability id exits 4, an unknown probe kind is never reported healthy, a missing registry file exits 2. |
+| Permission engine | Evaluation precedes execution (records carry `enforced_before_execution`), a personal-data read is denied with exit 3 and never executed, `R2` on the workspace is `NEEDS_AUTH` with exit 4, a bounded spawn propagates the child's exit code, an unknown risk class is default-denied, an approved workspace outranks a broad personal-data root, a traversal target is denied. |
+| Checkpoint and resume | A job killed mid-run resumes from disk alone with no step duplicated or lost, a missing checkpoint exits 4, a tampered checkpoint fails its seal with exit 5, a second job refuses an existing session checkpoint, a mismatched `--steps` exits 2. |
+
+## Drive a CLI by hand
+
+```
+node tools/handoff.mjs build --source tests/fixtures/minimal-transcript.jsonl --project demo
+node tools/handoff.mjs list
+node tools/handoff.mjs show minimal-transcript
+node tools/handoff.mjs verify minimal-transcript
+node tools/handoff.mjs config
+
+node tools/runtime-engine.mjs policy
+node tools/runtime-engine.mjs evaluate --risk R0 --target tests/fixtures/minimal-transcript.jsonl
+
+node tools/capability-registry.mjs check --registry capability-registry.json
+```
+
+`build`, `rename` and `retitle` write into the resolved store. Point `HANDOFFS_ROOT` at a
+temporary directory while experimenting so a test session is not added to your own store:
+
+```
+HANDOFFS_ROOT=/tmp/ah-scratch node tools/handoff.mjs build --source tests/fixtures/minimal-transcript.jsonl
+```
+
+On Windows use `set HANDOFFS_ROOT=...` in cmd, or `$env:HANDOFFS_ROOT="..."` in PowerShell.
+
+| Tool | Exit codes |
+|---|---|
+| `tools/handoff.mjs` | 0 success, 1 verification failure or I/O error, 2 usage or invalid config, 3 ambiguous id prefix, 4 no matching handoff or no usable turns |
+| `tools/runtime-engine.mjs` | 0 allowed, 2 usage or config error, 3 denied, 4 needs authorization or missing checkpoint, 5 corrupt checkpoint, 137 simulated kill, otherwise the child's exit code |
+| `tools/capability-registry.mjs` | 0 all required capabilities healthy, 1 a required capability is unknown or unhealthy, 2 registry missing or invalid, 4 unknown capability id |
+
+## Add a harness adapter
+
+The engine consumes one canonical input shape, so an adapter is anything that turns a
+session store into that shape. One JSONL line:
+
+```json
+{"seq":0,"ts":"<epoch or ISO>","harness":"<name>","source":"<origin path>","session":"<id>",
+ "thread":"<project/thread>","role":"user|assistant|system|tool","kind":"<reasoning|tool_use|text>",
+ "text":"<message body>"}
+```
+
+Rules the parser applies. Text is taken from `text`, then `content`, then `parts[].text`. A
+JSONL line that does not parse, or whose text is blank, is skipped. The class comes from
+`kind` and `role`: `tool` in `kind`, or `role: tool`, is `TOOL`; `reason` or `think` in
+`kind` is `THOUGHT`; `role: user` or `kind: human` is `USER`; `role: assistant` or `kind: ai`
+is `AGENT`; anything else is `OTHER`. A `.txt` or `.md` source is read as role-marked text
+instead (`user:`, `assistant:`, `tool:`, optionally prefixed with `#`).
+
+Checklist:
+
+1. Produce the canonical JSONL from the store, without modifying the store.
+2. Build from it with `HANDOFFS_ROOT` set to a temporary directory and read the result.
+3. Add a row to [ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md): store path, adapter route, status. Claim
+   `VERIFIED` only for a source you actually ran.
+4. If the parser changed, add a fixture under `tests/fixtures/` and a test to
+   `tools/handoff.test.mjs`.
+
+## Rules for a change
+
+- Add no runtime dependency. The engine stays importable and runnable with a bare Node
+  installation.
+- Keep the exit codes. They are contracts (see the table above and
+  [INTEGRATION.md](INTEGRATION.md)).
+- Never commit session data or credentials: no `handoffs/`, `projects/`, `links/`,
+  `.agents-handoff/`, no `*.key`, `*.pem`, `*.token`, and no transcript copied from a real
+  session. Test input belongs in `tests/fixtures/`.
+- A behaviour change comes with a test in `tools/handoff.test.mjs` and an update to the
+  document that owns the contract: [FORMAT.md](FORMAT.md) for the files and fields,
+  [PERMISSIONS.md](PERMISSIONS.md) for policy semantics, [INTEGRATION.md](INTEGRATION.md)
+  for the command surface.
+- Run the suite before proposing the change and report its actual result, including
+  failures you could not fix.
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `SKILL.md` | The skill definition a harness reads: when to use it, its commands and its rules. |
+| `docs/` | These documents. |
+| `install/` | `install.mjs`, the `npx` installer, and its own README. |
+| `tools/handoff.mjs` | The handoff engine: build, list, show, verify, rename, retitle, config. |
+| `tools/agents-handoff.mjs` | The runtime verbs layered over the engine. |
+| `tools/runtime-engine.mjs` | Permission policy, bounded execution, checkpoints and resume. |
+| `tools/capability-registry.mjs` | Probes declared capabilities and reports honest verdicts. |
+| `tools/handoff.test.mjs` | The test suite. |
+| `tools/lib/handoff-root.mjs` | The single definition of where handoffs are stored. |
+| `schemas/` | `handoff.schema.json`, the portable payload contract. |
+| `templates/` | The handoff render template. |
+| `refs/` | Reference documents: harness adapters, protocol, roles, validator, brief checklist. |
+| `tests/fixtures/` | Deterministic inputs for the suite. |
+| `permission-policy.json` | The default permission policy. |
+| `capability-registry.json` | The default capability declarations. |
+| `handoff.config.schema.json`, `handoff.config.example.json` | Schema and example for `handoff.config.json`. |
+| `.github/workflows/` | Continuous integration and release workflows. |
+
+## Documentation is part of the contract
+
+A claim in these documents is expected to be checkable against the code. If you change a
+file layout, a field, a flag or an exit code, update the document that states it in the same
+change. Do not document an option that a tool does not implement; if something is reserved
+but not implemented, say so, as `handoff.config.schema.json` does for `auto_capture`.
+
+## License
+
+MIT. By contributing you agree your contribution is distributed under it.