# handoff

Use this to review, check and clean up the notes your agents leave for each other before they reach shared memory.

For machines that ingest handoffs from multiple repos, copy `.brigade/handoff-sources.example.json` to `.brigade/handoff-sources.json` and list the repo roots and writer inboxes the canonical ingestor scans. `brigadestack handoff sources init` writes local handoff source coverage for Claude, Codex, OpenCode, and Hermes (flags: `--target`, `--force`, `--json`). `brigadestack handoff doctor` reports pending writer-inbox files (`.claude/memory-handoffs/`, `.codex/memory-handoffs/`, and the other configured writer inboxes) that are not covered by that local source list.

## Draft

`brigadestack handoff draft` writes a new handoff note into a selected writer inbox. One of `--content` or `--content-file` is required for the note body.

```bash
brigadestack handoff draft --target ./my-repo --inbox codex \
  --title "What changed" \
  --summary "Short note future agents should know." \
  --content "The durable note itself goes here."
```

Draft files are created with mode 0600, so only your user can read them until the ingestor moves them. Related flags: `--workspace` points at the memory workspace that holds `memory/cards` and bootstrap documents (default `--target`), and `--expected-sha` supplies the SHA-256 of the current card for `update-card` drafts (looked up in `--workspace` when omitted). `handoff lint` also accepts `--workspace`.

The agent decides when to write a handoff, following the AGENTS.md that BrigadeStack generates. It writes one only when the session produced knowledge that the repo, git history, or an existing card does not already hold: a root cause, a decision with its reason, a new operational fact, or a stated preference. If nothing qualifies, it writes no file and ends the session with one line:

```text
Nothing durable: <reason>
```

If the draft is written but fails lint, the command says so clearly and reports the kept path and the next step instead of failing silently.

## Migrate

`brigadestack handoff migrate` converts near-miss homegrown handoff notes (loose `- Type:` style metadata) into the BrigadeStack template through the standard draft renderer, so existing notes stop failing lint identically to garbage.

```bash
brigadestack handoff migrate --target .
brigadestack handoff migrate --target . --apply
```

Dry-run by default. `--apply` rewrites convertible notes, preserves the originals under `migrated-originals/`, verifies the result passes lint, and records a receipt. Injection-flagged notes are never converted.

## Doctor and lint

- `brigadestack handoff doctor` reports pending writer-inbox handoffs that are not covered by the local source list, and can check `ingestor.last_run_log` for stale runs, skipped malformed handoffs, and warning summaries hidden behind no-reply cron output. Absent, unwatched writer inboxes collapse into a single summary line instead of one row per unselected agent tool.
- `brigadestack handoff lint` validates pending handoffs before ingest. Card actions require `Target card` plus `Suggested card content` and must omit document sections. `no-card` actions require document sections and must omit card sections. Lint also reports prompt-injection signal counts per file, so a poisoned note cannot read as fully clean from the lint path. The embedded content guard checks egress, not instructions.

```bash
brigadestack handoff doctor
brigadestack handoff lint
```

## Draft queue

- `brigadestack handoff list` lists local Memory Handoff drafts from `.claude/memory-handoffs/`, `.codex/memory-handoffs/`, and configured source inboxes.
- `brigadestack handoff show <handoff-id-or-path>` shows lint status, target card or document, source import id, source fingerprint, scanner provenance, and stale age.
- `brigadestack handoff archive <handoff-id-or-path>` moves one reviewed draft into `.brigade/handoffs/archive/` and records closeout metadata in `.brigade/handoffs/archive.jsonl`.
- `brigadestack handoff archive --all-reviewed` archives lint-valid drafts only. It does not run the canonical ingestor or edit memory.
- `brigadestack handoff closeout <draft-id-or-path>` writes local closeout metadata for reviewed drafts (`--all` closes out all non-archived drafts, `--defer` marks selected drafts deferred instead of reviewed).

```bash
brigadestack handoff list
brigadestack handoff show <handoff-id-or-path>
brigadestack handoff archive <handoff-id-or-path>
brigadestack handoff archive --all-reviewed
brigadestack handoff closeout <handoff-id-or-path>
```

## Ingest receipts and issues

- `brigadestack handoff runs` and `brigadestack handoff run-show <run-id>` read normalized local ingestion receipts from `.brigade/handoffs/ingest-runs/`.
- `brigadestack handoff receipt plan` previews a normalized external ingestion receipt. `brigadestack handoff receipt record` writes it.
- `brigadestack handoff reconcile` parses the configured `ingestor.last_run_log`, writes a normalized local receipt, and connects ingested, skipped, or failed outcomes back to draft and archive metadata. It does not run the ingestor or edit canonical memory.
- `brigadestack handoff issues` groups handoff-ingest warnings with repair guidance.
- `brigadestack handoff import-issues` imports those issues as local work.
- `brigadestack handoff sync-issues` imports new issues and closes stale local handoff tasks/imports once the latest scan no longer reports them.

```bash
brigadestack handoff runs
brigadestack handoff run-show <run-id>
brigadestack handoff receipt plan
brigadestack handoff receipt record
brigadestack handoff reconcile
brigadestack handoff issues
brigadestack handoff import-issues
brigadestack handoff sync-issues
```

For handoff-ingest issues, prefer `brigadestack handoff sync-issues` over repeated raw imports. It imports only issue ids that have not already been seen locally and marks stale handoff-ingest imports/tasks resolved when the latest log no longer contains them.

The handoff template lives at `<inbox>/TEMPLATE.md`. `brigadestack handoff-template` prints it, and `--target` prefers a target's installed template when present.