(BE-3871) #52

New issue

Closed

opened 2026-10-26 22:35:45 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:35:45 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/github-workflows/pull/42
Author: @mattmillerai
Created: 7/21/2026
Status: ✅ Merged
Merged: 7/21/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-3871-groom-briefs

📝 Commits (2)

ad5461d feat(groom): extract finder/verifier briefs into .github/groom/ (BE-3871)
8ccf76e fix(groom): harden finder/verifier briefs per cursor-review panel (BE-3871)

📊 Changes

3 files changed (+99 additions, -0 deletions)

View changed files

➕ .github/groom/README.md (+83 -0)
➕ .github/groom/finder.md (+9 -0)
➕ .github/groom/verifier.md (+7 -0)

📄 Description

ELI-5

Groom is the periodic robot that reads a repo and suggests worthwhile cleanups
(dedupe this, converge that, delete this dead code). Until now its two
instruction sheets — the finder (proposes cleanups) and the verifier (a
fresh skeptic that CONFIRMs/DOWNGRADEs/REJECTs each one) — were buried as inline
text inside a shell script on the studio. This PR lifts those two sheets out into
plain, reviewable files under .github/groom/, exactly like
.github/cursor-review/ already owns the review-panel prompts. Now the team can
PR against the prompt — which is the whole point of the groom initiative:
collaborate on the prompt, not the code.

Nothing runs differently today. The studio keeps using its inline copy until a
separate follow-up points it at these files. This PR just creates the shared,
proven source of truth.

What

Extracts the GROOM_FINDER / GROOM_VERIFIER briefs out of the studio runner's
inline heredocs into version-controlled brief files:

.github/groom/finder.md — phase-1 finder brief (candidate findings, hard
precision bar, steelman-against per finding).
.github/groom/verifier.md — phase-2 adversarial-verifier brief
(CONFIRM / DOWNGRADE / REJECT, security flag, stable dedup signature).
.github/groom/README.md — the two-phase contract, the JSON handoff shape,
and the placeholder-substitution consumption contract the reusable groom
workflow (Phase 2, forthcoming) and the studio daemon will both use.

Runtime specifics (repo, clone path, scan scope, output paths) are tokenized as
{{DOUBLE_BRACE}} placeholders — double-brace so they never collide with the
single-brace JSON inside the briefs. A consumer fetches the file at a pinned ref,
substitutes the placeholders, and passes the result as the phase prompt.

Byte-parity (proven)

The brief files were generated directly from the current inline source (never
hand-transcribed), and I verified that substituting the placeholders back with
real runtime values reproduces the current inline brief byte-for-byte — for
both a package scope and a whole-repo scope:

FINDER   parity: IDENTICAL (1662 bytes)   VERIFIER parity: IDENTICAL (1845 bytes)   # package scope
FINDER   parity: IDENTICAL (1589 bytes)   VERIFIER parity: IDENTICAL (1835 bytes)   # whole-repo scope

So a consumer that renders template + substitution gets exactly today's prompt
— which is what lets the studio daemon adopt the shared briefs with zero change
to what groom finds.

Scope / judgment calls (please read)

Acceptance criterion "studio groom reads the shared briefs; a live tick
yields equivalent findings" is intentionally NOT in this PR. That repoint
lives in a different repo (the studio groom daemon / supervisor-groom.sh),
so it is a sequenced follow-up PR that can only land after these files are
on main (the daemon fetches them from here). This PR delivers criterion 1
(the files exist) and criterion 3 (no behavior change today — the daemon still
runs its inline heredocs until it's repointed), and de-risks the repoint by
proving the static byte-parity above. The follow-up just swaps the inline
heredocs for a fetch + the placeholder substitution documented in the README.
AGENTS.md / top-level README left unchanged on purpose. The README catalog
and the AGENTS.md "new reusable workflow" convention are about workflows;
groom has no workflow yet (that's Phase 2). Wiring .github/groom/ into the
catalog is the natural job of the Phase-2 workflow PR, so I kept this diff to
just the three brief files rather than touch the gated AGENTS.md.
Not a stacked PR — base is main.

Ticket: BE-3871 (parent BE-3870).

_{🔄 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/42 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 7/21/2026 **Status:** ✅ Merged **Merged:** 7/21/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-3871-groom-briefs` --- ### 📝 Commits (2) - [`ad5461d`](https://github.com/Comfy-Org/github-workflows/commit/ad5461d13b529ab01d2cd6baa32279d46d178e72) feat(groom): extract finder/verifier briefs into .github/groom/ (BE-3871) - [`8ccf76e`](https://github.com/Comfy-Org/github-workflows/commit/8ccf76e126022847a2b3f82333f8ac91d81308e0) fix(groom): harden finder/verifier briefs per cursor-review panel (BE-3871) ### 📊 Changes **3 files changed** (+99 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `.github/groom/README.md` (+83 -0) ➕ `.github/groom/finder.md` (+9 -0) ➕ `.github/groom/verifier.md` (+7 -0) </details> ### 📄 Description ## ELI-5 Groom is the periodic robot that reads a repo and suggests worthwhile cleanups (dedupe this, converge that, delete this dead code). Until now its two instruction sheets — the **finder** (proposes cleanups) and the **verifier** (a fresh skeptic that CONFIRMs/DOWNGRADEs/REJECTs each one) — were buried as inline text inside a shell script on the studio. This PR lifts those two sheets out into plain, reviewable files under `.github/groom/`, exactly like `.github/cursor-review/` already owns the review-panel prompts. Now the team can PR against the *prompt* — which is the whole point of the groom initiative: **collaborate on the prompt, not the code.** Nothing runs differently today. The studio keeps using its inline copy until a separate follow-up points it at these files. This PR just creates the shared, proven source of truth. ## What Extracts the `GROOM_FINDER` / `GROOM_VERIFIER` briefs out of the studio runner's inline heredocs into version-controlled brief files: - **`.github/groom/finder.md`** — phase-1 finder brief (candidate findings, hard precision bar, steelman-against per finding). - **`.github/groom/verifier.md`** — phase-2 adversarial-verifier brief (`CONFIRM` / `DOWNGRADE` / `REJECT`, `security` flag, stable dedup `signature`). - **`.github/groom/README.md`** — the two-phase contract, the JSON handoff shape, and the placeholder-substitution **consumption contract** the reusable groom workflow (Phase 2, forthcoming) and the studio daemon will both use. Runtime specifics (repo, clone path, scan scope, output paths) are tokenized as `{{DOUBLE_BRACE}}` placeholders — double-brace so they never collide with the single-brace JSON inside the briefs. A consumer fetches the file at a pinned ref, substitutes the placeholders, and passes the result as the phase prompt. ## Byte-parity (proven) The brief files were generated **directly from the current inline source** (never hand-transcribed), and I verified that substituting the placeholders back with real runtime values reproduces the current inline brief **byte-for-byte** — for both a package scope and a whole-repo scope: ``` FINDER parity: IDENTICAL (1662 bytes) VERIFIER parity: IDENTICAL (1845 bytes) # package scope FINDER parity: IDENTICAL (1589 bytes) VERIFIER parity: IDENTICAL (1835 bytes) # whole-repo scope ``` So a consumer that renders `template + substitution` gets exactly today's prompt — which is what lets the studio daemon adopt the shared briefs with **zero change to what groom finds.** ## Scope / judgment calls (please read) - **Acceptance criterion "studio groom reads the shared briefs; a live tick yields equivalent findings" is intentionally NOT in this PR.** That repoint lives in a *different repo* (the studio groom daemon / `supervisor-groom.sh`), so it is a **sequenced follow-up PR** that can only land after these files are on `main` (the daemon fetches them from here). This PR delivers criterion 1 (the files exist) and criterion 3 (no behavior change today — the daemon still runs its inline heredocs until it's repointed), and **de-risks** the repoint by proving the static byte-parity above. The follow-up just swaps the inline heredocs for a fetch + the placeholder substitution documented in the README. - **AGENTS.md / top-level README left unchanged on purpose.** The README catalog and the AGENTS.md "new reusable workflow" convention are about *workflows*; groom has no workflow yet (that's Phase 2). Wiring `.github/groom/` into the catalog is the natural job of the Phase-2 workflow PR, so I kept this diff to just the three brief files rather than touch the gated AGENTS.md. - **Not a stacked PR** — base is `main`. Ticket: BE-3871 (parent BE-3870). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:35:45 +00:00