diff --git a/openspec/changes/document-system-architecture/design.md b/openspec/changes/document-system-architecture/design.md index e282789..1376f8a 100644 --- a/openspec/changes/document-system-architecture/design.md +++ b/openspec/changes/document-system-architecture/design.md @@ -155,3 +155,29 @@ rule to a directory named `examples/`. Rejected — the property that matters is whether the directive crosses a repository boundary, and a rule written against a directory name would miss a nested tool module and would not survive anyone choosing a different name. + +## The module path was not the only wrong home + +Renaming the module surfaced two more declarations naming `retr0h`, neither of +them a module path and neither reachable by the requirement that governs one: + +- `docs/docusaurus.config.ts` sets `organizationName: 'retr0h'` three lines + below `url: 'https://osapi-io.github.io/'`. The file contradicts itself, and + the site publishes anyway. +- `contributing.md` links Discussions to `retr0h/go-gilt` — not a former owner + of this repository, but a different project entirely, carried in by whatever + the file was copied from. + +A wrong module path fails loudly: the toolchain cannot resolve it. These fail +quietly — the build passes, the site deploys, and the link lands on somebody +else's project. That asymmetry is the reason to state the requirement in terms +of where a repository says it lives rather than in terms of Go modules. + +Attribution is excluded. `@retr0h` as a document's author, `NOTE(retr0h)` in a +comment, and the `retr0h` entry in `repos.json` branch protection all name a +person, and a person does not move when a repository does. + +*Alternative considered:* fold these into `correct-documentation-drift` under "a +cross-reference resolves to what it names". Rejected for the Docusaurus setting +— a deployment config is not a cross-reference, and stretching that requirement +to cover it would make it mean any wrong string anywhere. diff --git a/openspec/changes/document-system-architecture/specs/module-dependencies/spec.md b/openspec/changes/document-system-architecture/specs/module-dependencies/spec.md index b0aad60..915164e 100644 --- a/openspec/changes/document-system-architecture/specs/module-dependencies/spec.md +++ b/openspec/changes/document-system-architecture/specs/module-dependencies/spec.md @@ -21,6 +21,35 @@ A Go module SHALL declare a path matching the repository that holds it. - **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 diff --git a/openspec/changes/document-system-architecture/tasks.md b/openspec/changes/document-system-architecture/tasks.md index b303f90..05c8835 100644 --- a/openspec/changes/document-system-architecture/tasks.md +++ b/openspec/changes/document-system-architecture/tasks.md @@ -19,10 +19,18 @@ Sequenced: `osapi` renames and publishes before `osapi-orchestrator` moves. - [ ] 3.1 `gohai` — describe the consumer relationship it has, not the one intended + - [ ] 3.2 Confirm no repository documents a `replace`-based linkage + - [ ] 3.3 Confirm no `go.mod` contains a `replace` directive pointing outside its own repository +- [ ] 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 + different project + ## 4. Verification - [ ] 4.1 Confirm every module path matches its repository location @@ -30,3 +38,5 @@ Sequenced: `osapi` renames and publishes before `osapi-orchestrator` moves. holds it - [ ] 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, + excluding attribution of a person