sysadminandClaude Opus 4.8
25cf323d14
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]>
142 lines
4.3 KiB
Markdown
142 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```md
|
|
## 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:
|
|
|
|
1. **Find the latest CTH comment** before doing work.
|
|
2. Treat the **latest valid CTH** as the current handoff state.
|
|
3. **Post a new CTH** when you finish, block, skip, supersede, request
|
|
changes, approve, or hand off.
|
|
4. Do **not** rely on stale non-CTH comments when a newer CTH exists.
|
|
5. Casual discussion comments do not need to be CTH comments.
|
|
|
|
## Examples
|
|
|
|
### PR approved and ready for merger
|
|
|
|
```md
|
|
## 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
|
|
|
|
```md
|
|
## 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
|
|
|
|
```md
|
|
## 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
|
|
|
|
```md
|
|
## 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
|
|
|
|
```md
|
|
## 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
|
|
|
|
```md
|
|
## 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.
|
|
```
|
|
|
|
## Related
|
|
|
|
- [`llm-workflow-runbooks.md`](llm-workflow-runbooks.md)
|
|
- [`../skills/llm-project-workflow/templates/canonical-thread-handoff.md`](../skills/llm-project-workflow/templates/canonical-thread-handoff.md)
|
|
- #495 — canonical next-action comment fields
|
|
- #496 — fail-closed validation for workflow-changing comments |