Repository navigation
Description
Problem
The hygiene lane is 66 continue-on-error gate steps spread over the lint and lint-2 jobs in .github/workflows/ci.yml (lines 540 to 1734 on main at 123c94b91). 35 of them call a scripts/ gate directly; the rest call ci-workflows composite actions (exec-bit, machine-specific paths and others) or inline shell. No script, Makefile, package.json script, or git hook runs them together on a workstation:
ls scriptshas no runner;package.jsonhas noscriptsblock.- The repo has no
lefthook.yml,.pre-commit-config.yamlor.husky/. The only installed git hook is aprepare-commit-msgshim, and the lefthook binary it calls prints "No config files" on every commit.
So the only way to learn which gates a change trips is to push and wait for CI.
Evidence
On #5992, these failed in CI and each needed a separate push and CI round:
exec-bit,spoke-plugin-root(scripts/check-spoke-plugin-root.sh),plugin-options-docs(scripts/sync-plugin-options-docs.py --check),shell-portability-lint(scripts/check-shell-portability.sh) on run 37094085450, fixed in78a01940c("fix: satisfy the exec-bit, plugin-root, options-docs and portability lint").changed-skills(scripts/check-changed-skills.sh),machine-specific-paths,stale-base-overlapandchangelog-parity-bumpon #5920, as reported by the authoring session (run IDs not re-checked here).
Every one of these is a deterministic script that needs only the checkout and origin/main.
Impact
Each CI-only failure costs one push, one ci run (PR median about 3.5 min after #5886) plus test-windows (about 11 to 13 min), and a fresh turn to read the log. While main merges about 3 PRs an hour, each extra round also raises the odds of a version collision and another base merge.
Proposed fix options
scripts/run-hygiene-gates.sh [--base <ref>], called by CI as well. One script owns the gate list, runs each gate against the diff, prints<gate>: ok|FAILplus the gate's own output for failures, and exits non-zero on any failure. CI's two lint jobs call it (or call it per half) instead of listing steps inline, so the local and CI lists cannot drift. Composite-action gates either get a local equivalent or are listed as "CI only" in the script's output.- A local-only script that mirrors the inline steps. Less change to
ci.yml, but it is a second list that drifts the first time someone adds a step. - A pre-push hook. Only worth it on top of option 1, and opt-in, since some gates need
origin/mainfetched and Python with the pinned requirements.
Recommendation: option 1. One gate list serves both places, and the same script can print each failure's reason into the CI annotation (see the companion draft on aggregate-hygiene-results.sh). Basis: the eight CI-only failures above; ci.yml step count from grep -c 'continue-on-error: true' over the lint jobs.
Acceptance criteria
- One command, documented in
AGENTS.md, runs everyscripts/hygiene gate from both lint jobs againstorigin/mainon a workstation and exits non-zero when any fails. - CI runs the same gate list from the same source, so adding a gate in one place adds it to both.
- Gates that cannot run locally are named in the command's output, not skipped silently.
- Re-running the eight failures above locally on their failing heads reproduces each one.
Activity
kyle-sexton commentedon Oct 4, 2026
This was generated by AI during triage.
Routing: human-gated, decision needed. Work class: structural (C4). Priority: medium.
Why a human decides: the repo already decided to defer exactly this.
README.md:145-163("Local pre-flight for hygiene gates", from the #3522 owner decision) maps every CI gate to its local command, and says "There is no single script that runs the whole hygiene set ... A pre-commit hook or a make target that wraps the runnable rows is a later tooling decision, not this record." This issue asks for that decision. The recommended option also moves the gate list out of the CI workflow and into a script that every hygiene job calls, which is a cross-cutting CI change (C4).Verification of the claims on main:
scripts/hasaggregate-hygiene-results.sh, which reads CI outcomes and runs no gates). There is nolefthook.yml,.pre-commit-config.yamlor.husky/.lintandlint-2no longer exist. The hygiene gates now run in four jobs,lint-repo,lint-shell,check-pluginsandcheck-skills, each ending in the aggregator (.github/workflows/ci.yml:978,:1230,:1611,:1936). The ci.yml has 69continue-on-error: truesteps.The decision:
scripts/run-hygiene-gates.sh [--base <ref>]owns the gate list, and every hygiene job calls it, so the local and CI lists cannot drift. Cost: restructures the four hygiene jobs' gate steps. Per-gate step names and outcomes then come from the script rather than from separate workflow steps.What the answer unblocks: the brief, and whether #6009's annotation work should wait for the runner (#6009 is defaulted to its smaller option 1 now; whichever lands second rebases onto the other's gate steps).
Agent Brief (for after the decision, option 1):
<gate>: ok|FAILper gate plus the output of each failure, exits non-zero when any gate fails, and names each gate it cannot run locally (composite-action gates, missing tools) as "CI only" or "skipped: ". It never skips one silently. The hygiene jobs get their gate list from the same source, so adding a gate in one place adds it in both.AGENTS.md; re-running the failing gates from the issue body's examples on their failing heads reproduces each failure; CI's hygiene results are unchanged on a clean PR.kyle-sexton commentedon Oct 13, 2026
Decision recorded. The owner accepted the adjudicated recommendation on 2026-10-12.
Keep #6008 open and narrow it: extend scripts/check-affected.sh (the runner #7185 built) with the deterministic gates it still omits, make it print every CI hygiene gate it does not run as 'CI only: ', add a contract test that fails when a scripts/ gate in pr-require-checks.yml is neither run by it nor on that list, and name it in AGENTS.md. Do not restructure the four CI hygiene jobs (the issue's option 1). Close #6008 when the issue's eight evidence failures reproduce locally or are named CI-only.
Why: origin/main scripts/check-affected.sh runs 8 diff-scoped checks and its header says it covers 'the diff-scoped LINT tier, not CI's whole-repo scanners', so it fails the issue's acceptance criteria (one command for every scripts/ gate, gates that cannot run locally named in the output, the eight #5992/#5920 failures reproducible); spoke-plugin-root, plugin-options-docs, changed-skills, changelog-parity-bump and machine-specific-paths are not run by any local entry point, and CI runs on 2026-10-12/13 still show typos, changed-skills and gitleaks failing after #7185 merged. Fowler, the Google SWE book and DORA agree that a fast local pre-push subset plus CI as the deciding gate is the practice, so widening the runner meets the need and option 1 (CI reading one shared gate list, a C4 change to four jobs) is not required by any owner decision or upstream source. One constraint neither researcher caught: check-spoke-plugin-root.sh, sync-plugin-options-docs.py, check-changed-skills.sh and check-changelog-parity.sh cd to their own script dir and ignore CHECK_DATA_ROOT, so in the hook's trusted-copy mode (#7229) they would inspect the merge-base extract instead of the branch; each needs the CHECK_DATA_ROOT pattern from check-shell-portability.sh:191-193, and changed-skills must SKIP in that mode because it executes plugins/skill-quality/scripts/check-skill.sh from the branch tree.
Precedence applied: Rule 2 over rule 5: the owner's newest merged decisions (#7185 built the runner and set its blocking budget; #7229 set its trust model; #3522 option d for machine-specific-paths) frame the answer, and the seed record's 'close as satisfied' ranks last against the issue's own acceptance criteria and the live script. No ADR applies. Upstream (rule 4) supports a fast local subset with CI deciding, so no owner decision conflicts with current facts; option 1 has no owner decision for or against it and is not needed to meet the criteria.
Sources:
Next: Owner comments on #6008 to narrow it (no close). One PR against this repo: (1) scripts/check-affected.sh adds, each calling the script CI calls: typos --config _typos.toml on changed files; scripts/check-spoke-plugin-root.sh --check; python3 scripts/sync-plugin-options-docs.py --check; scripts/check-changelog-parity.sh --check-bump ; scripts/check-changed-skills.sh only when plugins/*/skills/** changed and only when not foreign (it runs branch plugin code), else SKIP with that reason; (2) check-spoke-plugin-root.sh, sync-plugin-options-docs.py, check-changed-skills.sh and check-changelog-parity.sh honor CHECK_DATA_ROOT the way check-shell-portability.sh:191-193 does, so the #7229 trusted-copy mode reads the branch tree; (3) the runner prints 'CI only: ' for every hygiene gate in pr-require-checks.yml it does not run (machine-specific-paths pointing at the README row from the #3522 decision, the ci-workflows composites, the whole-repo scanners); (4) a contract test beside scripts/check-affected.test.sh fails when a 'run: scripts/...' gate in lint-repo, lint-shell, check-plugins or check-skills is neither called by check-affected.sh nor on its CI-only list; (5) one line in AGENTS.md naming scripts/check-affected.sh; (6) verification: rerun the runner on #5992's failing head (parent of 78a0194) and show each of the issue's eight failures reproduces or is named CI-only, and time a branch touching shell, a plugin and a skill against the roughly 60 s blocking budget the owner accepted in #7185. The PR closes #6008; file nothing new. #7092 only changes the steps' shell: lines, so it does not collide. Open: the full 271-head CI tally (scratchpad gate-failures.tsv, method: per failed run, failed hygiene job annotations titled ' failed') was 13 heads in when this record was written; whether the post-#7185 failures of gates the runner does run came from pushes that bypass the hook (cloud lanes, git -C, human pushes) was not checked.
Researched by two independent agents (local evidence and upstream docs) and adjudicated by a third.
kyle-sexton commentedon Oct 13, 2026
Owner batch-ratified this admission in an attended session on 2026-10-12: work-class: scoped. Rule: class C1-C3, no trust surface, the independent check confirmed the recorded decision, and no owner step remains.
kyle-sexton commentedon Oct 13, 2026
Correction: this issue already carried work-class: structural, which batch ratification never admits. The admission above is reverted; it stays escalated for an attended decision.
kyle-sexton commentedon Oct 18, 2026
Decision recorded.
Question: You accepted a narrowed scope on 2026-10-12: extend check-affected.sh, print "CI only: " for the rest, add a contract test, and add one AGENTS.md line. The issue still carries
work-class: structural. Options: (a) relabel it scoped and admit it; (b) keep it structural and build it attended; (c) close it as superseded by #7185.Owner's answer: (a) relabel scoped and admit it to the lane, with "Merging: a human merges this PR" in its brief, because the change adds a line to AGENTS.md, which every agent loads. The build stays unattended; the owner reads the AGENTS.md line before merge. Basis: report-outcome.mjs:117, :487-491 (the human-merge line is otherwise written only for structural or untrusted-provenance issues); owner change to the agent recommendation, 2026-10-18.
The owner accepted this recommendation as item D13 of a 21-decision batch in an attended backlog-shaping session on 2026-10-18. The batch question: "Accept all 21 batch 7 decisions, with my change to D13 (#6008 goes to the lane, but you merge its PR because it edits AGENTS.md)? I post a 'Decision recorded.' comment on each issue." The owner answered: "Accept, with my D13 change (Recommended)".
Posted by AI from the owner's answer in that session.
kyle-sexton commentedon Oct 18, 2026
Agent Brief
Type: Task
Summary: Widen the local hygiene runner so one command runs every deterministic in-repo gate CI's hygiene jobs run against the diff, names each gate it does not run as CI only, and is named in AGENTS.md.
Current behavior:
scripts/check-affected.sh, the runner a person, an agent and the pre-push hook all call, runs only the diff-scoped lint tier: markdown, shellcheck, shell-portability, exec-bit, changelog-fragments, stale-base-overlap, validate-plugins, ruff, and the affected tests with--tests. Several in-repo gates that CI's four hygiene jobs (lint-repo,lint-shell,check-plugins,check-skillsin the PR checks workflow) run have no local entry point: typos, spoke-plugin-root, plugin-options-docs, changelog-parity and changed-skills. The runner does not name the gates it skips, so their failures show only after a push. The spoke-plugin-root, plugin-options-docs, changed-skills and changelog-parity scripts resolve their data from their own directory and ignoreCHECK_DATA_ROOT, so in the pre-push hook's trusted-copy mode they would read the merge-base copy instead of the branch. AGENTS.md does not name the runner.Desired behavior:
SKIPwith its reason, a failure prints its reproduce command, and the runner exits 0, 1 or 2 as today.CHECK_DATA_ROOTnaming the branch tree), the spoke-plugin-root, plugin-options-docs and changelog-parity checks read the branch tree, the way the shell-portability check already honorsCHECK_DATA_ROOT. The changed-skills check reportsSKIPwith a reason in that mode, because it executes the branch's own skill-quality code.CI only: <gate>line for every hygiene gate in the four jobs that it does not run: the ci-workflows composite gates, the whole-repo scanners, and machine-specific-paths with a pointer to the README's local-run row. No gate is left out silently.scripts/gate that one of the four hygiene jobs calls is neither run by the runner nor on its CI-only list.scripts/check-affected.shas the local check to run before a push. The README's "Local pre-flight for hygiene gates" sentence on what the runner covers matches the new behavior.Key interfaces:
scripts/check-affected.shoutput: new check names, and newCI only: <gate>lines; flags and the 0/1/2 exit contract unchanged.CHECK_DATA_ROOTenvironment contract: honored by the spoke-plugin-root, plugin-options-docs and changelog-parity check scripts, with no change to what they check.Acceptance criteria:
scripts/run-test-file.sh scripts/check-affected.test.shpasses, with new cases showing that (1) a change to a skill file runs changed-skills, and the same change in trusted-copy mode reports itSKIPwith a reason; (2) a new check whose tool is missing reportsSKIP, not a failure; (3) the output carries aCI only:line for a gate the runner does not run.scripts/gate is added to a hygiene job without being run or listed.CHECK_DATA_ROOTsupport reading the tree the variable names.scripts/check-affected.sh..github/or.claude/changes.Out of scope:
.github/is edited.This was generated by AI during backlog shaping. The owner decided this issue (batch 7, D13) and approved its admission with a human merge in an attended backlog-shaping session on 2026-10-18.
docs: drop the check-affected AGENTS.md line