feat(groom): extract finder/verifier briefs into .github/groom/ (BE-3871)#42
Merged
Conversation
…871)
Extract the two-phase groom prompts (finder + adversarial verifier) out of the
studio runner's inline heredocs into version-controlled, co-ownable brief files,
mirroring how .github/cursor-review/ owns the review-panel prompts. Runtime
values are tokenized as {{DOUBLE_BRACE}} placeholders; a consumer substitutes
them at run time, reproducing the previous inline prompt byte-for-byte.
- finder.md — phase-1 candidate-finding brief
- verifier.md — phase-2 CONFIRM/DOWNGRADE/REJECT + dedup-signature brief
- README.md — the two-phase contract, JSON handoff shape, and the
placeholder-substitution consumption contract
mattmillerai
added
agent-coded
mattmillerai
marked this pull request as ready for review
July 21, 2026 02:42
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughAdds a documented two-phase Groom workflow: a Finder generates ranked refactor findings, and a Verifier independently validates them using JSON handoff files, fixed verdicts, security flags, signatures, and substitution rules. ChangesGroom workflow
Sequence Diagram(s)sequenceDiagram
participant Repository as origin/main checkout
participant Finder as Finder agent
participant FinderOutput as FINDER_OUT JSON
participant Verifier as Verifier agent
participant VerifierOutput as VERIFIER_OUT JSON
Repository->>Finder: Inspect repository read-only
Finder->>FinderOutput: Write candidate findings
FinderOutput->>Verifier: Supply candidate JSON
Repository->>Verifier: Recheck code evidence
Verifier->>VerifierOutput: Write verdicts and signatures
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔍 Cursor Review — Consolidated panel
Triggered by @mattmillerai.
Found 7 finding(s).
| Severity | Count |
|---|---|
| 🟠 High | 3 |
| 🟡 Medium | 1 |
| 🟢 Low | 3 |
Panel: 6/8 reviewers contributed findings.
Reviewers that did not contribute: kimi-k2.5:adversarial (empty), kimi-k2.5:edge-case (empty)
…-3871) Address review-panel findings on the extracted groom briefs: - verifier: emit "security" as an explicit <true|false> placeholder (was a hard-coded false that could anchor the model and defeat the security gate) - both briefs: add an untrusted-input + no-network + no-mutation boundary (repo content and the finder JSON are UNTRUSTED DATA; never follow embedded instructions), while preserving read-only shell inspection and the one result-file write — mirrors the finder's READ-ONLY line onto the verifier - verifier: require the signature <slug> be derived deterministically so the same finding yields the same dedup key across runs - both briefs: require VALID escaped JSON output (esp. the multi-line body) - README: document the substitution-escaping contract and reconcile the parity note with the added safety rails Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 canPR 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_VERIFIERbriefs out of the studio runner'sinline heredocs into version-controlled brief files:
.github/groom/finder.md— phase-1 finder brief (candidate findings, hardprecision bar, steelman-against per finding).
.github/groom/verifier.md— phase-2 adversarial-verifier brief(
CONFIRM/DOWNGRADE/REJECT,securityflag, stable dedupsignature)..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 thesingle-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:
So a consumer that renders
template + substitutiongets 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)
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.
and the AGENTS.md "new reusable workflow" convention are about workflows;
groom has no workflow yet (that's Phase 2). Wiring
.github/groom/into thecatalog 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.
main.Ticket: BE-3871 (parent BE-3870).