docs: rescope the job-architecture extraction

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.

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