Board Validate

Run node {{KIT}}/scripts/validate-board.mjs {{BOARD}}/data.json and fix what it flags. Validate whenever the board was hand-edited or a run behaves unexpectedly.

What to check

• Schema — every ticket matches {{BOARD}}/board.schema.json (valid status, priority, swag, model; required id + status). Tickets in {{BOARD}}/archive.json are schema-checked too — they stay dependency targets forever.
• Unique ids — no two epics or tickets share an id, across data.json + archive.json. A cross-file collision is an error: archive-on-done tooling deletes the wrong ticket on exactly that case.
• Dependencies resolve — every id in depends_on exists in data.json or archive.json (landed tickets move to the archive by design, so deps legitimately point there), and there are no cycles. An id found in neither file is a hard error: the runtime treats an absent dependency as satisfied, so a typo silently unblocks the ticket instead of holding it.
• Archive-only statuses — archived, duplicate, and wont-do are terminal states for tickets that left the board without being completed; they may appear only in archive.json. A live ticket carrying one is an error — folding a declined or duplicate ticket into done records work as finished that never was.
• failureKind — blocker tickets from a failed merge may carry failureKind (merge-conflict, merge-schema-invalid, merge-unknown-status, merge-missing-sha) so failures are classifiable; the validator warns on unknown values.
• Eligibility sanity — at least one todo ticket is unblocked, or the orchestrator will correctly report idle. If you expected work to run, this is usually why it didn't.
• Agent plans — every code in agent_plan maps to a real agent in agents/. Terminal gates (qa → merge, plus pd for multi-agent/human-gated) are appended at run time by the orchestrator, so a bare ["backend"] is fine — it runs backend → qa → merge.
• Model floors — the validator warns when a ticket's model is below its area's floor (config.model.floors); it will run on the stronger model. Set it explicitly to silence the warning.
• Epic references — every epicId points at a real epic.
• Plan scope — once {{BOARD}}/plan.json names a deliverable, use case, or requirement, the validator warns on any ticket whose traces_to is empty, points at an id the plan doesn't define, or points at an OUT- id. It stays a warning here on purpose: you must be able to jot a ticket before the plan covers it. It becomes a block at run time — the orchestrator refuses to pick a scope-blocked ticket. Fix it by adding the requirement (/plan-update) or by having a human write a scope_exception with the reason. A project with no plan has the gate off, and the validator says so.
• Initiative ownership — only once {{BOARD}}/plan.json defines at least one initiative; a plan without them changes nothing here. Then:
  • a live epic with no initiativeId warns, and its tickets are refused at pick time. That split is deliberate: a board gains its first initiative with every epic unassigned, and erroring would make it invalid at exactly the moment nothing could fix it — the plan CLI cannot write a board. So the work stops without the board breaking. Assign it with maestro ticket edit-epic <id> --initiative <I-n>.
  • an epic naming an initiative the plan does not define is an error, whether or not the plan still defines any initiatives at all. Deleting the last one does not make a dangling reference acceptable, it just makes it easier to miss.
  • a trace that crosses initiatives is an error, for epics and tickets alike. An epic or ticket may trace to a project-wide item (one no initiative owns) or to one owned by its own initiative. Nothing else.
  • a scope_exception does not clear an ownership error. It is a human's decision about project scope; it says nothing about which initiative owns a requirement.
  • archived epics and archived tickets are checked too — a landed ticket's traces are what per-initiative delivery is computed from, so a dangling one there corrupts the reporting rather than merely being untidy.
• Plan coverage — the validator lists plan items no ticket is working. An uncovered FR- is either a missing ticket or a requirement that shouldn't have been in the plan.
• Human gates — the validator warns when a human_gate value isn't in config.humanGates, so gates stay a known vocabulary the orchestrator matches reliably rather than free text. It also warns when a human-gated ticket sits in todo or in-progress — the gate makes it ineligible, so that status is misleading; clear the gate or move it back to backlog.

Common failures

• A ticket stuck because it depends_on something that's blocked, not done.
• A dev ticket wrongly depending on a release/prod ticket — prod is a separate track; remove the dependency.
• A ticket with no model — it'll fall back to the area default; set it explicitly if it matters.