Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 73 Pull Requests 9 Actions Packages Projects Releases Wiki Activity

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

Merged
sysadmin merged 2 commits from feat/issue-505-canonical-thread-handoff into master 2026-07-09 07:49:13 -05:00
Conversation 7 Commits 2 Files Changed 10
+572
jcwalker3 commented 2026-07-08 02:45:10 -05:00
Owner
Copy Link
Copy Source

Summary

Closes #505.

Adds the CTH (Canonical Thread Handoff) protocol so issue and PR threads carry an authoritative workflow handoff comment with status, blockers, proof, and a ready-to-paste next prompt.

Changes

  • canonical_thread_handoff.py — CTH types, template renderer, parser, validator, latest-CTH discovery
  • docs/canonical-thread-handoff.md — protocol definition, discovery/posting rules, six examples
  • docs/llm-workflow-runbooks.md — CTH section for agent operators
  • skills/llm-project-workflow/templates/canonical-thread-handoff.md — paste-ready template
  • Updated author/reviewer/merger prompts and canonical workflows to require CTH discovery and posting
  • tests/test_canonical_thread_handoff.py — module + documentation checks (10 tests)

Validation

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_canonical_thread_handoff.py -q
# 10 passed

Worktree

/Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff @ 25cf323

LLM Handoff Metadata

  • LLM-Agent-SHA: llm-25cf323
  • LLM-Role: implementer
  • Authenticated-Gitea-User: jcwalker3
  • MCP-Profile: prgs-author
  • Branch: feat/issue-505-canonical-thread-handoff
  • Self-review allowed: no
## Summary Closes #505. Adds the **CTH (Canonical Thread Handoff)** protocol so issue and PR threads carry an authoritative workflow handoff comment with status, blockers, proof, and a ready-to-paste next prompt. ## Changes - `canonical_thread_handoff.py` — CTH types, template renderer, parser, validator, latest-CTH discovery - `docs/canonical-thread-handoff.md` — protocol definition, discovery/posting rules, six examples - `docs/llm-workflow-runbooks.md` — CTH section for agent operators - `skills/llm-project-workflow/templates/canonical-thread-handoff.md` — paste-ready template - Updated author/reviewer/merger prompts and canonical workflows to require CTH discovery and posting - `tests/test_canonical_thread_handoff.py` — module + documentation checks (10 tests) ## Validation ```bash /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_canonical_thread_handoff.py -q # 10 passed ``` ## Worktree `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff` @ `25cf323` ## LLM Handoff Metadata - LLM-Agent-SHA: llm-25cf323 - LLM-Role: implementer - Authenticated-Gitea-User: jcwalker3 - MCP-Profile: prgs-author - Branch: feat/issue-505-canonical-thread-handoff - Self-review allowed: no
jcwalker3 added 1 commit 2026-07-08 02:45:10 -05:00
feat: add Canonical Thread Handoff protocol (Closes #505) 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]>
jcwalker3 commented 2026-07-08 21:31:14 -05:00
Author
Owner
Copy Link
Copy Source

pr: #509
branch: feat/issue-505-canonical-thread-handoff
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff
profile: prgs-author
session_id: unknown
phase: claimed
head_before: 25cf323d14
expires_at: 2026-07-09T04:31:14Z
reviewer_active: no

<!-- mcp-conflict-fix-lease:v1 --> pr: #509 branch: feat/issue-505-canonical-thread-handoff worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff profile: prgs-author session_id: unknown phase: claimed head_before: 25cf323d143f56b7d2a959c5f6cb381c745c619f expires_at: 2026-07-09T04:31:14Z reviewer_active: no
jcwalker3 added 1 commit 2026-07-08 21:32:25 -05:00
fix: resolve conflicts for PR #509 05ea99cd32 
Merge prgs/master into PR branch to restore mergeability.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
sysadmin commented 2026-07-08 21:48:56 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #509
issue: #505
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 63070-ce744cc38fb9
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr509-issue-505
phase: claimed
candidate_head: 05ea99cd32
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:48:55Z
expires_at: 2026-07-09T04:48:55Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #509 issue: #505 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 63070-ce744cc38fb9 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr509-issue-505 phase: claimed candidate_head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:48:55Z expires_at: 2026-07-09T04:48:55Z blocker: none
sysadmin commented 2026-07-08 21:52:21 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #509
issue: #505
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 63070-ce744cc38fb9
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr509-issue-505
phase: released
candidate_head: 05ea99cd32
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:52:20Z
expires_at: 2026-07-09T04:52:20Z
blocker: manual-release

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #509 issue: #505 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 63070-ce744cc38fb9 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr509-issue-505 phase: released candidate_head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:52:20Z expires_at: 2026-07-09T04:52:20Z blocker: manual-release
sysadmin commented 2026-07-09 07:47:05 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #509
issue: #505
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 94966-7714d3af380d
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff
phase: claimed
candidate_head: 05ea99cd32
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T12:47:03Z
expires_at: 2026-07-09T14:47:03Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #509 issue: #505 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 94966-7714d3af380d worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff phase: claimed candidate_head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8 target_branch: master target_branch_sha: none last_activity: 2026-07-09T12:47:03Z expires_at: 2026-07-09T14:47:03Z blocker: none
sysadmin commented 2026-07-09 07:48:10 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #509
issue: #505
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 94966-7714d3af380d
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff
phase: claimed
candidate_head: 05ea99cd32
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T12:48:09Z
expires_at: 2026-07-09T14:48:09Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #509 issue: #505 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 94966-7714d3af380d worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff phase: claimed candidate_head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8 target_branch: master target_branch_sha: none last_activity: 2026-07-09T12:48:09Z expires_at: 2026-07-09T14:48:09Z blocker: none
sysadmin approved these changes 2026-07-09 07:48:30 -05:00
sysadmin left a comment
Owner
Copy Link
Copy Source

APPROVE PR #509 (Closes #505)

Head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8
Reviewer: sysadmin / prgs-reviewer
Author: jcwalker3 (not self-review)

Scope (10 files, additive)

  • canonical_thread_handoff.py CTH types/render/parse/validate
  • Protocol docs + template
  • Author/reviewer/merger workflow hooks require latest-CTH discovery and posting
  • Explicit: CTH is not merge approval

Validation

pytest tests/test_canonical_thread_handoff.py -q
# 10 passed

APPROVE — mergeable; ready for prgs-merger.

## APPROVE PR #509 (Closes #505) **Head:** `05ea99cd3213248b3de2ab8fcc20231a27de62f8` **Reviewer:** sysadmin / prgs-reviewer **Author:** jcwalker3 (not self-review) ### Scope (10 files, additive) - `canonical_thread_handoff.py` CTH types/render/parse/validate - Protocol docs + template - Author/reviewer/merger workflow hooks require latest-CTH discovery and posting - Explicit: CTH is not merge approval ### Validation ``` pytest tests/test_canonical_thread_handoff.py -q # 10 passed ``` **APPROVE** — mergeable; ready for prgs-merger.
sysadmin commented 2026-07-09 07:48:54 -05:00
Owner
Copy Link
Copy Source

adopted_at: 2026-07-09T12:48:53Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 94966-7714d3af380d
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 7883
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #509
issue: #505
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 97845-6cb30b115f84
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff
phase: adopted
candidate_head: 05ea99cd32
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T12:48:53Z
expires_at: 2026-07-09T14:48:53Z
blocker: none

<!-- mcp-review-lease-adoption:v1 --> adopted_at: 2026-07-09T12:48:53Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: 94966-7714d3af380d adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 7883 adoption_reason: merger-handoff-approved-head <!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #509 issue: #505 reviewer_identity: sysadmin profile: prgs-merger session_id: 97845-6cb30b115f84 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-505-canonical-thread-handoff phase: adopted candidate_head: 05ea99cd3213248b3de2ab8fcc20231a27de62f8 target_branch: master target_branch_sha: none last_activity: 2026-07-09T12:48:53Z expires_at: 2026-07-09T14:48:53Z blocker: none
sysadmin merged commit 7274b76e81 into master 2026-07-09 07:49:13 -05:00
Sign in to join this conversation.
Reviewers
No Reviewers
sysadmin
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#509