Repository navigation
Conversation
## 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>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
There was a problem hiding this comment.
🔵 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
Codecov Report❌ Patch coverage is
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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
## 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>
|
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. |

Summary
Promotes the pull requests merged into develop since release 2.0.1166.
check=parser directive in the prose gate.workflow-modelinput against the registry.pr_review.py's pure check and round readers into the leaf modulespr_review_checks.pyandpr_review_rounds.py.waitwhile any workflow run on the head has not completed.waithelp andscripts/README.mdnow say what a held head's exit0does not prove: aCHECKS UNREADABLEpayload, 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:
a61d1e2adevelop0a0efea1developc2c71ea7develop4ec37c34developf20a543c85f0ce60developfcd48e2ddevelop3426a19cdevelopea4b0bb7develop236eceabdevelop3545ba46develop46010530develop, and a Copilot table on an earlier head naming exactly the changed files🤖 Generated with Claude Code