Add controller issue-acceptance gate before issues can be closed as complete #500

New Issue

2026-07-08T02:22:50-05:00

jcwalker3 commented

2026-07-08 02:22:50 -05:00

Problem

A PR being merged does not always prove the linked issue is fully satisfied. The code may pass review but still miss acceptance criteria, lack tests, need documentation, require UX polish, or expose follow-up gaps.

We need a controller gatekeeper step after PR merge and before an issue is considered complete.

Goal

Add workflow support and validation so issues are not considered complete merely because a PR merged. A controller must perform an issue-acceptance audit and either accept the issue or request more work.

Core rule

Only a controller/issue-acceptance role should mark an issue as complete after checking the merged work against the issue's acceptance criteria.

If the controller is not satisfied, they must post a canonical next-action comment explaining what is missing and who acts next.

Required workflow

Author implements issue.
Author opens PR.
Reviewer reviews PR.
Merger merges approved PR.
Controller performs issue-acceptance audit.
Controller decides:
- ACCEPTED: issue can remain closed / be marked complete
- MORE_WORK_REQUIRED: issue must be reopened or follow-up issue created
- NEEDS_TESTS: more tests required
- NEEDS_DOCS: documentation required
- NEEDS_FEATURE_ENHANCEMENT: implementation is too narrow
- NEEDS_REVIEWER_CLARIFICATION: reviewer/controller discussion required
Controller posts canonical issue state comment with the decision and next prompt.

Controller acceptance comment template

Use this template when a controller audits a merged PR against an issue:

## Controller Issue Acceptance

STATE:
<accepted | more-work-required | needs-tests | needs-docs | needs-feature-enhancement | needs-follow-up-issue | blocked>

WHO_IS_NEXT:
<author | reviewer | merger | reconciler | controller | user>

NEXT_ACTION:
<one sentence>

NEXT_PROMPT:
<paste-ready prompt for the next LLM>

ISSUE:
#...

MERGED_PR:
#...

MERGE_COMMIT:
<sha>

ACCEPTANCE_CRITERIA_CHECKED:
- [x] ...
- [ ] ...

VALIDATION_REVIEWED:
<tests/proofs reviewed>

CONTROLLER_DECISION:
<accepted or rejected>

WHY:
<reasoning>

MISSING_WORK:
<none, or exact missing work>

FOLLOW_UP_ISSUES:
<none, or issue list to create>

BLOCKERS:
<none, or exact blockers>

LAST_UPDATED_BY:
<identity/profile/date>

Template rules

Do not write accepted unless acceptance criteria were checked.
Do not write issue complete unless the controller decision is accepted.
If more work is required, include a ready-to-paste author prompt.
If tests are missing, say exactly what tests are needed.
If docs are missing, say exactly what docs are needed.
If a follow-up issue is better than reopening, explain why.

Acceptance criteria

Add documentation for the controller issue-acceptance gate.
Add a canonical issue-acceptance comment template.
Add final-report validation requiring merged PR reports to identify whether controller acceptance is still pending.
Add validation that issue closure/completion requires controller acceptance proof.
Add tests rejecting final reports that say "issue complete" only because a PR merged.
Add tests requiring controller acceptance to cite:
- issue number
- merged PR number
- merge commit
- acceptance criteria checked
- tests/proofs reviewed
- final decision
- next actor
- next prompt
Add tests for controller rejection paths:
- more work required
- tests required
- docs required
- feature enhancement required
- follow-up issue required
If controller rejects completion, the comment must include a ready-to-paste author prompt.
If controller accepts completion, the comment must include proof that acceptance criteria are satisfied.
If Gitea auto-closes the issue via Closes #N, controller must still be able to reopen or create follow-up work if acceptance is not satisfied.

Non-goals

Do not let authors close their own issues as accepted.
Do not let reviewers automatically mark issue acceptance unless acting under controller capability.
Do not block normal PR merge mechanics.
Do not weaken role separation.

## Problem A PR being merged does not always prove the linked issue is fully satisfied. The code may pass review but still miss acceptance criteria, lack tests, need documentation, require UX polish, or expose follow-up gaps. We need a controller gatekeeper step after PR merge and before an issue is considered complete. ## Goal Add workflow support and validation so issues are not considered complete merely because a PR merged. A controller must perform an issue-acceptance audit and either accept the issue or request more work. ## Core rule Only a controller/issue-acceptance role should mark an issue as complete after checking the merged work against the issue's acceptance criteria. If the controller is not satisfied, they must post a canonical next-action comment explaining what is missing and who acts next. ## Required workflow 1. Author implements issue. 2. Author opens PR. 3. Reviewer reviews PR. 4. Merger merges approved PR. 5. Controller performs issue-acceptance audit. 6. Controller decides: - **ACCEPTED**: issue can remain closed / be marked complete - **MORE_WORK_REQUIRED**: issue must be reopened or follow-up issue created - **NEEDS_TESTS**: more tests required - **NEEDS_DOCS**: documentation required - **NEEDS_FEATURE_ENHANCEMENT**: implementation is too narrow - **NEEDS_REVIEWER_CLARIFICATION**: reviewer/controller discussion required 7. Controller posts canonical issue state comment with the decision and next prompt. ## Controller acceptance comment template Use this template when a controller audits a merged PR against an issue: ```text ## Controller Issue Acceptance STATE: <accepted | more-work-required | needs-tests | needs-docs | needs-feature-enhancement | needs-follow-up-issue | blocked> WHO_IS_NEXT: <author | reviewer | merger | reconciler | controller | user> NEXT_ACTION: <one sentence> NEXT_PROMPT: <paste-ready prompt for the next LLM> ISSUE: #... MERGED_PR: #... MERGE_COMMIT: <sha> ACCEPTANCE_CRITERIA_CHECKED: - [x] ... - [ ] ... VALIDATION_REVIEWED: <tests/proofs reviewed> CONTROLLER_DECISION: <accepted or rejected> WHY: <reasoning> MISSING_WORK: <none, or exact missing work> FOLLOW_UP_ISSUES: <none, or issue list to create> BLOCKERS: <none, or exact blockers> LAST_UPDATED_BY: <identity/profile/date> ``` ### Template rules 1. Do not write `accepted` unless acceptance criteria were checked. 2. Do not write `issue complete` unless the controller decision is accepted. 3. If more work is required, include a ready-to-paste author prompt. 4. If tests are missing, say exactly what tests are needed. 5. If docs are missing, say exactly what docs are needed. 6. If a follow-up issue is better than reopening, explain why. ## Acceptance criteria 1. Add documentation for the controller issue-acceptance gate. 2. Add a canonical issue-acceptance comment template. 3. Add final-report validation requiring merged PR reports to identify whether controller acceptance is still pending. 4. Add validation that issue closure/completion requires controller acceptance proof. 5. Add tests rejecting final reports that say "issue complete" only because a PR merged. 6. Add tests requiring controller acceptance to cite: - issue number - merged PR number - merge commit - acceptance criteria checked - tests/proofs reviewed - final decision - next actor - next prompt 7. Add tests for controller rejection paths: - more work required - tests required - docs required - feature enhancement required - follow-up issue required 8. If controller rejects completion, the comment must include a ready-to-paste author prompt. 9. If controller accepts completion, the comment must include proof that acceptance criteria are satisfied. 10. If Gitea auto-closes the issue via `Closes #N`, controller must still be able to reopen or create follow-up work if acceptance is not satisfied. ## Non-goals - Do not let authors close their own issues as accepted. - Do not let reviewers automatically mark issue acceptance unless acting under controller capability. - Do not block normal PR merge mechanics. - Do not weaken role separation. ## Related - #495 — canonical next-action comment templates and docs - #496 — fail-closed canonical comment validation before posting workflow comments - #303 — controller handoff schema for reconciliation workflows

jcwalker3 commented

2026-07-08 02:23:05 -05:00

Canonical Issue State

STATE: ready-for-author
WHO_IS_NEXT: author
NEXT_ACTION: Implement controller issue-acceptance gate docs, templates, and final-report validation rules
NEXT_PROMPT:

You are the author LLM implementing the controller issue-acceptance gate in Scaled-Tech-Consulting/Gitea-Tools for issue #500.

Goal: Add workflow support so issues are not considered complete merely because a PR merged. A controller must audit merged work against acceptance criteria and post a canonical Controller Issue Acceptance comment.

Hard rules:
1. Start with live identity/profile/runtime checks.
2. Confirm work_issue/create_pr capability before mutation.
3. Work only in a valid branches/ worktree.
4. Do not self-review or merge.
5. Do not weaken review/merge gates.
6. Do not touch /private/tmp/gitea_issue_lock.json.

Deliverables:
- docs for controller issue-acceptance gate
- canonical controller acceptance template file
- final_report_validator rules for controller acceptance pending/accepted/rejected
- tests for accepted and rejected controller decisions
- examples for accepted, more-work-required, needs-tests, needs-docs, follow-up-issue paths

Validation: run focused final-report/workflow tests then broader affected tests.

WHAT_HAPPENED: Durable workflow issue filed for post-merge controller acceptance gate
WHY: PR merge alone does not prove issue acceptance criteria are satisfied
RELATED_PRS: none
BLOCKERS: none
VALIDATION: not yet implemented
LAST_UPDATED_BY: prgs-author / jcwalker3

## Canonical Issue State STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Implement controller issue-acceptance gate docs, templates, and final-report validation rules NEXT_PROMPT: ```text You are the author LLM implementing the controller issue-acceptance gate in Scaled-Tech-Consulting/Gitea-Tools for issue #500. Goal: Add workflow support so issues are not considered complete merely because a PR merged. A controller must audit merged work against acceptance criteria and post a canonical Controller Issue Acceptance comment. Hard rules: 1. Start with live identity/profile/runtime checks. 2. Confirm work_issue/create_pr capability before mutation. 3. Work only in a valid branches/ worktree. 4. Do not self-review or merge. 5. Do not weaken review/merge gates. 6. Do not touch /private/tmp/gitea_issue_lock.json. Deliverables: - docs for controller issue-acceptance gate - canonical controller acceptance template file - final_report_validator rules for controller acceptance pending/accepted/rejected - tests for accepted and rejected controller decisions - examples for accepted, more-work-required, needs-tests, needs-docs, follow-up-issue paths Validation: run focused final-report/workflow tests then broader affected tests. ``` WHAT_HAPPENED: Durable workflow issue filed for post-merge controller acceptance gate WHY: PR merge alone does not prove issue acceptance criteria are satisfied RELATED_PRS: none BLOCKERS: none VALIDATION: not yet implemented LAST_UPDATED_BY: prgs-author / jcwalker3

jcwalker3 referenced this issue from a commit

2026-07-08 02:27:45 -05:00

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

jcwalker3 referenced a pull request that will close this issue

2026-07-08 02:28:52 -05:00

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

jcwalker3 referenced this issue

2026-07-08 02:29:48 -05:00

Add Canonical Thread Handoff protocol for issue and PR comments #505

sysadmin referenced this issue

2026-07-08 21:27:51 -05:00

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