Skip to content

Promote the pr_review.py Leaf-Module Split, the Held-Wait Run Hold, and Nine Fixes to Main - #3472

Merged
ptr727 merged 12 commits into
mainfrom
develop
Oct 25, 2026
Merged

ptr727 merged 12 commits into
mainfrom
develop

Conversation

@ptr727

@ptr727 ptr727 commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Summary

Promotes the pull requests merged into develop since release 2.0.1166.

  • #3444: keeps untracked files out of the pre-commit snippet's prose gate.
  • #3446: exempts the BuildKit check= parser directive in the prose gate.
  • #3448: compares intent staleness against the hub's own copy and names the moved canonical.
  • #3450: says only the prose gate is diff-scoped in the commit hook.
  • #3453: reclassifies HolidayLights as an operational config repository in the registry.
  • #3455: classifies the remaining subprocess failures by status rather than by prose.
  • #3464: splits the semicolon series in WORKFLOW.md's filesystem output-seam bullet.
  • #3466: audits a caller's workflow-model input against the registry.
  • #3469: emits one snapshot shape from the skills report's cannot-read paths.
  • #3462: splits pr_review.py's pure check and round readers into the leaf modules pr_review_checks.py and pr_review_rounds.py.
  • #3470: holds a covered held wait while any workflow run on the head has not completed.
  • #3473: answers this promotion's review. The wait help and scripts/README.md now say what a held head's exit 0 does not prove: a CHECKS UNREADABLE payload, the conditions the unregistered-required-check hold reads, and the reach of the completed-run read. The exit code itself stays for A Held Wait Exits 0 Under a DIRTY or BEHIND Merge Whose Required Checks Never Ran #3471.

Closes #3370
Closes #3372
Closes #3371
Closes #3369
Closes #3378
Closes #3454
Closes #3332
Closes #1759
Closes #3451

Constituent coverage

Each change this promotion carries had coverage on its own pull request into develop, at its merged head:

Pull request Merged head Coverage
#3444 a61d1e2a attested local pass at the merged head, base develop
#3446 0a0efea1 attested local pass at the merged head, base develop
#3448 c2c71ea7 attested local pass at the merged head, base develop
#3450 4ec37c34 attested local pass at the merged head, base develop
#3453 f20a543c a Copilot round on the merged head, its one changed file, no open findings
#3455 85f0ce60 attested local pass at the merged head, base develop
#3464 fcd48e2d attested local pass at the merged head, base develop
#3466 3426a19c attested local pass at the merged head, base develop
#3469 ea4b0bb7 attested local pass at the merged head, base develop
#3462 236eceab attested local pass at the merged head, base develop
#3470 3545ba46 attested local pass at the merged head, base develop
#3473 46010530 attested local pass at the merged head, base develop, and a Copilot table on an earlier head naming exactly the changed files

🤖 Generated with Claude Code

ptr727 and others added 11 commits October 24, 2026 18:48
## Summary

The `pre-commit` snippet ran the prose gate over `.` with
`pass_filenames: false`. `pre-commit` sets aside unstaged changes to
tracked files before a hook runs, but it leaves untracked files in
place, and the gate's discovery of `.` reads them. So an untracked file
holding a violation failed a commit that did not carry it.

- `catalog/snippets/pre-commit/.pre-commit-config.yaml`: the
`prose-gate` hook now takes the paths `pre-commit` passes (the staged
ones, or the conflicted ones during a merge), ending its entry with
`--diff HEAD --` so a dash-led name stays a path. `require_serial: true`
stops parallel batches, each of which would fetch the gate again.
`exclude: (^|/)reports/` mirrors the gate's default `generated_trees`,
since the gate judges a named file even inside a generated tree where a
`.` scan skips it.
- `catalog/snippets/pre-commit/README.md` and `GOVERNANCE.md` "Running
the Linters Locally" now say what the hook passes the gate.
- The Husky.Net snippet and the hub's own `.husky/pre-commit` are
unchanged, since the issue names them a separate question.

## Verification

Constructed scratch repositories, each with the hook config committed,
run with `pre-commit run prose-gate` (pre-commit 4.6.2), both with a
local copy of the gate and with the real snippet fetching the gate from
`main` through `hub_fetch_run.py`. Each scenario matched:

- the issue's repro, an untracked violation beside a clean staged file:
passes (the old shape fails)
- a staged new file with a violation, and a staged edit adding one:
fails
- only a `.py` file staged, with an untracked violation present: passes
(the old shape fails)
- only a binary staged, a staged deletion, and a staged deletion beside
an untracked violation: passes
- a partially staged file whose unstaged part holds a violation: passes
- a staged violation under `reports/` and under `docs/reports/`: passes
(without the `exclude`, it fails)
- a violation in a file whose name holds a space, and in `-dash.md`:
fails

## Local review

Three recorded `local-strict-review` passes. Round 1 found the missing
`require_serial`, two wording gaps, and three over-length sentences, all
fixed. Round 2 found one overstated `require_serial` sentence, fixed.
Round 3 found nothing.

Deferred: the `exclude` is a hand-kept copy of `generated_trees`. The
fix at the source is a gate-side switch in `prose_lint.py`, which sits
at its line ceiling (#3441), so it is filed as #3443.

Closes on promotion: #3370

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary

A Dockerfile opening on a BuildKit `check=` parser directive, such as `#
check=skip=CopyIgnoredFile`, drew `comment-case` in a whole-tree scan
and `comment-added` in diff mode. The directive vocabulary lives in
`.github/actions/prose-gate/prose-gate.json`, where `syntax=` and
`escape=` sat in `tool_directives` and `check=` did not.

- `.github/actions/prose-gate/prose-gate.json`: `check=` now sits beside
`syntax=` and `escape=` in `exemptions.tool_directives`. `prose_lint.py`
is unchanged.
- `tests/test_prose_lint.py`: a new test runs `main` in both scan modes
over a constructed Dockerfile. The directive line draws nothing, and a
lowercase prose line in the same position, the control, fails both
modes. The test pins `PROSE_ALLOW_COMMENTS` off, as its sibling
diff-mode tests do.

One correction to the issue's premise. The Dockerfile reference says
"Parser directive keys, such as `syntax` or `check`, aren't
case-sensitive, but they're lowercase by convention." So capitalizing
the line would not stop BuildKit reading it. The exemption is still the
fix. A `# Check=skip=CopyIgnoredFile` line still draws `comment-added`,
which asks for a deletion that changes the build, and the test's
docstring gives that reason.

## Verification

- Reproduced the issue's case with the gate before the change:
`Dockerfile:1: comment-case: comment sentence opens in lowercase`.
- With the JSON entry reverted, the new test fails on `(0, 0) != (1,
1)`. With it in place the test passes, also with
`PROSE_ALLOW_COMMENTS=1` exported.
- `python -m unittest discover -s tests -p 'test_prose*.py'` passes, and
`ruff format --check` and `ruff check` are clean on the test file.

## Local review

Three recorded `local-strict-review` passes. Round 1 found the unpinned
`PROSE_ALLOW_COMMENTS` and the docstring's wrong claim that BuildKit
reads the directive only in lowercase, both fixed. Round 2 found one
over-length docstring sentence the fix added, fixed. Round 3 found
nothing.

Closes on promotion: #3372

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…d Canonical (#3448)

## Summary

The intent staleness advisory in `spec/audit.py` flagged a copy that is
byte-identical to the hub's own file whenever the unit's `intentRef`
names a doc, and its message named the wrong thing as having changed.

- `check_intent_staleness` also skips where the copy is
content-identical to the hub's file at the unit's own `path`. Units
naming a `reference` are still judged against that reference alone.
- The message now reads "the intent canonical <path> changed later at
...".
- Tests in `tests/test_audit_helpers.py` cover the skip, the non-skip
for a differing copy, the `reference` unit, and the message.

Local strict review: round 1 found the `reference` case (fixed and
tested), round 2 found nothing.

Closes on promotion: #3371

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
## Summary

The Lint-group comment in both VS Code task snippets said the commit
hook runs the prose and EOL gates diff-scoped. Only the prose gate is
diff-scoped there. The hook's EOL entry runs `repo_gate.py --check eol`
with no `--diff`, over the whole tree, so `Lint: EOL` runs the hook's
own check on demand rather than a whole-repo variant of it.

- `catalog/snippets/configs/vscode-tasks.json` and
`catalog/snippets/configs/vscode-tasks-python.json`: the two comment
lines now say the prose gate is diff-scoped and the EOL gate whole-tree,
with no line added.
- `catalog/snippets/husky/README.md` and
`catalog/snippets/pre-commit/README.md`: the matching "same prose/EOL
gates in whole-repo mode" sentences carried the same claim and are
corrected and split.
- `GOVERNANCE.md` "Running the Linters Locally (Known-Working
Invocations)": "the diff-scoped doc gates" becomes "the doc gates", and
the VS Code Lint tasks bullet no longer calls `Lint: EOL` a whole-repo
version of a diff-scoped hook gate.

The change edits comment lines, so it carries the `comments` label.

## Pre-existing findings, not filed

- `GOVERNANCE.md:292`, style: removing one word from that single-line
bullet brings its existing long sentences (27 to 46 words) into the
diff-scoped `--check sentence-length` read. The change wrote none of
them, and the default prose gate passes.

Closes on promotion: #3369

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
#3455)

## Summary

Moves the remaining subprocess failures that were classified by message
prose onto the `CODESTYLE.md` "Operations and Failure Messages"
status-code rule.

- **`spec/audit.py` `gh()`**: with `ok404`, a failure now reads as
absence only when the stderr carries the `(HTTP 404)` notation `gh api`
prints. Bare "Not Found" or "HTTP 404" prose, another printed status, or
no status at all, such as a network error, raises as an unexpected
failure.
- **`scripts/skills_install.py`**: the expected "already there" case has
its own operation now, the listing, instead of a match on "already" in a
failed command's output. Where the marketplace listing already names
this checkout, the installer skips `claude plugin marketplace add`.
Where `claude plugin list --json` shows the plugin installed at user
scope, it skips `claude plugin install`. Each command that does run is
judged by its exit status alone. Where the plugin listing cannot be
read, the install runs and its exit status decides.
- **`host-setup/linux/setup-github.sh` `gh_account()` and
`host-setup/windows/setup-github.ps1` `Get-GhAccount`**: the check for
gh's `--active` flag (added in gh 2.57) is now the exit status of `gh
auth status --active --help` rather than a match on `unknown flag:
--active`. This is the same capability probe `pr_review.py` uses for
`--allow-escape-sequences`. The PowerShell twin had the same prose
match, so it moves too.

- **`host-setup/windows/setup-github.ps1` known-host checks**: a local
review pass found the same class at both `ssh-keygen -F github.com`
sites, which matched `found` in the output. They now read the exit
status, as the Linux twin already does. `scripts/README.md`
"`skills_install.py`" names the add and install skips.

The `scripts/pr_review.py` `unknown flag` retry is #3365's and is not
touched here.

## Findings from the local pass, fixed on the pull request

- `tests/test_setup_github.py` (introduced, design): the new known-host
harness repeated the existing Windows harness's parse-and-extract
preamble. Fixed in a10982d, where one `windows_harness` builder writes
it for both.

## Dropped findings

- `scripts/README.md:391` (style, pre-existing): four sentences this
change did not write exceed the advisory sentence-length check.
- `tests/test_install_tools.py` and `tests/test_bootstrap.py`
(consolidation, pre-existing): each carries its own copy of the same
parse-and-dot-source pwsh preamble.

Closes on promotion: #3378

## Verification

- New tests run on constructed output: `GhAbsenceCase` in
`tests/test_audit_helpers.py`, the add, install and listing cases in
`tests/test_skills_install.py` `RegisterCase`, the help-probe calls in
both the Linux and the Windows (pwsh) classes of
`tests/test_setup_github.py`, and `TestWindowsKnownHost`, which fails
against the old `-match 'found'` read.
- A pwsh probe confirmed `ssh-keygen -F` exits 0 for a known host, 1 for
an empty file, and 255 for a missing one.
- The capability probe was checked against the installed gh 2.103.2: `gh
auth status --active --help` exits 0, and the same command with an
unknown flag exits 1.
- Full suite under `python -m unittest discover -s tests`: 2909 tests
pass, 7 skipped.
- `ruff format --check`, `ruff check`, `mypy`, the prose gate against
`origin/develop`, and shellcheck, shfmt and PSScriptAnalyzer via
`scripts/docker_lint.py` all pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
HolidayLights holds xLights show folders edited in place on develop, so the registry records it as an operational config repo: lineEndings lf, a dispatch-only source release to GitHub, and a description naming xLights, FPP, and WLED that its README tagline mirrors. The driftNotes record the tracked .fseq renders, the local-only backups, the effect-presets CRLF pin, the 2025 and 2026 show folders and fleet baseline pending a develop->main promotion, and the planned rename to HolidayLights-Config.
…llet (#3464)

## Summary

`WORKFLOW.md`'s "Filesystem on a host the project owns" output-seam
bullet joined the deploy contract's guarantees into one sentence with
semicolons. Each guarantee is now its own sentence, with the meaning
unchanged. The Skill distributions are regenerated with
`scripts/build_dist.py`, so
`.agents/skills/workflow-ci-contract/references/architecture.md`,
`.github/skills/`, and `.claude-plugin/fleet-skills/` carry the same
text.

Closes on promotion: #3454

## Why the Prose Gate Passed It

The gate behaved as `comment-and-doc-style` states the rule, so no gate
issue is filed. `rule_semicolon` in
`.github/actions/prose-gate/prose_lint.py` exempts a sentence holding
more than one semicolon that also carries a comma, which is the rule's
own exception for a semicolon-separated list whose items contain commas.
The old sentence held two semicolons and several commas, so it read as
that list. It was a series of three "that" clauses, and the first one
carried commas, so the exemption fit its shape. The skip had nothing to
do with the word "that" or the bold-led list item. Copilot's downstream
finding was a preference for sentences over a semicolon series, and that
preference is the better reading here, which is why the text still
changes.

## Verification

- `git grep -n 'costs nothing;'` finds nothing.
- `scripts/build_dist.py --check` reports the generated distributions
current.
- `scripts/prose_lint.py --diff origin/develop` passes on the changed
files.
- Two recorded `local-strict-review` passes ran. The first found that
the recast deploy sentence ran to 35 words, and the second commit splits
it. The second pass found nothing this change introduced.

## Pre-existing findings, not filed

- `WORKFLOW.md:130`, `pre-existing`: the bullet's opening sentence ("the
leaf builds the tree, ships it to the host, and contributes no
`release-asset-*`") runs to 27 words under `--check sentence-length`.
This change did not touch that text.
- `WORKFLOW.md:130`, `pre-existing`: the Retention (D5.6) sentence runs
to 39 words under `--check sentence-length`. This change did not touch
that text.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Adds an audit check for the `workflow-model` input a caller passes to
`validate-task.yml`. Also moves the no-build caller snippet onto a
release that declares the input.

- **`interface.workflow-model`** (`spec/audit.py`, `spec/checks.json`)
reads the `validate` job's `with: workflow-model` in
`.github/workflows/test-pull-request.yml`. It reports DRIFT in two
cases: an operational registry entry that passes no `workflow-model:
operational`, and a release entry that passes any value other than
`release` or nothing. An empty value counts as a value rather than as
the default, because the validator treats any value other than `release`
as operational.
- **One model resolver.** `workflow_model_of` replaces the three inline
`workflowModel` fallbacks in `spec/audit.py`, used by the selectors, the
rulesets check and the sweep header.
- **Snippet.** `catalog/snippets/workflows/test-pull-request.yml` moves
its pin from `2.0.376` to `2.0.1166` and passes `workflow-model:
operational`. The snippet is the operational trigger shape. Its only
other job-level setting is `permissions: contents: read`, which still
matches every job in the pinned `validate-task.yml`.
- **Docs.** `docs/reusable-workflows.md` "Adopting the Gates" now says a
release-model adopter drops the input, along with the push trigger. It
also names the new check.
- **Tests.** `WorkflowModelCallerFindingsCase` covers an operational
caller with the input, an operational caller without it, a release
caller passing the wrong value, release callers that omit it or name
`release`, an empty value, callers and jobs the check does not read, the
real snippet, and the model fallback.

Verification: I ran the full `OPERATIONS.md` "Local Verification" block
locally, and every gate passed (2919 tests). I also ran a live
`spec/audit.py` over the hub and the operational and release config
repos. The new check reports exactly the three operational repos whose
caller omits the input, and none of the release repos.

Closes on promotion: #3332

## Declined local-pass finding

- `spec/audit.py` `workflow_model_caller_findings`, `introduced`: the
local pass called the structured-value branch added in 3426a19
over-hardening. Declined, because the branch is not hardening against an
input. The check exists to report a caller whose input disagrees with
the registry. Reading a mapping as the omitted default would make the
audit report a release caller as conformant when it is not, which is a
false negative in the check's own output.

## Pre-existing findings, not filed

- `docs/reusable-workflows.md:300`, `pre-existing`: the paragraph's
first sentence is 40 words, over `sentence-length`'s 25. The sentence
predates this change. This change only appended a separate 13-word
sentence to that line.

## Dropped findings

- `scripts/carry.py` `selector_set()` and `repo-config/configure.sh`,
`pre-existing` consolidation: both keep their own copy of the
`workflowModel` fallback that `workflow_model_of` now holds for
`spec/audit.py`. This change does not touch either file.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Closes the remaining #1759 follow-ups in `scripts/skills_install.py`.

- Items 1 and 2 were already fixed on `develop`: `no_snapshot()` answers
the live channel, and both bootstraps now say only that the output above
says why. Confirmed, not rewritten.
- Item 3: a test proves `--intended` without `--report` is refused
through `parser.error` and installs and registers nothing.
- Copilot follow-up: `no_snapshot()` now emits the same `snapshot` keys
as the judged path (`installedFrom` and `installedDirty` null,
`intended` and `intendedRef` resolved, `current` false), with a test
over the missing, unreadable, and unrecognized stamp cases that also
asserts the `--intended` revision reaches the resolver.
`scripts/README.md` states it.
- Git floor risk: not measured here (only git 2.47.3 available), filed
as #3468 rather than adding an unevidenced floor.

Local strict review: one finding (test did not prove `intended_rev` is
passed through), fixed. Full unit suite, ruff, and mypy green.

Closes on promotion: #1759

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
## Summary

`scripts/pr_review.py` sat at 2,999 lines against its 3,000-line
ceiling, so the #3451 fix had no room. The concern isn't the number.
Each fix added a few lines to one file until it needed a full refactor.
This change splits the file along the two kinds of reading the gate
does, rather than trimming it to fit:

- **`scripts/pr_review_checks.py`** reads the head's CI rollup. It holds
`check_nodes`, `check_shape`, the stuck and settling readers,
`held_checks_open`, `required_unmet`, the check constants
(`CHECK_GRACE`, `CHECK_STALL`, `CHECKS_WINDOW`), and the digest's check
lines.
- **`scripts/pr_review_rounds.py`** reads the review rounds. It holds
coverage and the file table, refusals and quota history, request state,
threads and finding matching, the local attestation and its hold, and
the reviewer-login vocabulary.
- **`scripts/pr_review.py`** keeps the GitHub calls, `digest`, the
verdict, the writes, and `main`. It is now 2,105 lines.

## Design

**The cut follows purity.** Both new modules are leaves. Each reads a
payload the gate already fetched, makes no network or subprocess call,
and never imports `pr_review`. Importing the gate from a module it
imports would load a second copy whenever the gate runs as `__main__`. A
leaf can also be tested without a mock. The rule that picks what moved:
every function that does not, even indirectly, call the network, a
subprocess, `print`, or `time`. `liveness` is the one exception, since a
test spies on it through the gate.

**Patched names stay in the gate.** Every name a test patches
(`gh_graphql`, `gh_rest`, `gql`, `_git`, `digest`, and the rest) stays
defined in `pr_review.py`. A patch on a name the moved code calls
through its own module would silently stop applying, and a test meant to
block a real `gh` call would let one through. The tests now call each
reader in the module that defines it. The parse-once spies count both
bindings of `check_nodes`.

**Data instead of a branch chain.** `digest`'s if/elif chain over stuck
shapes is now the `STUCK_LINES` table beside `check_shape`, rendered by
`check_lines`. A new shape is one entry in the module that defines
shapes. Its output is byte-identical to the chain it replaces. I
compared both versions over constructed payloads covering every shape, a
superseded failure, an unreadable rollup, missing workflow keys, a
truncated window, and an age-unknown stamp.

**What did not move, and why.** A survey of the rest found where the
gate keeps growing, and each is filed as its own issue rather than mixed
into a move:

- #3457: `digest` is about 300 lines of string concatenation. It can
become a pure renderer behind a thin shell, with its header built from
an ordered field list.
- #3458: `main` holds the whole `wait` body and about seven hand-written
flag-ownership checks, which a table can carry.
- #3459: four shapes repeat at each site in the gate: the "nothing was
written" refusal, the subprocess call, the write confirmation, and the
ref check.
- #3460: three payload accessors are spelled out about nineteen times
across the readers.
- #3461: `pr_review.py cleanup` already loads a second copy of the gate
through `pr_cleanup.py`, the hazard the leaf rule guards against.

These all edit `pr_review.py`, so they land one at a time.

**Ceilings as tripwires, not targets.** The size test now lists each
module with modest headroom over its current length: 2,200 for the gate,
450 for checks, and 700 for rounds. Its docstring says a ceiling reached
is a prompt to redesign along the module's boundaries, never to raise
it. New guards keep the boundary true:

- The whole-source write-verb, suppression, and node-id scans read all
three modules.
- A new case holds each reader's imports to the standard library and the
reviewer adapter, with a floor so an empty match fails.
- The same case asks a fresh interpreter, through `import_delta`,
whether importing the module loads the gate, the transport, or
`subprocess`.

**The `comments` label.** Most comment lines in the two new files moved
verbatim. These are newly written:

- each module's docstring
- the `STUCK_LINES` comment
- the `check_lines` docstring
- the comments on the new test constants

This unblocks #3451, whose fix lands on top in its own pull request.

## Remaining Local-Review Findings

- `pre-existing`: eight sentences over 25 words, all moved verbatim or
older text on a changed line: `scripts/README.md` lines 9 and 190,
`scripts/pr_review.py` line 16, `scripts/pr_review_checks.py` lines 88
and 94, and `scripts/pr_review_rounds.py` lines 367, 553, and 615.
- `introduced`, raised by the third pass after the edit budget ran out:
`tests/test_pr_review.py`
`test_the_readers_import_nothing_that_reaches_out` compares `before`
with `after` and never asserts that `before` is empty. A watched module
already loaded at interpreter start would therefore pass vacuously. Only
`subprocess` could be, and neither CI leg loads it today. The fix is
`self.assertEqual([], before)`, which this pull request's review loop
will dispose of.

## Verification

- `python -m unittest discover -s tests` (under `uvx --with-requirements
tests/requirements.txt`): 2,901 tests OK, 7 skipped, on the head.
- The `digest` output was compared byte for byte, old against new, over
the constructed payloads above.
- Each new guard was mutation-tested and fails when its target breaks:
  - a second `check_nodes` parse inside the checks module
  - `import subprocess` in the rounds module
- `import gh_graphql` in the Copilot adapter, caught through the rounds
module
- `ruff check`, `ruff format --check`, `mypy .`, `repo_gate.py --check
eol`, and `prose_lint.py --diff` with `--allow-comments`: clean.
- `local-strict-review`: three recorded frontier-tier passes. The first
raised five findings and the second three, all fixed. The edit budget
then ran out, and anything the third raised is listed above.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary

A pull request into a non-default branch is "held": an attested local
pass covers its head, and `pr_review.py wait` polls the head's checks
instead of a Copilot round. Run right after a push, that poll exited `0`
while CI was still running. A job behind `needs:` enters the rollup only
once its dependencies finish, so the merge read `CLEAN` and every
registered check was green while most of a run's jobs had not been
created yet. A caller trusting the exit judged the pull request ready.

The held poll now holds while any workflow run on the head has not
completed:

- `runs_open(pr)` in `scripts/pr_review_checks.py` names every workflow
run whose suite is not `COMPLETED`. It reads the head commit's own
suites and each rollup check run's suite, so a fresh head's run counts
before most of its jobs exist. A suite with no workflow run, such as
another app's that never reports, holds nothing.
- `held_checks_open` reads its conditions in this order:
  - a pull request no longer open releases
  - a merge reading `UNKNOWN` holds
- a `BLOCKED` merge with a required check stuck in a shape waiting does
not clear ends the poll at `44`
  - an open run holds
  - only then does a `CLEAN`, `UNSTABLE`, or `HAS_HOOKS` merge release
- A check run `WAITING` past `--check-grace` is its own `GATED` shape.
It gets a `CHECK WAITING ON ITS ENVIRONMENT` line saying to approve the
job or let its timer pass, since a re-run meets the same rule. `WAITING`
leaves `NOT_STARTED`.
- Where `workflowRun` is unreadable, an Actions suite stands in, named
`suite <id>`, through `unkeyed_actions_suite`, which `check_nodes`
shares. The head's suites query now selects `app{ slug }` for this.
- The `status=CHECKS_PENDING` line names the open runs. The `wait` help
and the `scripts/README.md` held-wait and exit-44 paragraphs describe
the new reading, in the code's order.

Closes on promotion: #3451

## Decisions

- **Every open run holds, with no exception.** Earlier revisions
released a run waiting on an environment, then one with a starved job.
Review showed each release reopened the early exit `0`: a job pending
behind a concurrency group, a busy runner pool, or a dependent not yet
registered. The cost is that a run waiting on an approval that never
comes, or on a job no runner takes, polls to the timeout. It then exits
`30`, with the digest's `GATED` or `CHECK NOT PICKED UP` line naming
what holds it.
- **A gated or long-running required check does not end a `BLOCKED` poll
at `44`.** A timer clears by itself and an approval may land, so on a
held head these hold to `30`. On the Copilot path a required gated check
still exits `44`, as a long-running one already did.
- **A required starved check under `BLOCKED` still exits `44` at once,**
as before.
- **No shared walker with `check_nodes`.** Its suite walk is threaded
through per-node normalization, so `runs_open` reads the suites itself.
The one condition the two share, whether a suite is an Actions suite
left unkeyed, is one predicate.
- **A job-less Actions suite may hold in degraded mode.** With
`workflowRun` unreadable, an unfinished Actions suite holds even when it
has no job yet, since right after a push it looks the same as one that
never gets a job. I measured the check suites on the 8 most recent pull
request heads here: every Actions suite carried jobs, and none sat
unfinished. The suites left queued with no jobs belonged to other apps
(`azure-pipelines`, `claude`, `coderabbitai`), which the predicate
excludes and a test pins.

## Remaining Local-Review Findings

Each push had recorded frontier-tier passes, and every `introduced`
finding they raised is fixed in the commits above, apart from these:

- `introduced`, fixed in `8acf0511`: the `wait` help's exit-30 line read
as a complete list of holds. It now points to the holds
`status=CHECKS_PENDING` names.
- `introduced`, deferred to #3471: the exit-0 help's completed-runs
clause now names coverage, the condition the code reads (`3545ba46`).
One path still falls outside it: when the rollup's commit is not the
head, `wait` deliberately exits `0` with `CHECKS UNREADABLE`, and no run
is read. That predates this change and a test pins it, but the help's
new clause now overclaims there. It joins #3471, which tracks exit `0`
where the required checks were never read.
- `pre-existing`: the help's claim that exit `0` means the head's
required checks settled is false under a `DIRTY` or `BEHIND` merge whose
required checks never ran. GitHub runs no `pull_request` workflow on a
conflicted pull request, and `held_checks_open` holds an unregistered
required context only under `BLOCKED`. These paths predate this change,
so they are left to an issue of their own.
- `introduced`, conditional: the degraded-mode decision above. If GitHub
ever leaves a job-less Actions suite queued on a head, the held wait
would poll to `30` in that mode alone. The measurement above found none.
- `style`: one help string and two help-text lines are wrapped short.
Declined, since no gate reads them and the file already carries longer
lines.
- `pre-existing`: a head read before any check suite exists, on a base
requiring no check, can still exit `0` under `CLEAN`. Nothing on the
head exists yet for any reader to see. Every develop ruleset in this
fleet requires the aggregator, so there the merge reads `BLOCKED` and
`required_unmet` holds.
- `pre-existing`: sentences over 25 words that this change only
rewrapped or left in place: three at `scripts/README.md` line 233,
`scripts/pr_review.py` lines 120 and 123, and the `49 =` help sentence.

## Verification

- `python -m unittest discover -s tests` (under `uvx --with-requirements
tests/requirements.txt`): 2,940 tests OK, 7 skipped, at `e4295145`. The
commits after it change only the `wait` help text, and the
`test_pr_review` and `test_cli_usage` suites pass on each.
- Each rule was mutation-tested, and dropping it fails a named test:
  - the run hold, and its place ahead of `CLEAN`
  - the closed-PR release
  - the stuck-required release ahead of the hold
  - the gated exemption from `44`
  - the `COMPLETED` skip
  - the no-workflow-run exclusion
  - the rollup-suite read
- the Actions fallback for a rollup suite, for a job-less head suite,
and its other-app exclusion
  - the `GATED` shape
- On a live pull request, #3462, a wait using an earlier revision of
this change (`f6837bd9`) held for 781 seconds until every run on the
head completed, then exited `0`. The same wait without it had returned
while two checks were still running.
- The extended suites query was read live with `status` against this
repository.
- `ruff check`, `ruff format --check`, `mypy .`, and `prose_lint.py
--diff`: clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings October 25, 2026 16:13
@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Unresolved critical and moderate findings remain in the held-wait workflow-run handling.

1 open issue
What changed in this PR

This pull request promotes the validated develop-branch fixes into main, covering prose-gate behavior, workflow-model auditing, status handling, repository metadata, and the pr_review.py reader split with held-wait safeguards.

Changes:

  • Refines pre-commit prose-gate scoping and BuildKit directive handling.
  • Adds workflow-model auditing, status-based subprocess handling, and consistent skills-report snapshots.
  • Reclassifies HolidayLights and updates workflow, governance, documentation, and generated skill references.
  • Splits review checks and round readers into leaf modules and holds waits for incomplete workflow runs.

The review has three open comments: a nit concerning the HolidayLights documentation row, a moderate pagination issue in workflow-run detection, and a critical issue where unreadable checks may be treated as settled.

File Summary
WORKFLOW.md Clarifies the filesystem deployment contract by splitting the output-seam guidance.
tests/​test_skills_install.py Tests snapshot shapes and status-based plugin handling.
tests/​test_setup_github.py Tests GitHub capability probes and known-host exit statuses.
tests/​test_prose_lint.py Covers the BuildKit check= directive in scan and diff modes.
tests/​test_pr_review_size.py Adds separate size ceilings for the review reader modules.
tests/​test_audit_helpers.py Tests intent staleness, workflow-model auditing, and HTTP status handling.
tests/​import_probe.py Allows import-boundary tests to specify watched modules.
spec/​checks.json Registers the workflow-model interface audit.
spec/​audit.py Adds workflow-model auditing and improves intent and HTTP status handling.
scripts/​skills_install.py Uses listings and exit status instead of subprocess message prose.
scripts/​README.md Documents the reader split, held waits, and installer reporting behavior.
scripts/​pr_review.py Delegates check and round reading and holds waits for open workflow runs. Open moderate P1 (1 vote): workflow suites are limited to the newest 50 without pagination. Open critical P1 (1 vote): unreadable checks can be treated as settled.
scripts/​pr_review_rounds.py Adds the pure review-round reader module.
scripts/​pr_review_checks.py Adds the pure check and workflow-run reader module.
registry/​repos.json Reclassifies HolidayLights as an operational repository. Open nit (1 vote): docs/eol-lf-rollout.md still labels it as release.
host-setup/​windows/​setup-github.ps1 Uses exit status for known-host and CLI capability checks.
host-setup/​linux/​setup-github.sh Uses an exit-status capability probe for gh --active.
GOVERNANCE.md Clarifies hook scope for prose and EOL gates.
docs/​reusable-workflows.md Documents the workflow-model input and audit check.
catalog/​snippets/​workflows/​test-pull-request.yml Updates the reusable workflow pin and passes the operational model.
catalog/​snippets/​pre-commit/​README.md Documents staged-path and generated-tree handling.
catalog/​snippets/​pre-commit/​.pre-commit-config.yaml Scopes prose checks to pre-commit paths and serializes execution.
catalog/​snippets/​husky/​README.md Corrects whole-tree prose and EOL task documentation.
catalog/​snippets/​configs/​vscode-tasks.json Corrects the Lint task scope comments.
catalog/​snippets/​configs/​vscode-tasks-python.json Applies the Lint task scope correction for Python.
.github/​skills/​workflow-ci-contract/​references/​architecture.md Regenerates the workflow contract distribution.
.github/​actions/​prose-gate/​prose-gate.json Exempts the BuildKit check= parser directive.
.claude-plugin/​fleet-skills/​skills/​workflow-ci-contract/​references/​architecture.md Regenerates the Claude Skill distribution.
.claude-plugin/​fleet-skills/​.source-digests/​workflow-ci-contract Updates the generated Skill source digest.
.agents/​skills/​workflow-ci-contract/​references/​architecture.md Updates the authored workflow contract reference.

Review effort: Lite

Comment thread scripts/pr_review.py Resolved
@codecov

codecov Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.92009% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.98%. Comparing base (687ccd9) to head (412ce42).
⚠️ Report is 419 commits behind head on main.

Files with missing lines Patch % Lines
scripts/pr_review_rounds.py 98.84% 3 Missing ⚠️
spec/audit.py 94.28% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3472      +/-   ##
==========================================
+ Coverage   80.76%   80.98%   +0.22%     
==========================================
  Files          23       25       +2     
  Lines        8839     8895      +56     
==========================================
+ Hits         7139     7204      +65     
+ Misses       1700     1691       -9     
Flag Coverage Δ
python-3.13 80.98% <98.92%> (+0.22%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

## Summary

Answers the finding the develop -> main promotion
[#3472](#3472) raised on
the `wait` help that
[#3470](#3470) wrote. The
help and `scripts/README.md` said a held head exits `0` with its
required checks settled and every workflow run completed. Two paths in
`held_checks_open` release without either:

- A payload with no commit matching the head, `CHECKS UNREADABLE`, reads
no run and no check.
- A required check not yet registered holds only a `BLOCKED` merge whose
base branch rules were read and whose rollup is not `CHECKS TRUNCATED`.
An empty rollup holds only `BLOCKED`, `BEHIND`, or `DRAFT`. Short of
those holds, a merge with some check posted, or a `DIRTY` one with none,
releases with a required check unregistered.

The help and the README's exit table and held-wait paragraph now say
this. The exit code itself is unchanged and stays for
[#3471](#3471) to
decide, whose done-when allows either a new exit or help naming each
exception. This change does the second without closing that decision.

## Verification

- Full unit suite, the `OPERATIONS.md` "Local Verification" command:
2940 tests, OK, 7 skipped, on the first commit. The `test_pr_review*.py`
set, 525 tests, OK, on the second.
- `prose_lint.py --diff` against the merge base, with and without
`--check sentence-length`: clean.
- Three local adversarial passes. The first two found three gaps, the
omitted `DRAFT` case, the unnamed rules-read and truncation conditions,
and an incomplete list of releasing merges, each fixed here. The third
found nothing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The promotion spans 30 reviewed files and includes workflow-run behavior plus generated and distributed changes, so final human approval is warranted.

No open issues 🎉

1 resolved since last review

Review effort: Lite

@ptr727

ptr727 commented Oct 25, 2026

Copy link
Copy Markdown
Owner Author

Answering the round on 412ce42, whose headline reads "needs a closer look" and counts no finding. Its one statement is that the promotion spans many reviewed files and touches workflow-run behavior plus generated and distributed content, so final human approval is warranted. That names no defect. It describes the gate this promotion already stops at, since merging into main waits on the maintainer's explicit go-ahead and is never taken by the driver. Coverage for this head rests on the promotion case: each of the twelve constituent pull requests carried full coverage at its merged head, listed in the body's Constituent coverage table. The one finding a round raised on this promotion was fixed in #3473 and its thread is resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants