Add canonical state handoff ledger for discussions, issues, and PRs #494

New Issue

2026-07-08T01:51:32-05:00

jcwalker3 commented

2026-07-08 01:51:32 -05:00

Problem

LLM sessions currently rely too much on transient chat history and final reports. When a new LLM enters the queue, it has to reconstruct state from scattered issue comments, PR bodies, previous chats, branch names, and assumptions.

We need Gitea itself to become the system of record for continuation. Every discussion, issue, and PR should clearly answer:

What is the current state?
What happened last?
What proof exists?
Who acts next?
What exact prompt should the next LLM run?

The desired end state is that a controller LLM can inspect the queue and continue correctly from the latest canonical Gitea comments — without asking the user what happened last.

Workflow model

Controller creates a discussion.
Discussion receives substantive comments.
Controller reviews/summarizes the discussion.
Controller creates issues from the discussion.
Author works an issue.
Author opens PR.
Reviewer reviews PR.
Controller verifies work completion.
Merger merges approved PR.
Reconciler closes superseded/duplicate/already-landed PRs.
Issue/PR state comments make the next action obvious at every step.

Scope

Add templates, helpers, validators, and documentation for a canonical state handoff ledger.

Required concepts

Discussion state comment
Issue state comment
PR state comment
Queue controller selection rules
Role handoff prompts
Discussion-to-issue conversion rules
Duplicate/supersession tracking
Review/merge readiness tracking
Final summary comments
Validation that final reports include a next-action state update

Discussion requirements

A discussion should not be converted into issues until it has at least 5 substantive comments, unless explicitly marked as urgent or trivial by a controller.
The 5 comments must be meaningful, not filler.
Useful discussion comment types may include:
- proposal
- risk/concern
- acceptance criteria
- implementation approach
- dependency/sequence
- summary
Once enough discussion has happened, a controller must post a summary.
The summary must include:
- decision
- issues to create
- non-goals
- unresolved questions
- next prompt
Created issues must link back to the discussion.
The discussion must link forward to the created issues.

Issue state requirements

Every active issue should have a latest canonical state comment with:

STATE:
NEXT_ACTOR:
NEXT_ACTION:
NEXT_PROMPT:
STATUS:
RELATED_PRS:
BRANCH:
HEAD_SHA:
VALIDATION:
BLOCKERS:
DUPLICATES_OR_SUPERSEDES:
LAST_UPDATED_BY:

PR state requirements

Every active PR should have a latest canonical state comment with:

STATE:
NEXT_ACTOR:
NEXT_ACTION:
NEXT_PROMPT:
ISSUE:
BASE:
HEAD:
HEAD_SHA:
REVIEW_STATUS:
VALIDATION:
BLOCKERS:
SUPERSEDES:
SUPERSEDED_BY:
MERGE_READY:
LAST_UPDATED_BY:

Queue controller requirements

A controller LLM should:

Read open PRs.
Read open issues.
Read active discussions.
For each object, read the latest canonical state comment.
Choose the next action based on state, not guesswork.
Prefer (in order):
- merge clean approved PRs
- review PRs needing review
- reconcile superseded duplicates
- continue blocked-but-unblocked issues
- create issues from completed discussions
- only then start new author work
Always output the exact prompt for the next role.

Acceptance criteria

AC1 — Documentation describing the discussion → issue → PR → review → merge → reconcile lifecycle.
AC2 — Templates for: discussion state comment, discussion summary comment, issue state comment, PR state comment, queue controller report.
AC3 — Final-report validation requires: current state, next actor, next action, ready-to-paste next prompt.
AC4 — Tests reject reports missing next-action handoff fields.
AC5 — Tests reject contradictory state (e.g. "ready to merge" with no approval; "external mutations none" while lock files edited; "issue done" with no PR/merge proof; "discussion complete" with no summary/issues).
AC6 — Guidance for discussions requiring ≥5 substantive comments before issue creation.
AC7 — Guidance for when fewer than 5 comments is acceptable (tiny mechanical changes, emergency fixes).
AC8 — Queue-selection docs so an LLM can inspect Gitea and choose the next role/action without chat context.
AC9 — Examples for real workflow states: discussion needs more comments; issue ready for author; PR needs review; PR approved and ready to merge; PR superseded and ready for reconciler; issue blocked.
AC10 — Existing workflows still work (no regression to role separation or current gates).

Non-goals

Do not build the full web UI here unless needed for minimal visibility.
Do not replace Gitea issues/PRs/discussions.
Do not rely on chat history as the source of truth.
Do not weaken role separation.
Do not allow reviewer/merger/author role confusion.

## Problem LLM sessions currently rely too much on transient chat history and final reports. When a new LLM enters the queue, it has to reconstruct state from scattered issue comments, PR bodies, previous chats, branch names, and assumptions. We need Gitea itself to become the **system of record for continuation**. Every discussion, issue, and PR should clearly answer: - What is the current state? - What happened last? - What proof exists? - Who acts next? - What exact prompt should the next LLM run? The desired end state is that a controller LLM can inspect the queue and continue correctly from the latest canonical Gitea comments — without asking the user what happened last. ## Workflow model 1. Controller creates a discussion. 2. Discussion receives substantive comments. 3. Controller reviews/summarizes the discussion. 4. Controller creates issues from the discussion. 5. Author works an issue. 6. Author opens PR. 7. Reviewer reviews PR. 8. Controller verifies work completion. 9. Merger merges approved PR. 10. Reconciler closes superseded/duplicate/already-landed PRs. 11. Issue/PR state comments make the next action obvious at every step. ## Scope Add templates, helpers, validators, and documentation for a **canonical state handoff ledger**. ### Required concepts 1. Discussion state comment 2. Issue state comment 3. PR state comment 4. Queue controller selection rules 5. Role handoff prompts 6. Discussion-to-issue conversion rules 7. Duplicate/supersession tracking 8. Review/merge readiness tracking 9. Final summary comments 10. Validation that final reports include a next-action state update ## Discussion requirements 1. A discussion should **not** be converted into issues until it has at least **5 substantive comments**, unless explicitly marked as **urgent** or **trivial** by a controller. 2. The 5 comments must be meaningful, not filler. 3. Useful discussion comment types may include: - proposal - risk/concern - acceptance criteria - implementation approach - dependency/sequence - summary 4. Once enough discussion has happened, a controller must post a **summary**. 5. The summary must include: - decision - issues to create - non-goals - unresolved questions - next prompt 6. Created issues must link back to the discussion. 7. The discussion must link forward to the created issues. ## Issue state requirements Every active issue should have a latest canonical state comment with: ```text STATE: NEXT_ACTOR: NEXT_ACTION: NEXT_PROMPT: STATUS: RELATED_PRS: BRANCH: HEAD_SHA: VALIDATION: BLOCKERS: DUPLICATES_OR_SUPERSEDES: LAST_UPDATED_BY: ``` ## PR state requirements Every active PR should have a latest canonical state comment with: ```text STATE: NEXT_ACTOR: NEXT_ACTION: NEXT_PROMPT: ISSUE: BASE: HEAD: HEAD_SHA: REVIEW_STATUS: VALIDATION: BLOCKERS: SUPERSEDES: SUPERSEDED_BY: MERGE_READY: LAST_UPDATED_BY: ``` ## Queue controller requirements A controller LLM should: 1. Read open PRs. 2. Read open issues. 3. Read active discussions. 4. For each object, read the **latest canonical state comment**. 5. Choose the next action based on state, not guesswork. 6. Prefer (in order): - merge clean approved PRs - review PRs needing review - reconcile superseded duplicates - continue blocked-but-unblocked issues - create issues from completed discussions - only then start new author work 7. Always output the exact prompt for the next role. ## Acceptance criteria - [ ] AC1 — Documentation describing the discussion → issue → PR → review → merge → reconcile lifecycle. - [ ] AC2 — Templates for: discussion state comment, discussion summary comment, issue state comment, PR state comment, queue controller report. - [ ] AC3 — Final-report validation requires: current state, next actor, next action, ready-to-paste next prompt. - [ ] AC4 — Tests reject reports missing next-action handoff fields. - [ ] AC5 — Tests reject contradictory state (e.g. "ready to merge" with no approval; "external mutations none" while lock files edited; "issue done" with no PR/merge proof; "discussion complete" with no summary/issues). - [ ] AC6 — Guidance for discussions requiring ≥5 substantive comments before issue creation. - [ ] AC7 — Guidance for when fewer than 5 comments is acceptable (tiny mechanical changes, emergency fixes). - [ ] AC8 — Queue-selection docs so an LLM can inspect Gitea and choose the next role/action without chat context. - [ ] AC9 — Examples for real workflow states: discussion needs more comments; issue ready for author; PR needs review; PR approved and ready to merge; PR superseded and ready for reconciler; issue blocked. - [ ] AC10 — Existing workflows still work (no regression to role separation or current gates). ## Non-goals - Do **not** build the full web UI here unless needed for minimal visibility. - Do **not** replace Gitea issues/PRs/discussions. - Do **not** rely on chat history as the source of truth. - Do **not** weaken role separation. - Do **not** allow reviewer/merger/author role confusion. ## Related Supports the larger MCP Control Plane workflow goal where LLMs can continue work from queue state without reconstructing context from prior chat sessions.

jcwalker3 referenced this issue

2026-07-08 02:02:03 -05:00

Require canonical next-action comments on issues, PRs, and discussions #495

jcwalker3 commented

2026-07-08 02:02:43 -05:00

Canonical Issue State

STATE:
superseded

WHO_IS_NEXT:
controller

NEXT_ACTION:
Treat issue #495 as the canonical tracking issue for canonical next-action comments; do not start parallel implementation on #494.

NEXT_PROMPT:

You are the queue controller for Scaled-Tech-Consulting/Gitea-Tools on prgs.

Issue #494 is superseded by #495 (expanded spec with WHO_IS_NEXT, WHAT_HAPPENED, WHY, validator ACs, and discussion summary format).

Action: when #495 merges, close #494 as duplicate/superseded with link proof. Do not assign author work to #494.

WHAT_HAPPENED:
Operator filed expanded durable spec as issue #495 with title "Require canonical next-action comments on issues, PRs, and discussions."

WHY:
#494 was an earlier draft with overlapping scope; #495 carries the authoritative expanded acceptance criteria and comment formats.

RELATED_DISCUSSION:
none

RELATED_PRS:

none

BRANCH:
none

HEAD_SHA:
none

VALIDATION:
none

BLOCKERS:
none — superseded by #495

LAST_UPDATED_BY:
jcwalker3 / prgs-author / 2026-07-08

## Canonical Issue State STATE: superseded WHO_IS_NEXT: controller NEXT_ACTION: Treat issue #495 as the canonical tracking issue for canonical next-action comments; do not start parallel implementation on #494. NEXT_PROMPT: ```text You are the queue controller for Scaled-Tech-Consulting/Gitea-Tools on prgs. Issue #494 is superseded by #495 (expanded spec with WHO_IS_NEXT, WHAT_HAPPENED, WHY, validator ACs, and discussion summary format). Action: when #495 merges, close #494 as duplicate/superseded with link proof. Do not assign author work to #494. ``` WHAT_HAPPENED: Operator filed expanded durable spec as issue #495 with title "Require canonical next-action comments on issues, PRs, and discussions." WHY: #494 was an earlier draft with overlapping scope; #495 carries the authoritative expanded acceptance criteria and comment formats. RELATED_DISCUSSION: none RELATED_PRS: - none BRANCH: none HEAD_SHA: none VALIDATION: none BLOCKERS: none — superseded by #495 LAST_UPDATED_BY: jcwalker3 / prgs-author / 2026-07-08

jcwalker3 referenced this issue from a commit

2026-07-08 02:14:35 -05:00

feat: add canonical state handoff ledger (#494)

jcwalker3 referenced a pull request that will close this issue

2026-07-08 02:14:55 -05:00

feat: add canonical state handoff ledger (Closes #494) #498

jcwalker3 referenced this issue

2026-07-08 02:29:48 -05:00

Add Canonical Thread Handoff protocol for issue and PR comments #505

sysadmin referenced this issue

2026-07-08 21:30:25 -05:00

feat: add canonical state handoff ledger (Closes #494) #498