diff --git a/openspec/changes/specify-documentation-homes/design.md b/openspec/changes/specify-documentation-homes/design.md index 630c4fc..6a26fb8 100644 --- a/openspec/changes/specify-documentation-homes/design.md +++ b/openspec/changes/specify-documentation-homes/design.md @@ -187,3 +187,46 @@ rule still in force. *Alternative considered:* keep the plan that records it. Rejected — a planning document is not where a binding rule belongs, and keeping one file to preserve one sentence reintroduces the directory this change removes. + +## An architecture document is not one genre + +`osapi` holds three documents named for architecture, and they are three +different things: + +| Document | Contains | Reader | +| ------------------------ | ----------------------------------------------------------- | --------------------------------- | +| `architecture.md` | the three processes, deployment models, how a request flows | someone new, or an operator | +| `system-architecture.md` | component map, entry points, layers, dependencies | a contributor navigating the code | +| `job-architecture.md` | routing rules, label limits, job states, package layout | someone building an operation | + +Only the third governs how new work is built, and it does so from sections +scattered through 561 lines rather than from the block named "Architecture +Principles". + +No other repository has a document like these. This is not an organization-wide +category with a naming problem; it is one repository's documents sharing a word. + +### The routing rule proves why extraction matters + +`job-architecture.md` states that an operation reaches `jobs.query` or +`jobs.modify` according to its suffix, and lists ten suffixes. The code uses +twenty. `.list` appears ten times and the rule does not classify it. Ten more +verbs — `stop`, `start`, `signal`, `shutdown`, `restart`, `remove`, `reboot`, +`install`, `enable`, `disable` — are unanticipated. Two documented suffixes are +unused. + +Nothing enforces the rule: the caller chooses `Query` or `Modify` directly. So +the code outgrew the document, and because a description is not checked against +anything, no one found out. A requirement with scenarios would have failed when +`.list` appeared. + +This is the case for decomposing an architecture document into capabilities +stated as the argument would not have made it: not that requirements belong in +the corpus on principle, but that a rule nobody checks stops being true and +keeps being read. + +*Alternative considered:* rename the three documents first, so their names match +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. diff --git a/openspec/changes/specify-documentation-homes/tasks.md b/openspec/changes/specify-documentation-homes/tasks.md index d13d5b5..5f3f5b0 100644 --- a/openspec/changes/specify-documentation-homes/tasks.md +++ b/openspec/changes/specify-documentation-homes/tasks.md @@ -22,8 +22,22 @@ - [ ] 3.1 `osapi` — propose a capability from `docs/sidebar/architecture/`: `principles.md` (8 constraints) and `api-guidelines.md` (6 API rules) -- [ ] 3.2 `osapi` — propose a capability from `job-architecture.md`'s - "Architecture Principles"; leave its remaining 550 descriptive lines in place +- [ ] 3.2 `osapi` — propose a `job-routing` capability from + `job-architecture.md`. Its requirements are spread through the document, not + confined to "Architecture Principles": the semantic routing rules that decide + whether an operation reaches `jobs.query` or `jobs.modify`, the target types + (`_all`, `_any`, hostname, label selector), hierarchical label prefix + matching, and the five-label limit with its consumer arithmetic +- [ ] 3.2a `osapi` — the routing rule has already drifted. It classifies + `.get`/`.query`/`.read`/`.status`/`.do` and + `.update`/`.set`/`.create`/`.delete`/`.execute`, while the code uses twenty + suffixes: `.list` appears ten times and is not classified at all, nor are + `stop`, `start`, `signal`, `shutdown`, `restart`, `remove`, `reboot`, + `install`, `enable`, or `disable`. `.read` and `.set` are documented and + unused. Establish the real rule before writing it as a requirement +- [ ] 3.2b `osapi` — leave the descriptive remainder of `job-architecture.md` in + place: job states, the append-only status design, package layout, and the + performance notes describe what the code is - [ ] 3.3 `gohai` — propose a capability from the collector done-definition and `docs/methodology.md`'s decision order and field-naming ladder - [ ] 3.4 `osapi` — propose capabilities from `CLAUDE.md`'s seven MANDATORY rule