docs(groomer): define close proof policy

[joryirving]

Defines the v1 proof boundary for #1069: only current-repository already_done may auto-close; duplicate and superseded stay recommendations. Documents human authority, audit and fixture gates for any later extension, plus the existing reopened/regression guardrail gap. No close behavior changes.

Closes #1069.

[joryirving]

I'd approve the decision itself. Only current-repo already_done auto-closes, and duplicate and superseded stay recommendations. That's the conservative read of #1069, and it lines up with what #1100 now enforces: every acceptance criterion grounded at the pinned SHA, with a closing PR as corroboration only. Dropping the "explicit human duplicate authority" path is also the right call to me. If a human already decided it's a duplicate, closing it themselves is one click, and building verified-actor plumbing so the groomer can do that click isn't worth it.

A few things I'd change before merging.

The reopened/regression gap is called out as needing "a separate guardrail follow-up", but nothing tracks it. A safety gap that only lives in a doc tends to rot, so I'd file it and link it here. The doc also undersells what already exists. src/lib/groomer/close-grounding.ts:16-19 makes a merged closing PR corroboration-only precisely because an open issue with a merged closing PR usually means someone reopened it. The residual risk is narrower and worth saying precisely: a regression where the code is still present but the behaviour is broken. Every criterion's text is still in the files, so grounding passes and a live bug gets closed. That's the case the follow-up needs to cover.

Most of the doc is the "Requirements for a separately approved extension" section and the 10-row fixture matrix, which specify close classes this same doc says aren't approved. Whoever eventually proposes one will write their own design, so I'd cut that down to two or three bullets (bound authority, live target re-check, regression fixtures).

The prose reads like it was negotiated with a reviewer. There are a lot of sentences that exist to say what the doc isn't claiming, like "This link documents policy intent, not support for any hypothetical authority or target-verification feature" in docs/hosted-groomer.md and "that prohibition does not claim the current pipeline never posts a comment before closing". The v1 decision fits in about four sentences and would be easier to trust if it read that way.

docs/hosted-groomer.md now states the boundary twice, once in the new line under Close policy and again in the rewritten paragraph near the end. One pointer to the new doc is enough.

The factual claims I checked hold up. GET /api/groomer/runs/[id] exists, recommendations live in mutationPlan and src/app/groomer/page.tsx only types that field without rendering it, and the applier does post a comment before closing (src/lib/groomer/mutation-applier.ts:9).

[its-saffron]

AI Automated Review (incremental)

Incremental review: reviewed the changes since the last managed review; unresolved findings from that review are carried forward.

Analysis engine: glm-5.3-flash@https://litellm.jory.dev/v1 (openai) — escalated (fast_low_confidence)

Recommendation: Approve. This incremental delta is a pure documentation trim of the groomer close policy (docs/groomer-close-policy.md) and its cross-reference in docs/hosted-groomer.md. No code, schema, workflow, or image changes; no risk flags; CI is green at the head SHA. The trim preserves every normative decision from the prior version — only already_done may auto-close, duplicate/superseded stay recommendations, a merged PR is corroboration only, and any extension requires a separately approved design with authority, live-target, and regression-fixture gates.

Change-by-change findings

1. docs/groomer-close-policy.md — Condensed from 48 to 27 lines. The v1 decision, the human-authority boundary, the duplicate-identity rule, and the superseded/already_done evidence rule all survive intact. The detailed fixture matrix and the per-gate expansion (bound evidence, versioned live check, safe uncertainty handling, no generic override) are collapsed into three bullets (bound authority, live target check, regression fixtures). This loses some prescriptive detail for future extension authors, but the doc explicitly frames these as gates for a separately approved extension, not current behavior, so nothing normative about today's groomer is weakened. One nuance: the prior text stated outright that "the existing already_done path does not check the issue's reopened/regression timeline"; the new text softens this to "The remaining risk is a live regression while the cited code remains present… PR 1113 tracks that guardrail," with the reopened-after-merge risk retained in the preceding sentence. The doc still does not claim the guardrail exists, so this is acceptable, but the explicit current-behavior caveat is now thinner (info).
2. docs/hosted-groomer.md — Two paragraph trims. The close-policy section keeps the link to groomer-close-policy.md and the approved-scope statement. The out-of-scope paragraph drops the explicit "The v1 decision for PR 1069 is made in [Groomer Close Policy]" framing, so the issue-number traceability from hosted-groomer.md back to PR 1069 now lives only one hop away in the linked doc (info).

Standards Compliance

• Lint/typecheck block CI (AGENTS.md): Satisfied — CI at commit 3fbbac4 reports Lint and Typecheck both success, along with Tests, Build, Coverage, Database migrations/integration, and smoke, all green.
• Code standards (error handling, validation, secrets): Not applicable — the diff touches only Markdown; no tokens, .env files, or build output are introduced.
• Label conventions / subsystem map: Not applicable — no labels or code paths are touched.

Linked Issue Fit

• The PR body says "Closes PR 1069" and frames the change as defining the v1 proof boundary. The requirement derived from PR 1069 — whether a merged PR referencing an issue suffices or current repo behavior must be verified — is answered directly in the doc: "a merged PR alone is insufficient," with corroboration-only status for related PRs/issues. This matches the implemented grounding contract visible in the repository (src/lib/groomer/close-grounding.ts requires every acceptance criterion to be grounded in a file read at the pinned head, and the eval corpus in src/lib/groomer/evals/cases/ rejects merged-PR-only and sibling-evidence closes), so the doc is consistent with actual behavior rather than aspirational.
• The doc's reopened/regression guardrail gap is now delegated to PR 1113. The linked-source fetch for PR 1113 returned no issue body, so I could not independently confirm that PR 1113 actually tracks that guardrail; the reference is plausible (the corpus links it as a source) but unverified (see Unknowns).

Tool Harness Findings

The tool harness issued no tool calls; this review is based on the provided corpus (diff, CI results, impact scan, history). No additional tool evidence was gathered.

Unknowns or Needs Verification

• PR 1113 content: The linked issue body was not fetched (GitHub HTML fetch skipped), so the claim "[PR 1113] tracks that guardrail" is unverified. If PR 1113 does not exist or tracks something else, the pointer should be corrected — low risk, docs-only.
• PR 1069 acceptance criteria: No issue body for PR 1069 is in the corpus; fit is assessed from the PR body, the requirement ledger, and the doc's internal consistency with the implemented grounding validator.
• Fixture-matrix removal: The removed fixture matrix was gate documentation for hypothetical future extensions, not a test of current behavior; no existing test asserted it, so its removal does not reduce coverage. The regression-while-excerpt-unchanged scenario remains an open guardrail (PR 1113), which the doc honestly discloses rather than claiming as implemented.

[its-saffron]

Info (docs): The explicit statement that the current already_done path does not check the reopened/regression timeline is softened to a PR 1113 pointer; consider keeping one sentence of current-behavior caveat for future readers.

Automated finding from AI PR review.

[its-saffron]

Info (docs): The trimmed paragraph drops the explicit 'PR 1069 v1 decision' reference, so traceability from hosted-groomer.md back to issue PR 1069 now depends entirely on the linked close-policy doc.

Automated finding from AI PR review.