Local CLI review mode + headless action with structured output

Part of #1367 (Phase 4 — Platform Reach).

Goal

Two delivery surfaces both competitors monetize:

A. Local CLI review (CodeRabbit CLI parity — docs)

buddy-bot review running locally against uncommitted/branch changes — review before pushing:

• buddy-bot review [--base main] [--staged] [--light] — diffs the working tree (or staged, or branch vs base), runs the #1375 engine + #1378 analyzers locally, prints findings in pretty|json|github formats (reuse src/analysis reporter pattern)
• --light: analyzers + cheap model / summary-only (fast pre-commit hook usage)
• --fix: apply committable suggestions to the working tree (prompt per hunk unless --yes)
• Agent-integration output: --format agent emits findings as an agent-ready prompt block (CodeRabbit pipes into Claude Code/Cursor this way) so users can do buddy-bot review --format agent | claude
• Keys from env/config as in #1373; no GitHub token needed for local mode (skip provider-dependent context gracefully)
• buddy-bot doctor: environment diagnosis (keys present, git state, tool availability from #1378, token scopes) — CodeRabbit ships this and it kills setup-support burden

B. Headless action with structured output (Pullfrog parity — headless action)

Run Buddy Bot's agent as a pipeline step with schema-validated output consumable by later steps:

- uses: stacksjs/buddy-bot-action@v1   # or: bunx buddy-bot run --prompt ... in any step
  id: notes
  with:
    prompt: "Summarize dependency changes merged this week as release notes"
    output_schema: '{"type":"object","properties":{"markdown":{"type":"string"}},"required":["markdown"]}'
- run: echo '$'

• CLI form: buddy-bot run --prompt <p> | --prompt-file <f> [--output-schema <json>] [--model <m>] [--mode read-only|write]
• Schema enforcement via #1373 json mode with validate+retry; nonconforming output fails the step (exit ≠ 0) — Pullfrog's contract
• Writes result to $GITHUB_OUTPUT when present; prints JSON to stdout otherwise (composable outside Actions too)
• Tool tier defaults to read-only; --mode write requires explicit opt-in
• Ship the thin wrapper action (action.yml, node20/composite invoking bunx buddy-bot run) in-repo under action/

Tasks

• Local diff collection (working tree/staged/branch) + local review path with graceful no-token degradation
• --light, --fix (hunk applier with per-hunk prompt), --format agent
• buddy-bot doctor with actionable remediation lines
• buddy-bot run headless command + $GITHUB_OUTPUT handling + schema validate/retry/fail
• action/action.yml composite wrapper + README usage
• Tests: local diff modes, schema pass/fail/retry, output escaping (multiline into GITHUB_OUTPUT heredoc format), doctor checks
• docs/cli/review.md, docs/ai/headless.md

Acceptance criteria

• buddy-bot review --base main on a dirty tree prints correct findings with no GitHub token
• buddy-bot review --format agent | <any agent CLI> round-trips usefully
• Headless step with a violated schema fails the job; valid output is fromJSON-consumable
• buddy-bot doctor correctly diagnoses missing keys/tools in fixture environments

Dependencies

• Requires #1373; local review quality depends on #1375 + #1378 (can ship analyzer-only --light first)

Landed in f0e93d2.

Local review: --staged/--branch/default working tree (which includes staged changes — a pre-commit review that ignored them would miss what you are about to commit). --light runs analyzers only, no key needed; with --fail-on major it blocks a commit from a hook. Analyzer findings merge into the model's.

Formats: pretty/json/github/agent. --format agent emits an instruction, not a report, and explicitly gives the agent permission to disagree — one that mechanically applies a wrong finding is worse than one that pushes back. Non-pretty formats own stdout so nothing lands mid-JSON.

--fix applies bottom-up per file so replacing a line cannot shift the ones still pending, and refuses a suggestion whose line no longer matches. Per-finding confirmation by default.

buddy-bot doctor: every problem carries its fix; missing keys and linters are warnings, not failures.

buddy-bot run: nonconforming output fails the step, after re-asking with the violations quoted back. The $GITHUB_OUTPUT heredoc delimiter is chosen to be absent from the value — otherwise crafted output could close the block early and inject workflow outputs.

action/action.yml passes the prompt through the environment rather than interpolating it into run:, since a prompt built from a PR title is attacker-controlled.

Docs: docs/cli/review.md, docs/ai/headless.md, action/README.md.