feat: add controller issue-acceptance gate (Closes #500)

Add issue_acceptance_gate validation for Controller Issue Acceptance comments, final-report rules blocking merge-only issue completion claims, documentation/templates, and regression tests. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-08 03:27:37 -04:00
parent 48cf3a334b
commit 33d01ba65e
6 changed files with 622 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Controller Issue-Acceptance Gate
+
+A merged PR does not automatically prove an issue is fully satisfied. After
+merge, a controller must audit the linked issue against its acceptance criteria
+and post a durable handoff before the issue is treated as complete.
+
+## Workflow position
+
+1. Author implements the issue and opens a PR.
+2. Reviewer reviews the PR.
+3. Merger merges the approved PR.
+4. **Controller performs issue-acceptance audit.**
+5. Controller posts a `## Controller Issue Acceptance` comment with either:
+   - `STATE: accepted` and checked criteria, or
+   - a rejection path (`more-work-required`, `needs-tests`, `needs-docs`, etc.)
+     with `MISSING_WORK` and a paste-ready `NEXT_PROMPT`.
+
+Gitea may auto-close an issue via `Closes #N` in the PR body. That closure is
+merge mechanics only. Controller acceptance is still required before any final
+report or queue controller treats the issue as complete.
+
+## Template
+
+Use `issue_acceptance_gate.render_controller_acceptance_template()` or the
+copy in
+[`skills/llm-project-workflow/templates/controller-issue-acceptance.md`](../skills/llm-project-workflow/templates/controller-issue-acceptance.md).
+
+## Final-report rules
+
+Final reports must not claim `issue complete` solely because a PR merged.
+Either:
+
+- include a valid `## Controller Issue Acceptance` block with
+  `STATE: accepted`, or
+- explicitly state `controller acceptance pending` and identify the controller
+  as the next actor.
+
+`final_report_validator` enforces this through
+`issue_acceptance_gate.validate_final_report_issue_acceptance()`.
+
+## Role boundaries
+
+- Authors must not mark their own issues accepted.
+- Reviewers must not mark issue acceptance unless acting under controller
+  capability.
+- Mergers merge PRs; they do not substitute for controller acceptance.
+
+## Related
+
+- #495 — canonical next-action comment templates
+- #496 — fail-closed canonical comment validation before posting
+- #303 — controller handoff schema for reconciliation workflows