Quirl release checklist

This checklist turns the release requirements into a repeatable Unix release. The checkboxes are a reusable operator template and intentionally reset for a new candidate; they are not the status display for an already published version. Each run applies to one exact candidate commit and artifact. A pass from an older commit is useful history, not release evidence. Linux and macOS are the supported interactive platforms. Windows is explicitly outside this release gate under ADR 0010. The capable-TTY default and retained Reedline fallback are governed by ADR 0012; shared theme behavior is governed by ADR 0013. Rust-native release and downloadable-asset ownership is governed by ADR 0026; the operator procedure is documented separately.

This checklist uses two explicit revisions:

candidate commit A is the source revision used to build, measure, record, tag, and publish the binary. The version tag and source archives point to A.
evidence commit B is an optional later documentation-only commit that may record A's measured results or link reviewed release assets. B never replaces, rebuilds, or relabels A. Any code, manifest, generated-contract, dependency, or release-profile change requires a new candidate A and a fresh gate.

v0.3.0 publication record

Quirl 0.3.0 was published on 6 September 2026:

The nondraft, non-prerelease, immutable v0.3.0 GitHub Release and tag identify candidate commit dfb43e54320d166ebe195bb5a0255b8aacbb11e5. Publication was verified at 2026-09-06T19:34:54Z (release ID 383694213). All 15 published asset digests and byte counts, plus the exact release body, matched the reviewed bundle.
Candidate verification, canonical quality gate, all four native packages, downloadable assets, aggregation, publication, and protected Homebrew job succeeded in release run 34054071682, attempt 1. Each exact native executable passed 101 successful automated PTY samples, 404 in total. The 0.3.0 performance record links unchanged reports, executable hashes, runner details, limits, and preserved older failed candidates.
The release manifest SHA-256 is 583a36d0d4ae5ae85e336d71695480bee2624778a41f7f52ff7bdd3ec2820329; reviewed release notes SHA-256 is 3d62a1cb5830c2fb69ef103ae8a984815e42d548fade13585a23ceba0202a379. Exact archive members matched the measured executable bytes on all four targets. Size remained advisory; latency, identity, completeness, retention, and cleanup gates were enforced.
Homebrew tap PR 8 merged as 57a937fe2b674dd29e7475522889f3bc77c88711. The formula on tap main matched the audited four published archive URLs and hashes.
The release-dispatched website asset run 34055349465 passed from the released candidate and pushed asset evidence commit cffebda4b43ad57f18dd3c1e63260ef381c059af. The live version-scoped manifest matched the committed channel.
The fresh terminal recording and capture provenance identify the exact published macOS ARM64 executable, SHA-256 30a6edce509a6220cfb4c505fe0192598d56174336a8720ffd0e2042be1c53d8. VHS captured 71.12 seconds in an isolated real PTY with key input. The provenance records exact package/report/runtime-asset and media identities, automated assertions and sampled visual inspection, and explicitly records no human or physical-terminal QA signoff.

Earlier failed candidates remain documented with their original outcomes. Passing this candidate does not retroactively pass them or establish infrastructure-only causes. These verified artifact and automated-evidence facts do not check the reusable human-review boxes below.

Historical v0.2.0 publication record

Quirl 0.2.0 was published on 5 September 2026:

The nondraft, immutable v0.2.0 GitHub Release and tag identify candidate commit 39589209ff32a0ac61af984aa31e4879edb113dd. All 15 published asset digests and byte counts matched the independently verified release bundle.
Candidate verification, all four native packages, downloadable assets, aggregation, and publication succeeded in release run 33989045593. All four exact native executables passed their enforcing performance gates: 101 successful automated PTY samples per target, 404 in total. The 0.2.0 performance record links the unchanged schema 8 reports, executable hashes, runner details, and measurement limits.
The composed release run is marked failed because its downstream Homebrew PR job received an empty private-key input. The standalone Homebrew run 33990534633 succeeded; tap PR 7 merged as e6b2880dcac33f825dd36327331a560e62c84511. Its four archive URLs and hashes matched the published manifest. Recovery did not replace any release asset or move the version tag.
The release-dispatched website asset run 33990164031 admitted the version-scoped channel with the released binary and pushed asset evidence commit 2981d379f046dbee6ebb56bf6291d27c4aa23616.
The recording prepared for 0.2.0 and its historical capture provenance identify a clean local ARM64 macOS build of the same candidate using the official release profile. Its binary digest differs from the hosted release asset, so the recording is not attributed to the distributed executable. VHS captured 71.2 seconds in a real PTY; the provenance records automated checks and explicitly records no human or physical-terminal QA signoff.

These published artifact and automated-evidence facts do not retroactively check every human-review item in the reusable procedure below.

Historical v0.1.0 publication record

Quirl 0.1.0 was published with the following release record:

The immutable v0.1.0 GitHub Release was published on 22 August 2026 from candidate commit 168f9f2e2f2899f7910ca64831561c8885d9ef24.
Candidate verification, cargo xtask check, all four native packages, downloadable assets, aggregation, publication, and website-channel bootstrap succeeded in the release run. That composed run is marked failed only because its initial Homebrew job did not complete; the repaired Homebrew run succeeded and the tap pull request merged.
The release operator completed human macOS, Linux, and remote PTY/SSH terminal review. The automated rich-PTY matrix remains supporting evidence rather than a substitute for that review.
The release shipped the deterministic text demo and recording recipe. At that release, no public real-terminal recording was linked from the project.
The performance record below measures an older artifact. It remains useful engineering history but is not presented as exact performance evidence for the published 0.1.0 binary.

This publication record states what can be attributed to v0.1.0 without retroactively checking steps for which no durable per-item signoff was stored. The empty checklist below remains the reusable procedure for a new candidate.

Historical exact-candidate performance evidence

Release evidence status — historical. Artifact evidence for measured candidate 23fd5d36907fc816bdafd9aa3c2dcb3afb69feb5 and artifact 9a893a5f1a0b49d62712f331c88966113d910d94efa9651dc4feffe9fd55b637 is historical. Evidence commit 14e70939d039d96c195f57452a0e1ec3928194af documents that measurement. It is evidence only for that named artifact, not for a later candidate. This historical record does not assert the release-readiness or human-review state of a later candidate.

The exact historical P14 environment, commands, aggregate measurements, and artifact identity remain in the performance record; they must not be copied into a later candidate's evidence. That historical record does not determine the readiness of a later candidate. Complete the automated, named-terminal, remote-PTY, and demo gates below against candidate A; record their exact identity and outcome in the release run or evidence commit B. The automated real-PTY harness is supporting evidence, not a human signoff.

1. Freeze the candidate

cargo xtask release plan selects the reviewed version from reachable Conventional Commits and cargo xtask release prepare shows the expected idempotent version, changelog, and notes changes without writing them.
The preparation PR was produced from cargo xtask release prepare --write; curated changelog content remains intact and only real product version sources changed.
The worktree is clean and main is synchronized with its release remote.
Cargo.lock, rust-toolchain.toml, the release profile, version strings, generated SDK, protocol manifest, and user-facing status text describe the candidate being shipped.
Curated external native command KDL has completed provenance, immutable revision, semantic, and license review. No Carapace draft or floating upstream reference is in the release source set; the importer pin identifies one reviewed immutable revision.
The compiled native catalog is QCNC schema version 1, names the intended platform facts, and has a recorded byte length and cryptographic checksum for this exact candidate. This artifact is distinct from the mutable local intelligence cache and from Catalog::builtin() metadata.
The reviewed config descriptor is schema v5, its golden fingerprint matches the candidate, and v0/v1/v2/v3/v4-to-v5 migration tests pass.
The supported compatibility boundary is unchanged: C0/C1-core is native on Linux/macOS; here-documents, process substitution, loops, functions, conditionals, and dialect control forms are explicit Bash/Zsh islands.
Deferred and best-effort work is visible in the README and release notes. In particular, do not present native Windows terminal behavior or Wasm execution as supported.

Record the candidate revision before building:

git status --short
QUIRL_CANDIDATE_COMMIT=$(git rev-parse HEAD)
export QUIRL_CANDIDATE_COMMIT
printf 'candidate A: %s\n' "$QUIRL_CANDIDATE_COMMIT"
git log -1 --format='%h %s'

2. Run the automated gate

cargo xtask check passes with the pinned Rust 1.97.1 toolchain.
cargo xtask release verify accepts the clean candidate tuple and rejects a dirty tree, mismatched binary version, or mismatched embedded commit.
The generated Lua SDK has no diff after cargo xtask sdk.
cargo xtask catalog fmt --check, cargo xtask catalog check, and cargo xtask catalog build pass; a second build is byte-identical, and the published image reopens through the hardened reader.
Catalog tests cover schema rejection, all declared byte/count/depth/query bounds, platform filtering, semantic ordering, snapshot/projection tampering, and atomic-publication cleanup. Runtime tests pass without Carapace or network access and preserve builtin/local-discovery fallback when the native artifact is unavailable.
cargo xtask rich-pty --check local-completion-discovery passes with its isolated fake Fish/Zsh providers; warm positive and negative cache tests prove deterministic restart behavior and no host rc, host completion, Carapace, or network dependency. The exact Carapace Bridge and Vincent Breitmoser notices remain present in crates/quirl-process/THIRD_PARTY_NOTICES.md.
Website dependencies were installed with npm ci --prefix website and cargo xtask website-check passes. This non-mutating gate checks generated mirror/reference freshness, semantic release-evidence attribution, lint, route type checking, and the production build using the committed website/package-lock.json.
The deterministic product tour passes against the candidate binary.
The release binary and benchmark harness are built together from the clean candidate.

cargo xtask check
cargo xtask sdk
git diff --exit-code -- docs/quirl.lua
npm ci --prefix website
cargo xtask website-check
scripts/demo.sh target/release/quirl
cargo xtask release-preview

The SDK command intentionally writes a generated file. If it changes, review and commit the source-of-truth HOST_API change and regenerated output, then restart this checklist from a clean candidate.

3. Verify the supported terminals

Run this section once on named Linux hardware and once on named macOS hardware. Record the OS version, architecture, terminal name/version, and whether a plain font or a Nerd Font was used. A glyph difference must never change behavior.

The exact commands and adversarial text-only checks are also recorded in the security and accessibility audit.

The historical P14 candidate's release artifact passed every automated scenario in cargo xtask rich-pty on actual macOS hardware. That run covered rich editing, completion, integrated runtime behavior, review regressions, native job control, noninteractive dialect islands, suspend/resume, fallback selection, and NO_COLOR. It used a programmatic 120×40 pseudo-terminal, not a named graphical terminal application. Consequently none of the human, cross-terminal, resize, remote-PTY, or Linux boxes in this section are checked.

4. Refresh performance evidence

Do not edit measurements by hand or reuse the previous digest. On an idle, named supported machine, compute the candidate binary's SHA-256 independently, then pass that exact digest to the enforcing harness:

if command -v sha256sum >/dev/null 2>&1; then
  QUIRL_EXPECTED_SHA256=$(sha256sum target/release/quirl | awk '{print $1}')
else
  QUIRL_EXPECTED_SHA256=$(shasum -a 256 target/release/quirl | awk '{print $1}')
fi
export QUIRL_EXPECTED_SHA256
printf 'candidate SHA-256: %s\n' "$QUIRL_EXPECTED_SHA256"
target/release/quirl-bench release \
  --quirl target/release/quirl \
  --expected-sha256 "$QUIRL_EXPECTED_SHA256" \
  --json

cargo xtask release-gate "$QUIRL_EXPECTED_SHA256" is the concise enforcing form when the human-readable report is sufficient; it also runs the explicit website gate and therefore requires the locked website dependencies to be installed. Use the direct command above to capture canonical JSON evidence.

The harness accepts the clean revision embedded independently in both quirl and quirl-bench, their matching source identity, the artifact profile, panic strategy, operating system, architecture, and independent digest.
All enforced PTY latency, first-prompt, explicit caller size, and bounded-history budgets pass, or the release stops with the miss preserved in the record.
The exact release binary's byte size and independent digest are recorded. At or below 5 MiB (5,242,880 bytes) is ideal; above 8 MiB (8,388,608 bytes) records an advisory warning. Investigate growth without a clear user benefit. There is no default project size ceiling; an explicit --max-binary-bytes remains enforceable. Missing size or identity evidence still blocks release. See ADR 0036.
Rich-surface draw and edit latency are measured on the selected candidate; QUIRL_UI_TIMINGS=1 is diagnostic evidence, not a substitute for the enforcing PTY harness.
The release evidence names candidate A's exact revision, artifact digest, hardware, OS, Rust version, sample counts, results, and limitations. It may be captured as a release asset first and checked into docs/benchmarks/release-v1.0.md later in evidence commit B.
The performance record and the binary intended for publication describe the same artifact. Any source or release-profile change invalidates the run.

5. Capture the real-terminal demo

The README demo must be a recording of the release binary in a real PTY, never an animation assembled to resemble terminal output. Use a fresh temporary Quirl config/state directory so personal history, paths, repository remotes, usernames, and secrets cannot appear. Set the terminal to 120×32 or another documented fixed size and keep the take short enough to understand without narration.

scripts/demo.tape is the reproducible VHS capture recipe, while cargo xtask demo is the accessible text-only companion. Record only the already-built, measured candidate A artifact:

scripts/record-demo.sh target/release/quirl "$QUIRL_EXPECTED_SHA256"

The wrapper verifies the digest before launching VHS, requires vhs, ttyd, ffmpeg, and JetBrainsMono Nerd Font, and uses the same private, disposable Quirl environment as the text tour. The recipe may automate keystrokes and timing, but every visible frame must still come from a real invocation of the candidate binary. A missing recording prerequisite is a preflight failure, not permission to substitute fabricated terminal output.

The local-search scene installs native command facts using the existing verified runtime-asset updater, then builds embeddings from the pinned local model. By default the updater uses the published release manifest. For an unpublished candidate or offline recording, pass a local manifest containing both required assets and local file:// URLs as the optional third argument. The text tour accepts the same manifest through QUIRL_DEMO_ASSET_MANIFEST:

scripts/record-demo.sh target/release/quirl "$QUIRL_EXPECTED_SHA256" /absolute/path/runtime-assets.json

AI preparation also requires GNU timeout (gtimeout on macOS). Its three setup phases each have a 120-second limit and two-second termination grace. After real interactive discovery, the tape runs the private ./prepare-search helper with one 30-second limit. It first waits for a harmless private PATH executable to appear in index explain, proving discovery published, then rebuilds the current index and checks both semantic readiness and actual hybrid retrieval. Failure stops the take; it must not be replaced with lexical output labeled as semantic search. Suggestions are candidates for human review, not verified executable plans or evidence that model rankings are always correct. The recording remains a real PTY capture, not physical-terminal testing.

Recommended shot list:

Start the exact release binary and show that auto selected the inline Ratatui frame with context and textual status.
Type part of a real command, open semantic completion, move once, and close it without hiding the prompt.
Run a short native byte pipeline and a boolean list.
Switch to data mode and run a compact structured pipeline whose typed result fits on screen.
Open the history or file overlay and select an item with the keyboard.
End on one brief explicit Bash/Zsh island or a helpful unsupported-syntax diagnostic, making the compatibility boundary visible rather than implied.

Before publishing the capture:

Watch the complete recording at normal speed and inspect individual frames around menus and mode switches.
Verify that every command and result came from the candidate binary.
Verify there is no secret, personal path, username, hostname, private repository, or unrelated shell history in the capture.
Verify the experience remains understandable in the repository's static fallback image or alt text.
Verify prompt symbols are decorative: a plain-font capture remains readable, and the recording does not tell users a Nerd Font is required.
Add the reviewed artifact to the README with its capture environment and a nearby link to the text-only product tour.

6. Package and publish

Not release blockers

The following work can improve Quirl later but is not silently attached to this current Unix release gate:

native Windows terminal handoff, suspension semantics, and Windows hardware validation;
native implementation of here-documents, process substitution, loops, functions, conditionals, or other Bash/Zsh dialect control forms;
a Wasm execution engine, remote plugin registry, publisher identity, or signed transparency log;
exact emulation of Bash/Zsh option state or framework-sized startup files;
S3 or mirror-backed asset providers beyond the versioned GitHub Release assets and version-scoped website channels; and
removal of Reedline or replacement of the current simple-terminal fallback.

These are explicit support boundaries. A future project may promote one only with its own implementation, adversarial tests, documentation, and release evidence.

Quirl release checklist

On this page