docs(parallel-issues): document merge-plan input shape and name validator field failures

[thewrz]

This was written agentically; verify its assertions:

Why

write-merge-plan.sh requires generatedAt (and a specific independent/chains record shape) in its merge-plan input, but triage-and-selection.md only showed generatedAt on the schema-2 output. The first real handoff on 2026-08-22 failed with the generic merge plan is malformed, ambiguous, or does not match dispatch entries and cost a source read. Closes #400.

What

Documents the exact merge-plan input JSON and its field rules in triage-and-selection.md, and adds a diagnostic pass to write-merge-plan.sh that names the first failing field (e.g. merge plan is invalid: merge plan is missing required field: generatedAt). The boolean accept/reject gate is byte-for-byte unchanged; the diagnostic runs only on its failure path and falls back to the old message.

Decisions

• Diagnostic layered beside the existing gate rather than replacing it, so a diagnostic bug can never loosen validation.
• The documented example was round-tripped through the real script (the first draft reused issue 164 in both sections and the validator correctly rejected it — fixed before commit).
  base=origin/main
  files=3
  total.insertions=135
  total.deletions=5
  total.lines=140
  operational.files=3
  operational.insertions=135
  operational.deletions=5
  operational.lines=140
  generated.files=0
  generated.insertions=0
  generated.deletions=0
  generated.lines=0
  lockfile.files=0
  lockfile.insertions=0
  lockfile.deletions=0
  lockfile.lines=0
  fixture.files=0
  fixture.insertions=0
  fixture.deletions=0
  fixture.lines=0
  non_operational.files=0
  non_operational.insertions=0
  non_operational.deletions=0
  non_operational.lines=0

Testing

• New regression: missing generatedAt → rc=1 and stderr names the field
• Focused write-merge-plan suite 10/10; full suite green (agent-run.sh --cmd test, worktree log 20260822T220041Z-test.log)
• CI green

🤖 Co-authored by Claude Fable 5 (root) / claude-sonnet-5 (worker).

Closes #400

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b2af7132-462d-4ac5-b898-0ee2fcfc985b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

This was written agentically; verify its assertions:

Adversarial review receipt

• Reviewer: provider=openai; model=gpt-5.6-terra; effort=xhigh; mode=cross-provider (reason: peer-cli=codex present)
• Counts: P1=0; P2=1; total=1
• Confirmed finding: diagnostic pass crashed on non-object merge-plan records — verdict=fixed; fix commit SHA(s)=ee7321708e9a67c1477a2e29e84fa9e2c7098a96

🤖 Co-authored by Claude Fable 5 (root).