Skip to content

Commit aa9814f

Browse files
committed
docs(openspec): the infrastructure spec asserted the gate this PR removes
`### Requirement: Unarchived OpenSpec changes fail on main only` described the `validate.yml` step deleted here, in detail, down to "a stack that merges forward leaves `main` red until its final slice" — the behaviour this change exists to end. Missed on the first pass. CLAUDE.md and the iterate-pr skill were updated because they are where a person goes to read about the workflow; the spec is the repo's own source of truth for infrastructure behaviour and is exactly the place the claim "documentation follows the code" had to reach. Nothing would have caught it. `openspec validate --all --strict` checks that a spec is well formed and `openspec-visibility.cjs` checks that the parser can see every requirement; neither compares a requirement against the workflow it describes. The drift would have sat there being read as true. Kept as a NEGATIVE requirement rather than deleted. "No check requires a change to be archived" is itself a property worth asserting, and it carries the reasoning that produced it: two gates, both measuring "work is in progress" when the thing worth detecting is work that stalled. Deleting the requirement outright would have thrown that away and invited a third gate. Found by the review on #218.
1 parent b1750ce commit aa9814f

1 file changed

Lines changed: 8 additions & 11 deletions

File tree

  • openspec/specs/infrastructure

‎openspec/specs/infrastructure/spec.md‎

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -276,26 +276,23 @@ The second check verifies that every `### Requirement:` heading sits under `## R
276276
- **WHEN** a spec reaches end of file with a code fence still open, as happens when an opening fence is lost and its closer is left dangling
277277
- **THEN** the visibility step SHALL fail, because everything after that point is unreadable to the check as well as to the parser
278278

279-
### Requirement: Unarchived OpenSpec changes fail on main only
279+
### Requirement: No check requires an OpenSpec change to be archived
280280

281-
The workflow SHALL fail when `main` carries a directory under `openspec/changes/` other than `archive/`, and SHALL make that check on `push` events to `main` only. No pull request check SHALL require a change to be archived.
281+
No workflow SHALL fail because a directory other than `archive/` exists under `openspec/changes/`, on a pull request or on `main`. An unarchived change directory is the normal state of work in progress, and nothing reports it.
282282

283-
An unarchived change directory is the normal state of a pull request — a change is archived exactly once, on the last slice of the work — so a pull-request gate has to infer stack position to avoid firing on work still in flight, and a check that is expected-red across most of a stack trains people to ignore red. On `main` the question has an unambiguous answer: once the work has landed, whatever remains under `openspec/changes/` is debris. A stack that merges forward leaves `main` red until its final slice archives the change; that red blocks nothing, because branch protection reads each pull request's own `Validate` run.
283+
Two gates were tried and both measured the wrong thing. A pull-request gate had to infer stack position to avoid firing on work still in flight, and a check that is expected-red across most of a stack trains people to ignore red. Moving it to `main` removed those false positives and introduced a worse one: a stack that merges forward leaves its change directory on `main` until the final slice, so `main` ran red for as long as the stack took to drain. A signal that is expected to be red is not a signal.
284284

285-
#### Scenario: Unarchived change on main fails the workflow
286-
287-
- **WHEN** a commit is pushed to `main` and a directory other than `archive/` exists under `openspec/changes/`
288-
- **THEN** the workflow SHALL fail, naming each unarchived directory
285+
Both versions detected "work is in progress". What is worth detecting is work that stalled and was abandoned, and the directory looks identical in either case, so neither gate could tell them apart. A replacement that measures abandonment rather than activity is a separate piece of design.
289286

290287
#### Scenario: Unarchived change on a pull request does not fail
291288

292289
- **WHEN** a pull request carries an unarchived change directory under `openspec/changes/`
293-
- **THEN** the workflow SHALL NOT fail for it, because the check is skipped on pull request events
290+
- **THEN** no check SHALL fail for it
294291

295-
#### Scenario: Archived changes pass
292+
#### Scenario: Unarchived change on main does not fail
296293

297-
- **WHEN** a commit is pushed to `main` and `openspec/changes/` holds only `archive/`
298-
- **THEN** the check SHALL succeed
294+
- **WHEN** a commit is pushed to `main` and a directory other than `archive/` exists under `openspec/changes/`
295+
- **THEN** no check SHALL fail for it, because a forward-merging stack is expected to leave one there until its final slice
299296

300297
### Requirement: Workflow uses pnpm matching packageManager field
301298

0 commit comments

Comments
 (0)