docs(T4.2): v4.0.0 train rollback runbook - #293
Merged
Conversation
Written BEFORE any v4.0.0/folio-v1.0.0 tag exists, per the plan's own scheduling (T4.2 has no dependency on T4.0/T4.1/T4.1b/T4.1c and gates T4.3). Covers: - Path A: craft revert map (dev->main merge-commit revert, Homebrew re-point via craft.rb url+sha256, GitHub release annotated not deleted since a prior good version exists to point users to). - Path B: folio revert map (release+tag deletion appropriate here specifically because this is folio's FIRST release - no prior version exists, so nothing to annotate a "superseded" note toward; formula removed entirely, not downgraded, since it's created fresh in T4.3). - Explicit sequencing invariant: craft must not tag v4.0.0 before folio's release is confirmed fully live. - Path C: the partial-rollback question (folio ships, craft stalls) is deliberately left unresolved - stated as a question with arguments on both sides, not answered. This was flagged during Phase 4 planning as needing a human decision; the runbook's job is to make sure whoever hits this scenario sees the question, not to guess an answer for them. Homebrew automation detail confirmed by reading homebrew-release.yml: it pushes directly to homebrew-tap's main via a GitHub App token, no PR step - the runbook's revert commands reflect that (direct commit+push, not a PR-and-merge cycle, for the tap repo specifically; craft's and folio's own main branches DO go through a revert PR, per their branch protection).
Data-Wise
added a commit
that referenced
this pull request
Jul 16, 2026
T4.0-T4.2 complete (folio sync, /folio:do router+tests+docs, rollback runbook PR #293). T4.3 complete: folio v1.0.0 released, homebrew-tap manifest entry (PR #141) + test_paths audit fix (PR #142), brew install/audit verified clean. Adds the two /goal-ready SPEC files authored during Phase 4 planning.
Data-Wise
added a commit
that referenced
this pull request
Jul 16, 2026
Version bump from 2.61.2 to 4.0.0 via bump-version.sh (47 commands, 2 agents, 40 skills, 64 specs). Converts CHANGELOG.md/docs/CHANGELOG.md Unreleased section to 4.0.0, expanding docs/CHANGELOG.md with the full PR list since 2.61.1 (#279 through #293). Closes gaps surfaced by pre-release-check.sh's doc-coverage and docs-staleness gates: - Missing REFCARD rows (code:demo, git:issue-check) and mkdocs.yml nav entries (code:demo, site:deploy); new docs/commands/code/demo.md and docs/commands/site/deploy.md written (no prior site page existed for either command). - audit-router skill (T3.6) was never added to docs/skills-agents.md. - v4 rollback runbook added to mkdocs.yml nav. pre-release-check.sh 4.0.0: PASSED (remaining items are cross-repo or pre-existing advisories: homebrew-tap's craft.rb desc count, a pre-existing internal-doc nav gap, and .STATUS drift notes). Full pytest suite: 2637 passed, 0 failed. CI bash suites all green (branch_guard_e2e's sole failure is the documented runner-sensitive perf test, confirmed via SKIP_PERF).
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
Rollback runbook for the v4.0.0 train (
ORCHESTRATE-folio-split.mdPhase 4, T4.2 —docs/specs/SPEC-v4-rollback-runbook-2026-07-16.md). Written BEFORE any v4.0.0/folio-v1.0.0 tagexists, per the plan's own scheduling — T4.2 has no dependency on T4.0/T4.1/T4.1b/T4.1c and
gates T4.3 (folio can't release until this exists).
main, Homebrew re-point (craft.rburl+sha256),GitHub release annotated (not deleted — a prior good version exists to point users to).
release/tag and removing the formula entirely — there's no prior version to fall back to or
downgrade toward. Confirmed via
homebrew-release.ymlthat the tap-repo push is direct(GitHub App token, no PR step) — the runbook's commands reflect that specifically for the tap
repo, while craft's/folio's own
mainreverts go through a PR per their branch protection.confirmed fully live.
stalls. Per the open judgment call flagged during Phase 4 planning, this is presented as a
question with arguments both ways, not answered — the runbook's job is to make sure whoever
hits this scenario sees the question, not to guess for them.
Test plan
Docs-only PR, no code/test changes. Verification is a read-through, per the SPEC's own Test
Plan section — no pytest/CI tier applies to a runbook. Pre-commit hooks (markdownlint,
mermaid-validate, etc.) passed clean on commit.
🤖 Generated with Claude Code