sysadminandClaude Opus 4.8
d50328aea4
Add templates, validators, and documentation for discussion/issue/PR state comments and final-report next-action handoff fields. Wire enforcement into assess_final_report_validator across all workflow task kinds. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# 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/`. |