agents-handoff 0.0.0-stage → 2.0.2

package/docs/LEVEL4.md

@@ -0,0 +1,202 @@
+---
+title: Level 4 — the dynamic runtime layer
+---
+
+# Level 4 — the dynamic runtime layer
+
+The engine ([handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs)) is passive: something has to invoke it. The
+runtime layer is [tools/agent-handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs), which acts on the
+state of the store — it probes for staleness, checks a handoff against a contract, composes
+sessions, imports other stores and maintains the index.
+
+Every mutating command takes a lock, so two runs cannot capture or merge the same session at
+once. Locks live in `<root>/.locks/` and are named after a hash of the operation target.
+
+```bash
+node tools/agent-handoff.mjs <command> [args]
+```
+
+| Command | Purpose |
+|---|---|
+| `auto --source <file>` | Build only when the source is newer than the stored manifest. |
+| `verify-gate <id-prefix>` | Five checks: sha, counts, payload, contract, evidence. |
+| `promote <id-prefix>` | Stamp promotion metadata on a handoff's manifest. |
+| `merge <a> <b>` | Compose two sessions of one project into one handoff. |
+| `dispatch <id-prefix> --task <objective>` | Hand the continuation to a worker (Level 5). |
+| `federated-merge --from <root>` | Import sessions from another store root. |
+| `self-improve` | Collect brief shortfalls into a rules candidate file. |
+| `index` | Rebuild `INDEX.json` and report stale sessions. |
+
+An unknown command prints that list and exits 2.
+
+## `auto` — self-triggering capture
+
+```bash
+node tools/agent-handoff.mjs auto --source transcript.jsonl \
+  [--session <id>] [--harness <name>] [--project <name>] [--min-fresh-ms <n>]
+```
+
+`--source` is required. Two gates run before any build:
+
+1. **Freshness.** If the session's manifest exists and `source_mtime - manifest.updated_at`
+   is below `--min-fresh-ms` (default 60000), nothing is built and the command prints
+   `{"action":"skip-fresh"}`.
+2. **Lock.** A capture already in flight for the same project and session exits 3.
+
+It then runs the engine's `build` and prints `{"action":"captured",...}`. A missing source
+file exits 2.
+
+## `verify-gate` — the evidence gate
+
+```bash
+node tools/agent-handoff.mjs verify-gate <id-prefix>
+```
+
+| Check | Passes when |
+|---|---|
+| `sha` | `manifest_sha256` equals the hash of the manifest without that field. |
+| `counts` | Lines in `timeline.jsonl` equal `turn_count`. |
+| `payload` | `HANDOFF.llm.json` parses as JSON. |
+| `contract` | `HANDOFF.md` contains all seven contract fields, each at the start of a line. |
+| `evidence` | Not `RESULT: DONE` with no `EVIDENCE:` line. |
+
+The contract fields are `RESULT`, `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`,
+`RISKS`, `FOLLOW_UP`. The verdict is `VERIFIED` when every check is `PASS`, otherwise
+`REJECTED`, printed as JSON with the per-check table.
+
+**The command exits 0 in both cases.** A caller must read `ok` or `verdict` from the JSON —
+the exit code alone does not report a rejection. Only a bad prefix (exit 3) or a missing
+manifest is visible as a nonzero status.
+
+## `promote` — stamping verified work
+
+```bash
+node tools/agent-handoff.mjs promote <id-prefix>
+```
+
+The manifest is backed up to `manifest.json.bak`, the gate above is run and its verdict is
+printed, and the manifest is then stamped with `promoted_at` and `promoted_by` and re-hashed.
+
+Two honest caveats:
+
+- The gate result is **printed, not enforced**. The stamp is written even when the verdict is
+  `REJECTED`; a caller that wants a gate must run `verify-gate` and branch on `verdict`
+  before calling `promote`.
+- Promotion is local. It writes one flag pair into one manifest file; it contacts no external
+  system and publishes nothing.
+
+## `merge` — composing two sessions
+
+```bash
+node tools/agent-handoff.mjs merge <id-prefix-a> <id-prefix-b>
+```
+
+Timelines are concatenated and sorted by `ts`, and written to a new session directory named
+`<a>+merge+<b>` under the first project. The merged manifest records `harness: "merged"`,
+`merged_from: [a, b]` and a fresh `raw_sha256` over the joined timeline. A note is appended
+to `links/<project-b>.md` with a `<!-- merged:<id> -->` marker, so a re-run does not duplicate
+it.
+
+A merged session has no `HANDOFF.md`, no payload and no `TOOLS.md`, so it fails `verify-gate`
+on `contract` and `payload` until a brief is written for it, and `index` reports it as stale.
+
+## `federated-merge` — importing another store root
+
+```bash
+node tools/agent-handoff.mjs federated-merge --from <remote-root> [--from <root> ...] [--dry-run]
+```
+
+Each remote root is expected to have the same `projects/<project>/<session>/` layout. A
+session is imported when its `manifest_sha256` differs from the local copy, or when no local
+copy exists; identical sessions are counted as skipped, so re-running imports only what
+changed. `--dry-run` lists the actions without writing.
+
+On import: an existing local manifest is backed up to `manifest.json.bak-federated`, the
+session directory is copied, and `federated_from` and `federated_at` are stamped on the
+canonical manifest, which is then re-hashed. Every imported session is verified with the
+engine's `verify` afterwards, and the index is rebuilt. Per-session failures are listed in
+the `failed` array rather than aborting the run. A root without a `projects/` directory is
+recorded as failed, and a missing `--from` exits 2.
+
+## `self-improve` — brief shortfalls
+
+```bash
+node tools/agent-handoff.mjs self-improve
+```
+
+Every session is scanned, and a session with 40 or more USER+AGENT turns whose `HANDOFF.md`
+is shorter than 800 characters is reported as a candidate. The output is written to
+`docs/self-improve-candidates.json` inside the skill directory — deliberately skill-relative,
+so a configured store never collects rule candidates. The file lists counts, not content.
+
+## `index` — the store index
+
+```bash
+node tools/agent-handoff.mjs index
+```
+
+Rebuilds `<root>/INDEX.json` from the manifests, with one entry per session (`id`, `uuid`,
+`project`, `harness`, `turns`, `revisions`, `updated`, `manifest_sha256`), and reports
+sessions that have a manifest but no `HANDOFF.md`.
+
+## Bounded execution — `runtime-engine.mjs`
+
+[tools/runtime-engine.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/runtime-engine.mjs) is the command-execution half of the
+runtime: every operation is evaluated against `permission-policy.json` **before** it runs, and
+a denied operation is recorded but never executed.
+
+```bash
+node tools/runtime-engine.mjs evaluate --risk R0..R4 [--target <path>] [--json]
+node tools/runtime-engine.mjs run --risk R0|R1 --op read --target <path>
+node tools/runtime-engine.mjs run --risk R1 --op spawn --args "<node args>"
+node tools/runtime-engine.mjs policy
+node tools/runtime-engine.mjs job --session <s> --steps <n> [--fail-at <k>] [--json]
+node tools/runtime-engine.mjs resume --session <s> --steps <n> [--json]
+node tools/runtime-engine.mjs status --session <s> [--json]
+```
+
+| Verdict | Meaning |
+|---|---|
+| `ALLOWED` | The grant for the risk class's level is `allow`. |
+| `DENIED` | Refused: an explicit denial, a personal-data path, an unknown risk, or an unknown grant. |
+| `NEEDS_AUTH` | The grant is `needs_auth`; the operation waits for authorization and does not run. |
+
+Targets are classified in a fixed order: an explicit denial first, then the engine's own
+state directory, then the approved workspaces, then the broad personal-data roots, then
+system read-only roots, otherwise external. A personal-data or denied path is refused at any
+risk. A read-only level is allowed inside an approved workspace or a system path; every other
+level requires an approved workspace. Levels, risk classes and grants are documented in
+[PERMISSIONS.md](PERMISSIONS.md).
+
+The `spawn` operation is bounded: it runs the local node binary with the given arguments, the
+working directory pinned to the repository, a 15000 ms timeout, and the output captured and
+hashed rather than streamed. Each decision — allowed, refused or failed — is written to
+`<state>/executions/<id>.json` with `enforced_before_execution: true`.
+
+Checkpoints make a job resumable from disk alone: after each step, `<state>/checkpoints/<session>.json`
+is rewritten with a sha256 seal, and the step is appended to `<state>/jobs/<session>/work.log`.
+Each step is permission-gated at `R1`. `--fail-at <k>` simulates an abrupt kill before step
+`k` executes, leaving the durable state at `k-1`.
+
+The state directory is `<repo>/.agent-handoff`, or `AGENT_HANDOFF_STATE_DIR` when set.
+
+| Code | Meaning |
+|---|---|
+| 0 | Allowed, executed, or completed. |
+| 1 | Execution error, or the child produced no exit code. |
+| 2 | Usage or configuration error. |
+| 3 | Denied. |
+| 4 | Needs authorization, or no checkpoint to resume from. |
+| 5 | Checkpoint corrupt, or its integrity seal does not match. |
+| 137 | Simulated abrupt kill. |
+| other | The captured exit code of the spawned child. |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | A mutating command failed; the lock was released. |
+| 2 | Usage or configuration error, including an unresolvable store root. |
+| 3 | A lock is held, an id prefix is ambiguous, or a referenced path is missing. |
+| 4 | No session matches the prefix. |

package/docs/LEVEL5.md

@@ -0,0 +1,96 @@
+---
+title: Level 5 — collaborative dispatch
+---
+
+# Level 5 — collaborative dispatch
+
+A handoff normally ends as files on disk, and something reads it later. The dispatch command
+lets a handoff whose own record is complete hand its continuation to a worker through a local
+broker, instead of waiting for a reader.
+
+```bash
+node tools/agent-handoff.mjs dispatch <id-prefix> --task "<objective>" \
+  [--role <role>] [--parent <parentTaskId>] [--broker <broker-root>] [--live]
+```
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `<id-prefix>` | required | The handoff that is handing off its continuation. |
+| `--task <objective>` | required | What the worker is being asked to do. |
+| `--role <role>` | `implementation-agent` | The role the request is addressed to. |
+| `--parent <parentTaskId>` | `handoff:<id>` | The parent the request is attached to. |
+| `--broker <root>` | none | Root of the broker program. |
+| `--live` | off | Enqueue the request instead of printing it. |
+
+## The gate
+
+Dispatch refuses to hand over work from a handoff that is not internally complete. Before
+anything is built, `HANDOFF.md` is read and two things are required:
+
+1. all seven contract fields are present, each at the start of a line — `RESULT`,
+   `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`, `RISKS`, `FOLLOW_UP`;
+2. a record that says `RESULT: DONE` also carries an `EVIDENCE:` line.
+
+When either fails, the command prints the refusal and exits 1:
+
+```json
+{ "ok": false, "status": "GATE_REJECTED", "session": "<id>",
+  "reason": "handoff fails the evidence gate (missing contract fields: ...; DONE-without-EVIDENCE=true)" }
+```
+
+The gate reads `HANDOFF.md` only. It does not recompute the manifest hash, check the timeline
+count, or parse the payload — those are `verify-gate` checks. A handoff can therefore pass the
+dispatch gate while failing `verify-gate` on `sha`, `counts` or `payload`; run
+`verify-gate <id>` first when that matters.
+
+## The envelope
+
+| Field | Value |
+|---|---|
+| `from_handoff` | The session id the request came from. |
+| `project` | The project that session belongs to. |
+| `role` | `--role`. |
+| `parentTaskId` | `--parent`, by default `handoff:<id>`. |
+| `objective` | `--task`. |
+| `evidence` | The session's `manifest_sha256`, so the receiver can check what it was given. |
+| `evidenceRequirements` | `["verified-handoff"]`. |
+| `dispatchedAt` | Timestamp of the envelope. |
+| `broker_mode` | `live` or `dry-run`. |
+| `handoff_dir` | Absolute path of the session directory. |
+
+## States
+
+| State | When | Exit |
+|---|---|---|
+| `GATE_REJECTED` | The contract or evidence check failed. Nothing is sent. | 1 |
+| `DRY_RUN` | `--live` was not passed, or no broker root was given. The envelope is printed. | 0 |
+| `DISPATCHED` | `--live` and a broker root were given and the broker answered. | 0 |
+
+`DRY_RUN` is the default. It prints the envelope and one line of advice: either re-run with
+`--live`, or pass a broker root and `--live`. A dry run writes nothing and starts no process.
+
+## Live dispatch
+
+With both `--live` and a broker root, the command requires
+`<broker-root>/runtime/request-child-worker.mjs`; if that file is missing it exits 3 and
+sends nothing. It then runs:
+
+```
+node <broker-root>/runtime/request-child-worker.mjs <broker-root> <parentTaskId> <role> <task> handoff:<id>
+```
+
+The broker's stdout is parsed as JSON and returned as `broker_output` alongside the envelope.
+A broker that fails to start, or that prints something that is not JSON, exits 1.
+
+Two limits worth knowing:
+
+- **No dedupe and no lock.** Unlike `auto`, `merge` and `promote`, dispatch takes no lock and
+  keeps no record of a previous dispatch. Running a live dispatch twice enqueues the request
+  twice; a caller that needs once-only delivery must guard it.
+- **The broker is a separate program.** This skill builds the envelope, checks the gate and
+  invokes the broker entry point. What the broker does with the request — how it queues it,
+  which worker picks it up, whether it dedupes — is not implemented or verified here.
+
+The traceability chain that does exist: `parentTaskId` defaults to `handoff:<id>`, and
+`evidence` carries the handoff's manifest hash, so a request can be traced back to the session
+directory, its manifest, and the source transcripts recorded in `source_paths`.

package/docs/PERMISSIONS.md

@@ -0,0 +1,145 @@
+---
+title: Permissions
+---
+
+# Permissions
+
+The runtime layer evaluates a permission policy before it executes anything. The policy is a
+JSON file; the implementation is `tools/runtime-engine.mjs`.
+
+```
+node tools/runtime-engine.mjs run --risk R0 --op read --target tests/fixtures/minimal-transcript.jsonl
+```
+
+Every operation is evaluated first and executed only on an `ALLOWED` verdict. A `DENIED` or
+`NEEDS_AUTH` operation does not run, and its decision record is written with
+`enforced_before_execution: true`.
+
+## The policy file
+
+`permission-policy.json` in the skill root is the default. Every runtime verb accepts
+`--policy <path>`; a relative path resolves against the skill root.
+
+| Key | Shipped value |
+|---|---|
+| `approved_workspaces` | `.` (the skill root), `repo-upstream`, `.agent-handoff`, `.context` |
+| `system_read_only_roots` | `C:\Windows`, `C:\Program Files`, `C:\Program Files (x86)` |
+| `personal_data_roots` | `C:\Users` |
+| `denied_roots` | empty |
+| `grants` | `DISCOVERY_ONLY` allow, `READ_ONLY` allow, `WORKSPACE_WRITE` allow, `EXTERNAL_EFFECT` needs_auth, `DESTRUCTIVE` needs_auth, `IRREVERSIBLE` needs_auth |
+| `risk_to_level` | `R0` → `READ_ONLY`, `R1` → `WORKSPACE_WRITE`, `R2` → `EXTERNAL_EFFECT`, `R3` → `DESTRUCTIVE`, `R4` → `IRREVERSIBLE` |
+
+The shipped roots are Windows-shaped. On macOS and Linux they match no existing path, so
+anything outside `approved_workspaces` classifies as `EXTERNAL_PATH`. Set platform-appropriate
+roots before relying on classification outside the workspace.
+
+A policy that is missing, is not valid JSON, or lacks `grants` or `risk_to_level` is a
+configuration error: exit 2, nothing executed.
+
+## Levels and grants
+
+| Level | Grant in the shipped policy | Meaning |
+|---|---|---|
+| `DISCOVERY_ONLY` | allow | Read metadata, list, inspect. |
+| `READ_ONLY` | allow | Read files and state. |
+| `WORKSPACE_WRITE` | allow | Write inside an approved workspace. |
+| `EXTERNAL_EFFECT` | needs_auth | Network or external service. |
+| `DESTRUCTIVE` | needs_auth | Delete or overwrite. |
+| `IRREVERSIBLE` | needs_auth | Operations that cannot be undone. |
+
+A grant value of `allow` yields `ALLOWED`, `needs_auth` yields `NEEDS_AUTH`, and any other
+value yields `DENIED`. Unknown risk classes are denied, not allowed.
+
+Because grants are keyed by level rather than by operation, an operator can permit every
+`EXTERNAL_EFFECT` operation, or require authorization for every workspace write, with one
+edit.
+
+## Target classification
+
+`classify()` tests the target against the policy roots, most specific rule first:
+
+| Order | Class | Source |
+|---|---|---|
+| 1 | `DENIED_ROOT` | `denied_roots` |
+| 2 | `APPROVED_WORKSPACE` | the runtime's own state directory, wherever `AGENT_HANDOFF_STATE_DIR` points |
+| 3 | `APPROVED_WORKSPACE` | `approved_workspaces` |
+| 4 | `PERSONAL_DATA_PATH` | `personal_data_roots` |
+| 5 | `SYSTEM_PATH` | `system_read_only_roots` |
+| 6 | `EXTERNAL_PATH` | nothing matched |
+
+Rule 3 must precede rule 4. A globally installed skill lives under the user's home
+directory, which is normally inside a personal-data root; if the broad root won, every
+operation inside a real installation would be denied at any risk.
+
+## Verdicts
+
+| Target class | `READ_ONLY` / `DISCOVERY_ONLY` | `WORKSPACE_WRITE` and above |
+|---|---|---|
+| `APPROVED_WORKSPACE` | allowed | grant applies |
+| `SYSTEM_PATH` | allowed | denied |
+| `PERSONAL_DATA_PATH` | denied | denied |
+| `DENIED_ROOT` | denied | denied |
+| `EXTERNAL_PATH` | denied | denied |
+
+Personal data and explicitly denied roots are denied at every risk level. Writes and effects
+are allowed only inside an approved workspace.
+
+| Verdict | Exit code |
+|---|---|
+| `ALLOWED` | 0 |
+| `DENIED` | 3 |
+| `NEEDS_AUTH` | 4 |
+| usage or configuration error | 2 |
+
+## What the gateway covers
+
+| Operation | How it is gated |
+|---|---|
+| `run --op read --target <path>` | Evaluated against the target. On `ALLOWED` the file is read and the record carries `bytes` and `content_sha256`. |
+| `run --op spawn --args "<node args>"` | Evaluated against the workspace root. The child is the running Node binary with the given arguments, working directory pinned to the skill root, 15-second timeout, stdout and stderr digested into the record, child exit code propagated. |
+| `job` / `resume` steps | Each step is evaluated at `R1` against the job state directory before the work log is appended. |
+| `evaluate` | Decides and prints; executes nothing. |
+| `policy` | Prints the loaded policy and exits 0. |
+
+Every decision, allowed or denied, is written to
+`<state dir>/executions/<timestamp>-<pid>-<random>.json`. The state directory is
+`AGENT_HANDOFF_STATE_DIR` when set, and `<skill>/.agent-handoff` otherwise; it is treated as
+an approved workspace wherever it points.
+
+## Declared but not enforced
+
+- `DISCOVERY_ONLY` has a grant, but the shipped `risk_to_level` maps no risk to it, so no
+  `--risk` value reaches that level. It becomes reachable only if a policy maps a risk class
+  to it.
+- The policy gates the runtime engine only. `tools/handoff.mjs`, the capability registry and
+  the installer do not consult it: the handoff engine writes to its resolved store without a
+  permission decision, and the registry probes are classified by their own declarations.
+- There is no interactive approval prompt. `NEEDS_AUTH` reports that authorization is
+  required; granting it means changing the policy, and the decision is recorded either way.
+
+## Changing the policy
+
+1. Decide the level. Operations are keyed by risk class (`R0`–`R4`), which maps to a level.
+2. Edit `permission-policy.json`, or write a separate policy file and pass
+   `--policy <path>`.
+3. Change `grants` to move a whole level between allow, needs-auth and denial; change
+   `risk_to_level` to reclassify a risk class; add entries to `approved_workspaces`,
+   `personal_data_roots`, `system_read_only_roots` or `denied_roots` to move a path between
+   classes.
+4. Test one decision without executing it:
+
+```
+node tools/runtime-engine.mjs evaluate --risk R2 --target README.md --json
+```
+
+5. Confirm what the runtime actually loaded:
+
+```
+node tools/runtime-engine.mjs policy --json
+```
+
+A `denied_roots` entry outranks an approved workspace, so it is the switch to use when a
+path must be off limits regardless of any other rule.
+
+See [INTEGRATION.md](INTEGRATION.md) for wiring these commands into another system, and
+[LEVEL4.md](LEVEL4.md) for the runtime verbs as a whole.

package/docs/PROVENANCE.md

@@ -0,0 +1,83 @@
+---
+title: Provenance
+---
+
+# Provenance
+
+## What this document covers
+
+Every handoff carries a hash chain that ties its rendered files to the transcript it was built from.
+This document states what is hashed, how to re-verify it, and what the check cannot prove.
+
+## The chain
+
+| Artifact | Field | Definition |
+|---|---|---|
+| Source transcript | `raw_sha256` | SHA-256 of the whole source file, read as UTF-8 at build time |
+| `manifest.json` | `manifest_sha256` | SHA-256 of `JSON.stringify(manifest)` with `manifest_sha256` removed |
+| `HANDOFF.summary.json` | `provenance.raw_sha256`, `provenance.manifest_sha256` | Copies of the two hashes above |
+| `HANDOFF.llm.json` | `provenance.manifest_sha256` | Copy of the manifest hash |
+| `HANDOFF.md` | *Provenance* section | Both hashes and the revision, rendered as text |
+
+`manifest.json` also records `source_paths` (every transcript ever merged into the session),
+`watermark` (the highest turn sequence emitted), `revisions` and `turn_count`.
+
+## Verification
+
+```bash
+node tools/handoff.mjs verify <id-prefix>
+```
+
+`verify` recomputes `manifest_sha256` from the stored manifest and compares it, then requires
+`timeline.jsonl` to exist and to hold exactly `turn_count` lines, then parses `HANDOFF.llm.json`.
+It prints one `PASS` line, or `FAIL` with the reason.
+
+| Exit | Meaning |
+|---|---|
+| 0 | All three checks passed |
+| 1 | Manifest mismatch, timeline missing, turn-count drift, or unparsable payload |
+| 2 | No prefix given |
+| 3 | Prefix matched more than one session |
+| 4 | No session matched, or no handoffs exist |
+
+## What the check detects
+
+- A stored manifest whose fields have been edited or added.
+- A truncated or padded `timeline.jsonl`, because its line count must equal `turn_count`.
+- A missing timeline.
+- A `HANDOFF.llm.json` that is no longer valid JSON.
+
+## What the check cannot detect
+
+- **Edits to unhashed renders.** `HANDOFF.md`, `HANDOFF.summary.json` and `TOOLS.md` are not hashed.
+  Their bytes can be changed freely and `verify` still passes.
+- **Timeline content edits that preserve the line count.** A rewritten turn keeps the count.
+- **Re-hashing by the editor.** The hashes are self-consistent, not signed. Anyone who edits the
+  manifest can recompute `manifest_sha256` and produce a folder that verifies clean. There is no key
+  material, no signature and no external trust anchor.
+- **Anything outside the session folder.** `PROJECT.md`, `INDEX.json` and `links/*.md` carry no
+  hashes.
+
+Treat the chain as damage detection, not as authentication.
+
+## Update instead of recreate
+
+Re-running `build` on the same session id merges rather than duplicates: turns with a sequence above
+`watermark` are appended to `timeline.jsonl`, `revisions` increments, and the manifest hash is
+recomputed. If the source is unchanged and no new turns exist, the run reports `up-to-date` and
+bumps nothing. The rendered summary, payload and `HANDOFF.md` are regenerated from the full
+timeline, so a revision never mixes stale and fresh text.
+
+## Privacy note on `source_paths`
+
+A manifest records the absolute path of every transcript that fed the session. A handoff folder
+therefore contains the local paths of the machine it was built on. Review that field before sharing
+a folder outside the machine.
+
+## Repository provenance
+
+- License: MIT, see [../LICENSE](https://github.com/Alot1z/agent-handoff/blob/main/LICENSE).
+- The engine and runtime use only `node:` built-ins. No third-party source is bundled and
+  `package.json` declares no dependencies.
+- Development notes, internal plans and research material are not part of this repository and are
+  not published with it.

package/docs/SECURITY.md

@@ -0,0 +1,93 @@
+---
+title: Security
+---
+
+# Security
+
+## Scope
+
+agent-handoff reads session transcripts you point it at and writes a handoff folder to disk. It has
+no network code, no third-party dependencies, and no privileged operations. This document states
+what the tool does with data, what it refuses to do, and which guarantees it does not make.
+
+## What the tool reads
+
+| Input | How it is used |
+|---|---|
+| The file passed to `build --source` | Read as UTF-8 text and parsed into turns. A `.jsonl` file is parsed line by line; anything else is parsed with role markers. |
+| `handoff.config.json` | Walked up from the current directory and validated against `handoff.config.schema.json`. A present-but-invalid file is fatal (`exit 2`). |
+
+Adapters that read a harness session store are external to the engine. They read stores and never
+write to them. See [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
+
+## What the tool writes
+
+Under the resolved root (see [FORMAT.md](FORMAT.md)): `HANDOFF.md`, `HANDOFF.summary.json`,
+`HANDOFF.llm.json`, `timeline.jsonl`, `TOOLS.md`, `manifest.json`, and per project `PROJECT.md`,
+plus `INDEX.json` and `links/*.md`. Nothing else is written and nothing outside the root is
+modified.
+
+Writes go straight to the destination path with `fs.writeFileSync`. They are not atomic and are not
+staged through a temporary file, so an interrupted run can leave a partial file. `verify` detects
+that only indirectly — see [PROVENANCE.md](PROVENANCE.md).
+
+## Secrets
+
+The engine performs **no secret detection and no redaction**. A transcript containing a token or a
+key produces a handoff containing that token or key. There is no scanning pass, no allowlist and no
+masking.
+
+`handoff.config.example.json` lists an `exclude_from_handoff` array. Treat that as intent, not as an
+enforced control: the engine reads `storage.path`, `handoff_dir`, `project_name` and `linking` from a
+config, and does not read that array.
+
+Only hand off transcripts you have reviewed. Keep `.env` files and key material out of version
+control, and do not commit a handoff folder that quotes them.
+
+## Malicious input
+
+A transcript is data. It is never evaluated, never executed, and never interpreted as configuration
+or as a request. Concretely:
+
+- A tool call recorded in a transcript is copied verbatim as text into `TOOLS.md`. The engine does not run it.
+- A transcript cannot change the engine's arguments, the store root, or the exit code beyond a parse failure.
+- A transcript with no parsable turns stops the run (`exit 4`). Individual malformed JSONL lines are skipped.
+
+The realistic risk is not code execution but content. A handoff is a readable document that a later
+human or agent may treat as instructions, and it inherits whatever instructions the transcript
+contained. Review a handoff before handing it to another agent.
+
+## Paths and the workspace boundary
+
+The engine resolves `--source` against the current directory and writes under the resolved root. It
+performs no workspace-boundary check of its own: a path you pass is a path it uses.
+
+`permission-policy.json` declares the boundary for the runtime layer — approved workspaces,
+read-only system roots, personal-data roots, per-level grants (`READ_ONLY` and `WORKSPACE_WRITE`
+allowed; `EXTERNAL_EFFECT`, `DESTRUCTIVE` and `IRREVERSIBLE` need authorization) and the R0–R4 risk
+mapping. See [PERMISSIONS.md](PERMISSIONS.md). The handoff engine itself does not consult that file.
+
+## Guarantees that are not made
+
+- No sandboxing. No process isolation, no privilege separation. The tool runs with the permissions of the user who invoked it.
+- No encryption. Handoff files are plain text and JSON.
+- No authentication. Hashes are self-consistent, not signed — see [PROVENANCE.md](PROVENANCE.md).
+- No audit log and no system logging.
+- No secret scanning, no PII detection, no redaction.
+
+## Dependencies
+
+None. The engine and the runtime use only `node:` built-ins and require Node 18 or newer. The
+installer is a single script with no package dependencies.
+
+## Reporting a vulnerability
+
+Report it privately to the maintainer, not in a public issue. Use the repository's private
+vulnerability reporting if it is enabled, otherwise contact the maintainer directly. Include the
+command, the input, and the observed result.
+
+## Checklist before publishing a handoff folder
+
+- [ ] The transcript was reviewed and contains no credentials, tokens or personal data.
+- [ ] The handoff quotes no private path and no machine identifier.
+- [ ] `node tools/handoff.mjs verify <id-prefix>` passes for every session in the folder.