Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions openspec/changes/specify-documentation-homes/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 7 additions & 3 deletions openspec/changes/specify-documentation-homes/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down