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
parent 9ada4762c5
commit 25cf323d14
10 changed files with 572 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Template: Canonical Thread Handoff (CTH)
+
+Copy, fill the fields, and post as an issue or PR comment.
+
+```text
+## CTH: <Type>
+
+Status: <current workflow state>
+Next owner: <author|reviewer|merger|controller|operator>
+Current blocker: <none or exact blocker>
+Decision: <what was decided this session>
+Proof: <commands, SHAs, gate outputs, or explicit pending proof>
+Next action: <one concrete step for the next actor>
+Ready-to-paste prompt: <full prompt the next session should paste>
+```
+
+Allowed `<Type>` values:
+
+- State Handoff
+- Controller Decision
+- Author Handoff
+- Reviewer Handoff
+- Merger Handoff
+- Supersession Notice
+- Blocker
+
+Rules:
+
+- Find the latest CTH comment in the thread before starting work.
+- Treat the latest valid CTH as the current source of truth.
+- Post a new CTH when you finish, block, skip, supersede, approve, request
+  changes, or hand off.
+- A CTH summarizes workflow state; formal Gitea review verdicts remain
+  authoritative for merge gates.
+
+Full protocol: `docs/canonical-thread-handoff.md`
@@ -10,6 +10,9 @@ Load the canonical workflow first:
 Final report schema: `schemas/review-merge-final-report.md`.

 Rules (llm-project-workflow):
+- Find the latest CTH comment on the PR/issue thread before starting work.
+  Post a new CTH: Merger Handoff (or CTH: Blocker) at session end.
+  Template: skills/llm-project-workflow/templates/canonical-thread-handoff.md
 - Only an eligible, NON-author reviewer merges. If authenticated user == PR
  author → STOP.
 - Do not merge unless the PR is open, mergeable, and its checks/review pass.
@@ -35,6 +35,9 @@ Load the canonical workflow first:
 Final report schema: `schemas/review-merge-final-report.md`.

 Rules (llm-project-workflow):
+- Find the latest CTH comment on the PR/issue thread before starting work.
+  Post a new CTH: Reviewer Handoff (or CTH: Blocker) at session end.
+  Template: skills/llm-project-workflow/templates/canonical-thread-handoff.md
 - Review in a SEPARATE detached review worktree, never the author's folder.
 - Worktree safety (#233): before checkout, diff, validation, review, or merge,
  report the starting worktree path and whether it was dirty. If unrelated
@@ -10,6 +10,9 @@ Final report schema: skills/llm-project-workflow/schemas/work-issue-final-report
 Router: skills/llm-project-workflow/SKILL.md (task mode: work-issue)

 Rules (llm-project-workflow):
+- Find the latest CTH comment on the issue/PR thread before starting work.
+  Post a new CTH: Author Handoff (or CTH: Blocker) at session end.
+  Template: skills/llm-project-workflow/templates/canonical-thread-handoff.md
 - No repo changes without a tracking issue. If none exists, create one first;
  if it can't be created, stop.
 - Work only in an isolated branch worktree under branches/. The main checkout
@@ -26,6 +26,12 @@ workflow rules exactly.

 ## 0. Load the canonical workflow first

+Before starting PR work, **find the latest CTH comment** on the PR or linked
+issue thread. Treat that CTH as the current handoff state. Post a new
+**CTH: Reviewer Handoff**, **CTH: Merger Handoff**, **CTH: Blocker**, or
+**CTH: Supersession Notice** when you finish, block, skip, supersede,
+approve, request changes, or hand off. See `docs/canonical-thread-handoff.md`.
+
 Before starting PR work, check whether the project provides a canonical PR review/merge workflow through a project skill, runbook, or MCP helper.

 If available, load it first and report:
@@ -26,6 +26,12 @@ This is an author/coder workflow. It is not a reviewer workflow.

 ## 0. Load the canonical workflow first

+Before starting issue work, **find the latest CTH comment** on the target
+issue or linked PR thread. Treat that CTH as the current handoff state unless
+a newer authoritative gate supersedes it. Post a new **CTH: Author Handoff**
+(or `CTH: Blocker`) when you finish, block, or hand off.
+See `docs/canonical-thread-handoff.md`.
+
 Before starting issue work, check whether the project provides a canonical work-on-issue workflow through a project skill, runbook, or MCP helper.

 If available, load it first and report: