docs(specs): repair the shipped-spec task ledger and gate it - #698
Merged
Merged
Conversation
Both specs reached main with Status: Shipped and every one of their tasks unticked, although each task had landed in the same pull request that shipped the spec (#659 and #666). The boxes and the history then disagree, and completed work reads as outstanding. Tick all nine tasks of the prefetch spec and all eight of the image-source spec; no wording changes. Signed-off-by: thxCode <thxcode0824@gmail.com>
The document was a working scope draft for a verification pass, not a specification of anything the repository ships: nothing in the tree references it, and its content lives on in the task records it summarizes. A spec on main is a contract with its readers, and this one has no implementation to contract with. Signed-off-by: thxCode <thxcode0824@gmail.com>
The S6 and S7 specs reached main with every task unticked although the
work had landed, and the only thing that caught it was a reader. Add a
fifth rule to check-specs.sh: in a Shipped spec, an unticked task's
block must say why it stays open -- a written deferral ('tracked as',
'routed to', 'left unticked', 'deferred', 'moved to', 'parked',
'NOT DONE') or a 'Blocked by:' naming an external blocker. A list of
the plan's own task numbers is its ordering, not a deferral, and 'None'
or a bare dash says nothing; both are reported.
The five legitimately open tasks already on main -- each blocked on
hardware or routed elsewhere in writing -- pass unchanged and are the
rule's baseline. Verified against the pre-fix S7 spec: seven of its
eight unticked tasks are caught, the eighth names a real sentence and
is the accepted hole of a tripwire rule. The selftest gains the shapes
in both directions, including the ordering-is-not-a-deferral case.
Signed-off-by: thxCode <thxcode0824@gmail.com>
|
✅ OpenCodeReview: Review skipped: no items were selected. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
/kind documentation
/kind cleanup
What this PR does / why we need it:
Repairs the shipped-spec task ledger and adds the gate that should have caught its drift.
Two pieces of ledger corruption surfaced on main:
specs/2026-09-27-model-prefetch.md(shipped in feat: prefetch model weights onto nodes with tenant budgets and pins #659) andspecs/2026-09-27-model-image-source.md(shipped in feat: add the OCI image source to ModelArtifact #666) reached main with Status: Shipped andevery one of their tasks unticked, although each task had landed in the same pull request. The
boxes and the history disagreed, and completed work read as outstanding. This PR ticks all nine
and all eight tasks; no wording changes. (
specs/2026-09-27-model-peer-sync.md, reported in thesame breath, was checked and is clean: all six of its tasks were ticked in its own shipping
commit.)
specs/2026-09-28-closure-verification.mdwas a working scope draftfor a verification pass, not a specification of anything the repository ships. Nothing in the
tree references it. Removed.
The reason both could happen: nothing reads a spec's task list. This PR adds a fifth rule to
check-specs.sh— in a Shipped spec, an unticked task's block must say why it stays open, eitherwith a written deferral (
tracked as,routed to,left unticked,deferred,moved to,parked,NOT DONE) or with aBlocked by:naming an external blocker. A list of the plan's owntask numbers is the plan's ordering, not a deferral;
Noneand a bare dash say nothing. The fivelegitimately open tasks already on main — each blocked on hardware or routed elsewhere in writing —
pass unchanged and serve as the rule's baseline. Verified against the pre-fix S7 spec: seven of its
eight unticked tasks are caught (the eighth's
Blocked bycarries a real sentence, the acceptedhole of a tripwire rule). The selftest gains the shapes in both directions, including the
ordering-is-not-a-deferral case and the non-Shipped escape.
Which issue(s) this PR links to:
None — reported directly.
Special notes for your reviewer:
Gate evidence on this branch:
check-specs.shgreen over the fixed tree (60 specs), the selftestgreen with the six new cases,
make lint docsgreen,check-agents-shellclean on both scripts.Does this PR introduce a user-facing change?