CI: gate main on openspec validate --all --strict #105

Activity

1. theCodeDrift commented on Aug 15, 2026

   

   theCodeDrift

   on Aug 15, 2026

   MemberAuthor

   More actions

   Follow-up from the cleanup in #106: --strict alone isn't enough. It misses a whole class of rot.

   A second ## silently truncates a spec

   Anything after a second ## heading inside the requirements section stops being parsed as a requirement. What's below it isn't invalid, it's invisible. Measured across openspec/specs/:

   Spec	Requirements in file	Visible to the parser	--strict verdict
   cli-rules	33	23	failing (for unrelated reasons)
   infrastructure	20	1	passing
   skills	7	1	passing

   infrastructure and skills were green the whole time. 35 requirements went unread while the validator reported success. That's worse than a red check: a passing gate is an active claim that the spec was read.

   Same shape as the cli-help defect found earlier, where a lost opening code fence turned a documentation template's ## Goal / ## Preconditions into real headings and hid every requirement below them.

   So the gate wants two checks

   1. pnpm openspec validate --all --strict (the original ask)
   2. Every ### Requirement: sits under ## Requirements

   The second is a few lines and catches what the first structurally cannot:

   for spec in pathlib.Path('openspec/specs').glob('*/spec.md'):
       lines = spec.read_text().split('\n')
       total = sum(1 for l in lines if l.startswith('### Requirement:'))
       visible, inreq = 0, False
       for l in lines:
           if l.startswith('## '):
               inreq = l.strip() == '## Requirements'
           elif l.startswith('### Requirement:') and inreq:
               visible += 1
       if total != visible:
           fail(f"{spec}: {total - visible} requirement(s) hidden by a '##' heading")

   #106 brings all 23 specs to 0 failures with every requirement visible, so both checks are green today and the gate can go on without landing red.

   Topical grouping inside a requirements section still works, just as a bold lead-in line rather than a heading. #106 converts ## API Contract, ## Build Tooling, ## Distribution and friends that way.
2. theCodeDrift

   added 5 commits that reference this issue on Aug 19, 2026

   docs(openspec): make every spec pass validate --all --strict

   ...

   d9857e4

   docs(openspec): make every spec pass validate --all --strict

   ...

   c779ff7

   docs(openspec): make every spec pass validate --all --strict

   ...

   f23dac0

   docs(openspec): make every spec pass validate --all --strict

   ...

   a9293c2

   ci: gate main on spec validity and requirement visibility

   ...

   0aeb833
3. theCodeDrift

   closed this as completedin #114on Aug 20, 2026