fledge spec lint: quality gate for the spec itself (not just code-vs-spec)

[0xLeif]

Origin: a four-reader book club on the CorvidLabs books flagged that spec-sync validates code against the spec but has no opinion on whether the spec itself is any good. A thin, aspirational, or poisoned spec passes structurally while being wrong. The spec is the one input to the agent pipeline that nothing validates today. (Books: Open Source Tooling ch9 "What spec-sync does not check"; Field Guide ch9 "The spec is an input too".)

Proposal

Add fledge spec lint, a gate that runs on the spec before any agent loop and in CI, and blocks on failure.

Checks

• All seven required sections present and non-empty: Purpose, Public API, Invariants, Behavioral Examples, Error Cases, Dependencies, Change Log.
• No TODO / TBD / FIXME placeholder strings in Purpose or Public API.
• version frontmatter is a valid semver string.
• Every file under files: exists on disk (a spec pointing at deleted files is a staleness / input-poisoning vector).
• At least one acceptance signal and one rejection signal: the spec must state what proves success and what proves failure (non-empty Behavioral Examples + Error Cases, or explicit accepts: / rejects: blocks). From First-Class ch9.

Acceptance criteria

• fledge spec lint [path] exits non-zero with a structured list of failures; exit 0 when clean.
• Works as a pre-commit hook and a CI gate, mirroring fledge spec check.
• --json output, consistent with the rest of fledge.

Filed from the book club review; tracked for later work.

[0xLeif]

Update from the author interview: the quality judgment should be agent-graded, not a static linter. A model reviews the spec for quality the way fledge review reviews code (is the why falsifiable, are invariants real constraints vs decorative, is there an acceptance and a rejection signal), with a human able to override. Keep the cheap structural checks (sections present, files resolve, valid semver) as a fast pre-pass, but "is this spec good" needs a model, not regex.