# Canonical state handoff ledger (#494)

Gitea is the system of record for continuation. Every discussion, issue, and PR
should answer: current state, last proof, who acts next, and the exact prompt for
the next role.

## Lifecycle

1. Controller opens a discussion.
2. Discussion accumulates substantive comments (default minimum: five).
3. Controller posts a discussion summary when ready.
4. Controller creates linked issues from the summary.
5. Author locks issue, implements, opens PR.
6. Reviewer reviews at current head.
7. Merger merges after formal approval.
8. Reconciler closes superseded or already-landed PRs.
9. Issue/PR/discussion state comments make the next action obvious at every step.

## Discussion rules

- Do **not** convert a discussion into issues until it has at least **five
  substantive comments**, unless the discussion state comment marks
  `URGENCY: urgent` or `URGENCY: trivial`.
- Substantive comment types: proposal, risk/concern, acceptance criteria,
  implementation approach, dependency/sequence, summary.
- Before issue creation, post a **discussion summary** with decision, issues to
  create, non-goals, unresolved questions, and next prompt.
- Created issues must link back to the discussion; the discussion must link
  forward to created issues.

## State comment templates

Use `state_handoff_ledger.py` helpers or copy the canonical blocks:

- `render_discussion_state_comment(...)`
- `render_discussion_summary_comment(...)`
- `render_issue_state_comment(...)`
- `render_pr_state_comment(...)`
- `render_queue_controller_report(...)`

Post state comments as the **latest canonical update** on the object. Do not
bury state inside PR bodies only.

## Final report requirements

Every final report must include a `Controller Handoff` section with:

- **Current status** — live state after this session
- **Next actor** — `author`, `reviewer`, `merger`, `reconciler`, or `controller`
- **Next action** — one imperative step
- **Next prompt** — ready-to-paste prompt for the next role

`assess_final_report_next_action_handoff` and
`assess_contradictory_state_handoff` enforce these fields and reject
contradictory claims (for example, ready-to-merge without approval, issue done
without PR proof, discussion complete without summary).

## Queue controller selection (priority order)

1. Merge clean approved PRs at current head.
2. Review PRs needing review.
3. Reconcile superseded or already-landed duplicates.
4. Continue blocked-but-now-unblocked issues.
5. Create issues from completed discussions.
6. Start new author work only when higher-priority queue items are clear.

For each candidate object, read the **latest canonical state comment** before
choosing an action. Output the exact next-role prompt in the controller report.

## Example workflow states

| State | Next actor | Typical next action |
|-------|------------|---------------------|
| Discussion needs more comments | controller | Facilitate discussion until five substantive comments or urgent/trivial exception |
| Issue ready for author | author | Lock issue and implement in `branches/` worktree |
| PR needs review | reviewer | Review at pinned head in reviewer worktree |
| PR approved at head | merger | Merge with merger profile after eligibility proof |
| PR superseded | reconciler | Close duplicate/already-landed PR with proof |
| Issue blocked | controller | Post issue state comment with blockers and next prompt |

## Non-goals

- Chat history is not the source of truth.
- Do not weaken author/reviewer/merger/reconciler separation.
- Do not replace Gitea issues, PRs, or canonical workflow files under
  `skills/llm-project-workflow/`.