Gitea-Tools/docs/state-handoff-ledger.md

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/.