Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions openspec/changes/specify-documentation-homes/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,3 +161,29 @@ drops the others.
*Alternative considered:* convert `CLAUDE.md` to a pointer first and sort the
content afterwards. The conversion is what forces the decision about each block,
so deferring it means writing a `CONTRIBUTING.md` that has to be rewritten.

## One rule was about to be deleted with its only record

Reviewing the 76 planning documents before removal, as section 4 requires, found
seventy that were implementation choreography for shipped work and six that
carried decision rationale. Five of the six describe architecture that the
repository still documents. One does not.

The unified-domain-endpoint plan decided to remove `POST /job` and route all job
creation through domain endpoints. The rule still binds — the only `post:`
remaining on the job API is `/api/job/{id}/retry`, an action on an existing job
rather than a way to create one — but no current document states it. Not
`api-guidelines.md`, not `architecture.md`, not `CLAUDE.md`.

That makes it invisible in a specific way: the rule is expressed as an endpoint
that is *absent*, so nothing a reader opens will mention it, and a contributor
adding a domain has no way to discover the constraint before violating it.

Relocating what the architecture documents say would not have produced this
requirement, because those documents do not say it. It needed its own task, or
deleting the planning directory would have removed the last written record of a
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.
5 changes: 5 additions & 0 deletions openspec/changes/specify-documentation-homes/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,11 @@
messages, linting, and test conventions across `CLAUDE.md`, `development.md`,
and `testing.md` before the root `CONTRIBUTING.md` is written, so the
conversion has one source to draw from
- [ ] 3.9 `osapi` — capture "job creation goes through domain endpoints" as a
requirement. Removing `docs/plans/` deletes its only written record: the rule
still binds (the sole `post:` on the job API is `/api/job/{id}/retry`, an
action on an existing job) but is stated in no current document, so relocating
what `api-guidelines.md` and `job-architecture.md` say will not produce it
- [ ] 3.7 Leave each source document in place as a pointer to the capability
- [ ] 3.8 `osapi` — leave `architecture.md`, `system-architecture.md`, `ui.md`,
and the eight-step "Adding a New API Domain" walkthrough in the repository;
Expand Down