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

New Issue

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

jcwalker3 commented

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

Decision

Use the umbrella term:

CTH — Canonical Thread Handoff

A CTH comment is the authoritative handoff comment in a Gitea issue or PR thread. It records current state, decisions, blockers, proof, and the exact next prompt/action for the next LLM or person.

Problem

LLM sessions currently leave free-form comments, review reports, controller reports, and handoffs in many formats. Later sessions cannot quickly determine:

what the latest decision is
what state is canonical
whether a PR is blocked, superseded, approved, stale, or ready for merge
what prompt/action should be used next
which comments are casual discussion versus authoritative workflow state

Goal

Standardize a Canonical Thread Handoff (CTH) protocol for issue and PR comment threads so future LLM/controller sessions can find the current source of truth before acting.

Acceptance criteria

1. Define the term

CTH = Canonical Thread Handoff
A CTH is the source-of-truth workflow handoff comment in a Gitea issue or PR thread.

2. Add standard CTH comment types

CTH: State Handoff
CTH: Controller Decision
CTH: Author Handoff
CTH: Reviewer Handoff
CTH: Merger Handoff
CTH: Supersession Notice
CTH: Blocker

3. Required base template

## CTH: <Type>

Status:
Next owner:
Current blocker:
Decision:
Proof:
Next action:
Ready-to-paste prompt:

Extended fields may map to the canonical issue/PR state templates in #495.

4. Update workflow docs/runbooks

Agents must:

search for the latest CTH comment before acting
treat the latest valid CTH as the current handoff state
post a new CTH when they finish, block, skip, supersede, request changes, approve, or hand off
avoid relying on stale non-CTH comments when a newer CTH exists

5. Update reviewer/author/merger prompts

"Find the latest CTH comment before doing work."
"Post a new CTH at the end of the session."

6. Add examples for

PR approved and ready for merger
PR request-changes back to author
duplicate/superseded PR closure
blocked workflow due to dirty root/worktree
stale head requiring fresh review
issue implementation handoff

7. Add tests or documentation checks

If this repo has prompt/docs validation for workflow wording, add checks that runbooks and prompts reference CTH discovery and posting rules.

8. CTH does not replace formal Gitea reviews

A CTH can summarize an APPROVE/REQUEST_CHANGES decision.
Formal Gitea review state remains authoritative for merge gates.
A CTH is a workflow handoff, not a merge approval by itself.

Non-goals

Do not replace formal Gitea review/approve mechanics.
Do not weaken role separation or existing gates (#496 validation wall).
Do not require every casual comment to be a CTH.
Do not rely on chat history as source of truth.

## Decision Use the umbrella term: **CTH — Canonical Thread Handoff** A CTH comment is the authoritative handoff comment in a Gitea issue or PR thread. It records current state, decisions, blockers, proof, and the exact next prompt/action for the next LLM or person. ## Problem LLM sessions currently leave free-form comments, review reports, controller reports, and handoffs in many formats. Later sessions cannot quickly determine: - what the latest decision is - what state is canonical - whether a PR is blocked, superseded, approved, stale, or ready for merge - what prompt/action should be used next - which comments are casual discussion versus authoritative workflow state ## Goal Standardize a **Canonical Thread Handoff (CTH)** protocol for issue and PR comment threads so future LLM/controller sessions can find the current source of truth before acting. ## Acceptance criteria ### 1. Define the term - **CTH** = Canonical Thread Handoff - A CTH is the source-of-truth workflow handoff comment in a Gitea issue or PR thread. ### 2. Add standard CTH comment types - `CTH: State Handoff` - `CTH: Controller Decision` - `CTH: Author Handoff` - `CTH: Reviewer Handoff` - `CTH: Merger Handoff` - `CTH: Supersession Notice` - `CTH: Blocker` ### 3. Required base template ```md ## CTH: <Type> Status: Next owner: Current blocker: Decision: Proof: Next action: Ready-to-paste prompt: ``` Extended fields may map to the canonical issue/PR state templates in #495. ### 4. Update workflow docs/runbooks Agents must: - search for the latest CTH comment before acting - treat the latest valid CTH as the current handoff state - post a new CTH when they finish, block, skip, supersede, request changes, approve, or hand off - avoid relying on stale non-CTH comments when a newer CTH exists ### 5. Update reviewer/author/merger prompts - "Find the latest CTH comment before doing work." - "Post a new CTH at the end of the session." ### 6. Add examples for - PR approved and ready for merger - PR request-changes back to author - duplicate/superseded PR closure - blocked workflow due to dirty root/worktree - stale head requiring fresh review - issue implementation handoff ### 7. Add tests or documentation checks If this repo has prompt/docs validation for workflow wording, add checks that runbooks and prompts reference CTH discovery and posting rules. ### 8. CTH does not replace formal Gitea reviews - A CTH can summarize an APPROVE/REQUEST_CHANGES decision. - Formal Gitea review state remains authoritative for merge gates. - A CTH is a workflow handoff, not a merge approval by itself. ## Non-goals - Do not replace formal Gitea review/approve mechanics. - Do not weaken role separation or existing gates (#496 validation wall). - Do not require every casual comment to be a CTH. - Do not rely on chat history as source of truth. ## Related - #494 — canonical state handoff ledger (superseded by #495) - #495 — canonical next-action comment templates and fields - #496 — fail-closed validation for workflow-changing comments - #500 — controller issue-acceptance gate - #303 — controller handoff schema for reconciliation workflows

jcwalker3 commented

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

CTH: State Handoff

Status: ready-for-author
Next owner: author
Current blocker: none
Decision: File durable CTH protocol issue; implementation not started
Proof: issue #505 created with full acceptance criteria
Next action: Implement CTH docs, templates, runbook updates, prompt changes, and validation checks
Ready-to-paste prompt:

You are the author LLM implementing the Canonical Thread Handoff (CTH) protocol in Scaled-Tech-Consulting/Gitea-Tools for issue #505.

Goal: Standardize CTH as the umbrella term for authoritative issue/PR thread handoffs. Agents must find the latest CTH before acting and post a new CTH when finishing, blocking, approving, superseding, or handing off.

Deliverables:
1. Define CTH term and map to #495 canonical field templates where needed
2. Add CTH comment types: State Handoff, Controller Decision, Author/Reviewer/Merger Handoff, Supersession Notice, Blocker
3. Add base template (Status, Next owner, Current blocker, Decision, Proof, Next action, Ready-to-paste prompt)
4. Update docs/llm-workflow-runbooks.md and role prompts with CTH discovery/posting rules
5. Add examples for approved PR, request-changes, superseded PR, blocked worktree, stale head, issue handoff
6. Add docs/prompt validation tests if applicable
7. Document that CTH does not replace formal Gitea reviews

Hard rules: do not weaken #496 validation; do not replace merge gates; work in branches/ worktree.

Validation: run docs/prompt validation tests and broader workflow doc contract tests.

Canonical Issue State

STATE: ready-for-author
WHO_IS_NEXT: author
NEXT_ACTION: Implement CTH protocol docs, templates, and runbook/prompt updates
NEXT_PROMPT:

(See CTH block above.)

WHAT_HAPPENED: Durable CTH protocol issue filed to standardize thread handoff naming and discovery
WHY: Free-form comments make it hard for later sessions to find authoritative workflow state in issue/PR threads
RELATED_PRS: none
BLOCKERS: none
VALIDATION: not yet implemented
LAST_UPDATED_BY: prgs-author / jcwalker3

## CTH: State Handoff Status: ready-for-author Next owner: author Current blocker: none Decision: File durable CTH protocol issue; implementation not started Proof: issue #505 created with full acceptance criteria Next action: Implement CTH docs, templates, runbook updates, prompt changes, and validation checks Ready-to-paste prompt: ```text You are the author LLM implementing the Canonical Thread Handoff (CTH) protocol in Scaled-Tech-Consulting/Gitea-Tools for issue #505. Goal: Standardize CTH as the umbrella term for authoritative issue/PR thread handoffs. Agents must find the latest CTH before acting and post a new CTH when finishing, blocking, approving, superseding, or handing off. Deliverables: 1. Define CTH term and map to #495 canonical field templates where needed 2. Add CTH comment types: State Handoff, Controller Decision, Author/Reviewer/Merger Handoff, Supersession Notice, Blocker 3. Add base template (Status, Next owner, Current blocker, Decision, Proof, Next action, Ready-to-paste prompt) 4. Update docs/llm-workflow-runbooks.md and role prompts with CTH discovery/posting rules 5. Add examples for approved PR, request-changes, superseded PR, blocked worktree, stale head, issue handoff 6. Add docs/prompt validation tests if applicable 7. Document that CTH does not replace formal Gitea reviews Hard rules: do not weaken #496 validation; do not replace merge gates; work in branches/ worktree. Validation: run docs/prompt validation tests and broader workflow doc contract tests. ``` --- ## Canonical Issue State STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Implement CTH protocol docs, templates, and runbook/prompt updates NEXT_PROMPT: ```text (See CTH block above.) ``` WHAT_HAPPENED: Durable CTH protocol issue filed to standardize thread handoff naming and discovery WHY: Free-form comments make it hard for later sessions to find authoritative workflow state in issue/PR threads RELATED_PRS: none BLOCKERS: none VALIDATION: not yet implemented LAST_UPDATED_BY: prgs-author / jcwalker3

jcwalker3 referenced this issue from a commit

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

feat: add Canonical Thread Handoff protocol (Closes #505)

jcwalker3 referenced a pull request that will close this issue

2026-07-08 02:45:10 -05:00

feat: add Canonical Thread Handoff protocol (Closes #505) #509

sysadmin referenced this issue

2026-07-08 13:05:00 -05:00

Detect stale MCP runtime before mutation tools execute #545

sysadmin referenced this issue

2026-07-08 21:48:56 -05:00

feat: add Canonical Thread Handoff protocol (Closes #505) #509