Files

T

sysadminandClaude Opus 4.8 25cf323d14 feat: add Canonical Thread Handoff protocol (Closes #505 )

Define CTH comment types, base template, parser/validator helpers, protocol
documentation with examples, and workflow/runbook/prompt updates so agents
discover and post authoritative thread handoffs before acting.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

2026-07-08 03:44:58 -04:00

4.3 KiB

Raw Permalink Blame History

Canonical Thread Handoff (CTH)

CTH = Canonical Thread Handoff

A CTH comment is the authoritative workflow handoff 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.

CTH comments complement — but do not replace — formal Gitea review state. A CTH may summarize an APPROVE or REQUEST_CHANGES decision, yet merge gates still require the live Gitea review verdict.

CTH comment types

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

Required base template

## CTH: <Type>

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

Extended fields may map to canonical issue/PR state templates from #495 when that layer is available. Until then, keep the base fields complete.

Discovery and posting rules

Before acting in an issue or PR thread:

Find the latest CTH comment before doing work.
Treat the latest valid CTH as the current handoff state.
Post a new CTH when you finish, block, skip, supersede, request changes, approve, or hand off.
Do not rely on stale non-CTH comments when a newer CTH exists.
Casual discussion comments do not need to be CTH comments.

Examples

PR approved and ready for merger

## CTH: Reviewer Handoff

Status: approved_at_current_head
Next owner: merger
Current blocker: none
Decision: APPROVE recorded at head abc123...
Proof: gitea_submit_pr_review performed; visible verdict APPROVE
Next action: eligible merger merges PR #N with pinned expected_head_sha
Ready-to-paste prompt: Merge PR #N for issue #M if live head still abc123... and merge gates pass.

PR request-changes back to author

## CTH: Reviewer Handoff

Status: request_changes_at_current_head
Next owner: author
Current blocker: unresolved findings in validation report
Decision: REQUEST_CHANGES at head def456...
Proof: gitea_submit_pr_review performed; blocking review visible
Next action: author fixes findings and pushes; reviewer re-validates fresh head
Ready-to-paste prompt: Fix PR #N review findings, push to feat/issue-M-..., post Author Handoff CTH.

Duplicate / superseded PR closure

## CTH: Supersession Notice

Status: superseded
Next owner: controller
Current blocker: duplicate branch/PR work
Decision: close PR #N; continue on PR #M
Proof: duplicate gate linked open PR #M for issue #K
Next action: controller closes superseded PR and records canonical state
Ready-to-paste prompt: Close superseded PR #N; confirm PR #M remains canonical for issue #K.

Blocked workflow due to dirty root/worktree

## CTH: Blocker

Status: blocked_preflight
Next owner: operator
Current blocker: dirty control checkout / branches worktree mismatch
Decision: stop before mutation
Proof: verify_preflight_purity failed; workspace diagnostics attached
Next action: repair worktree or relaunch MCP from branches/ worktree
Ready-to-paste prompt: Repair dirty workspace, relaunch MCP from branches/review-prN, retry review.

Stale head requiring fresh review

## CTH: Reviewer Handoff

Status: stale_head
Next owner: reviewer
Current blocker: live head differs from pinned review head
Decision: prior approval not valid for current head
Proof: expected_head_sha mismatch at merge gate
Next action: re-run validation and post fresh review decision
Ready-to-paste prompt: Re-validate PR #N at live head, dry-run review gates, submit fresh verdict.

Issue implementation handoff

## CTH: Author Handoff

Status: implementation_complete_pending_review
Next owner: reviewer
Current blocker: none
Decision: PR #N ready for review at head fedcba...
Proof: tests passed in branches/issue-M-...; PR opened with Closes #M
Next action: reviewer acquires lease and validates PR #N
Ready-to-paste prompt: Review PR #N for issue #M; pin head fedcba... before mutations.

llm-workflow-runbooks.md
../skills/llm-project-workflow/templates/canonical-thread-handoff.md
#495 — canonical next-action comment fields
#496 — fail-closed validation for workflow-changing comments

4.3 KiB Raw Permalink Blame History