fix(gate): drop the spelled step count — the one shared cell concurrent guard PRs collide on

[macanderson]

Problem

check-gate-parity.sh held AGENTS.md and CONTRIBUTING.md to a spelled-out gate-step total on top of its per-step name checks. The name checks merge cleanly — each step is grepped independently, so two PRs adding different guards produce diffs with no overlap. The total is the one shared cell both branches must rewrite: each updates it correctly against its own base, and the second to merge leaves GATE_STEPS one ahead of the prose. That turned docs guards red on main twice on 2026-08-06 (module-reachability #1750 vs self-driving-test), failing every open PR — and main is red on exactly this again at the base of this branch: GATE_STEPS has 25 steps, both documents said twenty-four.

Decision

Issue #1883's option (1): drop the total from the prose entirely.

• AGENTS.md — "That is twenty-four steps, and the list is not maintained by hand…" → "The list is not maintained by hand…"
• CONTRIBUTING.md — "Or just make gate, which is the twenty-four of them in order." → "Or just make gate, which runs them in order."
• scripts/check-gate-parity.sh — delete number_word() and both does not spell the gate's step count branches; record the rationale in the header's "deliberately does NOT check" paragraph. The name-by-name checks and the ghost check — the halves that caught the two real drifts (docs: gate step lists are hand-restated in AGENTS.md and CONTRIBUTING.md with no drift guard #1437) — are untouched.

The number told a reader nothing actionable (the list is right there, derived and checked name-by-name), and it was the only part of the prose that could go stale by merge skew alone. This also un-reds main's current gate-parity failure as a side effect.

Verification

The issue's Verify is a two-branch merge experiment — impractical in CI — so the witness is the equivalent single-tree experiment:

1. On unmodified origin/main (the live collision): old guard fails — FAIL — AGENTS.md does not spell the gate's step count as 'twenty-five'. The gate runs 25 steps. (both docs). This branch: OK — 25 gate steps, named in AGENTS.md and CONTRIBUTING.md.
2. Fake-step experiment: appended fake-step to GATE_STEPS and named it in both documents without touching any count — the shape a merged pair of guard PRs produces. Old guard: FAIL — 26 gate steps is outside the range number_word() spells (the count discipline fires). New guard: OK — 26 gate steps…. Scaffolding reverted after the run.
3. shellcheck scripts/check-gate-parity.sh clean; sigpipe-safe piped invocation ./scripts/check-gate-parity.sh | head -1 prints the OK line.
4. Adjacent toolchain-free guards on the final tree: check-command-docs, check-brand-case, check-left-behind, check-doc-links all green. Shell/docs-only change — no cargo surface touched.

Closes #1883

Refs #1437, #1750, #1645

Summary by Sourcery

Remove gate step count spelling checks to avoid merge conflicts and keep documentation resilient to concurrent guard changes.

Enhancements:

• Simplify check-gate-parity guard by dropping spelled-out step count enforcement while retaining per-step name and ghost checks.

Documentation:

• Update AGENTS.md and CONTRIBUTING.md to stop stating a specific spelled-out gate step count and instead describe the list procedurally.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Ignored		Aug 6, 2026 11:22am

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

This PR removes the spelled-out gate step count from documentation and from the gate parity script, keeping only per-step name and ghost checks so concurrent guard-adding PRs no longer collide on a shared count cell, while preserving existing verification behavior otherwise.

Flow diagram for updated check-gate-parity.sh gate parity guard

flowchart TD
  A[Run check-gate-parity.sh] --> B[Invoke make gate-steps]
  B --> C[Compute count from GATE_STEPS]
  C --> D{count == 0?}
  D -- yes --> E[Fail: no gate steps]
  D -- no --> F[Per-step name checks in AGENTS.md]
  F --> G[Per-step name checks in CONTRIBUTING.md]
  G --> H[Ghost checks in CONTRIBUTING.md fence]
  H --> I{Any failures?}
  I -- yes --> J[Exit 1 with failure messages]
  I -- no --> K[Print OK with count and docs]

  style E fill:#fdd
  style J fill:#fdd
  style K fill:#dfd

Loading

File-Level Changes

Change	Details	Files
Remove count-based logic from the gate parity check while documenting the rationale and keeping name and ghost checks intact.	Update the script header to describe that the prose and total step count are deliberately not checked and explain the merge-collision rationale. Remove the number_word() helper and its numeric range enforcement logic. Remove the per-document check that the spelled-out count word appears in AGENTS.md and CONTRIBUTING.md. Simplify the final success message to no longer mention the spelled-out word, only the numeric count and document names.	scripts/check-gate-parity.sh
Stop stating a specific total number of gate steps in AGENTS.md while keeping the explanation of how the list is derived and guarded.	Rewrite the sentence that previously claimed "That is twenty-four steps" so it now directly explains that the list is machine-derived and parity-checked without mentioning a step count. Ensure surrounding explanatory text about GATE_STEPS and the gate-parity check remains unchanged.	AGENTS.md
Stop stating a specific total number of gate steps in CONTRIBUTING.md and rephrase the description of make gate.	Change the sentence describing make gate from specifying "the twenty-four of them in order" to a count-free phrasing that it "runs them in order". Leave the rest of the guidance about the gate list, its source in GATE_STEPS, and the parity check intact.	CONTRIBUTING.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1883	Remove the requirement that AGENTS.md and CONTRIBUTING.md contain a spelled-out total gate-step count, so that concurrent guard-adding PRs no longer collide on a shared prose cell.	✅
#1883	Update scripts/check-gate-parity.sh to stop deriving and checking a spelled-out step count (including removing number_word and related failure logic) while preserving the per-step name checks and ghost checks.	✅
#1883	Document in scripts/check-gate-parity.sh’s header comments that the prose and step total are deliberately not checked, including the rationale tied to merge-collision issues.	✅

Possibly linked issues

• gate: the spelled-out gate-step count is a shared cell two concurrent PRs always collide on #1883: PR implements issue gate: the spelled-out gate-step count is a shared cell two concurrent PRs always collide on #1883 option (1) by deleting the prose step count and related checks from gate parity.
• gate: the spelled-out gate-step count is a shared cell two concurrent PRs always collide on #1883: PR directly addresses the issue’s gate-doc parity, resolving it by dropping fragile spelled-out step counts.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.