Director: spec validation gate (pre-flight)

[fgmacedo]

Future enhancement: Spec validation gate

Summary

Before the Director plans, ask: is this spec plannable? A pre-flight pass reads the spec end-to-end and produces a structured validation report classifying issues as blocker, warning, or suggestion across categories like acceptance, clarity, completeness, observability, security, testability, architecture, and scope. Inside bcc run, validation runs as the first step of the autonomous flow: blockers abort before any Executor session starts; warnings and suggestions land in the journal and execution proceeds. As a standalone command, bcc validate <spec> lets authors check a spec at edit time and gates CI on PRs that touch specs.

Problem

Today the Director trusts the spec. If the spec has open questions, missing acceptance criteria, or under-specified cross-cutting concerns, the Executor improvises (poorly), stalls, or completes phases the user later realizes did not solve the problem. The cost of a bad spec is paid in iterations, not at edit time. Spec quality is unevenly enforced too: experienced authors develop intuition for "executable spec", new authors lose iterations on their first long run.

Goals

• Validation runs as the first autonomous step inside bcc run; blockers abort, warnings persist to the journal.
• Standalone bcc validate <spec> produces the same report at edit time, no execution side effect.
• Issues categorized so the author can triage; each issue concrete enough to act on without re-reading the whole spec.
• CI-friendly exit codes: zero on clean, non-zero at or above a configurable severity threshold.
• Cached per spec hash; --resume and re-runs against an unmodified spec skip the gate.
• Vendor-agnostic: works on any Director adapter bcc supports.

Non-goals

• bcc never edits the user's spec; the report describes issues, the author writes the fix.
• No prompt to "press P to proceed" on clean specs; validation is invisible without blockers.
• No project-specific style validation (lint rules, naming).
• No codebase-aware validation; the Director judges the spec on its own terms.