feat: add handoff lint

Author: solomonneas

CHANGELOG.md

@@ -59,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade handoff doctor` ingestor-log checks for stale latest-run logs, skipped malformed handoffs, warning summaries, and no-reply/no-update masking signals.
 - `brigade handoff issues` and `brigade handoff import-issues` to turn handoff ingest warnings into grouped repair guidance and local work imports.
 - `brigade handoff issues --category` and `brigade handoff import-issues --category` for category-limited handoff issue review/import.
+- `brigade handoff lint` to validate pending or explicit handoff files before ingest and catch card/document action mismatches that would be skipped later.
 - `docs/import-schema.md` documenting the local import JSONL contract for scanners and wrappers.
 - Cybersecurity plugin roadmap covering broad agent-workspace security checks plus Brigade-specific scanner, doctor, import, and multi-harness security checks.
 - Built-in `security` station and `brigade security scan` for read-only agent workspace security checks.

README.md

@@ -95,6 +95,7 @@ brigade init --target ./repo --harnesses none           # generic install
 Once installed, `brigade doctor` verifies the wiring and `brigade status` reports over the station registry.
 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 doctor` reports pending `.claude/memory-handoffs/` and `.codex/memory-handoffs/` files that are not covered by that local source list.
+Run `brigade handoff lint` before ingesting pending handoffs when you want to catch action/target mismatches early.
 If your ingestor writes a latest-run log, set `ingestor.last_run_log` in that local config so the doctor can warn on stale runs, skipped malformed handoffs, and warning summaries hidden behind no-reply cron output.
 Use `brigade handoff issues` to group those warnings with repair guidance, then `brigade handoff import-issues` to route them into the normal local work import inbox.
 
@@ -155,6 +156,7 @@ brigade dogfood
 brigade dogfood next
 brigade dogfood --target /path/to/repo
 brigade handoff doctor
+brigade handoff lint
 brigade handoff issues
 brigade handoff import-issues
 brigade work bootstrap
@@ -360,6 +362,7 @@ Handoff behavior:
 - By default it writes a reviewable handoff to `.claude/memory-handoffs/` under `--cwd`.
 - Use `--handoff-inbox <path>` for Codex, OpenCode, GPT, Hermes, OpenClaw, or another writer inbox.
 - The handoff targets `.learnings/LEARNINGS.md` as a `no-card` document update.
+- `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.
 - The normal `brigade ingest` route can review or ingest that handoff.
 - If handoff writing fails after synthesis, Brigade still prints the final answer and keeps the final artifacts.
 - Failed handoff writes exit nonzero and mark `run.json` as `handoff-failed`.

ROADMAP.md

@@ -125,6 +125,7 @@ Goal: prevent durable memory from silently rotting.
 - Add a handoff doctor that compares repo-local writer inboxes such as `.claude/memory-handoffs/` and `.codex/memory-handoffs/` against the canonical ingestor source list, warning when handoffs exist in directories the owner is not scanning. Status: started with `brigade handoff doctor`, `.brigade/handoff-sources.example.json`, and `brigade doctor` / `brigade work doctor` integration.
 - Add handoff-ingest observability checks for hidden warning states, including unreachable remote sources, malformed handoffs that are skipped, and runs that emit `NO_REPLY` despite warnings. Status: started with optional `ingestor.last_run_log` checks in `brigade handoff doctor`.
 - Turn handoff-ingest warnings into repairable local work. Status: started with `brigade handoff issues`, `brigade handoff import-issues`, repair guidance, and `brigade work brief` issue counts.
+- Catch handoff action/target mismatches before ingest. Status: started with `brigade handoff lint`, doctor warnings, issue imports, and template guidance that forces card and document handoffs into mutually exclusive branches.
 
 ## Later Phase: Portable Operator Setup
 

src/brigade/cli.py

@@ -115,6 +115,10 @@ def _build_parser() -> argparse.ArgumentParser:
     p_handoff_doctor.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
     p_handoff_doctor.add_argument("--sources", type=Path, default=None, help="Override .brigade/handoff-sources.json.")
     p_handoff_doctor.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    p_handoff_lint = handoff_sub.add_parser("lint", help="Validate pending or explicit memory handoff files.")
+    p_handoff_lint.add_argument("paths", nargs="*", type=Path, help="Handoff files to validate. Defaults to pending inbox files.")
+    p_handoff_lint.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
+    p_handoff_lint.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     p_handoff_issues = handoff_sub.add_parser("issues", help="Group actionable handoff ingest issues.")
     p_handoff_issues.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
     p_handoff_issues.add_argument("--sources", type=Path, default=None, help="Override .brigade/handoff-sources.json.")
@@ -678,6 +682,8 @@ def main(argv=None) -> int:
 
         if args.handoff_command == "doctor":
             return handoff_cmd.doctor(target=args.target, sources=args.sources, json_output=args.json)
+        if args.handoff_command == "lint":
+            return handoff_cmd.lint(target=args.target, paths=args.paths, json_output=args.json)
         if args.handoff_command == "issues":
             return handoff_cmd.issues(
                 target=args.target,