bug: --json commands must always return valid JSON, even for empty/error states

[Wirasm]

Problem

Some --json commands return plain text instead of JSON for certain states:

kild pr my-branch --json
# "No PR found for branch 'kild/my-branch'"   ← plain text, not JSON

This breaks the Assistant Agent persona's ability to reliably parse CLI output. The --json flag is a contract: "this command will return valid JSON."

Expected Behavior

Every --json command should return valid JSON for all states:

kild pr my-branch --json
# {"pr": null, "branch": "kild/my-branch"}

kild pr my-branch --json  # when PR exists
# {"pr": {"number": 123, "state": "open", ...}, "branch": "kild/my-branch"}

Scope

Audit all commands with --json flag:

• kild list --json — appears correct
• kild status --json — appears correct
• kild stats --json — appears correct
• kild stats --all --json — appears correct
• kild overlaps --json — appears correct
• kild pr --json — BROKEN (returns plain text for no-PR case)
• kild pr --json --refresh — needs verification
• kild daemon status --json — appears correct
• kild health --json — needs verification (if it exists)

Principle

From the branding docs: "Must have --json output for parsing" and "Meaningful exit codes." The --json output is the programmatic API surface for the Assistant Agent and Worker Agent personas. It must be reliable.

[Wirasm]

Investigation: --json commands must always return valid JSON

Type: BUG

Assessment

Metric	Value	Reasoning
Severity	HIGH	Breaks the programmatic API surface for agent automation; --json is a contract for scripting callers
Complexity	LOW	All fixes are isolated to CLI command handlers in 3 files; same pattern repeated
Confidence	HIGH	Root cause is obvious: conditional branches print plain text without checking json_output flag

---

Problem Statement

Several CLI commands with --json flag violate the JSON contract by printing plain text for "empty" or "error" states. The primary offender is kild pr --json which prints "No PR found for branch 'kild/my-branch'" as plain text. Two other commands (stats --all --json, overlaps --json) have the same pattern.

---

Root Cause Analysis

Command handlers read json_output flag but only use it in the "happy path" where data exists. Empty/error states print plain text unconditionally via early returns that bypass the JSON check.

Anti-pattern found in 3 commands:

// Early return with plain text BEFORE json check
if some_empty_condition {
    println!("Plain text message");  // BUG: ignores json_output
    return Ok(());
}
// ... later ...
if json_output { /* JSON output */ }

Reference implementation (daemon status) does it correctly:

if json {
    let status = if running { json!({"running": true, ...}) }
                 else { json!({"running": false}) };
    println!("{}", serde_json::to_string_pretty(&status)?);
}

---

Implementation Plan

Step	File	Change
1	crates/kild/src/commands/pr.rs:41	No-remote path: output {"pr": null, "branch": "...", "reason": "no_remote_configured"}
2	crates/kild/src/commands/pr.rs:103	No-PR path: output {"pr": null, "branch": "..."}
3	crates/kild/src/commands/stats.rs:129	Empty --all: output []
4	crates/kild/src/commands/overlaps.rs:26-36	Empty/insufficient kilds: output {"overlapping_files": [], "clean_kilds": [], "reason": "..."}
5	crates/kild/tests/cli_json_output.rs	Add integration tests for empty-state JSON

Detailed Implementation Steps

Step 1-2: Fix pr.rs — Wrap plain text early-returns with if json_output { json!(...) } else { println!(...) } for both the no-remote and no-PR-found paths.

Step 3: Fix stats.rs — Empty --all should output [] (matching list --json pattern for empty arrays).

Step 4: Fix overlaps.rs — Both empty (0 kilds) and insufficient (1 kild) paths should output a JSON object with the same shape as normal output (overlapping_files, clean_kilds arrays) plus a reason field.

Step 5: Tests — Add test_stats_all_json_outputs_valid_json and test_overlaps_json_outputs_valid_json to the existing cli_json_output.rs integration test file.

---

Audit Results

Command	Status
kild list --json	OK
kild status --json	OK
kild pr --json	BROKEN (2 paths)
kild stats --json	OK (single branch)
kild stats --all --json	BROKEN (empty state)
kild overlaps --json	BROKEN (empty/insufficient states)
kild health --json	OK
kild daemon status --json	OK (reference implementation)

---

Validation

cargo fmt --check && cargo clippy --all -- -D warnings && cargo test --all && cargo build --all

---

Next Step

To implement: /prp-issue-fix 369

---

Investigated by Claude