agents-handoff 0.0.0-stage → 2.0.2

package/docs/CHANGELOG.md

@@ -0,0 +1,151 @@
+---
+title: Changelog
+---
+
+# Changelog
+
+All notable changes to agent-handoff are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases before 2.0.0
+were development builds and were never published, so they are not listed.
+
+The version in [package.json](https://github.com/Alot1z/agent-handoff/blob/main/package.json)
+and [skill.json](https://github.com/Alot1z/agent-handoff/blob/main/skill.json) is the release
+version. The version of the separate installer package is in
+[install/package.json](https://github.com/Alot1z/agent-handoff/blob/main/install/package.json)
+and has its own
+[changelog](https://github.com/Alot1z/agent-handoff/blob/main/install/CHANGELOG.md).
+
+## [Unreleased]
+
+Add entries under the matching heading as changes land.
+
+### Added
+
+- **[Session index](https://alot1z.github.io/agent-handoff/SESSIONS.html)** (`docs/SESSIONS.md`):
+  a page rendered from a real handoff store, listing the captured sessions in
+  `examples/sessions/` with their project, harness, turn count, revision, manifest hash and
+  integrity verdict, plus the commands that reproduce each check. The sample store is built by
+  the engine from the two transcripts this repository ships, and
+  `.github/scripts/build-sessions-index.mjs --check` fails the build when the page and the store
+  disagree.
+- The installer is published to npm from the release workflow: a tag publishes `install/` as
+  `agents-handoff`, skips a version npm already has, and reports — without failing the
+  release — when `NPM_TOKEN` is not configured.
+
+### Changed
+
+- `npx agents-handoff` now installs the skill as documented. The published package
+  carries `install/` alone, so the installer downloads the archive for the requested version and
+  copies from it. It previously looked for the skill files beside itself, found none, and
+  reported success while installing nothing.
+- The clean-checkout suite builds its fixture from the shipped projection rather than the
+  development tree, which is what let the installer's broken source paths pass every local test.
+
+### Fixed
+
+- The installer lost fourteen files whenever it ran outside the development tree: `README.md`,
+  `LICENSE` and the twelve guides were addressed under `repo-upstream/<path>`, a directory only
+  the development tree has. Sources are written in the shipped tree's terms and resolved against
+  both layouts, and an install that cannot resolve a source now fails with the missing paths
+  instead of warning and continuing.
+- CI failed on every run: the runtime-layer smoke test ran `agent-handoff.mjs list`, which is not
+  a verb of that tool (it exits 2). The step builds a handoff into a scratch store and runs
+  `index`, a verb that exists.
+- The shipped version disagreed across files: `SKILL.md` said 2.0.0 while `skill.json` and
+  `package.json` said 2.0.1, and the installer carried its own 2.0.0 constant, so every install
+  reported the previous version. `SKILL.md` is now the single source of truth, the installer
+  reads it, and the suite asserts the two agree.
+- `install/package.json` pointed `repository` at a different repository from the one serving the
+  package; it now names this repository, with `homepage` and `bugs`.
+- `handoff.config.schema.json` declared its `$id` under a path that does not serve the schema.
+- `examples/demo/example-usage.md` addressed the engine as `../../../tools/handoff.mjs`, one
+  directory above the repository root, so every command in it failed when pasted.
+- `tests/acceptance/acceptance.yaml` described the development tree: it listed documents that
+  are not published, scanned a directory that is not published, and asserted two behaviours the
+  shipped CLI does not have (`--help` exiting 0, `list` succeeding on an empty store). Every
+  entry was re-run against a clean checkout and now states what was observed.
+- Documentation stopped describing files that are not published: `src/` was listed as part of an
+  installation in `INSTALL.md`, `UNINSTALL.md` and `UPGRADE.md`, and documented as a repository
+  directory in `CONTRIBUTING.md`.
+- `ARCHITECTURE.md` claimed nothing in the repository makes a network call, which stopped being
+  true once the installer fetched archives.
+
+## [2.0.1] — 2026-10-09
+
+Documentation release. No behaviour changed; no public interface changed.
+
+### Added
+
+- **[Command reference](https://github.com/Alot1z/agent-handoff/blob/main/docs/CLI.md)**
+  (`docs/CLI.md`): every executable, verb, flag, exit code, environment variable and file
+  written, in one place.
+- **[Architecture](https://github.com/Alot1z/agent-handoff/blob/main/docs/ARCHITECTURE.md)**
+  (`docs/ARCHITECTURE.md`): the five layers, the data flow, store-root resolution, the
+  write-safety discipline, and the boundaries the tool does not cross.
+- **[Troubleshooting](https://github.com/Alot1z/agent-handoff/blob/main/docs/TROUBLESHOOTING.md)**
+  (`docs/TROUBLESHOOTING.md`): symptom, cause and fix, keyed to the real exit codes.
+- This changelog, and a Changelog page on the site rendered from it, so the repository file
+  and the published page cannot drift apart.
+- A docs-consistency check (`.github/scripts/check-docs.mjs`) run in CI: every page under
+  `docs/` must appear in the navigation, and every relative link must resolve where it is
+  read.
+
+### Changed
+
+- README now links the published [installation guide](https://alot1z.github.io/agent-handoff/INSTALL.html)
+  and the [documentation site](https://alot1z.github.io/agent-handoff/) at the top, and its
+  documentation table covers every page.
+- Links in `docs/` that pointed outside the published site are absolute URLs, so they resolve
+  for a reader of the documentation instead of returning 404.
+- `package.json` homepage points at the documentation site.
+
+## [2.0.0] — 2026-10-08
+
+The first public release: a capture engine, a runtime layer over it, an installer, and the
+documentation site.
+
+### Added
+
+- **Capture engine** (`tools/handoff.mjs`, published as the `agent-handoff` bin). `build`
+  reads a JSONL or plain-text transcript and writes a handoff directory:
+  `HANDOFF.md`, `HANDOFF.summary.json`, `HANDOFF.llm.json`, `timeline.jsonl`, `TOOLS.md`,
+  `manifest.json`. Also `list`, `show`, `verify`, `rename`, `retitle` and `config`.
+- **Incremental builds.** Each build appends only the turns above the recorded `watermark`
+  and leaves `timeline.jsonl` untouched, so re-running over a longer transcript extends the
+  handoff instead of duplicating it. A rebuild with no new turns and an unchanged source hash
+  prints `handoff: up-to-date` and writes nothing.
+- **sha256 provenance.** `manifest.json` carries `raw_sha256` over the source bytes and a
+  self-hash `manifest_sha256` over itself. `verify` recomputes the self-hash, checks the
+  `timeline.jsonl` line count against `turn_count`, and parses `HANDOFF.llm.json`.
+- **Store-root resolution** (`tools/lib/handoff-root.mjs`): `HANDOFFS_ROOT`, then
+  `handoff.config.json` found by walking up, then a `handoffs/` directory on the same walk,
+  then the skill directory. Reported by `handoff.mjs config`.
+- **Runtime layer** (`tools/agent-handoff.mjs`): `auto`, `verify-gate`, `promote`, `merge`,
+  `federated-merge`, `self-improve`, `index`. Every mutating command takes a lock, backs up
+  before writing, verifies after applying, and rolls back on failure.
+- **Bounded execution** (`tools/runtime-engine.mjs`): risk classes `R0`–`R4` evaluated against
+  `permission-policy.json` before any operation runs, resumable jobs with sealed checkpoints,
+  and a per-decision record in the state directory.
+- **Capability probes** (`tools/capability-registry.mjs`): `file-exists`, `dir-writable` and
+  `command` probes that report `healthy` / `unhealthy` / `unknown` with the evidence behind
+  each verdict.
+- **Installer** (`install/`, package `agents-handoff`): `install`, `update`, `remove`,
+  `verify`, `list`, `where`, targeting a resolved global root, `./local/skills/agent-handoff`,
+  or `./skills/agent-handoff`.
+- **Documentation site** at <https://alot1z.github.io/agent-handoff/>, built by GitHub Pages
+  from `docs/`.
+- **CI** (`.github/workflows/ci.yml`): the test suite on Node 18, 20 and 22, a runtime-layer
+  smoke test, installer help, and a required-file and JSON-validity check.
+
+### Security
+
+- The engine reads transcripts and writes handoff files. It makes no network calls, and it
+  never writes secrets. The limits of what the provenance chain proves are stated in
+  [docs/PROVENANCE.md](https://github.com/Alot1z/agent-handoff/blob/main/docs/PROVENANCE.md),
+  not implied.
+
+[Unreleased]: https://github.com/Alot1z/agent-handoff/compare/v2.0.1...main
+[2.0.1]: https://github.com/Alot1z/agent-handoff/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/Alot1z/agent-handoff/tree/v2.0.0

package/docs/CLI.md

@@ -0,0 +1,196 @@
+---
+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 `agent-handoff` bin |
+| [`tools/agent-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs) | Runtime layer: acts on the state of the store. | `node tools/agent-handoff.mjs <verb>` |
+| [`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/agent-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`. |
+
+`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 `.agent-handoff/`.
+
+## `install/install.mjs` — installer
+
+Published as `agents-handoff`. Location resolution is documented in
+[INSTALL.md](INSTALL.md).
+
+| Verb | Effect |
+|---|---|
+| `install` (default) | Install the skill. |
+| `update` | Update to the latest or a specified version. |
+| `remove` | Remove the installation. |
+| `verify` | Verify installation integrity. |
+| `list` | List every installed location. |
+| `where` | Show the resolved global root and why it was chosen. |
+
+| 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. |
+
+## 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>/.agent-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` |
+
+`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/`,
+  `.agent-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/agent-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.