Skip to content

release-checklist.md

Latest commit

 

History

History
104 lines (87 loc) · 13.6 KB

release-checklist.md

File metadata and controls

104 lines (87 loc) · 13.6 KB
Raw

Release Checklist

Release evidence must be sanitized and attached to the release decision. Do not invent application, MCP, tag, or compatibility versions.

Release evidence (leave blank until observed)

Field Observed value
Candidate commit
Codex Desktop version/build
codebase-memory version/commit
Final immutable tag
  • Disposable Codex Desktop E2E completed and evidence sanitized.
  • Final immutable tag created with separate maintainer authorization.

Deterministic gate

Run from the repository root on Windows PowerShell 5.1:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\preflight.ps1 -SelfTest
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\preflight.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\index-mode.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\source-input.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\chain-store.tests.ps1
node --test .\scripts\dispatch-return-runtime.tests.mjs
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\init-controller.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\control-state.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\task-set-reset.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\skill-size.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\skill-contract.tests.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\preflight.ps1 -ReleaseGate

In the installed maintainer environment, also run the official Skill validator supplied with Codex and record its exact command and result. Do not add that environment-owned path to repository CI.

Disposable Codex Desktop gate

Record the actual Codex Desktop and codebase-memory versions used, then verify with disposable, non-sensitive directories:

  • save the exact controller root as a Codex project through the app;
  • initialize and verify the bounded controller and memory-store scaffold;
  • confirm ignored derived views are generated by Rebuild and are not required as untrackable template seeds;
  • create, update, and terminally archive a CHAIN through exact head-hash CAS; prove stale writes fail, exact replay is idempotent, and direct derived-view tampering fails verification;
  • migrate at least 501 terminal CHAINs in a disposable controller; prove startup memory stays at or below 200 lines and 25 KiB, the compact index retains exact totals with at most 500 terminal summaries, and Get still resolves an omitted archived CHAIN;
  • create, read, and reuse one local controller task bound to that exact saved project;
  • reject stale, archived, wrong-project, and wrong-host task IDs;
  • clear one proven stale controller binding and replace one stale project binding using exact CAS-protected reconciliation evidence;
  • prove a controller failure does not block an otherwise ready project;
  • enqueue two tasks for one project and one for another; prove same-project FIFO, independent-project concurrency, exact replay idempotency, and write-lease retention/release;
  • reject a new enqueue without closed readiness and an exact return route; prove read-only target/capability discovery happens before attempt one, external writes require an opaque capability reference, rollback/verification are frozen, and credential-file locators are rejected;
  • send one single sealed dispatch via ExportDispatch as closed single-line JSON, verify dispatchHash, identity-bound taskSpecHash, and a different hash after resealed rework; force delivery-unknown and prove timeout never resends while authoritative non-delivery permits only one same-attempt reopen;
  • explicitly complete a project task in native-callback mode and prove it sends one compact best-effort wake to the sealed controller task; the callback alone changes no canonical state, targeted read_thread supplies the evidence, and an uncertain callback is not retried;
  • exercise three attempts total—initial, whole-batch repair, architecture rebaseline—and prove the next result is CONVERGENCE_FAILED with no automatic successor;
  • prove a terminal completed implementation retains its lease, can consume the shared retry budget when acceptance or review fails, and becomes convergence-failed when later review fails after the final attempt;
  • return a stable resultState=blocked packet with the exact frozen task hash and prove the CHAIN and lease remain blocked without inventing another task state;
  • exercise economy, balanced, and frontier routing; prove rework persists the same or a higher evidence-backed class, rejects downgrade, and never escalates merely for waiting or another example;
  • reject credential-bearing/open-schema Git input, collapse a semantic duplicate, and reject duplicate sources with conflicting per-source options before Git;
  • exercise the complete pressure scenario in controller-bootstrap.md;
  • verify the four-quadrant intake asks at most three material questions in one round, otherwise proceeds with assumptions, and converts a shared unknown into a one variable experiment with explicit success/failure signals;
  • verify approval_policy="on-request", sandbox_mode="workspace-write", and approvals_reviewer="auto_review" in a disposable profile;
  • confirm a routine workspace call needs no manual prompt, an eligible boundary uses auto-review, and a high-risk or Computer Use boundary still requires the user;
  • hold one unresolved runtime approval and prove there is no follow-up, retry, or new invocation for that project while unrelated work continues;
  • record cancelRequestedAt during that approval and prove the controller must not claim the call stopped; after ten one-minute foreground snapshots, return monitoring-paused without changing the manifest dispatch phase, evidence, or lease and without a controller-bound recurring heartbeat;
  • with the trusted Stop Hook enabled, prove capability preflight selects receipts-and-wake; export without sending, register the complete sealed identity and dispatchHash, verify runtime readback and the exact envelope, then deliver and finish it after monitoring-paused; prove one atomic receipt is written without full assistant content and unchanged inboxes are silent;
  • without one required Hook, Node, rule, worker, or heartbeat capability, prove omitted mode falls back to native-callback, then foreground; an explicitly requested unavailable mode blocks only that return lane;
  • return one terminal transport/tool-bootstrap/payload-parse failure before repository work; prove record-dispatch-outcome binds its exact failureClass to the same terminal evidenceHash, branch, HEAD, and dirty hash still match, and reconcile-preflight-failure reopens it once without consuming a business attempt; reject a mismatched class/hash, review evidence, or changed baseline, and prove the later same-dispatch turn receives a distinct turnId-bound receipt;
  • prove ~/.codex/skill-state/onboard-code-projects is absent from global writable_roots; worker-safe calls use the runtime's fixed default registry and must not accept an explicit --state-path; validate with codex execpolicy check that only node + exact installed Skill runtime + worker-safe subcommand is allowed, while capture-stop, acknowledgement/unregister/controller replacement, any --state-path, a payload state-path override, a controller-writable runtime copy, and another script are unmatched;
  • prove the poller cannot accept, mutate, or acknowledge business state; require targeted task evidence before canonical persistence and receipt acknowledgement, reject malformed/stale/wrong-task/wrong-root/non-terminal/renamed receipts, and retry only an unacknowledged claim after its lease;
  • confirm an existing task-level permission override needs one in-task mode selection, with reload/restart only for changed global configuration, and never causes entry-task recreation;
  • verify an observed recurring boundary uses only a narrow writable_roots entry or precise prefix rule, requires explicit user authorization, and never uses danger-full-access or disabled approval;
  • confirm no projectless or worktree controller/entry task exists;
  • from a disposable task outside the reset set, run a write-free task-set reset Plan and a separate Apply of its exact hash against an exact generated v3 controller. Prove only operation/from/strictly-derived-to/coordinator/exact old bindings/target roots/creation IDs/expected saved-project IDs/hosts bind the hash; summaries, history digests, quiescence, CHAIN heads, and timestamps do not. Prove initialEvidenceHash binds the complete closed Apply history/quiescence/active-CHAIN packet and finalEvidenceHash binds the final archived-history/quiescence/active-CHAIN packet; adapters recompute and audit changed evidence without another user authorization and reject forged evidence;
  • prove the runtime reset fence is prepared and read back before manifest Apply; then prove Apply creates project bootstrap tasks once and the controller bootstrap task once in standby with only the unique creation marker and no business handoff, fully reads/sanitizes/pre-summarizes old history, archives/readbacks old projects then old controller, rebuilds the final full summary when archived digest drifted, persists/delivers final handoffs, verifies standby acknowledgements, then performs runtime replacement prepare, manifest switch, runtime replacement commit/readback, manifest completion seal, runtime fence completion against the exact seal/manifest hash, RecoverTaskSetResetSeal as the sole unfreeze, and external-coordinator archive;
  • reproduce historyDigest by reading to hasMore=false, ordering closed {turnId,status,completedAt} rows oldest-to-newest, hashing UTF-8 compact JSON with SHA-256, and checking oldest/newest/count/EOF. Prove message text and tool output never enter the digest or replacement prompt and the sanitized summary has a separate summaryHash;
  • fault every reset boundary and prove forward-only same-operation recovery rebuilds final handoff from complete archived history, with no delta handoff, CHAIN mutation/rebinding, duplicate create, worker, automation, or false completion. Prove a seal marker blocks controller, CHAIN, and runtime writes until exact runtime completion readback releases it; a missing runtime packet may repair history/manifest but cannot unfreeze. For an empty/client-only/timeout create result, prove create_thread is never retried: reconcile only by unique marker plus exact saved project/root/host and initial-turn readback; zero or multiple matches remain frozen/unknown. Prove missing task APIs, ambiguous/multi-root or unprovable cwd, custom/legacy/store-backed v2, changed stable scope, nonquiet state, forged closed readback packets, and stale CHAIN heads fail closed;
  • sanitize roots, IDs, prompts, and tool output before retaining evidence.

Dogfood records

Complete 3-5 dogfood records before release. Leave rows unchecked and blank until each scenario is actually run; never infer or prefill results.

Done Scenario Date TTHW Manual interventions Tasks created Wrong-project incidents Duplicate-task incidents Reason codes Outcome
[ ]
[ ]
[ ]
[ ]
[ ]

Upgrade and rollback rehearsals

  • Immutable pre-controller upgrade: install an old immutable pre-controller revision, capture its no-controller v1 result, upgrade to the candidate, and prove the same no-controller request still returns the exact v1 per-project schema.
  • Legacy trusted-controller separation: exercise an old trusted-controller input and the new generic controller input separately. Confirm the candidate does not reinterpret or automatically migrate legacy state, files, or bindings.
  • Generated controller upgrade: install exact immutable pre-store v1 and pre-store v2 controllers. Prove the first result requires separate authorization, then run Plan → authorized Apply → Verify. Confirm only state present in those exact known manifests survives, the memory store verifies, a caught partial replacement rolls back, and edited, custom, unknown, or store-backed v2 inventories fail closed for a separately reviewed migration.
  • Legacy ledger shadow migration: prepare and verify without changing sources, retain source hashes and semantic-validator hash, prove a source change blocks cutover, preserve exact legacy bytes, and apply only after authoritative evidence says the controller task is idle.
  • Rollback rehearsal: after a disposable candidate run, stop dispatch, restore the prior immutable revision, preserve the controller manifest and tasks, and prove existing project entry tasks remain usable without destructive cleanup.

Release and rollback

  • Confirm README links and Simplified Chinese UTF-8 rendering.
  • Confirm CHANGELOG.md describes only Unreleased work until an authorized release is cut.
  • Tagging, pushing a tag, or creating a release requires separate maintainer authorization. Use an immutable tag only after every gate passes.
  • To roll back, follow the completed rollback rehearsal: stop new dispatch, preserve the failing manifest and sanitized evidence, restore the prior immutable source revision, and use only confirmed adapter cleanup for matching intents/candidates. Do not delete user repositories, Codex projects/tasks, indexes, or controller state as part of package rollback.