Merge pull request 'feat: add Canonical Thread Handoff protocol (Closes #505)' (#509) from feat/issue-505-canonical-thread-handoff into master

2026-07-09 07:49:13 -05:00
parent 5ada9e6cc0 05ea99cd32
commit 7274b76e81
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
 - Repository targeting (#530): pass explicit `remote=`, `org=`, and `repo=` on
  every gitea-tools call (e.g. `remote=prgs org=Scaled-Tech-Consulting
  repo=Gitea-Tools`). A bare `remote=prgs` can resolve to the wrong default repo
@@ -36,6 +36,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
 - Repository targeting (#530): pass explicit `remote=`, `org=`, and `repo=` on
  every gitea-tools call (e.g. `remote=prgs org=Scaled-Tech-Consulting
  repo=Gitea-Tools`). A bare `remote=prgs` can resolve to the wrong default repo
@@ -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