docs(v1.85.0): post-ship retrospective fixes for v1.84.0#437
Merged
Conversation
Independent Fable + Codex audit of the just-shipped v1.84.0 release found 4 gaps in CLAUDE_CODE_SDLC_WIZARD.md: - Stale "7 rounds" example (actually 11); round 8, not round 5, was the sharper illustrative finding - Missing "CERTIFIED is not the finish line" lesson (cross-model review and CI are different verification layers) - CI Feedback Loop section weaker than skills/sdlc/SKILL.md's own copy (missing NEVER AUTO-MERGE, read-logs-even-when-green, cross-model CI-log audit) - No Policy Migration Inventory checklist item, despite SDLC.md already documenting this exact lesson from v1.84.0 Also settles ROADMAP #437's open design question (commit_sha-based staleness check, implementation to follow as a separate TDD PR) and records maintainer intent for #434/#438 (Fable-led sibling-repo sync after this release, not GH issue posting from this session). Version bumped 1.84.0 -> 1.85.0 across all tracked locations. Codex cross-model review (2 rounds) caught 2 more stale version pointers outside the documented checklist (ROADMAP.md living-tracker row, cowork/README.md) - fixed, and the checklist itself updated so the gap doesn't recur.
7 tasks
BaseInfinity
added a commit
that referenced
this pull request
Jul 6, 2026
CI's test-cowork-drift.sh caught cowork/skills/sdlc/SKILL.md drifting from the canonical skills/sdlc/SKILL.md -- the commit_sha instructions added for #437 in the previous commit never got copied to this second tracked location. Byte-for-byte cp of content already certified in PR #438's round-3 review. Fast-tracked through a scoped 2-round Codex check (round 1 correctly flagged the fix wasn't actually staged yet; round 2 confirmed staging + re-verified the diff-empty/tests-pass content).
BaseInfinity
added a commit
that referenced
this pull request
Jul 6, 2026
…438) * fix(hooks): codex-gate-check.sh stale-certification loophole (#437) A CERTIFIED/REVIEWED handoff.json status was checked as a literal string with no freshness check -- any number of commits made after certification would sail through the gate on the same stale status forever. Proven live during the v1.84.0 release: 2 real post-certification commits both passed the gate on a round-11 CERTIFIED handoff that was never re-issued. Certification now records commit_sha (HEAD at cert time) in handoff.json; the gate compares it to current HEAD and treats a mismatch -- or a missing field, e.g. an old-format handoff.json predating this fix -- as stale (exit 2, same as an uncertified commit). This allows exactly one commit after certification and blocks the next one until re-cert. CODEX_GATE_SKIP=1 remains the logged-justification escape hatch. TDD: 2 new tests proven RED against the unmodified hook, GREEN after; 2 existing tests updated to real git-repo fixtures with a matching commit_sha (191/191 hook tests green, up from 189). 3-round Codex cross-model review: round 1 caught a second, duplicate copy of the review protocol in the wizard doc missing the commit_sha instruction. Round 2's mutation testing proved the first regression test (a whole-file count comparison) had real slack, and surfaced a third, entirely separate flow-diagram copy that had also been missed. Rebuilt the test as a per-line proximity check and proved it against all 3 mutation scenarios independently before round 3 certified clean. Also fixes a latent bug in tests/test-self-update.sh's multi-reviewer checks (bare ? treated as literal in basic regex, not a quantifier), exposed while trimming skills/sdlc/SKILL.md back under its char budget. Version bump 1.85.0 -> 1.86.0. * fix(cowork): sync sdlc SKILL.md drift caught by CI (PR #438 follow-up) CI's test-cowork-drift.sh caught cowork/skills/sdlc/SKILL.md drifting from the canonical skills/sdlc/SKILL.md -- the commit_sha instructions added for #437 in the previous commit never got copied to this second tracked location. Byte-for-byte cp of content already certified in PR #438's round-3 review. Fast-tracked through a scoped 2-round Codex check (round 1 correctly flagged the fix wasn't actually staged yet; round 2 confirmed staging + re-verified the diff-empty/tests-pass content).
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.
Summary
Independent Fable + Codex retrospective audit of the just-shipped v1.84.0 release found 4 doc gaps in
CLAUDE_CODE_SDLC_WIZARD.md(the portable doc that ships to every consumer repo):CI Feedback Loopsection was measurably weaker thanskills/sdlc/SKILL.md's own copy of the same section — synced (NEVER AUTO-MERGE, read-logs-even-when-green, cross-model CI-log audit)SDLC.mdalready documenting this exact lesson from v1.84.0 — graduated it into the portable docAlso:
ROADMAP.mddocs(v1.85.0): post-ship retrospective fixes for v1.84.0 #437's previously-open design question (commit_sha-based staleness check for the codex-gate hook) — implementation is a separate, standalone TDD PR, not bundled hereROADMAP.mdliving-tracker row,cowork/README.md) — fixed, and the checklist itself updated so this class of miss doesn't recur. Round 2: CERTIFIED.Doc-only release — no hook, skill logic, or CLI behavior changes.
Test plan
test-doc-consistency.sh— 52/52test-wizard-doc-hook-templates.sh— 3/3test-postmortem-lessons.sh— 7/7test-docs-usability.sh— 29/29 (confirms version pointer parity)test-hooks.sh— 189/189test-cli.sh— 97/97test-self-update.sh— 153/153test-plugin.sh— 26/26