agents-handoff 0.0.0-stage → 2.0.2

package/docs/FORMAT.md

@@ -0,0 +1,157 @@
+---
+title: Handoff format
+---
+
+# Handoff format
+
+One handoff is a directory of files generated from a session transcript. The source
+transcript is read, never written: every handoff file is a render of it, and the
+renders carry the digests that let you prove which source bytes produced them.
+
+Everything below describes the behaviour of `tools/handoff.mjs`.
+
+## Where handoffs live
+
+`tools/lib/handoff-root.mjs` is the single implementation of this order. First match wins:
+
+| Order | Source | Notes |
+|---|---|---|
+| 1 | `HANDOFFS_ROOT` | Environment override. Always wins. The test suite uses it to stay hermetic. |
+| 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 | `<dir>/handoffs/` | Zero-config convention, checked at each level of the same upward walk. |
+| 4 | the skill directory | Default store when no environment variable, config or `handoffs/` directory is found. |
+
+A `handoff.config.json` that is present but invalid fails the run with exit 2 instead of
+falling back, because falling back would write the session to a store other than the one
+that was configured. The schema for that file is `handoff.config.schema.json`.
+
+```
+node tools/handoff.mjs config
+```
+
+prints the resolved root, which rule chose it (`env`, `config`, `discover`, `default`),
+the config file used, the schema path, the configured project name and whether
+cross-project linking is enabled.
+
+## Directory layout
+
+```
+<root>/
+  INDEX.json                          index of every session, rewritten on each build
+  links/<other-project>.md            cross-project relation notes
+  projects/<project>/
+    PROJECT.md                        project file: one line per session
+    <session>/                        one handoff
+```
+
+A legacy layout — session directories directly under `<root>` — is migrated on the next
+build: any directory holding a `manifest.json` is moved to `projects/<project>/`, using the
+project recorded in its manifest.
+
+## Files in a session directory
+
+| File | Written by | Contents |
+|---|---|---|
+| `HANDOFF.md` | `build`, `retitle`, `rename` | Human render: objective, current state, open loops, the last 40 turns as a table, tool-call digest, where the other files are, provenance. |
+| `HANDOFF.summary.json` | `build`, `retitle`, `rename` | Compact machine payload, `schema_version` `2.0.0-summary`. Objective, `state_now` head (600 chars), open loops, counts, artifact names, provenance. |
+| `HANDOFF.llm.json` | `build`, `retitle`, `rename` | Full machine payload, `schema_version` `2.0.0`. The summary fields plus the complete `timeline[]` and `tool_calls[]` arrays, with the turn class stored as `class`. |
+| `timeline.jsonl` | `build` (append-only) | One JSON object per turn: `{seq, ts, class, text}`. New turns are appended; existing lines are never rewritten. |
+| `TOOLS.md` | `build` | Every tool turn in full, untruncated, as `## [seq] <ts>` sections. The table in `HANDOFF.md` is a 120-character digest of the same turns. |
+| `manifest.json` | `build`, `retitle`, `rename` | The record the other files are verified against. See below. |
+
+Renders (`HANDOFF.md`, the two JSON payloads) are rewritten on every build; `timeline.jsonl`
+is not.
+
+## manifest.json
+
+| Field | Meaning |
+|---|---|
+| `session` | Session id as resolved for this handoff. |
+| `project` | Project slug. |
+| `harness`, `model` | From `--harness` / `--model`, from the source's own fields, or `unknown` / `""`. |
+| `created_at`, `updated_at` | ISO 8601. `created_at` is set once on creation. |
+| `source_paths` | Every source path this session was ever built from. |
+| `watermark` | Highest `seq` already emitted. Turn `seq <= watermark` is already in `timeline.jsonl`. |
+| `raw_sha256` | SHA-256 of the source bytes at the last build. |
+| `revisions` | Number of writes. Increments on every build, `retitle` and `rename`. |
+| `turn_count` | Number of turns in `timeline.jsonl` after the build. |
+| `counts` | Turn counts by class: `USER`, `AGENT`, `THOUGHT`, `TOOL`. |
+| `manifest_sha256` | Self-hash: SHA-256 of the manifest JSON with this field removed. |
+| `prev_project` | Set when `rename` moves the session to another project. |
+| `titled_from` | Previous directory names, set by `retitle`. |
+
+## Turn classes
+
+`classify()` assigns each turn one class, in this order:
+
+| Class | Rule |
+|---|---|
+| `TOOL` | `kind` contains `tool`, or `role` is `tool`. |
+| `THOUGHT` | `kind` contains `reason` or `think`. |
+| `USER` | `role` is `user`, or `kind` is `human`. |
+| `AGENT` | `role` is `assistant`, or `kind` is `ai`. |
+| `OTHER` | Everything else. Kept in `timeline.jsonl`, omitted from the tables in `HANDOFF.md`. |
+
+Turn text is taken from `text`, then `content`, then `parts[].text`.
+
+## Accepted input
+
+A source file ending in `.jsonl` is read line by line. Each line is parsed
+independently; a line that does not parse, or whose text is blank, is skipped. `seq` is used
+when it is a finite number, and the line index otherwise.
+
+Any other extension is parsed as text: a line matching `user:`, `human:`, `assistant:`,
+`ai:`, `system:` or `tool:` (optionally prefixed with `#`) starts a turn, and following
+lines are appended to it. The role marker decides the class. Adapters that produce either
+shape are listed in [ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
+
+If no turn parses, the build fails with exit 4.
+
+## Session id and directory name
+
+1. `--session <id>`, if given.
+2. else the `session` field of the first JSONL line, if present.
+3. else the source file name without its `.jsonl`, `.txt` or `.md` extension.
+
+The directory name replaces every character outside `[\w.-]` with `_`. `INDEX.json` is
+checked first: if a session with that id or with the same session UUID already exists, its
+project and directory name are reused, so a rebuild lands in the same place.
+
+`retitle <id-prefix> <new-name>` renames the directory to the slugified name, records the
+old name in `titled_from`, increments `revisions`, re-seals the manifest and refreshes every
+render. `rename <id-prefix> <new-project>` moves the session under another project and sets
+`prev_project`.
+
+## Revisions, watermark and idempotence
+
+Each build appends only the turns with `seq > watermark`, then sets `watermark` to the
+highest `seq` seen and increments `revisions`. A rebuild with no new turns and an unchanged
+`raw_sha256` prints `handoff: up-to-date` and writes nothing.
+
+## Provenance and verification
+
+| Value | Definition |
+|---|---|
+| `raw_sha256` | SHA-256 of the exact source bytes read. |
+| `manifest_sha256` | SHA-256 of the manifest with `manifest_sha256` removed. |
+| `provenance` block in both JSON payloads | `sources`, `raw_sha256`, `manifest_sha256`, `revision`, `watermark`, `total_turns`. |
+
+```
+node tools/handoff.mjs verify <id-prefix>
+```
+
+recomputes the manifest hash, requires `timeline.jsonl` to exist, compares its line count
+with `turn_count`, and parses `HANDOFF.llm.json`. It prints `PASS <id> [...]` and exits 0, or
+`FAIL <id>: ...` and exits 1. Exit 2 is a usage error, 3 an ambiguous prefix, 4 no match.
+
+## Payload schemas
+
+`schemas/handoff.schema.json` is the portable handoff payload contract, version `1.0`: a
+single JSON object with required keys `schema_version`, `handoff_id`, `mission_id`,
+`task_id`, `created_at`, `updated_at`, `source`, `state` and `next_action`, and optional
+blocks for capabilities, permissions, checkpoint, artifacts, evidence, decisions, errors and
+the next action.
+
+The engine does not emit that payload. Its own outputs are the session files listed above,
+and the JSON it writes is validated by consumption, not by that schema. The schema is the
+interchange contract for a consumer that wants a single structured document.

package/docs/INSTALL.md

@@ -0,0 +1,179 @@
+---
+title: Installation
+---
+
+# Installation
+
+agent-handoff turns a working session into a portable handoff folder, and verifies that folder
+later. It is a Node.js command-line skill with no runtime dependencies.
+
+## Requirements
+
+| Requirement | Notes |
+|---|---|
+| Node.js >= 18.0.0 | The engine uses ES modules and `node:fs`. |
+| `unzip` | Only needed to extract a release archive by hand. |
+| No network at run time | The engine never makes a network call. |
+
+## Quick start
+
+```bash
+npx agents-handoff
+```
+
+The installer copies the skill files into the resolved global root, then reports how many files
+it copied. Confirm the installation:
+
+```bash
+node "<install-path>/tools/handoff.mjs" config
+```
+
+That prints the handoff root the engine will use:
+
+```
+handoff: config root=<dir>
+handoff: config source=default
+handoff: config file=none
+handoff: config schema=<dir>/handoff.config.schema.json
+```
+
+## Where a global install goes
+
+`--location global` does not point at a fixed directory. The installer searches for a store and
+reports the reason it chose one. The order is:
+
+| # | Condition | Result |
+|---|---|---|
+| 1 | `AGENT_HANDOFF_GLOBAL_DIR` is set | that directory |
+| 2 | A skill store already holds an `agent-handoff` install | the newest such location |
+| 3 | `~/.agents/skills` exists | `~/.agents/skills` |
+| 4 | A skill store exists | its first account-skill root |
+| 5 | Nothing found | the default store, created on install |
+
+An account-skill store keeps skills two identifier levels below the store itself:
+
+```
+<store>/<account-id>/<profile-id>/agent-handoff/
+```
+
+`<store>` is `%APPDATA%\<client>\account-skills` on Windows, and `~/.<client>/account-skills` or
+`~/.config/<client>/account-skills` on macOS and Linux, for whichever desktop client keeps
+skills there. The installer searches every store it can find and never assumes one of them.
+
+Inspect the decision before installing anything:
+
+```bash
+npx agents-handoff where
+```
+
+```
+Global install root: <dir>
+  chosen because: <reason>
+  override with: AGENT_HANDOFF_GLOBAL_DIR=<dir> or --path <dir>
+```
+
+`--list` shows the resolved root, the local location, every candidate root, the harness skills
+home, and — inside a git repository — the project location. Each installed location is printed
+with its version and the number of manifest files present.
+
+## Locations
+
+| Location | Target directory |
+|---|---|
+| `global` (default) | `<resolved global root>/agent-handoff` |
+| `local` | `./local/skills/agent-handoff` |
+| `project` | `./skills/agent-handoff` |
+| `--path <dir>` | exactly `<dir>` |
+
+## Options
+
+| Option | Default | Effect |
+|---|---|---|
+| `--location <global\|local\|project>` | `global` | Which location to install, update, remove or verify. |
+| `--path <dir>` | none | Use this directory instead of a resolved location. |
+| `--version <v>` | `latest` | Request a version. Confirm what landed with `--verify`, which prints the installed version. |
+| `--force`, `-f` | off | Skip confirmations and overwrite an existing installation. |
+| `--help`, `-h` | — | Print the installer usage text. |
+
+The installer accepts both bare verbs and flag forms: `install`/`--install`, `update`/`--update`,
+`remove`/`--remove`, `verify`/`--verify`, `list`/`--list`.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `install`, `i` (default) | Copy the skill files to the target. |
+| `update`, `u` | Reinstall over an existing installation. See [UPGRADE.md](UPGRADE.md). |
+| `remove`, `rm` | Remove the installation. See [UNINSTALL.md](UNINSTALL.md). |
+| `verify`, `v` | Check every manifest file, the skill metadata, and that the engine runs. |
+| `list`, `ls` | List installed locations with version and manifest file count. |
+| `where` | Print the global root and why it was chosen. |
+
+## Verify an installation
+
+```bash
+npx agents-handoff --verify
+```
+
+Verification runs three kinds of check:
+
+1. every file named in the installer manifest exists in the target;
+2. `SKILL.md` declares both `name` and `version`;
+3. `node tools/handoff.mjs config` exits 0 and prints the `handoff: config root=` marker — this
+   exercises the engine's module graph, so a missing module fails here.
+
+Each check is printed with a pass or fail mark. On success the installer also prints the
+installed location and version; on failure it exits non-zero and tells you to reinstall.
+
+There is no `--verbose` flag.
+
+## Installing again
+
+Installing over an existing installation does nothing by default when the requested version is
+`latest`: the installer reports the version already present, then stops. It tells you to use
+`--update` to upgrade, or `--force` to reinstall the same files.
+
+## Manual installation
+
+Use the release archive when you cannot run `npx`.
+
+1. Download the archive from the repository releases page: `agent-handoff-latest.zip`, or
+   `agent-handoff-v<version>.zip` for a pinned version.
+2. Extract it into the target directory with `unzip`.
+3. Confirm the engine runs: `node "<target>/tools/handoff.mjs" config`.
+
+A complete installation contains `SKILL.md`, `skill.json`, the manifest JSON files,
+`tools/` (the engine and its runtime), `tools/lib/`, `schemas/`, `refs/`, `templates/`, `docs/`,
+and `tests/`. That list is not a description: it is the installer's manifest, and a run that
+cannot resolve any entry fails rather than reporting an incomplete installation as a success.
+
+## Handoff storage is separate
+
+Two environment variables decide two different things, and they are not interchangeable:
+
+| Variable | Decides |
+|---|---|
+| `AGENT_HANDOFF_GLOBAL_DIR` | Where the installer puts the skill. |
+| `HANDOFFS_ROOT` | Where the engine stores handoff data. |
+
+By default the engine stores handoff data under its own root, inside the installation. Set
+`HANDOFFS_ROOT` when you want handoffs somewhere else, for example in a versioned directory.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `Cannot write to <dir>` | The target is not writable. Pick another location with `--path`, or fix permissions. |
+| `Not installed at <dir>` | `update` and `verify` require an existing installation. Run `install` first. |
+| `Incomplete install: <n> of <m> file(s) missing — …` | The tree the installer reads from is not a complete one. Install from a fresh clone, or from a freshly downloaded archive. |
+| `no published release found — fetching the main branch` | Not an error: `--version latest` found no release object, so the archive of `main` is used instead. Pass `--version <x>` to install a released tag. |
+| `Cannot extract the archive (tar exited …)` | `tar` is missing, or the download did not arrive intact. The message prints the `curl` and `tar` commands that do the same job by hand. |
+| The wrong root was chosen | Run `where` to see the reason, then set `AGENT_HANDOFF_GLOBAL_DIR` or pass `--path`. |
+| `remove` did nothing | Removal asks for confirmation, and refuses in a non-interactive shell. Pass `--force`. |
+| Verification fails | The output names the failing check. Fix it, or reinstall with `--force`. |
+
+## See also
+
+- [UPGRADE.md](UPGRADE.md)
+- [UNINSTALL.md](UNINSTALL.md)
+- [../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md)

package/docs/INTEGRATION.md

@@ -0,0 +1,188 @@
+---
+title: Integrating agent-handoff
+---
+
+# Integrating agent-handoff
+
+The engine is a command-line program with a file contract. There is no daemon, no network
+call and no database. Integration means three things: getting a transcript into the canonical
+input shape, running the engine, and reading the artifacts it writes.
+
+- Put a transcript in the canonical shape: [Input contract](#input-contract).
+- Run it: [Build a handoff](#build-a-handoff) and [Exit codes](#exit-codes).
+- Read the result: [Output artifacts](#output-artifacts) and [Manifest fields](#manifest-fields).
+
+## Input contract
+
+Every input line is one JSON object (JSONL). Any program that can write JSONL can feed the
+engine; no client is required.
+
+```json
+{"seq":0,"ts":"1787669764492","harness":"dsh","source":"<origin path>",
+ "session":"<id>","thread":"<project/thread>","role":"user|assistant|system|tool",
+ "kind":"<free-form: reasoning|tool_use|text>","text":"<message body>"}
+```
+
+| Field | Used for | Notes |
+|---|---|---|
+| `seq` | ordering, watermark | Falls back to the line index when absent or non-numeric. |
+| `ts` | timeline ordering | `timestamp` is accepted as an alias. |
+| `role` | turn class | `user`, `assistant`, `system`, `tool`. |
+| `kind` | turn class refinement | `tool_use` → TOOL, `reasoning`/`thinking` → THOUGHT. |
+| `text` | the turn body | `content` and `parts[].text` are accepted as aliases. |
+| `session` | handoff id | Used when `--session` is not passed. |
+| `thread` | project inference | A `--tag--` inside the thread name is read as the project. |
+| `harness` | provenance | Not read from the line. Set it with `--harness`; otherwise it is `unknown`. |
+| `source` | provenance | Not read from the line. `source_paths` records the file given to `--source`. |
+
+`harness` and `source` are carried for whatever reads the file later. The engine itself reads
+`seq`, `ts`, `role`, `kind` and `text`, plus `session` and `thread` from the first line.
+
+Turn classification order (`classify()` in [handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs)):
+
+1. `kind` contains `tool`, or `role` is `tool` → **TOOL**
+2. `kind` contains `reason` or `think` → **THOUGHT**
+3. `role` is `user`, or `kind` is `human` → **USER**
+4. `role` is `assistant`, or `kind` is `ai` → **AGENT**
+5. anything else → **OTHER**
+
+A line whose body is empty after that mapping is skipped. A file whose name ends in `.jsonl`
+is parsed as JSONL; every other file is parsed as text, using role markers:
+
+```
+user: what needs to happen next
+assistant: the plan is in refs/plan.md
+```
+
+The marker is `user|human|assistant|ai|system|tool`, optionally prefixed by `#` and followed
+by `:` or `>`. Lines after a marker are appended to that turn until the next marker. A
+`system:` line becomes OTHER, so it stays in the record without appearing as dialogue.
+
+If no usable turn is parsed, the build fails with exit 4 rather than writing an empty handoff.
+
+## Build a handoff
+
+```bash
+node tools/handoff.mjs build --source transcript.jsonl \
+  --session my-session --harness claude-code --model <name> \
+  --project my-project --objective "what this session was for"
+```
+
+| Flag | Effect |
+|---|---|
+| `--source <file>` | The transcript to ingest. Required. |
+| `--session <id>` | Handoff id. Default: the `session` field, else the file name. |
+| `--harness <name>` | Provenance label. Default `unknown`; the engine reads no harness field. |
+| `--model <name>` | Provenance label. Stored, never invented. |
+| `--project <name>` | Project group. Default: config, then the `--tag--` in the thread, then the harness. |
+| `--objective <text>` | Overrides the objective taken from the transcript. |
+| `--force-harness` | Rewrite an existing harness value. Without it, a set value is kept. |
+| `--force-model` | Rewrite an existing model value. Without it, a set value is kept. |
+
+`node tools/handoff.mjs --handoff --source transcript.jsonl` is an alias of `build`.
+
+A rebuild of the same session is incremental: only turns above the manifest watermark are
+appended, and a source whose bytes and watermark are unchanged prints `up-to-date` and writes
+nothing.
+
+## Where handoffs are stored
+
+The root is resolved by one module, [tools/lib/handoff-root.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/lib/handoff-root.mjs),
+in this order:
+
+| # | Source | Detail |
+|---|---|---|
+| 1 | `HANDOFFS_ROOT` environment variable | Always wins. This is what makes a CI run hermetic. |
+| 2 | `handoff.config.json` | Found by walking up from the current directory. |
+| 3 | a `handoffs/` directory | Found by walking up from the current directory. |
+| 4 | the skill directory | Final fallback when nothing else exists. |
+
+Inside a config, `storage.path` beats `handoff_dir`, and a relative `handoff_dir` resolves
+against the config's own directory. The walk is bounded to ten levels. A config file that is
+present but invalid fails the run with exit 2 — it is never ignored, because falling back
+would write to a different store than the one configured.
+
+`node tools/handoff.mjs config` prints the resolved root, the source that decided it, the
+config path, the schema path, the project name and whether cross-linking is on.
+
+## Output artifacts
+
+```
+<root>/
+├── INDEX.json                        # rebuilt from every manifest
+├── projects/<project>/
+│   ├── PROJECT.md                    # project name, session list
+│   └── <session>/
+│       ├── HANDOFF.md                # the brief a human or agent reads
+│       ├── HANDOFF.summary.json      # compact payload (schema 2.0.0-summary)
+│       ├── HANDOFF.llm.json          # full payload (schema 2.0.0)
+│       ├── timeline.jsonl            # append-only, one turn per line
+│       ├── TOOLS.md                  # every tool call, verbatim
+│       └── manifest.json             # provenance and counters
+└── links/<other-project>.md          # cross-project relation notes
+```
+
+`TOOLS.md` is the fidelity tier: it carries each tool call in full. The table inside
+`HANDOFF.md` is a digest of the same turns.
+
+## Manifest fields
+
+| Field | Meaning |
+|---|---|
+| `session`, `project`, `harness`, `model` | Identity and provenance. |
+| `created_at`, `updated_at` | First write, last write. |
+| `source_paths` | Every source file ingested for this session. |
+| `watermark` | Highest ingested `seq`. Everything below it is already in the timeline. |
+| `raw_sha256` | Hash of the source bytes at the last build. |
+| `revisions` | Build count for this session. |
+| `turn_count` | Lines in `timeline.jsonl`. |
+| `counts` | Turn count per class: USER, AGENT, THOUGHT, TOOL. |
+| `manifest_sha256` | Hash of the manifest without this field. |
+
+## Verify a handoff
+
+```bash
+node tools/handoff.mjs list                 # all sessions
+node tools/handoff.mjs list <project>       # one project
+node tools/handoff.mjs show <id-prefix>     # print the brief
+node tools/handoff.mjs verify <id-prefix>   # manifest sha, turn count, payload parses
+```
+
+`verify` recomputes the manifest hash, compares the timeline line count against
+`turn_count`, and parses `HANDOFF.llm.json`. It prints `PASS <id> [...]` or fails with exit 1
+and the first broken check. See [PROVENANCE.md](PROVENANCE.md) for what the hash chain does
+and does not detect.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | Integrity failure: tampered manifest, unparsable manifest, unexpected error. |
+| 2 | Usage or configuration error: missing `--source`, missing argument, invalid config. |
+| 3 | Ambiguous id prefix — more than one session matched. |
+| 4 | No usable turns, no handoffs, or no session matching the prefix. |
+
+## CI recipe
+
+```yaml
+- name: Build and verify the handoff
+  env:
+    HANDOFFS_ROOT: ${{ github.workspace }}/.handoffs
+  run: |
+    node skills/agent-handoff/tools/handoff.mjs build \
+      --source exported-transcript.jsonl --project ci --harness generic
+    node skills/agent-handoff/tools/handoff.mjs verify "$(ls .handoffs/projects/ci | head -1)"
+```
+
+`HANDOFFS_ROOT` keeps the run off any configured store, and `verify` returns the exit code a
+pipeline can gate on.
+
+## Limits
+
+- Filesystem only: nothing is uploaded, and no network call is made.
+- No watcher: a build happens when it is invoked. See [LEVEL4.md](LEVEL4.md) for the layer
+  that probes for staleness and runs the build for you.
+- The engine reads whatever the transcript contains, including secrets. Redaction is the
+  caller's job. See [SECURITY.md](SECURITY.md).
+- Adapter routes for common session stores: [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).