From 6bdb0cfefd76b33a69b916aad30ce6c2ee59785f 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: Sat, 15 Aug 2026 22:23:52 -0700 Subject: [PATCH] docs: archive architecture and drift changes document-system-architecture establishes module-dependencies, so correct-documentation-drift's MODIFIED delta finally has a target to edit in place. Archiving in that order merges six requirements into the corpus without orphaning any. Co-Authored-By: Claude Opus 5 (1M context) --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/module-dependencies/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/module-dependencies/spec.md | 0 .../tasks.md | 24 +-- openspec/specs/module-dependencies/spec.md | 199 ++++++++++++++++++ 11 files changed, 211 insertions(+), 12 deletions(-) rename openspec/changes/{correct-documentation-drift => archive/2026-08-15-correct-documentation-drift}/.openspec.yaml (100%) rename openspec/changes/{correct-documentation-drift => archive/2026-08-15-correct-documentation-drift}/design.md (100%) rename openspec/changes/{correct-documentation-drift => archive/2026-08-15-correct-documentation-drift}/proposal.md (100%) rename openspec/changes/{correct-documentation-drift => archive/2026-08-15-correct-documentation-drift}/specs/module-dependencies/spec.md (100%) rename openspec/changes/{correct-documentation-drift => archive/2026-08-15-correct-documentation-drift}/tasks.md (100%) rename openspec/changes/{document-system-architecture => archive/2026-08-15-document-system-architecture}/.openspec.yaml (100%) rename openspec/changes/{document-system-architecture => archive/2026-08-15-document-system-architecture}/design.md (100%) rename openspec/changes/{document-system-architecture => archive/2026-08-15-document-system-architecture}/proposal.md (100%) rename openspec/changes/{document-system-architecture => archive/2026-08-15-document-system-architecture}/specs/module-dependencies/spec.md (100%) rename openspec/changes/{document-system-architecture => archive/2026-08-15-document-system-architecture}/tasks.md (50%) create mode 100644 openspec/specs/module-dependencies/spec.md diff --git a/openspec/changes/correct-documentation-drift/.openspec.yaml b/openspec/changes/archive/2026-08-15-correct-documentation-drift/.openspec.yaml similarity index 100% rename from openspec/changes/correct-documentation-drift/.openspec.yaml rename to openspec/changes/archive/2026-08-15-correct-documentation-drift/.openspec.yaml diff --git a/openspec/changes/correct-documentation-drift/design.md b/openspec/changes/archive/2026-08-15-correct-documentation-drift/design.md similarity index 100% rename from openspec/changes/correct-documentation-drift/design.md rename to openspec/changes/archive/2026-08-15-correct-documentation-drift/design.md diff --git a/openspec/changes/correct-documentation-drift/proposal.md b/openspec/changes/archive/2026-08-15-correct-documentation-drift/proposal.md similarity index 100% rename from openspec/changes/correct-documentation-drift/proposal.md rename to openspec/changes/archive/2026-08-15-correct-documentation-drift/proposal.md diff --git a/openspec/changes/correct-documentation-drift/specs/module-dependencies/spec.md b/openspec/changes/archive/2026-08-15-correct-documentation-drift/specs/module-dependencies/spec.md similarity index 100% rename from openspec/changes/correct-documentation-drift/specs/module-dependencies/spec.md rename to openspec/changes/archive/2026-08-15-correct-documentation-drift/specs/module-dependencies/spec.md diff --git a/openspec/changes/correct-documentation-drift/tasks.md b/openspec/changes/archive/2026-08-15-correct-documentation-drift/tasks.md similarity index 100% rename from openspec/changes/correct-documentation-drift/tasks.md rename to openspec/changes/archive/2026-08-15-correct-documentation-drift/tasks.md diff --git a/openspec/changes/document-system-architecture/.openspec.yaml b/openspec/changes/archive/2026-08-15-document-system-architecture/.openspec.yaml similarity index 100% rename from openspec/changes/document-system-architecture/.openspec.yaml rename to openspec/changes/archive/2026-08-15-document-system-architecture/.openspec.yaml diff --git a/openspec/changes/document-system-architecture/design.md b/openspec/changes/archive/2026-08-15-document-system-architecture/design.md similarity index 100% rename from openspec/changes/document-system-architecture/design.md rename to openspec/changes/archive/2026-08-15-document-system-architecture/design.md diff --git a/openspec/changes/document-system-architecture/proposal.md b/openspec/changes/archive/2026-08-15-document-system-architecture/proposal.md similarity index 100% rename from openspec/changes/document-system-architecture/proposal.md rename to openspec/changes/archive/2026-08-15-document-system-architecture/proposal.md diff --git a/openspec/changes/document-system-architecture/specs/module-dependencies/spec.md b/openspec/changes/archive/2026-08-15-document-system-architecture/specs/module-dependencies/spec.md similarity index 100% rename from openspec/changes/document-system-architecture/specs/module-dependencies/spec.md rename to openspec/changes/archive/2026-08-15-document-system-architecture/specs/module-dependencies/spec.md diff --git a/openspec/changes/document-system-architecture/tasks.md b/openspec/changes/archive/2026-08-15-document-system-architecture/tasks.md similarity index 50% rename from openspec/changes/document-system-architecture/tasks.md rename to openspec/changes/archive/2026-08-15-document-system-architecture/tasks.md index 05c8835..bc86f74 100644 --- a/openspec/changes/document-system-architecture/tasks.md +++ b/openspec/changes/archive/2026-08-15-document-system-architecture/tasks.md @@ -8,35 +8,35 @@ Sequenced: `osapi` renames and publishes before `osapi-orchestrator` moves. -- [ ] 2.1 Search for consumers of `github.com/retr0h/osapi` outside the +- [x] 2.1 Search for consumers of `github.com/retr0h/osapi` outside the organization -- [ ] 2.2 `osapi` — rename the module to `github.com/osapi-io/osapi` and update +- [x] 2.2 `osapi` — rename the module to `github.com/osapi-io/osapi` and update its own imports -- [ ] 2.3 `osapi-orchestrator` — update its `require` and importing files once +- [x] 2.3 `osapi-orchestrator` — update its `require` and importing files once the new path is published ## 3. Correct the documentation -- [ ] 3.1 `gohai` — describe the consumer relationship it has, not the one +- [x] 3.1 `gohai` — describe the consumer relationship it has, not the one intended -- [ ] 3.2 Confirm no repository documents a `replace`-based linkage +- [x] 3.2 Confirm no repository documents a `replace`-based linkage -- [ ] 3.3 Confirm no `go.mod` contains a `replace` directive pointing outside +- [x] 3.3 Confirm no `go.mod` contains a `replace` directive pointing outside its own repository -- [ ] 3.4 `osapi` — `docs/docusaurus.config.ts` declares +- [x] 3.4 `osapi` — `docs/docusaurus.config.ts` declares `organizationName: 'retr0h'` three lines below `url: 'osapi-io.github.io'` -- [ ] 3.5 `osapi` — `contributing.md` links Discussions to `retr0h/go-gilt`, a +- [x] 3.5 `osapi` — `contributing.md` links Discussions to `retr0h/go-gilt`, a different project ## 4. Verification -- [ ] 4.1 Confirm every module path matches its repository location -- [ ] 4.2 Confirm every `replace` directive points within the repository that +- [x] 4.1 Confirm every module path matches its repository location +- [x] 4.2 Confirm every `replace` directive points within the repository that holds it -- [ ] 4.3 Confirm every documented dependency appears in the corresponding +- [x] 4.3 Confirm every documented dependency appears in the corresponding `go.mod` -- [ ] 4.4 Confirm no repository names an owner or project other than its own, +- [x] 4.4 Confirm no repository names an owner or project other than its own, excluding attribution of a person diff --git a/openspec/specs/module-dependencies/spec.md b/openspec/specs/module-dependencies/spec.md new file mode 100644 index 0000000..4a12132 --- /dev/null +++ b/openspec/specs/module-dependencies/spec.md @@ -0,0 +1,199 @@ +# module-dependencies Specification + +## Purpose + +Records how osapi-io repositories depend on one another and how those +dependencies are declared, so that a description of the system can be checked +against what the code actually does. + +## Requirements + +### Requirement: Module path matches repository location + +A Go module SHALL declare a path matching the repository that holds it. + +#### Scenario: Consumer resolves a dependency + +- **WHEN** a developer runs `go get` using the repository's location +- **THEN** the module resolves, because its declared path is that location + +#### Scenario: Repository moves between owners + +- **WHEN** a repository moves to a different organization +- **THEN** its module path is updated to match, and consumers are updated in the + same change + +### Requirement: A repository's declared home matches where it lives + +A repository SHALL NOT name an owner, project, or location other than its own. +This covers every place the repository states where it lives — the module path, +site deployment configuration, and links to the project's own issue tracker, +discussions, or releases. + +A module path is checked by the toolchain and fails loudly when wrong. These +other declarations fail quietly: the build passes, the site publishes, and the +link resolves to somebody else's project. + +#### Scenario: A repository moves between owners + +- **WHEN** a repository moves to a different organization +- **THEN** every declaration of where it lives is updated, not only the ones a + compiler checks + +#### Scenario: Site deployment names a different organization + +- **WHEN** a documentation site declares the organization it deploys under +- **THEN** that organization is the one hosting it, rather than a former owner + the published URL contradicts + +#### Scenario: A link points at the author's other project + +- **WHEN** documentation links to the project's issue tracker, discussions, or + releases +- **THEN** the link names this repository, not one it was copied from + +### Requirement: Dependencies are declared by version + +A repository SHALL depend on another repository by a released or pinned version +in `go.mod`. + +A `replace` directive pointing outside the repository that holds it MAY be used +locally while developing against an unreleased change in a sibling repository. +It SHALL NOT be merged. + +A `replace` directive pointing within the repository that holds it is a +different thing and SHALL be merged. A nested module — an example or tool module +under a repository that already declares its own — resolves its parent through +`replace` so it compiles against the working tree rather than a published +version. Without it the example cannot demonstrate the code it ships beside. + +The distinction is direction, not mechanism: a `replace` crossing a repository +boundary substitutes for a version that should be pinned; one staying inside it +is how a nested module refers to its own repository. + +#### Scenario: Consumer builds without the sibling checked out + +- **WHEN** a repository is built by someone who has not cloned its sibling + repositories +- **THEN** the build resolves every dependency from the module proxy + +#### Scenario: An example module ships beside the code it demonstrates + +- **WHEN** a repository carries a nested example module +- **THEN** that module declares a `replace` pointing at its own repository root, + and it is merged, because the example must build against the source it sits + next to + +#### Scenario: Developing against an unreleased sibling change + +- **WHEN** a developer adds a `replace` directive to test against a sibling + repository's unmerged branch +- **THEN** it is removed and the dependency repinned to the released version + before the change is merged + +#### Scenario: The sibling change merges first + +- **WHEN** the sibling change is merged and published +- **THEN** the dependent repository pins the new version, and the `replace` + directive that stood in for it is gone + +### Requirement: Documented relationships match declared ones + +Documentation describing a dependency between repositories SHALL match what +`go.mod` declares. A repository SHALL NOT describe itself as consumed by, or +consuming, a repository it has no declared dependency on. + +Documentation describing tooling SHALL match what the repository installs and +declares. A repository SHALL NOT name a library, tool, or directory it does not +use. + +A repository SHALL NOT describe another repository's choices. Those go stale +without anyone editing the file that states them. + +#### Scenario: A relationship is planned but not built + +- **WHEN** a repository is intended to be used by another but is not yet +- **THEN** its documentation says so, rather than describing the intended state + as current + +#### Scenario: A dependency is removed + +- **WHEN** a repository stops depending on another +- **THEN** the documentation describing that relationship is removed in the same + change + +#### Scenario: A library is replaced + +- **WHEN** a repository migrates from one library to another +- **THEN** its documentation and its dependency installation are updated in the + same change, so neither names the library it left + +#### Scenario: Documentation points at a directory + +- **WHEN** documentation tells a reader where something lives +- **THEN** that path exists, or the documentation says it does not yet + +#### Scenario: One repository describes another's tooling + +- **WHEN** a repository's documentation states which library a different + repository uses +- **THEN** the claim is removed, because nothing updates it when that repository + changes + +### Requirement: A cross-reference resolves to what it names + +A reference naming where content lives SHALL resolve to that content. Moving +content SHALL include repointing every reference to it, in the same change. + +A reference SHALL be checked against the content, not the path. A path that +still resolves does not establish that what it once held is still there. + +#### Scenario: Content moves out of a file that remains + +- **WHEN** a document's content is moved to another file, and the original file + is kept as a pointer +- **THEN** references into the original are repointed, because the file still + resolves while the section it named no longer exists + +#### Scenario: A reference names a section anchor + +- **WHEN** documentation links to a heading in another file +- **THEN** that heading exists in that file + +#### Scenario: A symbol is cited by location + +- **WHEN** documentation tells a reader which file defines a function +- **THEN** the function is defined there, and a refactor that moves it updates + the citation + +#### Scenario: A reference attributes a rule to a file + +- **WHEN** documentation justifies a decision as following a rule "per" a named + file +- **THEN** that file states the rule, rather than having handed it off to + another file + +### Requirement: A counted claim matches what it counts + +Documentation stating how many of something exists SHALL match the code. A +document SHALL NOT state a count it does not derive, and a table enumerating +items SHALL contain only items of the kind it names. + +#### Scenario: A count is stated in prose + +- **WHEN** documentation says how many fields carry a particular tag +- **THEN** the number matches the code, or the prose describes the set without + counting it + +#### Scenario: A table mixes two kinds of row + +- **WHEN** a table listing one kind of item contains rows pasted from a table + above it +- **THEN** the foreign rows are removed, because a reader cannot tell which rows + belong + +#### Scenario: The set grows + +- **WHEN** an item of the counted kind is added +- **THEN** the count is updated in the same change, or the prose is rewritten so + no count needs maintaining