diff --git a/openspec/changes/specify-documentation-homes/design.md b/openspec/changes/specify-documentation-homes/design.md index 6a26fb8..2219b6e 100644 --- a/openspec/changes/specify-documentation-homes/design.md +++ b/openspec/changes/specify-documentation-homes/design.md @@ -230,3 +230,53 @@ their genres. Rejected for now — renaming before extraction relabels documents that still contain requirements, and these are site routes, so the rename costs external links. It belongs after, when what remains is unambiguously description. + +## The corpus promised something it does not hold + +The `specs` README says of `openspec/specs/`: + +> What survives is `openspec/specs/` — the current description of how osapi-io +> behaves, kept honest by every change that passes through. + +It is not that. Of the six capabilities in the corpus, five govern how work is +done — package layout, coverage targets, continuous integration, labels, +justfile modules, module paths, ignore files, badges. Only `sdk-standards` says +anything about how the software behaves. A reader could learn all forty-five +requirements and know the linting rules without learning that osapi has three +processes or what a provider is. + +The gap is an artifact of sequence rather than intent. Every change so far has +been repository standardization, and standardization produces rules about +process. The capabilities queued next — routing, API design, provider semantics, +domain completeness — are about behavior, and the corpus will start to resemble +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. + +### An entry point, before there are twenty capabilities + +`openspec/` holds six capability directories and eleven archived changes, and +nothing that says where to start. That is survivable at six and is not at +twenty. + +The requirement asks for a map rather than a summary: naming each capability and +what it covers, saying what the corpus is, and pointing at the archive for +reasoning. A summary would restate the requirements and drift from them; a map +stays true as long as the names do. + +*Alternative considered:* generate the entry point from the capability files. +Rejected — the useful part is the sentence explaining what a capability is for +and when to reach for it, which is not derivable from a list of `SHALL` +statements. + +### Purpose sections carry the orientation + +The second requirement follows from the same problem. A capability opening with +its first requirement teaches a reader who already knows the domain and no one +else. Asking the `## Purpose` to state what the capability governs, and why that +ground needs governing, is what makes the corpus readable rather than only +searchable. diff --git a/openspec/changes/specify-documentation-homes/specs/documentation/spec.md b/openspec/changes/specify-documentation-homes/specs/documentation/spec.md index ce69d68..dc5c107 100644 --- a/openspec/changes/specify-documentation-homes/specs/documentation/spec.md +++ b/openspec/changes/specify-documentation-homes/specs/documentation/spec.md @@ -143,6 +143,52 @@ what each part covers. navigation - **THEN** that navigation is the index, and no second one is maintained +### Requirement: The corpus has an entry point + +The corpus SHALL contain a document naming every capability and what each one +covers, so a reader arriving without knowing which capability holds what can +find their way in. + +That document SHALL state what the corpus is: the rules the organization's +software is held to, and where the reasoning behind each rule is kept. It SHALL +NOT describe the corpus as a description of how the software behaves, because +descriptions of current behavior stay in the repositories that hold the code. + +#### Scenario: A reader arrives at the corpus + +- **WHEN** someone opens the corpus without knowing which capability governs the + work they are doing +- **THEN** an entry point names each capability and what it covers, rather than + requiring every capability to be opened + +#### Scenario: A capability is added + +- **WHEN** a change adds a capability to the corpus +- **THEN** the entry point names it, so the map does not fall behind what it + maps + +#### Scenario: A reader wants to know why a rule exists + +- **WHEN** a requirement's reasoning matters more than its wording +- **THEN** the entry point says the reasoning is in the archived change that + introduced it, rather than leaving the archive to be discovered + +### Requirement: A capability says what it is for before it constrains + +A capability SHALL open by stating what it governs and why that ground needs +governing. + +A reader who does not already know the domain SHALL be able to learn what the +capability is about from that opening, without reconstructing it from the +requirements below. + +#### Scenario: A capability is read by someone new to the domain + +- **WHEN** a contributor opens a capability governing a subsystem they have not + worked in +- **THEN** its opening explains what the subsystem is for, so the requirements + that follow are read with the reason for them in view + ### Requirement: Documentation organisation is the repository's own The names and shape of directories inside `docs/` SHALL be chosen by the diff --git a/openspec/changes/specify-documentation-homes/tasks.md b/openspec/changes/specify-documentation-homes/tasks.md index 5f3f5b0..6ca5b00 100644 --- a/openspec/changes/specify-documentation-homes/tasks.md +++ b/openspec/changes/specify-documentation-homes/tasks.md @@ -71,8 +71,19 @@ the corpus. Done for `osapi-orchestrator`; `osapi` has no root `CONTRIBUTING.md` until `standardize-repository-layout` task 4.5 writes one +## 4a. Make the corpus navigable + +- [ ] 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.3 `specs` — confirm each capability's `## Purpose` states what it + governs, rather than restating its first requirement + ## 5. Verification - [x] 5.1 Confirm every repository's documentation is indexed - [x] 5.2 Confirm no repository contains a planning directory - [ ] 5.3 Confirm no relocated requirement is stated in two places +- [ ] 5.4 Confirm the entry point names every capability in the corpus