agents-handoff 0.0.0-stage → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# 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, 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.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 `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/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,111 @@
-# Temporary Holding Version
+# agent-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.
+- Reads any JSONL or plain-text transcript, whatever produced it.
+- Every artifact carries a sha256 provenance chain, and `verify` recomputes it.
+- Writes are backed up, verified and rolled back on failure.
+
+## Install
+
+```bash
+npx agents-handoff
+npx agents-handoff where     # show the resolved install root, and why it was chosen
+```
+
+The installer resolves the global root instead of hard-coding one. 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/agent-handoff.mjs        runtime layer: auto, verify-gate, promote, merge, self-improve, index, dispatch
+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 npx installer 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: agent-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.2
+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/agent-handoff.mjs`: auto, verify-gate, promote, merge, self-improve |
+| **L5 Collaborative** | Verified handoff dispatches a worker | none until run | `tools/agent-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/agent-handoff.mjs auto --source <file> --session <id> --harness <h> --project <p>
+HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs verify-gate <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs promote <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs merge <a> <b>
+HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs self-improve
+HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs index
+HANDOFFS_ROOT=<store> node tools/agent-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/agent-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": ".agent-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"
+    }
+  ]
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,164 @@
+---
+title: Architecture
+---
+
+# Architecture
+
+## The problem the shape solves
+
+A working session lives inside whatever client recorded it. Continuing that session
+elsewhere means either pasting the chat back in, or starting from memory. Both lose the part
+that matters: the exact turns, the tool calls, and the ability to prove which source bytes
+produced the brief you are reading.
+
+agent-handoff turns the session into files instead. A directory of plain text and JSON, a
+hash chain over it, and a fixed folder layout. Anything that can read a file can continue
+from one, with no shared memory between the two sessions.
+
+## Layers
+
+Five layers, each with one job, and each usable without the ones above it.
+
+| Layer | File | Job |
+|---|---|---|
+| Capture engine | `tools/handoff.mjs` | Turns one transcript into one handoff folder. Passive: something has to invoke it. |
+| Runtime layer | `tools/agent-handoff.mjs` | Acts on the state of the store: staleness, gates, composition, imports, index. |
+| Bounded execution | `tools/runtime-engine.mjs` | Decides whether an operation may run, before running it. |
+| Capability probes | `tools/capability-registry.mjs` | Reports what a declared capability actually does on this machine. |
+| Distribution | `install/install.mjs` | Puts the skill where a client will look for it. |
+
+The capture engine has no opinion about installation, and the runtime layer has no opinion
+about transcripts — it shells out to the engine for builds and verification. That split is
+what lets a store be inspected with one file, `manifest.json`, without loading anything else.
+
+## Data flow
+
+```
+transcript ─────────────► build ─────────────► <root>/projects/<project>/<session>/
+   (.jsonl or .txt)                    │              HANDOFF.md
+                                       │              HANDOFF.summary.json
+                                       │              HANDOFF.llm.json
+                                       │              timeline.jsonl   (append-only)
+                                       │              TOOLS.md
+                                       │              manifest.json    (hash chain)
+                                       │
+             verify ◄──────────────────┘   recompute manifest_sha256
+                                           count timeline.jsonl lines
+                                           parse HANDOFF.llm.json
+
+INDEX.json  ◄──── index / build          one row per session
+links/*.md  ◄──── merge                  cross-project relation notes
+```
+
+A second build over a longer transcript appends only the turns above the watermark. Nothing
+already written to `timeline.jsonl` is rewritten, so a brief can be regenerated without
+invalidating what a consumer already read.
+
+## Where the store lives
+
+`tools/lib/handoff-root.mjs` is the single implementation of the resolution order, so the
+engine and the runtime layer can never disagree about which store they are operating on.
+First match wins:
+
+1. `HANDOFFS_ROOT`, the environment override.
+2. `handoff.config.json`, found by walking up from the current directory, at most 10 levels.
+   `storage.path` beats `handoff_dir`; a relative `handoff_dir` resolves against the
+   directory holding the config.
+3. A `handoffs/` directory, checked at each level of the same upward walk.
+4. The skill directory, as the last resort.
+
+A config file that is present but invalid stops the run with exit 2 instead of falling
+through to rule 3. Falling back would write the session to a different store than the one
+that was configured, which is worse than refusing.
+
+`handoff.mjs config` prints the resolved root and the rule that chose it (`env`, `config`,
+`discover`, `default`).
+
+## The provenance chain
+
+Two hashes, and one of them covers the other.
+
+| Value | Definition |
+|---|---|
+| `raw_sha256` | SHA-256 of the exact source bytes read at the last build. |
+| `manifest_sha256` | SHA-256 of the manifest JSON with `manifest_sha256` removed. |
+
+`verify` recomputes the self-hash, requires `timeline.jsonl`, compares its line count with
+`turn_count`, and parses `HANDOFF.llm.json`. It prints `PASS` or `FAIL` and exits 0 or 1.
+
+What the chain detects: a manifest edited by hand, a truncated or extended timeline, a
+payload that no longer parses. What it does not do is prove that the source was authentic —
+read [PROVENANCE.md](PROVENANCE.md) for the precise boundary.
+
+## Concurrency and write safety
+
+Every mutating runtime command takes a lock before touching the store. Locks live in
+`<root>/.locks/` and are named after a hash of the operation target, so two runs on
+different sessions do not block each other while two runs on the same session do. A held
+lock exits 3.
+
+The discipline for a mutation is the same everywhere: take the lock, back up what is about
+to change, apply, verify the result, and roll back on failure. `federated-merge` backs up a
+local manifest to `manifest.json.bak-federated` before copying over it, and verifies every
+imported session with the engine afterwards. `promote` backs a manifest up to
+`manifest.json.bak` before stamping it.
+
+## Bounded execution
+
+`runtime-engine.mjs` separates the decision from the act. `evaluate` classifies a target and
+returns a verdict without running anything; `run` evaluates first and only then acts, and a
+denied operation is recorded but never executed. Targets are classified in a fixed order —
+an explicit denial, then the engine's own state directory, then approved workspaces, then
+the broad personal-data roots, then system read-only roots, otherwise external — so a
+personal-data or denied path is refused at any risk class.
+
+Every decision is written to `<state>/executions/<id>.json` with
+`enforced_before_execution: true`. Levels, risk classes and grants are in
+[PERMISSIONS.md](PERMISSIONS.md).
+
+## Honest verdicts
+
+The capability registry reports `healthy`, `unhealthy` or `unknown`, each with the evidence
+that produced it. A probe kind with no implementation returns `unknown` rather than
+`healthy`. `check` exits non-zero when a required capability is `unknown`, because an
+unanswered question is not a pass.
+
+The same rule applies to the evidence gate. `verify-gate` returns `REJECTED` in its JSON
+when a check fails, and exits 0 either way, so the verdict has to be read rather than
+inferred from a status code. `promote` prints the gate result without enforcing it, which is
+stated in the command reference rather than left for a caller to discover.
+
+## Boundaries
+
+- The engine makes no network calls, and neither does the runtime layer. The one component
+  that reaches the network is the installer, and only when it runs as the published package:
+  it downloads the archive for the version being installed. See
+  [COMPATIBILITY.md](COMPATIBILITY.md) and [INSTALL.md](INSTALL.md).
+- The source transcript is read and never written.
+- No secrets are stored. The code reads no credential files.
+- No model is called. The `.llm.json` payload is shaped for a model to read, not produced by
+  one.
+- `spawn` runs only the local node binary, with a 15000 ms timeout and its output captured
+  and hashed rather than streamed.
+
+## Repository layout
+
+```
+tools/handoff.mjs          capture engine
+tools/agent-handoff.mjs    runtime layer
+tools/runtime-engine.mjs   bounded execution
+tools/capability-registry.mjs  capability probes
+tools/lib/handoff-root.mjs store-root resolution (single owner)
+tools/handoff.test.mjs     the hermetic test suite
+docs/                      this documentation and the Pages site
+refs/                      reference material: adapters, protocol, roles, brief checklist
+templates/                 handoff templates and the LLM payload schema
+schemas/                   the portable handoff payload schema
+install/                   the npx installer package
+tests/                     acceptance fixture and a minimal transcript
+```
+
+The documentation site at <https://alot1z.github.io/agent-handoff/> is built by GitHub Pages
+directly from `docs/`. `docs/_data/nav.yml` is the navigation, `docs/_config.yml` is the
+Jekyll configuration, and `.github/scripts/check-docs.mjs` fails CI when a page is missing
+from the navigation or a relative link does not resolve.