fix(gate): stop checking the gate-step count, which caused reds instead of catching them (#1883)

[macanderson]

This unbreaks main

main is red on gate-parity, so docs guards fails on every open PR. This fixes it and removes the reason it will happen again.

The defect

check-gate-parity.sh checked two things about AGENTS.md and CONTRIBUTING.md:

every step in GATE_STEPS is named	earns its keep — #1437 records two real drifts it caught
the spelled-out total matches	a single shared cell two concurrent PRs must both write

The names are checked one at a time, so two PRs adding different guards produce diffs that merge cleanly. The total does not have that property, and it broke twice on 2026-08-06: module-reachability (#1750) and self-driving-test landed within an hour, each having dutifully updated both documents to "twenty-four". The second merge left GATE_STEPS at 25 with the prose saying 24. Two separate agents then opened competing two-line fixes for it (#1863, #1882 — I closed the latter, which was mine).

A guard that causes reds instead of catching them is not a guard.

Why deleting it loses nothing

The count told a reader no fact the checked list does not already carry: if every step is named, the number of them is not independently knowable-wrong. It was a derived value maintained by hand — precisely the defect this guard exists to prevent one level up.

Option 1 of the three in #1883, and the only one that leaves nothing to go stale. Deriving the word (option 2) keeps a number nobody reads; a --fix flag (option 3) still leaves main red until somebody runs it.

number_word() and the count comparison go. The name checks, the ghost check (a CONTRIBUTING command that is no longer a gate step) and the fence parsing are untouched.

Verification, both directions

Narrowing a guard needs proof it still guards:

$ perl -pi -e 's/ \+ module-reachability//' AGENTS.md
$ ./scripts/check-gate-parity.sh
check-gate-parity: FAIL — AGENTS.md never mentions the gate step 'module-reachability'

$ # restored
check-gate-parity: OK — all 25 gate steps are named in AGENTS.md and CONTRIBUTING.md.

make shellcheck clean.

Why this PR and not #1863

#1863 is the same two-line count fix, opened first, and I closed my duplicate in its favour. It cannot merge.

It is docs-only; ci.yml carries paths-ignore for *.md; so all three required contexts (fmt + clippy + test, cargo deny + cargo audit, harbor_adapter + analyzer pytest) never report, and GitHub leaves it BLOCKED forever:

$ gh pr view 1863 --json mergeStateStatus     # BLOCKED, every reported check passing
$ gh api .../protection/required_status_checks --jq .contexts
["fmt + clippy + test","cargo deny + cargo audit","harbor_adapter + analyzer pytest"]

ci.yml's own comment says that filter is safe because merge_group ignores paths-ignore — which is true only with a merge queue enabled, and it is not (#1645). So the path filter is currently a trap for every docs-only PR in this repository. Filed separately; it is a bigger problem than this one.

This PR touches scripts/, so it gets its checks and can actually land.

Closes #1883
Refs #1750, #1863, #1645

Summary by Sourcery

Stop enforcing a spelled-out gate-step count in documentation guards to prevent false failures while preserving per-step parity checks between scripts and docs.

Bug Fixes:

• Fix gate-parity script failures caused by mismatched manually maintained total step counts across concurrent documentation changes.

Enhancements:

• Simplify the gate-parity check script by removing unused number-word logic and tightening its success messaging.
• Clarify AGENTS.md and CONTRIBUTING.md to describe gate execution without a hard-coded step count and to document the rationale for dropping the total.

[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:30am

[sourcery-ai]

Reviewer's Guide

Stops check-gate-parity from enforcing a spelled-out total gate-step count and updates docs accordingly, so the guard only verifies per-step parity by name and no longer causes merge conflicts when multiple PRs add steps concurrently.

Flow diagram for updated gate-parity guard behavior

flowchart TD
  Start([Run check-gate-parity.sh]) --> A[Read GATE_STEPS from Makefile]
  A --> B[Compute count of gate steps]
  B --> C{count == 0?}
  C -->|yes| F1[Print check-gate-parity: FAIL — no gate steps] --> EndFail1((Exit 1))
  C -->|no| D[For each doc: AGENTS.md, CONTRIBUTING.md]

  D --> E[Verify every GATE_STEPS entry is named in doc]
  E --> G[Check for ghosts: commands in CONTRIBUTING.md not in GATE_STEPS]
  G --> H{Any failures?}
  H -->|yes| EndFail2((Exit 1))
  H -->|no| I[Print check-gate-parity: OK — all count gate steps are named in AGENTS.md and CONTRIBUTING.md]
  I --> EndOK((Exit 0))

  subgraph Removed_total_count_check
    B --> R1[Derive spelled-out number word from count]
    R1 --> R2[grep for number word in AGENTS.md and CONTRIBUTING.md]
    R2 --> R3{Mismatch?}
    R3 -->|yes| RFail[Previously: FAIL because prose count was stale]
    R3 -->|no| RPass[Previously: continue]
  end

Loading

File-Level Changes

Change	Details	Files
Remove numeric word mapping and prose count enforcement from the gate parity script, keeping only per-step name checks.	Delete number_word() helper and its count range validation logic from the shell script. Remove grep-based check that each doc spells out the gate step count word, so docs are no longer required to maintain a spelled-out total. Simplify the success message to report only the numeric count and that all gate steps are named in both documents.	scripts/check-gate-parity.sh
Align AGENTS.md and CONTRIBUTING.md with the new behavior by eliminating hard-coded totals and documenting why the total is omitted.	Remove the spelled-out total gate-step count from AGENTS.md and reword the description to emphasize the list is derived from GATE_STEPS and guarded by check-gate-parity. Add explanatory text in AGENTS.md describing why no total is given and how count-based prose caused merge collisions and main breakage. Update CONTRIBUTING.md to replace the specific "twenty-four" wording with a count-agnostic phrase ("runs all of them in order"), matching the new guard behavior.	AGENTS.md CONTRIBUTING.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1883	Modify scripts/check-gate-parity.sh to stop checking the spelled-out gate-step total while preserving the per-step name checks and ghost checking.	✅
#1883	Update AGENTS.md and CONTRIBUTING.md to remove the hard-coded spelled-out gate-step count from the prose and instead describe the gate steps without a fragile total.	✅
#1883	Eliminate the failure mode where concurrent PRs adding gate steps collide on updating the shared spelled-out total, so that merging such PRs does not leave main red due to gate-parity.	✅

Possibly linked issues

• gate: the spelled-out gate-step count is a shared cell two concurrent PRs always collide on #1883: The PR directly implements the issue’s recommended fix: remove spelled-out count checks and prose totals to avoid collisions.

---

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.