docs(smoke): say what the smoke run does gate

[michen00]

What changes, and why

Three places asserted that the smoke workflow gates nothing:

• CLAUDE.md:36 — "It gates nothing, because by the time it runs the version number is spent."
• .github/workflows/smoke.yml:12 — "It cannot gate anything, and is not built to."
• .github/workflows/release.yml:218 — "It gates nothing -- by the time it runs, every version number is spent."

The release flow contradicts all three, twenty-eight lines below the last of them. alias is needs: [binaries, pypi, crates, smoke], and the comment directly above that job already states the exception and its reasoning: "It waits on smoke, unlike anything else that follows the publish jobs. The publishes are irreversible and must not be held up, but moving this tag is both reversible and a recommendation... A red smoke run leaves the alias where it was, which is the safe direction."

So the true claim is narrower than the written one. Smoke gates none of the publishes, and nothing irreversible sits behind it — but it does decide whether @v0 follows this release. A maintainer reading only the absolute version has no way to learn that a red run has any consequence, when it has exactly one, and it is the one a consumer pinned to @v0 feels.

The switch count in the same sentence

CLAUDE.md:36 also said "Its two footholds in the harness are RUST_BINARY and REQUIRE_INSTALLED_PACKAGE". Smoke sets three:

$ grep -n 'REQUIRE_INSTALLED_PACKAGE\|REQUIRE_RUST_BINARY\|RUST_BINARY' .github/workflows/smoke.yml
235:          REQUIRE_INSTALLED_PACKAGE: '1'
241:          REQUIRE_INSTALLED_PACKAGE: '1'
242:          REQUIRE_RUST_BINARY: '1'
243:          RUST_BINARY: ${{ steps.crate.outputs.binary }}
249:          REQUIRE_INSTALLED_PACKAGE: '1'
250:          REQUIRE_RUST_BINARY: '1'
251:          RUST_BINARY: ${{ steps.released.outputs.binary }}

The omitted one is REQUIRE_RUST_BINARY, which is the guard that stops a failed install from quietly downgrading to testing the checkout — the exact failure the surrounding sentence exists to warn about, and the failure that workflow's first run actually had ("the first run of this workflow checked out v0.0.1 and quietly tested the checkout instead"). smoke.yml's own comment naming the switches was short the same one, so both move together.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

Comments and one CLAUDE.md sentence. No job's needs:, if: or steps change.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy — yamllint, actionlint, check-github-workflows, markdownlint and both spell gates — plus unwrap-markdown-prose-py --fail-on-change CLAUDE.md, since tidy skips this repository's own hook.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Clarify smoke checks gate the major release alias

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Corrects release documentation: smoke gates the reversible v0 alias, not artifact publishes.
• Documents all three harness switches preventing smoke tests from silently using checkout
 artifacts.

Diagram

graph TD
  B["Binaries"] --> S["Smoke checks"] -->|gates| A["Alias job"] --> V(["v0 alias"])
  P["PyPI publish"] --> S
  C["Crates publish"] --> S

Loading

High-Level Assessment

The current approach is appropriate: it corrects misleading comments at each relevant source without changing the already-correct workflow dependencies. Changing workflow behavior or consolidating the explanation elsewhere would add risk or reduce local clarity.

Files changed (3) +19 / -11

Documentation (3) +19 / -11

release.ymlDocument smoke validation as the alias gate +5/-3

Document smoke validation as the alias gate

• Narrows the claim that smoke gates nothing by explaining that publishes remain ungated while the reversible alias job waits for smoke validation.

.github/workflows/release.yml

smoke.ymlClarify smoke gating and required harness switches +13/-7

Clarify smoke gating and required harness switches

• Explains why smoke cannot gate irreversible publishes but does gate movement of the 'v0' alias. Adds 'REQUIRE_RUST_BINARY' to the documented switches that ensure installed artifacts are tested.

.github/workflows/smoke.yml

CLAUDE.mdAlign maintainer guidance with the release workflow +1/-1

Align maintainer guidance with the release workflow

• Corrects the smoke workflow overview to describe its effect on the major alias and enumerate all three harness switches. The guidance now matches the release dependency graph and smoke configuration.

CLAUDE.md

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.37%. Comparing base (1e9ac89) to head (8e8ddb4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #35   +/-   ##
=======================================
  Coverage   87.37%   87.37%           
=======================================
  Files           3        3           
  Lines         689      689           
=======================================
  Hits          602      602           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The changes are documentation/comment-only and were verified to match the actual release.yml dependency (alias needs smoke) and the harness env switch behavior used by smoke runs.

Pull request overview

This PR corrects and clarifies repository documentation/comments about what the smoke.yml workflow can and cannot gate in the release process, aligning the narrative with the actual release.yml job dependencies and the CLI harness switches used by smoke runs.

Changes:

• Clarifies that smoke.yml gates none of the publishes, but can gate moving the v0 alias via the alias job waiting on smoke.
• Updates smoke workflow header comments to explicitly document the alias-job exception and why it’s safe/reversible.
• Fixes the documented harness “footholds” for smoke runs to include REQUIRE_RUST_BINARY alongside RUST_BINARY and REQUIRE_INSTALLED_PACKAGE.

File summaries

File	Description
CLAUDE.md	Updates architecture docs to accurately describe smoke gating scope and the three harness env switches used by smoke runs.
.github/workflows/smoke.yml	Refines workflow-level comments to distinguish publish gating vs. v0 alias gating, and corrects the documented harness switches.
.github/workflows/release.yml	Adjusts the smoke-job comment to match the fact that alias depends on smoke while publishes do not.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.