[mdonnalley]

Summary

Declares a command's JSON result as a command fact and checks it in tests, without changing how handlers write output. branches delete is the first command to adopt it.

• CommandOutputAnnotation (supabase/CommandOutput) stores a command's output schema; withOutput attaches it. Handlers keep writing through Output.
• The registry gains the test and report-only check kinds. The output fact is registered as test-checked, and the catalog shows its JSON Schema.
• mockOutput takes an optional contract. In json and stream-json it fails a result that doesn't match the schema (including undeclared keys) or a second result write. verifyCompletion also fails a handler that succeeds without writing a result, and leaves a failing handler's own error unchanged.
• The docs spec publishes a declared schema as json_output_schema (draft 2020-12) and omits the field otherwise.
• An adoption test requires output, target policy and permissions on every executable command. Output omissions are listed in OUTPUT_EXCEPTIONS, with logs and functions serve marked as streaming. An output exception can't excuse another missing fact, and an exception that no longer applies fails the test, so the list can only shrink.

Not in this PR: result ownership, write ordering, cleanup and compile-time enforcement stay with the deferred boundary work. Report-only production checks have no implementation yet.

Stacked on #7586.

Linked issue

CLI-2961

[github-actions]

🤖 AI Review

Confirmed Claude's single finding: the declared output contract omits the target field added by production JSON output, while the mock hides this mismatch. Codex reported no findings. Verification used code inspection; tests were not run because dependencies are absent.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	apps/cli/src/commands/branches/delete/delete.output.ts:6	correctness	claude	The branches delete output contract omits target, although production JSON output adds it when a target is announced, including linked-parent resolution without explicit target flags. The published json_output_schema therefore disagrees with actual output. The new contract test misses this because mockOutput validates the payload without adding the announced target.

Stats

Claude findings: 1 · Codex findings: 0 · Confirmed: 1 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[github-actions]

🟠 MAJOR · correctness · source: claude

The branches delete output contract omits target, although production JSON output adds it when a target is announced, including linked-parent resolution without explicit target flags. The published json_output_schema therefore disagrees with actual output. The new contract test misses this because mockOutput validates the payload without adding the announced target.

Evidence: delete.output.ts:6-10 declares only project_ref and message. delete.handler.ts:34-37 resolves the parent target; command-internal/target/parent-scoped-project-ref.ts:36-46 announces it. shared/output/output.layer.ts:62-67 adds target, and :602-605/:649 routes JSON success through that merge. command-facts/command-output.ts:30-32 rejects undeclared keys. docs/docs-spec.ts:448-450 publishes the contract directly. tests/helpers/mocks.ts:419-422 validates only {...data, message}, despite tests/helpers/command-mocks.ts:1501-1505 providing the target cell.

Suggested fix: Include an optional target using the shared CommandTargetJson schema, and make mockOutput apply production's target merge before contract validation. Add coverage that validates output after announcing a linked target.