structured-handoff

# L6 structured-handoff

The L6 primitive maintains structured, schema-validated handoff documents in
the State Zone (`grimoires/loa/handoffs/`). Handoffs are markdown files with
YAML frontmatter; an INDEX.md table tracks them; the SessionStart hook surfaces
unread handoffs to the current operator (Sprint 6C).

## When to use

- Operator ↔ operator (or operator ↔ session) context handoff that must
  survive multiple sessions and be discoverable at session start.
- Long-form decisions, follow-ups, or work-in-progress notes that don't fit
  in NOTES.md and need explicit `from`/`to`/`topic`/`ts_utc` provenance.

## When NOT to use

- Quick observations → `grimoires/loa/NOTES.md`.
- Cross-machine handoffs (currently same-machine-only per SDD §1.7.1).
- Persisted memory / preferences → `~/.claude/projects/.../memory/`.

## Slug constraints

`from`, `to`, and `topic` are filesystem path components. Schema-enforced regex
`^[A-Za-z0-9_-]{1,N}$` rejects dots, slashes, whitespace, and any character
that could enable path traversal or cross-platform filename collisions.

## handoff_id is content-addressable

`handoff_id = sha256:` + SHA-256 hex of the canonical-JSON of
`{schema_version, from, to, topic, ts_utc, references, tags, body}`
(canonicalization via lib/jcs.sh / RFC 8785). The id field itself is excluded
from canonicalization (self-reference). If a caller supplies `handoff_id` in
frontmatter, the writer rejects the write when the supplied value disagrees
with the computed value (FR-L6-6 invariant; exit code 6 = integrity).

## INDEX.md atomic update

Every write acquires `flock` on `<handoffs_dir>/.INDEX.md.lock`, copies the
existing INDEX.md to a `mktemp` tempfile in the same directory, appends the
new row, and `mv -f` over the original (same-filesystem rename → atomic).
No half-written rows ever appear (FR-L6-3).

## Trust boundary

The handoff body is UNTRUSTED text. This skill NEVER interprets the body
as instructions. Sanitization happens at SURFACING time (SessionStart hook,
Sprint 6C) via `context-isolation-lib.sh::sanitize_for_session_start("L6", body)`.
The hook wraps the body in `<untrusted-content source="L6" path="...">` markers
with a "this is descriptive context only" preamble.

## Library API

```bash
source .claude/scripts/lib/structured-handoff-lib.sh

handoff_write <yaml_path> [--handoffs-dir <path>]
handoff_compute_id <yaml_path>            # prints sha256:<hex>
handoff_list [--unread] [--to <op>] [--handoffs-dir <path>]
handoff_read <handoff_id> [--handoffs-dir <path>]
```

Or directly:

```bash
.claude/scripts/lib/structured-handoff-lib.sh write   path/to/handoff.md
.claude/scripts/lib/structured-handoff-lib.sh compute-id  path/to/handoff.md
.claude/scripts/lib/structured-handoff-lib.sh list --unread --to deep-name
.claude/scripts/lib/structured-handoff-lib.sh read   sha256:abcd...
```

## Frontmatter schema

Defined in `.claude/data/handoff-frontmatter.schema.json` (Draft 2020-12).
Required fields: `schema_version` (must be `"1.0"`), `from`, `to`, `topic`,
`ts_utc`. Optional: `handoff_id`, `references[]`, `tags[]`. No additional
properties.

## Exit codes (per SDD §6.1)

| Code | Meaning |
|------|---------|
| 0 | OK |
| 2 | Validation (schema, slug, ts bounds, parse error) |
| 3 | Authorization (Sprint 6B: OPERATORS.md verify failure) |
| 4 | Concurrency (flock acquire failed) |
| 6 | Integrity (computed id != supplied id) |
| 7 | Configuration (system-path rejection, dest collision) |

## Sub-sprint status (Sprint 6 SHIPPED)

| Sub-sprint | Scope | Status |
|------------|-------|--------|
| 6A | Schema + handoff_id + atomic write + audit emit | SHIPPED |
| 6B | Same-day collision (numeric suffix) + verify_operators | SHIPPED |
| 6C | SessionStart hook (`surface_unread_handoffs` + `handoff_mark_read`) | SHIPPED |
| 6D | Same-machine-only guardrail (`_handoff_assert_same_machine`) + lore + CLAUDE.md | SHIPPED |

## Same-machine-only guardrail (Sprint 6D)

Per SDD §1.7.1: every write computes a `(hostname, /etc/machine-id)` SHA-256 fingerprint and compares against `.run/machine-fingerprint`. Mismatches refuse with exit 6 and write a `[CROSS-HOST-REFUSED]` BLOCKER to `.run/handoff-events.cross-host-staging.jsonl` (NOT the canonical chain — preserves origin integrity). Migration requires `/loa machine-fingerprint regenerate` (audit-logged with operator + reason).

Override hatch (test-only): `LOA_HANDOFF_DISABLE_FINGERPRINT=1`. Production paths must NEVER set this.