agents-handoff 0.0.0-stage → 2.0.3

package/CHANGELOG.md

@@ -0,0 +1,192 @@
+# Changelog
+
+All notable changes to agents-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, and it is the version published to npm: the repository root is the
+[`agents-handoff`](https://www.npmjs.com/package/agents-handoff) package.
+
+## [Unreleased]
+
+Add entries under the matching heading as changes land.
+
+## [2.0.3] - 2026-10-09
+
+### Added
+
+- **Named harness targets.** One run can install the skill into Claude Code, Codex CLI and the
+  harness-neutral `~/.agents/skills` at once: `--claude`, `--codex`, `--agents`,
+  `--harness claude,codex` (repeatable), `--all` for every harness whose directory exists on
+  this machine, `--skills-dir <dir>` for any other stack, and `--project` for the
+  per-repository form. Every target gets its own copy and its own install record.
+- **`verify-package`**, a verb that checks an installation against the package npm is actually
+  serving for its version: it verifies the downloaded tarball against the registry's own
+  `integrity` and `shasum`, compares the published file set with the installed one file by
+  file, and compares the tarball sha256 with the value recorded for that install. `--record`
+  stores the tarball hashes in the install record, so later runs compare with a stored value.
+- The install record (`.agents-handoff-install.json`) now carries a `package` block — name,
+  version, registry, tarball URL, and the sha256/sha512/integrity/shasum filled in by
+  `verify-package` — so an installation can be checked against the published artifact rather
+  than only against itself.
+- Installing from the repository without publishing: `npx github:Alot1z/agent-handoff` runs the
+  same installer straight from GitHub, and the installation guide documents both that and the
+  clone-and-run path.
+- Five installer behaviour tests — multi-harness install with a record per target, `--update`
+  over every installation, `--verify` failing on a tampered copy, `remove` keeping user data,
+  and `verify-package` refusing a version npm does not serve. The suite is 34 tests.
+
+### Changed
+
+- `--update` and `--verify` with no harness flag now act on **every** installation found on the
+  machine instead of the one resolved target. A machine holding the skill in `~/.claude/skills`
+  and in `~/.agents/skills` has two copies, and updating only the resolved one left the other
+  silently stale; both verbs print a per-target summary.
+- The runtime layer's entry point is `tools/agents-handoff.mjs`, matching the product name.
+  `tools/agent-handoff.mjs` is installed alongside it as a forwarder, so notes and scripts that
+  name the old path keep working.
+
+### Fixed
+
+- `remove` deleted anything that was not one of three expected directory names, which meant a
+  handoff store kept under any other name was destroyed by `remove --force`. Removal is now
+  driven by the install manifest — what an install owns is what it copied — and the run prints
+  the entries it deliberately kept, including the store and `handoff.config.json`.
+
+## [2.0.2] - 2026-10-09
+
+### 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 skill is published to npm as
+  [`agents-handoff`](https://www.npmjs.com/package/agents-handoff), from the repository root,
+  and the release workflow publishes it on a tag: it skips a version npm already has, and
+  reports — without failing the release — when `NPM_TOKEN` is not configured. The package
+  carries the skill tree, so `npx agents-handoff` installs with no download.
+- `npm test`, `npm run check:docs` and `npm run check:session-index` are wired into
+  `prepublishOnly`, so a tree whose suite, links or session index are stale cannot be published.
+
+### Changed
+
+- `npx agents-handoff` now installs the skill as documented. It previously looked for the skill
+  files beside itself, found none, and reported success while installing nothing; a bare copy of
+  `install/` still falls back to downloading the archive for the requested version.
+- 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 `agents-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 `agents-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/agents-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/agents-handoff`,
+  or `./skills/agents-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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alot1z
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# agents-handoff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**[Installation guide →](https://alot1z.github.io/agent-handoff/INSTALL.html)**  ·  **[Documentation →](https://alot1z.github.io/agent-handoff/)**  ·  **[Changelog](CHANGELOG.md)**
+
+[![CI](https://github.com/Alot1z/agent-handoff/actions/workflows/ci.yml/badge.svg)](https://github.com/Alot1z/agent-handoff/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](#requirements)
+
+One handoff format for every AI coding harness. A working session — messages, tool calls,
+reasoning, and the provenance to prove where each byte came from — is captured as a folder
+that a fresh agent can continue from with zero shared memory. Zero runtime dependencies,
+Node.js 18 or newer, nothing read from the network at run time.
+
+## Install
+
+```bash
+npx agents-handoff --all      # every harness found on this machine, in one run
+```
+
+That is the whole install. Choose your stack instead — one harness, several, or a skills
+directory of your own:
+
+| Command | Installs into |
+|---|---|
+| `npx agents-handoff --claude` | `~/.claude/skills` — Claude Code |
+| `npx agents-handoff --codex` | `~/.codex/skills` — Codex CLI |
+| `npx agents-handoff --agents` | `~/.agents/skills` — the harness-neutral store |
+| `npx agents-handoff --harness claude,codex` | the named harnesses, in one run |
+| `npx agents-handoff --project --claude` | `./.claude/skills` — this repository only |
+| `npx agents-handoff --skills-dir <dir>` | any other stack, exactly |
+
+Without a harness flag the installer resolves the global root rather than hard-coding one and
+reports which it chose — `npx agents-handoff where` prints the same decision on its own.
+
+### Or straight from the repository
+
+```bash
+npx github:Alot1z/agent-handoff --claude   # run the installer from GitHub, no npm
+```
+
+```bash
+git clone https://github.com/Alot1z/agent-handoff.git
+cd agent-handoff
+node install/install.mjs --all      # the same installer, run from the tree
+```
+
+### Update it, and check it against the published package
+
+```bash
+npx agents-handoff --update                    # every installation found, one run
+npx agents-handoff --verify --provenance       # every installation, against its own record
+npx agents-handoff --verify-package --record   # against the tarball npm is serving
+npx agents-handoff --doctor                    # what is here, and is it intact
+npx agents-handoff --remove                    # removes the skill; your store is kept
+```
+
+Every install writes `.agents-handoff-install.json` beside the skill: a sha256 over the
+installed file set, what it was installed from, and a `package` block naming the version it
+should match. `verify` recomputes that hash and fails when a file changed, so an installation
+is checkable rather than merely present; `verify-package` fetches the published tarball,
+checks it against the registry's own integrity and shasum, and compares the installed files
+with the package file by file — `--record` stores the tarball hashes in the install record.
+`update` and `verify` with no harness flag act on **every** installation found, and `remove`
+deletes only what the install manifest owns, printing what it kept, so a store survives under
+any name. The resolution order, the location targets and the requirements are in the
+**[installation guide](https://alot1z.github.io/agent-handoff/INSTALL.html)** and
+[docs/INSTALL.md](docs/INSTALL.md).
+
+## Quick start
+
+```bash
+# Capture a session
+node tools/handoff.mjs build --source session.jsonl --harness claude-code --project my-project
+
+# List, inspect and verify what you captured
+node tools/handoff.mjs list
+node tools/handoff.mjs show <id-prefix>
+node tools/handoff.mjs verify <id-prefix>
+```
+
+`build` is incremental: re-running it over a longer transcript merges past the recorded
+watermark instead of creating a second handoff. `verify` exits non-zero when the manifest
+hash, the timeline line count or the LLM payload no longer match what was written.
+
+## What a handoff folder contains
+
+| File | Contents |
+|---|---|
+| `HANDOFF.md` | The brief a reader picks up cold: objective, current state, open loops, recent timeline |
+| `HANDOFF.summary.json` | The same brief as structured fields |
+| `HANDOFF.llm.json` | Payload shaped for a model to consume |
+| `timeline.jsonl` | Every turn, one per line, appended and never paraphrased |
+| `TOOLS.md` | The full tool-call log |
+| `manifest.json` | Counts, classes, source paths, and the sha256 provenance chain |
+
+The field-by-field contract is in [docs/FORMAT.md](docs/FORMAT.md).
+
+## Documentation
+
+Full documentation is published at **<https://alot1z.github.io/agent-handoff/>**.
+
+| Document | Covers |
+|---|---|
+| [docs/index.md](docs/index.md) | Start here: what the tool does and how the docs fit together |
+| [docs/INSTALL.md](docs/INSTALL.md) · [site](https://alot1z.github.io/agent-handoff/INSTALL.html) | Install, locations, install options, troubleshooting |
+| [docs/UPGRADE.md](docs/UPGRADE.md) | Updating an install, and what an update leaves alone |
+| [docs/UNINSTALL.md](docs/UNINSTALL.md) | Removing an install, and what is kept |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the layers fit together, the data flow, and the boundaries |
+| [docs/CLI.md](docs/CLI.md) | Every executable, verb, flag, exit code and state file |
+| [docs/FORMAT.md](docs/FORMAT.md) | Handoff folder layout, manifest fields, provenance chain |
+| [docs/SESSIONS.md](docs/SESSIONS.md) · [site](https://alot1z.github.io/agent-handoff/SESSIONS.html) | Session index: a sample store, its sessions, and the commands that verify them |
+| [docs/INTEGRATION.md](docs/INTEGRATION.md) | Feeding a transcript in from another program or a CI job |
+| [docs/LEVEL4.md](docs/LEVEL4.md) | The runtime layer: verbs, the evidence gate, bounded execution |
+| [docs/LEVEL5.md](docs/LEVEL5.md) | Dispatching a verified handoff to a worker |
+| [docs/PERMISSIONS.md](docs/PERMISSIONS.md) | Permission levels, risk classes, and what is enforced |
+| [docs/SECURITY.md](docs/SECURITY.md) | What is read and written, and the guarantees that are not made |
+| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | Platforms, Node versions, transcript formats |
+| [docs/PROVENANCE.md](docs/PROVENANCE.md) | The hash chain, what it detects, what it cannot |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Symptom, cause and fix, keyed to the real exit codes |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Running the tests and adding an adapter |
+| [CHANGELOG.md](CHANGELOG.md) | What changed in each release |
+| [refs/ADAPTERS.md](refs/ADAPTERS.md) | The canonical input shape and how each store maps onto it |
+
+## Repository layout
+
+```
+tools/handoff.mjs              capture engine (the CLI above)
+tools/agents-handoff.mjs        runtime layer: auto, verify-gate, promote, merge, self-improve, index, dispatch
+tools/agent-handoff.mjs        forwarder to the above, kept so older notes keep working
+tools/runtime-engine.mjs       bounded execution and the permission gate
+tools/capability-registry.mjs  capability health probes
+tools/lib/                     shared store-root resolution
+docs/  refs/  templates/       documentation, reference material, output templates
+schemas/                       handoff payload and configuration schemas
+install/                       the installer behind the agents-handoff npx package
+tests/                         acceptance fixture and a minimal transcript
+```
+
+## Requirements
+
+Node.js 18 or newer. No dependencies, no build step, no network access at runtime. See
+[docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+
+## Contributing
+
+Run the suite with `node tools/handoff.test.mjs`. It is hermetic — it writes to a scratch
+directory and needs no network. See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: agents-handoff
+description: >-
+  Write, verify, and hand off complete AI working sessions across any harness
+  (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Captures a
+  session as a portable, sha256-proven handoff folder a fresh agent can continue
+  from with zero shared memory, with versioned contracts, an evidence gate, and
+  backup/verify/rollback on every write. Zero runtime dependencies, no network.
+version: 2.0.3
+domain: orchestration
+tokens: 900
+allowed-tools: Bash(node:*), Read, Edit, Write
+---
+
+# Agent Handoff v2 — cross-harness session capture + verified continuation
+
+ONE handoff system for every harness, every project, every model — backed by versioned
+contracts, an evidence gate, and backup/verify/rollback on every write. Pick up any
+conversation anywhere, with provenance for every artifact.
+
+## Level map (progressive disclosure)
+
+| Level | When loaded | Token cost | Content |
+|-------|-------------|-----------|---------|
+| **L1 Metadata** | Always (frontmatter above) | ~100 | name + description |
+| **L2 Instructions** | This file, when triggered | <5k | core workflow + commands below |
+| **L3 Resources** | As needed | none until read | `docs/`, `templates/`, `refs/`, `tools/handoff.mjs` |
+| **L4 Dynamic** | When you need runtime/self-adapting | none until run | `tools/agents-handoff.mjs`: auto, verify-gate, promote, merge, self-improve |
+| **L5 Collaborative** | Verified handoff dispatches a worker | none until run | `tools/agents-handoff.mjs` dispatch + `docs/LEVEL5.md` |
+
+## What this skill is (capabilities + contracts)
+
+1. **Capture engine** (`tools/handoff.mjs`, zero deps) — builds
+   `projects/<project>/<session>/{HANDOFF.md, HANDOFF.summary.json, HANDOFF.llm.json,
+   timeline.jsonl, TOOLS.md, manifest.json}` with sha256 watermark-provenance; update-not-recreate.
+2. **Brief discipline** — lossless operational compression (10k-30k token briefs,
+   TASK / USER SPECIFICATION / CURRENT STATE / DONE / IN PROGRESS / PLANNED / FAILED / FILES /
+   VERIFICATION / ENVIRONMENT / NEXT / DO NOT), with length floors and a bootstrap text.
+3. **Evidence contract** — every handoff states RESULT/WHAT_CHANGED/VALIDATION/
+   EVIDENCE/BLOCKERS/RISKS/FOLLOW_UP; no evidence = no verified transition.
+4. **Write safety** — trigger on staleness, lock-guard, backup before write,
+   verify after write, rollback on failure, idempotent re-run.
+5. **Pipeline principles**:
+   - **Lossless raw**: rawInput/objective is verbatim, never replaced or paraphrased
+     (PromptIR rule). Matches handoff "objectives verbatim".
+   - **Versioned contracts**: every handoff artifact is a contract (schema v1, sha256);
+     re-run merges past watermark. No unversioned writes.
+   - **DecisionTrace**: record route/selection stages + provenance on every handoff
+     (stages: capture → brief → verify.gate → promote → dispatch).
+   - **Evidence-gated completion (ORC-1)**: state transitions only on evidence;
+     a worker-DONE is never a verified transition. verify.gate runs before promote/dispatch.
+   - **ContextPlan buckets (CTX-1)**: in the brief, classify context as required |
+     historical | authoritative | retrievable | sensitive | deferred with budget caps.
+   - **EVIDENCE_LEVELS ladder (KNOW-1)**: VERIFIED > OBSERVED > DERIVED > PREDICTED > UNKNOWN;
+     never silently upgrade; supersede rather than stack.
+   - **Autonomy ladder (CTL-1)**: observe → suggest → request-approval → constrained-execute →
+     workflow-execute → autonomous-within-policy. Handoff writes default to constrained-execute;
+     dispatch default dry-run.
+   - **Honesty rule (FINAL-1)**: oracle registry + success-criteria evaluator; RESULT is
+     DONE|PARTIAL|BLOCKED|FAILED — never fabricated.
+
+## Doctrine (unchanged + corpus-backed)
+
+1. Prompts are advisory; validators are authoritative. Fail closed on ambiguity (BLOCKED).
+2. Portability over compression: fidelity lives verbatim in the fileset (TOOLS.md, timeline.jsonl,
+   HANDOFF.llm.json); briefs reference by pointer.
+3. Downgrade unverified claims to their true evidence level — never upgrade.
+4. Handoff is prior knowledge, not ground truth: re-verify against the cheapest available
+   oracle, and keep instructions self-contained so a fresh agent can act cold.
+5. Max-local: every engine here runs with zero network deps; harness adapters are
+   probe-absent-safe (Claude Code, Codex, DeepSeek Harness, plain JSONL, plain text).
+
+## Core workflow
+
+### A. Capture (any harness)
+```bash
+cd <handoffs-store>          # or set HANDOFFS_ROOT
+node tools/handoff.mjs build --source <transcript.jsonl|.txt|.md> \
+  --session <id> --harness claude-code|codex|dsh|generic \
+  --model <name> --project <project> [--objective "text"]
+```
+Re-run merges past watermark. `verify <id-prefix>` checks manifest sha + turn-count + JSON parse.
+
+### B. Write the lossless brief (COS rules + CTX buckets)
+Headings TASK / USER SPECIFICATION / CURRENT STATE / DONE / IN PROGRESS / PLANNED-DECIDED /
+FAILED-UNRESOLVED / FILES / VERIFICATION / ENVIRONMENT / NEXT / DO NOT. Enforce floors
+(>=200 chars any session; >=1000 chars for >=20k recorded tokens). Preserve exact
+paths/ids/commands/error text. Mark context provenance: required | sensitive | deferred.
+
+### C. Gate with evidence (orchestrator + ORC-1)
+```
+RESULT: DONE | PARTIAL | BLOCKED | FAILED
+WHAT_CHANGED:
+VALIDATION:
+EVIDENCE:          # artifact + sha; must match pending dispatch (phaseId + dispatchId)
+BLOCKERS:
+RISKS:
+FOLLOW_UP:
+```
+
+### D. Level 4 runtime + L5 dispatch
+```bash
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs auto --source <file> --session <id> --harness <h> --project <p>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs verify-gate <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs promote <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs merge <a> <b>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs self-improve
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs index
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs dispatch <id-prefix> --task "<objective>" [--broker <orchestrator-root> --live]
+```
+Dispatch re-runs the evidence gate first; carries manifest sha256; dry-run by default
+(autonomy ladder: workflow-execute requires explicit --live).
+
+## Rules
+
+1. Never dump the whole corpus — load only what the task needs.
+2. Preserve provenance — every artifact carries raw + manifest sha256.
+3. Verbatim objectives (PromptIR lossless).
+4. Evidence gates — RESULT without EVIDENCE never becomes VERIFIED.
+5. Update, never duplicate (watermark merge).
+6. No secrets.
+7. Safety on writes (backup → apply → verify → rollback).
+8. User messages are the highest authority in any brief.
+9. Raw is never altered — handoffs render from canonical data.
+10. Self-improve — a refused/truncated brief is a knowledge candidate.
+11. Max-local: zero external-dependency engines; adapters absent-safe.
+12. Versioned contracts — every artifact has a schema version, a sha256 and a decided autonomy level.
+
+## Level map (L3 resources — read on demand)
+
+| Need | File |
+|------|------|
+| Live dispatch protocol | `refs/protocol.md` |
+| Role ladder | `refs/roles.md` |
+| Validator gate (12-point) | `refs/validator.md` |
+| Shared operating rules | `refs/handbook.md` |
+| Fresh-session bootstrap | `refs/bootstrap.md` |
+| Brief discipline | `refs/brief-checklist.md` |
+| Engine source | `tools/handoff.mjs` |
+| L4 runtime | `tools/agents-handoff.mjs` |
+| L4/L5 design | `docs/LEVEL4.md`, `docs/LEVEL5.md` |
+| Cross-harness adapters | `refs/ADAPTERS.md` |
+| Handoff format + schema | `docs/FORMAT.md`, `templates/` |
+| Installation | `docs/INSTALL.md` |
+
+**Version**: 2.0.0
+**Last Updated**: 2026-10-08

package/capability-registry.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0-capability-registry",
+  "capabilities": [
+    {
+      "id": "filesystem.read",
+      "kind": "file-exists",
+      "target": "tests/fixtures/minimal-transcript.jsonl",
+      "required": true,
+      "purpose": "read transcript sources for handoff builds"
+    },
+    {
+      "id": "filesystem.write",
+      "kind": "dir-writable",
+      "target": ".agents-handoff",
+      "required": true,
+      "purpose": "persist runtime state and checkpoints"
+    },
+    {
+      "id": "process.execute",
+      "kind": "command",
+      "command": "<node>",
+      "args": ["-e", "process.exit(0)"],
+      "required": true,
+      "purpose": "execute bounded engine subcommands"
+    }
+  ]
+}