[PR #227] [MERGED] docs: trim AGENTS.md to the 150-line target it enforces #234

New issue

Closed

opened 2026-10-26 22:37:38 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:37:38 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/github-workflows/pull/227
Author: @mattmillerai
Created: 8/26/2026
Status: ✅ Merged
Merged: 8/26/2026
Merged by: @mattmillerai

Base: main ← Head: matt/trim-agents-md

📝 Commits (2)

26e8409 docs: trim AGENTS.md to the 150-line target it enforces
3c87d30 docs: fix the eight review findings on the trimmed AGENTS.md

📊 Changes

1 file changed (+119 additions, -274 deletions)

View changed files

📝 AGENTS.md (+119 -274)

📄 Description

What

agents-md-integrity.yml — the standard this repo publishes to everyone else —
has been failing on this repo's own AGENTS.md. At 305 lines it was over the
hard 200-line ceiling. This brings it to 150, the aspirational target rather
than just under the ceiling.

before: FAIL: 'AGENTS.md' is 305 lines, over the hard ceiling of 200.
after:  Result: passed with 1 warning(s).     # the pre-existing CODEOWNERS warning

ELI5

Our own rulebook says "keep the rulebook under 200 lines." Ours had grown to 305,
so the checker we ship to other repos was red on us. This cuts it back to 150 by
deleting the parts that were already written down somewhere else and linking to
those places instead — nothing is actually forgotten, it just isn't said twice.

The trim is de-duplication, not deletion

Every passage removed already lives, usually in far more depth, in a doc
AGENTS.md links to. I checked each one before cutting it:

Removed from AGENTS.md	Already documented in
groom's `package.json` CLI pin	`.github/groom/README.md` §"the agent CLI pin (BE-5373)"
`job.workflow_sha` vs the OIDC claim	`docs/callers/groom.md`
the public-repo-hygiene allowlist rationale	`.github/public-repo-hygiene/README.md` §"Why the allowlist lives here"
roster / enrollment / un-bumpable entries	`.github/bump-callers/README.md`, `CONTRIBUTING.md`
cursor-review's deleted `blocking:` input	`README.md`, `docs/callers/cursor-review.md`, `.github/cursor-review/README.md`
the cursor-cli pin trust anchor + nixpkgs	`bump-cursor-cli-pin.yml`'s own header

Every instruction-to-an-agent in the old file is still present. What was cut
is the second telling of a rationale, not the rule.

Three substantive changes beyond compression

The per-workflow catalog is replaced by a pointer to the README table. A
second catalog drifts — and this one already had: it was missing
linear-ticket.yml and pr-area-label.yml entirely, both of which have had
docs/callers/ pages for a while.
The Commands block was stale the same way — it listed 9 suites against 13
test-*.yml workflows (no pr-risk, pr-size, area-label or linear-ticket). It
now gives the two general forms and names the path-filtered test workflow as
the authority, so it self-heals instead of drifting again.
The three things the public catalog genuinely cannot say are kept and made
explicit as their own block: this repo is deliberately not self-enrolled in
detect-unreviewed-merge or public-repo-hygiene, and a groom / pr-risk /
pr-derisk caller pins twice.

Review round (`3c87d30`)

The four-lab panel raised 8 findings; all 8 were verified against the tree and
fixed in 3c87d30, except two deferred to follow-ups (noted below).

High — bash <dir>/tests/test_*.sh ran only the FIRST suite: the glob's
remaining paths become ignored positional args, silently skipping 5 of
pr-risk's 6 and 2 of bump-callers' 3. Now a loop, and globbing tests/*.sh
rather than test_*.sh so it also reaches groom's sandbox-tests.sh — the
only automated proof of the agent credential boundary.
Medium — the condensed versioning step had dropped && git push -f origin v1, so following it moved the tag locally only. Restored, matching README.md.
Medium — "groom.yml is the sanctioned exception" read as exempting groom
from the empty-ref guard. Both load-bearing qualifiers are back: the carve-out
is the default: half only and only for a default of exactly '', and
job.workflow_sha proves IMMUTABILITY not non-emptiness, so groom still guards
every checkout. Both halves are gated by check_workflow_pins.py.
Low ×4 — groom's shell suite and cursor-review's shellcheck-only scripts
were missing from Commands; the Go size gate had no documented local command;
"Each directory owns a README" was false for .github/workflows/ and
scripts/check-pr-size/; and "one per fleet" dropped the carve-out that
pr-risk and pr-derisk SHARE PR_RISK_CALLERS (creating a PR_DERISK_CALLERS
the bumper never reads leaves those callers permanently unbumped).

The compression paying for these additions is the same de-duplication as the
original trim — rationale that already lives in the linked READMEs.

Provenance

Verified: python3 .github/agents-md-integrity/check_agents_md.py --root .
passes at 150 lines with only the pre-existing CODEOWNERS warning. Every command
the Commands block now documents was executed in a clean worktree: all five shell
suites via the new loop form (bump-callers 3/3, pr-risk 6/6, pr-derisk 1/1 pass;
area-label and groom fail only on missing local yq / apt-get), all seven
stdlib Python suites (OK), and the Go form. The de-duplication table above was
checked by grepping each dropped passage against the rest of the tree.

Deviations: none from the stated scope — still docs-only, still 150 lines.
Two findings were deferred rather than fixed here and are recorded as follow-ups:
self-enrolling this repo in agents-md-integrity (a new CI gate plus a roster
change, not a docs edit — so the false claim was softened to the truth instead),
and a pre-existing scripts/check-pr-size Go test that fails whenever git's
init.defaultBranch is main, surfaced by documenting the Go command.

Verification

python3 .github/agents-md-integrity/check_agents_md.py --root .   # passes

CLAUDE.md is untouched and still the bare @AGENTS.md shim; there is still no
.cursorrules. The remaining no CODEOWNERS file found warning is pre-existing
and out of scope for this PR.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/github-workflows/pull/227 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 8/26/2026 **Status:** ✅ Merged **Merged:** 8/26/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/trim-agents-md` --- ### 📝 Commits (2) - [`26e8409`](https://github.com/Comfy-Org/github-workflows/commit/26e8409af9efa46cc07c5994522379d941147b90) docs: trim AGENTS.md to the 150-line target it enforces - [`3c87d30`](https://github.com/Comfy-Org/github-workflows/commit/3c87d3030999abaf1cdb6f5a2a19392edf23f5ae) docs: fix the eight review findings on the trimmed AGENTS.md ### 📊 Changes **1 file changed** (+119 additions, -274 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+119 -274) </details> ### 📄 Description ## What `agents-md-integrity.yml` — the standard this repo *publishes to everyone else* — has been failing on this repo's own `AGENTS.md`. At **305 lines** it was over the hard 200-line ceiling. This brings it to **150**, the aspirational target rather than just under the ceiling. ``` before: FAIL: 'AGENTS.md' is 305 lines, over the hard ceiling of 200. after: Result: passed with 1 warning(s). # the pre-existing CODEOWNERS warning ``` ## ELI5 Our own rulebook says "keep the rulebook under 200 lines." Ours had grown to 305, so the checker we ship to other repos was red on us. This cuts it back to 150 by deleting the parts that were already written down somewhere else and linking to those places instead — nothing is actually forgotten, it just isn't said twice. ## The trim is de-duplication, not deletion Every passage removed already lives, usually in far more depth, in a doc `AGENTS.md` links to. I checked each one before cutting it: | Removed from AGENTS.md | Already documented in | |---|---| | groom's `package.json` CLI pin | `.github/groom/README.md` §"the agent CLI pin (BE-5373)" | | `job.workflow_sha` vs the OIDC claim | `docs/callers/groom.md` | | the public-repo-hygiene allowlist rationale | `.github/public-repo-hygiene/README.md` §"Why the allowlist lives here" | | roster / enrollment / un-bumpable entries | `.github/bump-callers/README.md`, `CONTRIBUTING.md` | | cursor-review's deleted `blocking:` input | `README.md`, `docs/callers/cursor-review.md`, `.github/cursor-review/README.md` | | the cursor-cli pin trust anchor + nixpkgs | `bump-cursor-cli-pin.yml`'s own header | **Every instruction-to-an-agent in the old file is still present.** What was cut is the second telling of a rationale, not the rule. ## Three substantive changes beyond compression 1. **The per-workflow catalog is replaced by a pointer to the README table.** A second catalog drifts — and this one already had: it was missing `linear-ticket.yml` and `pr-area-label.yml` entirely, both of which have had `docs/callers/` pages for a while. 2. **The Commands block was stale the same way** — it listed 9 suites against 13 `test-*.yml` workflows (no pr-risk, pr-size, area-label or linear-ticket). It now gives the two general forms and names the path-filtered test workflow as the authority, so it self-heals instead of drifting again. 3. **The three things the public catalog genuinely cannot say are kept and made explicit** as their own block: this repo is deliberately *not* self-enrolled in `detect-unreviewed-merge` or `public-repo-hygiene`, and a groom / pr-risk / pr-derisk caller pins twice. ## Review round (3c87d30) The four-lab panel raised 8 findings; all 8 were verified against the tree and fixed in `3c87d30`, except two deferred to follow-ups (noted below). - **High** — `bash <dir>/tests/test_*.sh` ran only the FIRST suite: the glob's remaining paths become ignored positional args, silently skipping 5 of pr-risk's 6 and 2 of bump-callers' 3. Now a loop, and globbing `tests/*.sh` rather than `test_*.sh` so it also reaches groom's `sandbox-tests.sh` — the only automated proof of the agent credential boundary. - **Medium** — the condensed versioning step had dropped `&& git push -f origin v1`, so following it moved the tag locally only. Restored, matching `README.md`. - **Medium** — "`groom.yml` is the sanctioned exception" read as exempting groom from the empty-ref guard. Both load-bearing qualifiers are back: the carve-out is the `default:` half only and only for a default of exactly `''`, and `job.workflow_sha` proves IMMUTABILITY not non-emptiness, so groom still guards every checkout. Both halves are gated by `check_workflow_pins.py`. - **Low ×4** — groom's shell suite and cursor-review's shellcheck-only scripts were missing from Commands; the Go size gate had no documented local command; "Each directory owns a README" was false for `.github/workflows/` and `scripts/check-pr-size/`; and "one per fleet" dropped the carve-out that pr-risk and pr-derisk SHARE `PR_RISK_CALLERS` (creating a `PR_DERISK_CALLERS` the bumper never reads leaves those callers permanently unbumped). The compression paying for these additions is the same de-duplication as the original trim — rationale that already lives in the linked READMEs. ## Provenance **Verified:** `python3 .github/agents-md-integrity/check_agents_md.py --root .` passes at 150 lines with only the pre-existing CODEOWNERS warning. Every command the Commands block now documents was executed in a clean worktree: all five shell suites via the new loop form (bump-callers 3/3, pr-risk 6/6, pr-derisk 1/1 pass; area-label and groom fail only on missing local `yq` / `apt-get`), all seven stdlib Python suites (OK), and the Go form. The de-duplication table above was checked by grepping each dropped passage against the rest of the tree. **Deviations:** none from the stated scope — still docs-only, still 150 lines. Two findings were deferred rather than fixed here and are recorded as follow-ups: self-enrolling this repo in `agents-md-integrity` (a new CI gate plus a roster change, not a docs edit — so the false claim was softened to the truth instead), and a pre-existing `scripts/check-pr-size` Go test that fails whenever git's `init.defaultBranch` is `main`, surfaced by documenting the Go command. ## Verification ```bash python3 .github/agents-md-integrity/check_agents_md.py --root . # passes ``` `CLAUDE.md` is untouched and still the bare `@AGENTS.md` shim; there is still no `.cursorrules`. The remaining `no CODEOWNERS file found` warning is pre-existing and out of scope for this PR. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:37:38 +00:00