diff --git a/openspec/changes/specify-documentation-homes/design.md b/openspec/changes/specify-documentation-homes/design.md index 2219b6e..219973c 100644 --- a/openspec/changes/specify-documentation-homes/design.md +++ b/openspec/changes/specify-documentation-homes/design.md @@ -253,9 +253,18 @@ its own description. It will never fully match it. Package maps and request flows stay in the repositories, because writing them as requirements produces a corpus that goes -stale on every refactor — a decision this capability already records. So the -README is corrected to say what the corpus is: the rules the software is held -to, with the reasoning in the archive. +stale on every refactor — a decision this capability already records. + +The README is left as it stands. "The current description of how osapi-io +behaves" is what OpenSpec's own model says `specs/` holds, so the sentence +states the destination correctly and the gap is in the corpus rather than in the +claim. Rewriting it to describe forty-five process rules would have recorded a +temporary state as the permanent intent. + +*Alternative considered:* correct the README to say the corpus holds rules. That +was the first draft of this task, and it was wrong. A README that describes what +a directory currently contains, rather than what it is for, stops being true the +moment the next capability lands. ### An entry point, before there are twenty capabilities diff --git a/openspec/changes/specify-documentation-homes/tasks.md b/openspec/changes/specify-documentation-homes/tasks.md index 6ca5b00..f73595e 100644 --- a/openspec/changes/specify-documentation-homes/tasks.md +++ b/openspec/changes/specify-documentation-homes/tasks.md @@ -75,9 +75,13 @@ - [ ] 4a.1 `specs` — write the corpus entry point naming every capability and what it covers -- [ ] 4a.2 `specs` — correct the README, which calls `openspec/specs/` "the - current description of how osapi-io behaves". It holds rules; five of its six - capabilities govern how work is done rather than how the software behaves +- [ ] 4a.2 `specs` — leave the README's description of `openspec/specs/` as "the + current description of how osapi-io behaves". That is what OpenSpec's own + model says the directory holds, so the sentence states the destination + correctly. The corpus has not arrived: five of its six capabilities govern how + work is done, because every change so far has been repository standardization. + Closing that gap is the behavior capabilities queued in section 3, not a + smaller claim in the README - [ ] 4a.3 `specs` — confirm each capability's `## Purpose` states what it governs, rather than restating its first requirement