agents-handoff 0.0.0-stage → 2.0.3

package/docs/ARCHITECTURE.md

@@ -0,0 +1,187 @@
+---
+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.
+
+agents-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/agents-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 — one harness, several at once, or an exact directory — and records what it installed. |
+
+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.
+
+## Install provenance
+
+A handoff folder proves what it was built from. An installation answers a different question:
+what is on this machine, and where did it come from. The installer writes
+`.agents-handoff-install.json` into every copy it makes, and `verify` re-hashes the same file
+set to compare the copy with that record.
+
+| Value | Definition |
+|---|---|
+| `files_sha256` | SHA-256 over the sorted `path\0sha256(file)` lines of every manifest file. |
+| `files` | Per-file sha256 values, so a mismatch names the file that changed. |
+| `source` | `tree` for a copy made from a checkout or archive beside the installer, or `archive` with the tag and the archive's own sha256 when the copy was fetched. |
+
+The install record is a record, not a signature: it proves what was installed and detects
+drift, and it cannot prove the tree it came from was trustworthy. That distinction is stated
+in full in [PROVENANCE.md](PROVENANCE.md).
+
+## 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/agents-handoff.mjs    runtime layer
+tools/agent-handoff.mjs     forwarder from the runtime layer's pre-rename path
+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
+docs/SESSIONS.md           the session index, rendered from a real store
+.github/scripts/           generators and checks: the session index, the doc link check
+refs/                      reference material: adapters, protocol, roles, brief checklist
+templates/                 handoff templates and the LLM payload schema
+schemas/                   the portable handoff payload schema
+install/                   the installer behind the agents-handoff npx package
+tests/                     acceptance fixture and a minimal transcript
+```
+
+Inside an installed copy — not in this repository — the installer adds
+`.agents-handoff-install.json`, the record of what landed there and what it was made from.
+
+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.

package/docs/CHANGELOG.md

@@ -0,0 +1,196 @@
+---
+title: Changelog
+---
+
+# 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