feat: require canonical next-action state comments (#495)

Add canonical issue/PR/discussion state comment templates and validators, final-report rules for STATE/WHO_IS_NEXT/NEXT_ACTION/NEXT_PROMPT, and queue-controller guidance. Posting enforcement remains in #496. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-08 03:17:38 -04:00
parent 48cf3a334b
commit 9235f3a23c
8 changed files with 757 additions and 1 deletions
@@ -167,6 +167,7 @@ Ready-to-copy task prompts live in [`templates/`](templates/):
 - [`reconcile-closed-not-merged-pr.md`](templates/reconcile-closed-not-merged-pr.md)
 - [`worktree-cleanup.md`](templates/worktree-cleanup.md)
 - [`release-tag.md`](templates/release-tag.md)
+- [`canonical-state-comments.md`](templates/canonical-state-comments.md)

 ## Adapting to a project

@@ -182,4 +183,4 @@ Ready-to-copy task prompts live in [`templates/`](templates/):

 Releases follow SemVer from remote `master` only, after full test suite passes.
 See [`templates/release-tag.md`](templates/release-tag.md) and
-`scripts/release-tag`.
+`scripts/release-tag`.
@@ -0,0 +1,148 @@
+# Template: canonical state comments
+
+Use these only for workflow-changing comments. Casual discussion does not need
+the full template.
+
+## Issue
+
+```text
+## Canonical Issue State
+
+STATE:
+<ready-for-author | in-progress | blocked | PR-open | needs-review | ready-to-merge | merged | closed | superseded>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | merger | reconciler | user>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+WHAT_HAPPENED:
+<latest meaningful event>
+
+WHY:
+<decision rationale>
+
+RELATED_DISCUSSION:
+<link/reference or none>
+
+RELATED_PRS:
+- #...
+
+BRANCH:
+<branch or none>
+
+HEAD_SHA:
+<40-character SHA or none>
+
+VALIDATION:
+<tests/proofs or none>
+
+BLOCKERS:
+<blocker and unblock condition, or none>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```
+
+## PR
+
+```text
+## Canonical PR State
+
+STATE:
+<needs-review | changes-requested | approved | stale-approval | ready-to-merge | merged | blocked | superseded>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | merger | reconciler | user>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+WHAT_HAPPENED:
+<latest meaningful event>
+
+WHY:
+<decision rationale>
+
+ISSUE:
+#...
+
+BASE:
+<branch>
+
+HEAD:
+<branch>
+
+HEAD_SHA:
+<40-character SHA>
+
+REVIEW_STATUS:
+<none | approved | changes-requested | stale | contaminated>
+
+VALIDATION:
+<tests/proofs>
+
+BLOCKERS:
+<blockers or none>
+
+SUPERSEDES:
+<PRs or none>
+
+SUPERSEDED_BY:
+<PR or none>
+
+MERGE_READY:
+<yes/no and why>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```
+
+## Discussion
+
+```text
+## Canonical Discussion Summary
+
+STATE:
+<needs-more-discussion | ready-for-issues | issues-created | closed>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | user>
+
+DECISION:
+<what was decided>
+
+WHY:
+<reasoning and tradeoffs>
+
+SUBSTANTIVE_COMMENTS:
+<count and summary>
+
+ISSUES_TO_CREATE_OR_CREATED:
+- #...
+
+DEPENDENCY_ORDER:
+<order or none>
+
+NON_GOALS:
+<non-goals>
+
+OPEN_QUESTIONS:
+<questions or none>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```