# handoff

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. `brigade handoff sources init` writes local handoff source coverage for Claude, Codex, OpenCode, and Hermes (flags: `--target`, `--force`, `--json`). `brigade 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

`brigade 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
brigade handoff draft --target ./my-repo --inbox codex \
  --title "What changed" \
  --summary "Short note future agents should know." \
  --content "The durable note itself goes here."
```

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

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

```bash
brigade handoff migrate --target .
brigade 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

- `brigade 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 harness.
- `brigade 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
brigade handoff doctor
brigade handoff lint
```

## Draft queue

- `brigade handoff list` lists local Memory Handoff drafts from `.claude/memory-handoffs/`, `.codex/memory-handoffs/`, and configured source inboxes.
- `brigade handoff show <handoff-id-or-path>` shows lint status, target card or document, source import id, source fingerprint, scanner provenance, and stale age.
- `brigade handoff archive <handoff-id-or-path>` moves one reviewed draft into `.brigade/handoffs/archive/` and records closeout metadata in `.brigade/handoffs/archive.jsonl`.
- `brigade handoff archive --all-reviewed` archives lint-valid drafts only. It does not run the canonical ingestor or edit memory.
- `brigade 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
brigade handoff list
brigade handoff show <handoff-id-or-path>
brigade handoff archive <handoff-id-or-path>
brigade handoff archive --all-reviewed
brigade handoff closeout <handoff-id-or-path>
```

## Ingest receipts and issues

- `brigade handoff runs` and `brigade handoff run-show <run-id>` read normalized local ingestion receipts from `.brigade/handoffs/ingest-runs/`.
- `brigade handoff receipt plan` previews a normalized external ingestion receipt; `brigade handoff receipt record` writes it.
- `brigade 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.
- `brigade handoff issues` groups handoff-ingest warnings with repair guidance.
- `brigade handoff import-issues` imports those issues as local work.
- `brigade handoff sync-issues` imports new issues and closes stale local handoff tasks/imports once the latest scan no longer reports them.

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

For handoff-ingest issues, prefer `brigade 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`; `brigade handoff-template` prints it, and `--target` prefers a target's installed template when present.