[PR #58] [MERGED] ci: add AGENTS.md integrity check (thin caller of shared workflow) #59

New issue

Closed

opened 2026-10-26 22:34:30 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:34:30 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-swift-sdk/pull/58
Author: @mattmillerai
Created: 8/2/2026
Status: ✅ Merged
Merged: 8/25/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-5927-agents-md-integrity

📝 Commits (1)

54462c9 ci: add AGENTS.md integrity check (thin caller of shared workflow)

📊 Changes

1 file changed (+18 additions, -0 deletions)

View changed files

➕ .github/workflows/agents-md-integrity.yml (+18 -0)

📄 Description

ELI-5

Every Comfy repo keeps its agent instructions in one thin AGENTS.md, with CLAUDE.md as a one-line import shim pointing at it. It's easy for that to quietly rot — someone pastes 400 lines into AGENTS.md, or drops a stale .cursorrules next to it, and the agents start reading two different sets of rules. This PR adds a tiny CI job that checks those rules on every PR, so the rot gets caught at review time instead of months later.

The job itself contains no logic. It just calls the shared reusable workflow in Comfy-Org/github-workflows, which is the single source of truth for the check. This repo already passes.

What changed

One new file: .github/workflows/agents-md-integrity.yml — an 18-line thin caller. Runs on pull_request and on pushes to main (this repo's default branch, confirmed via gh repo view).

Both the uses: ref and the workflows_ref input are pinned to the same full commit SHA (bcde90f4c5b0267d32583dc1d339ac8731c0da9a), not the v1 tag. That pairing is the point of the pattern: the checker script is fetched from that pinned commit of the public workflows repo rather than from this repo's own checkout, so a PR can never rewrite the check that gates it.

This repo is also now registered in the AGENTS_MD_CALLERS Actions variable on Comfy-Org/github-workflows under its canonical name Comfy-Org/comfy-swift-sdk, so the upstream auto-bump dispatcher will open SHA-bump PRs here when the shared workflow changes. (This repo was renamed from the old ComfySwiftSDK spelling; the canonical name is what got registered, deliberately, to avoid adding to the registry drift that's being cleaned up separately.)

Verification

Pre-existing compliance, checked before writing anything. Ran the upstream check_agents_md.py against a clean git archive export of origin/main: passed with one warning (no CODEOWNERS, so AGENTS.md has no DRI). That check is warn-only by default (require_codeowners defaults to false), so it does not fail the build. Re-ran the same checker against this branch's tree: same result, passed with 1 warning. So this job should be green on arrival, not red-on-arrival work for someone else.
Root AGENTS.md is 63 lines (ceiling 200, aspirational target 150). Root CLAUDE.md is the one-line @AGENTS.md import shim. No .cursorrules.
actionlint clean, on the new file and on all workflows in the repo.
Confirmed the pinned SHA resolves in Comfy-Org/github-workflows and that the reusable workflow at that exact ref declares a workflow_call trigger with a workflows_ref input — i.e. the pin is not pointing at a commit predating the input.
Repo suite green on this branch: swift build + swift test --no-parallel → 239 tests in 29 suites passed. (No Swift source is touched by this PR; run as a base-sanity check.)

Judgment calls

The registry entry was added before this PR merged, per the rollout runbook's ordering. That is safe rather than merely tolerable: the shared bumper (.github/bump-callers/bump-callers.sh) treats a caller repo whose files are all missing as a successful skip that commits nothing and opens no PR, and its trigger is a push to github-workflows main touching the reusable workflow or the checker — not this registration. So the pre-merge window is a no-op, and the entry starts working the moment this lands.
No concurrency: group, unlike this repo's ci.yml. Kept deliberately identical in shape to the wave-1 callers (e.g. comfy-toolbox) — the fleet's value is that every caller is byte-similar and machine-bumpable, and the job is a ~20s checkout-and-lint. Divergence here would be a small local win and a fleet-wide cost.
The WARN: no CODEOWNERS line will show up in the run annotations. It is intentional and non-fatal; adding a CODEOWNERS DRI for AGENTS.md is a separate call about who owns this file, not something to slip into a CI-wiring PR.

Follow-up for Matt

This check is not enforced until it is made a required status check. As added, AGENTS.md integrity runs on every PR and reports pass/fail, but nothing blocks a merge on it — a PR that bloats AGENTS.md past 200 lines or drops a .cursorrules would go red and still be mergeable. To close that gap, add AGENTS.md integrity (the job's name:, as it appears in the checks list once this has run once on main) to the branch-protection required-status-checks for main on Comfy-Org/comfy-swift-sdk. That is a repo-admin action and is intentionally left to you rather than done from here.

_{🔄 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/comfy-swift-sdk/pull/58 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 8/2/2026 **Status:** ✅ Merged **Merged:** 8/25/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-5927-agents-md-integrity` --- ### 📝 Commits (1) - [`54462c9`](https://github.com/Comfy-Org/comfy-swift-sdk/commit/54462c956f26d32cfc99d636bc0967b2b1196554) ci: add AGENTS.md integrity check (thin caller of shared workflow) ### 📊 Changes **1 file changed** (+18 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `.github/workflows/agents-md-integrity.yml` (+18 -0) </details> ### 📄 Description ## ELI-5 Every Comfy repo keeps its agent instructions in one thin `AGENTS.md`, with `CLAUDE.md` as a one-line import shim pointing at it. It's easy for that to quietly rot — someone pastes 400 lines into `AGENTS.md`, or drops a stale `.cursorrules` next to it, and the agents start reading two different sets of rules. This PR adds a tiny CI job that checks those rules on every PR, so the rot gets caught at review time instead of months later. The job itself contains no logic. It just calls the shared reusable workflow in `Comfy-Org/github-workflows`, which is the single source of truth for the check. This repo already passes. ## What changed One new file: `.github/workflows/agents-md-integrity.yml` — an 18-line thin caller. Runs on `pull_request` and on pushes to `main` (this repo's default branch, confirmed via `gh repo view`). Both the `uses:` ref and the `workflows_ref` input are pinned to the same full commit SHA (`bcde90f4c5b0267d32583dc1d339ac8731c0da9a`), not the `v1` tag. That pairing is the point of the pattern: the checker script is fetched from that pinned commit of the public workflows repo rather than from this repo's own checkout, so a PR can never rewrite the check that gates it. This repo is also now registered in the `AGENTS_MD_CALLERS` Actions variable on `Comfy-Org/github-workflows` under its **canonical** name `Comfy-Org/comfy-swift-sdk`, so the upstream auto-bump dispatcher will open SHA-bump PRs here when the shared workflow changes. (This repo was renamed from the old `ComfySwiftSDK` spelling; the canonical name is what got registered, deliberately, to avoid adding to the registry drift that's being cleaned up separately.) ## Verification - **Pre-existing compliance, checked before writing anything.** Ran the upstream `check_agents_md.py` against a clean `git archive` export of `origin/main`: **passed** with one warning (no `CODEOWNERS`, so `AGENTS.md` has no DRI). That check is warn-only by default (`require_codeowners` defaults to `false`), so it does not fail the build. Re-ran the same checker against this branch's tree: same result, **passed with 1 warning**. So this job should be green on arrival, not red-on-arrival work for someone else. - Root `AGENTS.md` is 63 lines (ceiling 200, aspirational target 150). Root `CLAUDE.md` is the one-line `@AGENTS.md` import shim. No `.cursorrules`. - `actionlint` clean, on the new file and on all workflows in the repo. - Confirmed the pinned SHA resolves in `Comfy-Org/github-workflows` and that the reusable workflow at that exact ref declares a `workflow_call` trigger with a `workflows_ref` input — i.e. the pin is not pointing at a commit predating the input. - Repo suite green on this branch: `swift build` + `swift test --no-parallel` → **239 tests in 29 suites passed**. (No Swift source is touched by this PR; run as a base-sanity check.) ## Judgment calls - **The registry entry was added before this PR merged**, per the rollout runbook's ordering. That is safe rather than merely tolerable: the shared bumper (`.github/bump-callers/bump-callers.sh`) treats a caller repo whose files are all missing as a successful skip that commits nothing and opens no PR, and its trigger is a push to `github-workflows` `main` touching the reusable workflow or the checker — not this registration. So the pre-merge window is a no-op, and the entry starts working the moment this lands. - **No `concurrency:` group**, unlike this repo's `ci.yml`. Kept deliberately identical in shape to the wave-1 callers (e.g. `comfy-toolbox`) — the fleet's value is that every caller is byte-similar and machine-bumpable, and the job is a ~20s checkout-and-lint. Divergence here would be a small local win and a fleet-wide cost. - The `WARN: no CODEOWNERS` line will show up in the run annotations. It is intentional and non-fatal; adding a `CODEOWNERS` DRI for `AGENTS.md` is a separate call about who owns this file, not something to slip into a CI-wiring PR. ## Follow-up for Matt **This check is not enforced until it is made a required status check.** As added, `AGENTS.md integrity` runs on every PR and reports pass/fail, but nothing blocks a merge on it — a PR that bloats `AGENTS.md` past 200 lines or drops a `.cursorrules` would go red and still be mergeable. To close that gap, add `AGENTS.md integrity` (the job's `name:`, as it appears in the checks list once this has run once on `main`) to the branch-protection required-status-checks for `main` on `Comfy-Org/comfy-swift-sdk`. That is a repo-admin action and is intentionally left to you rather than done from here. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:34:30 +00:00