From 3515ff6231e5ce67a7cb0a4dd0372ebc42b07de2 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:03:49 -0700 Subject: [PATCH] docs: rescope the job-architecture extraction Task 3.2 said to take the "Architecture Principles" block and leave the remaining 550 lines as description. Those lines hold the semantic routing rules and the five-label limit, which govern how an operation is built. The routing rule has already drifted: it classifies ten suffixes, the code uses twenty, and .list appears ten times unclassified. Nothing enforces it, so nobody found out. Co-Authored-By: Claude Opus 5 (1M context) --- .../specify-documentation-homes/design.md | 43 +++++++++++++++++++ .../specify-documentation-homes/tasks.md | 18 +++++++- 2 files changed, 59 insertions(+), 2 deletions(-) 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