You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit aa9814f
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: openspec/specs/infrastructure/spec.md
+8-11Lines changed: 8 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -276,26 +276,23 @@ The second check verifies that every `### Requirement:` heading sits under `## R
276
276
-**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
277
277
-**THEN** the visibility step SHALL fail, because everything after that point is unreadable to the check as well as to the parser
278
278
279
-
### Requirement: Unarchived OpenSpec changes fail on main only
279
+
### Requirement: No check requires an OpenSpec change to be archived
280
280
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.
282
282
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.
284
284
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.
289
286
290
287
#### Scenario: Unarchived change on a pull request does not fail
291
288
292
289
-**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
294
291
295
-
#### Scenario: Archived changes pass
292
+
#### Scenario: Unarchived change on main does not fail
296
293
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
299
296
300
297
### Requirement: Workflow uses pnpm matching packageManager field
0 commit comments