# Canonical State Comments

Gitea is the durable system of record for workflow continuation. When a
comment changes issue, PR, or discussion state, it should leave enough
information for the next role to continue without private chat history.

Canonical comments answer:

- what state the object is in
- who acts next
- what the next actor should do
- the exact prompt the next actor should run
- which proof, blocker, or dependency matters

Non-workflow discussion comments do not need this template.

## Issue State

Use this when an issue becomes ready, blocked, in progress, PR-open,
superseded, merged, or otherwise changes workflow direction.

```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 State

Use this when a PR needs review, receives changes requested, is approved,
is stale, is superseded, or becomes ready for merge.

```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 Summary

Discussions should normally have at least five substantive comments before
conversion into issues. A controller may waive that only for tiny mechanical,
urgent, or explicitly trivial work.

```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>
```

## Validation Rules

The final-report validator rejects canonical state update claims when the
report omits the canonical block or when the block lacks:

- `STATE`
- `WHO_IS_NEXT`
- `NEXT_ACTION`
- `NEXT_PROMPT`

It also rejects vague next actions such as `continue`, ready-to-merge states
without approval/head-SHA proof, superseded states without canonical item
proof, and blocked states without an unblock condition.