feat: require Controller Handoff plus Thread State Ledger (Closes #507) #511

Merged
sysadmin merged 6 commits from feat/issue-507-controller-thread-ledger into master 2026-07-09 08:27:45 -05:00
Owner

Closes #507

Summary

Requires every meaningful controller handoff to be followed by a concise [THREAD STATE LEDGER] comment that states canonical thread truth in ~30 seconds.

Changes

  • Add thread_state_ledger_validator.py with ambiguous-state detection, mutation-ledger contradiction checks, and blocker classifications
  • Add machine-checked scenario fixtures in thread_state_ledger_examples.py
  • Add canonical templates in docs/two-comment-workflow.md and examples
  • Wire two-comment workflow gate into gitea_create_issue_comment
  • Add shared.two_comment_workflow rule to final_report_validator.py
  • Add tests in tests/test_thread_state_ledger_validator.py (15 tests)

Validation

pytest tests/test_thread_state_ledger_validator.py tests/test_final_report_validator.py tests/test_mcp_server.py::TestIssueCommentTools::test_create_tagged_handoff_missing_mutation_ledger_blocked -q
# 51 passed
Closes #507 ## Summary Requires every meaningful controller handoff to be followed by a concise `[THREAD STATE LEDGER]` comment that states canonical thread truth in ~30 seconds. ## Changes - Add `thread_state_ledger_validator.py` with ambiguous-state detection, mutation-ledger contradiction checks, and blocker classifications - Add machine-checked scenario fixtures in `thread_state_ledger_examples.py` - Add canonical templates in `docs/two-comment-workflow.md` and examples - Wire two-comment workflow gate into `gitea_create_issue_comment` - Add `shared.two_comment_workflow` rule to `final_report_validator.py` - Add tests in `tests/test_thread_state_ledger_validator.py` (15 tests) ## Validation ``` pytest tests/test_thread_state_ledger_validator.py tests/test_final_report_validator.py tests/test_mcp_server.py::TestIssueCommentTools::test_create_tagged_handoff_missing_mutation_ledger_blocked -q # 51 passed ```
jcwalker3 added 2 commits 2026-07-08 02:50:52 -05:00
Introduce thread_state_ledger_validator for the mandatory two-comment
workflow: tagged [CONTROLLER HANDOFF] paired with [THREAD STATE LEDGER].
Wire validation into final_report_validator and gitea_create_issue_comment,
add runbook docs, worked examples, and tests.

Closes #507

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add two-comment workflow validation with tagged [CONTROLLER HANDOFF] and
[THREAD STATE LEDGER] templates, fail-closed comment posting gates, final-report
rules, worked examples, and documentation for precise server-side vs local state.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
jcwalker3 added 1 commit 2026-07-08 10:10:21 -05:00
Merge prgs/master into feat/issue-507-controller-thread-ledger and preserve PR intent
alongside compatible master guardrails.
Author
Owner

pr: #511
branch: feat/issue-507-controller-thread-ledger
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
profile: prgs-author
session_id: unknown
phase: claimed
head_before: 59f2de9711
expires_at: 2026-07-09T04:31:20Z
reviewer_active: no

<!-- mcp-conflict-fix-lease:v1 --> pr: #511 branch: feat/issue-507-controller-thread-ledger worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger profile: prgs-author session_id: unknown phase: claimed head_before: 59f2de9711222a05eb07222dfa41e45a7818a389 expires_at: 2026-07-09T04:31:20Z reviewer_active: no
jcwalker3 added 1 commit 2026-07-08 21:32:26 -05:00
Merge prgs/master into PR branch to restore mergeability.

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

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 10371-5292735bc447
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-feat-issue-507-controller-thread-ledger
phase: claimed
candidate_head: 97b3c6573b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T03:08:54Z
expires_at: 2026-07-09T05:08:54Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 10371-5292735bc447 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-feat-issue-507-controller-thread-ledger phase: claimed candidate_head: 97b3c6573be4930c6eab3576ffbe69e0c14835c1 target_branch: master target_branch_sha: none last_activity: 2026-07-09T03:08:54Z expires_at: 2026-07-09T05:08:54Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 10371-5292735bc447
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-feat-issue-507-controller-thread-ledger
phase: released
candidate_head: 97b3c6573b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T03:09:36Z
expires_at: 2026-07-09T05:09:36Z
blocker: manual-release

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 10371-5292735bc447 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-feat-issue-507-controller-thread-ledger phase: released candidate_head: 97b3c6573be4930c6eab3576ffbe69e0c14835c1 target_branch: master target_branch_sha: none last_activity: 2026-07-09T03:09:36Z expires_at: 2026-07-09T05:09:36Z blocker: manual-release
jcwalker3 added 1 commit 2026-07-09 07:27:59 -05:00
jcwalker3 added 1 commit 2026-07-09 08:14:49 -05:00
# Conflicts:
#	docs/llm-workflow-runbooks.md
#	final_report_validator.py
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:22:46Z
expires_at: 2026-07-09T15:22:46Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:22:46Z expires_at: 2026-07-09T15:22:46Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:23:16Z
expires_at: 2026-07-09T15:23:16Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:23:16Z expires_at: 2026-07-09T15:23:16Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:23:34Z
expires_at: 2026-07-09T15:23:34Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:23:34Z expires_at: 2026-07-09T15:23:34Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:24:02Z
expires_at: 2026-07-09T15:24:02Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:24:02Z expires_at: 2026-07-09T15:24:02Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:24:29Z
expires_at: 2026-07-09T15:24:29Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:24:29Z expires_at: 2026-07-09T15:24:29Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:24:56Z
expires_at: 2026-07-09T15:24:56Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:24:56Z expires_at: 2026-07-09T15:24:56Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: claimed
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:25:41Z
expires_at: 2026-07-09T15:25:41Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: claimed candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:25:41Z expires_at: 2026-07-09T15:25:41Z blocker: none
sysadmin approved these changes 2026-07-09 08:25:50 -05:00
sysadmin left a comment
Owner

Review APPROVE — PR #511

Sound scoped change for #507: Controller Handoff + Thread State Ledger validation.

Evidence: 10 files; local master merge clean; pytest 64 passed; fail-closed tagged comment gate only.

Canonical PR State

STATE: APPROVED at current head; awaiting merge
WHO_IS_NEXT: merger
NEXT_ACTION: merge PR #511 with expected_head_sha pin and expected_changed_files
NEXT_PROMPT:

Merge PR #511 on prgs Scaled-Tech-Consulting/Gitea-Tools at head a8177c2e73947a586a893825ef38721d6c06dd91 using prgs-merger gated workflow (adopt lease, merge_pr with confirmation MERGE PR 511).

WHAT_HAPPENED: Reviewer approved after local validation of thread-state ledger work
WHY: Scope matches #507; tests green; no blockers
ISSUE: #507
HEAD_SHA: a8177c2e73
REVIEW_STATUS: APPROVE
MERGE_READY: yes
BLOCKERS: none
VALIDATION: pytest 64 passed (thread_state_ledger + final_report + mcp comment gate) after merging prgs/master locally
LAST_UPDATED_BY: sysadmin (prgs-reviewer)

## Review APPROVE — PR #511 Sound scoped change for #507: Controller Handoff + Thread State Ledger validation. Evidence: 10 files; local master merge clean; pytest 64 passed; fail-closed tagged comment gate only. ## Canonical PR State STATE: APPROVED at current head; awaiting merge WHO_IS_NEXT: merger NEXT_ACTION: merge PR #511 with expected_head_sha pin and expected_changed_files NEXT_PROMPT: ```text Merge PR #511 on prgs Scaled-Tech-Consulting/Gitea-Tools at head a8177c2e73947a586a893825ef38721d6c06dd91 using prgs-merger gated workflow (adopt lease, merge_pr with confirmation MERGE PR 511). ``` WHAT_HAPPENED: Reviewer approved after local validation of thread-state ledger work WHY: Scope matches #507; tests green; no blockers ISSUE: #507 HEAD_SHA: a8177c2e73947a586a893825ef38721d6c06dd91 REVIEW_STATUS: APPROVE MERGE_READY: yes BLOCKERS: none VALIDATION: pytest 64 passed (thread_state_ledger + final_report + mcp comment gate) after merging prgs/master locally LAST_UPDATED_BY: sysadmin (prgs-reviewer)
Owner

adopted_at: 2026-07-09T13:26:27Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: continue-prgs-review-bbe8ce14df90
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 8023
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-merger
session_id: continue-prgs-review-bbe8ce14df90
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: adopted
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:26:27Z
expires_at: 2026-07-09T15:26:27Z
blocker: none

<!-- mcp-review-lease-adoption:v1 --> adopted_at: 2026-07-09T13:26:27Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: continue-prgs-review-bbe8ce14df90 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 8023 adoption_reason: merger-handoff-approved-head <!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-merger session_id: continue-prgs-review-bbe8ce14df90 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: adopted candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:26:27Z expires_at: 2026-07-09T15:26:27Z blocker: none
Owner

adopted_at: 2026-07-09T13:27:33Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: continue-prgs-review-bbe8ce14df90
adopted_from_profile: prgs-merger
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 8027
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-merger
session_id: continue-prgs-merger-9e0101f9da
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: adopted
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:27:33Z
expires_at: 2026-07-09T15:27:33Z
blocker: none

<!-- mcp-review-lease-adoption:v1 --> adopted_at: 2026-07-09T13:27:33Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: continue-prgs-review-bbe8ce14df90 adopted_from_profile: prgs-merger adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 8027 adoption_reason: merger-handoff-approved-head <!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-merger session_id: continue-prgs-merger-9e0101f9da worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: adopted candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:27:33Z expires_at: 2026-07-09T15:27:33Z blocker: none
sysadmin merged commit 325e0bb44c into master 2026-07-09 08:27:45 -05:00
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #511
issue: #507
reviewer_identity: sysadmin
profile: prgs-merger
session_id: continue-prgs-merger-9e0101f9da
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger
phase: released
candidate_head: a8177c2e73
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:29:13Z
expires_at: 2026-07-09T15:29:13Z
blocker: post-merge-moot

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #511 issue: #507 reviewer_identity: sysadmin profile: prgs-merger session_id: continue-prgs-merger-9e0101f9da worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-507-controller-thread-ledger phase: released candidate_head: a8177c2e73947a586a893825ef38721d6c06dd91 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:29:13Z expires_at: 2026-07-09T15:29:13Z blocker: post-merge-moot
Sign in to join this conversation.
No Reviewers
No labels
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

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