From bc7604cb441068816f21792c44bb6a79ba845ced Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sun, 16 Aug 2026 00:16:02 -0700 Subject: [PATCH] docs: leave the README claim, fill the corpus instead The task said to correct the README for calling openspec/specs/ the current description of how osapi-io behaves. That is what OpenSpec's model says the directory holds, so the sentence states the destination correctly. The gap is in the corpus, not the claim. Rewriting the README to describe forty-five process rules would record a temporary state as permanent intent. Co-Authored-By: Claude Opus 5 (1M context) --- .../changes/specify-documentation-homes/design.md | 15 ++++++++++++--- .../changes/specify-documentation-homes/tasks.md | 10 +++++++--- 2 files changed, 19 insertions(+), 6 deletions(-) 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