From 3b499cec2a672c60397af4b5043597e10dc100a3 Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Wed, 8 Jul 2026 03:47:06 -0400
Subject: [PATCH] feat: require Controller Handoff plus Thread State Ledger
 (Closes #507)

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) <noreply@anthropic.com>
---
 docs/llm-workflow-runbooks.md |   4 +-
 docs/two-comment-workflow.md  | 123 ++++++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+), 2 deletions(-)
 create mode 100644 docs/two-comment-workflow.md

diff --git a/docs/llm-workflow-runbooks.md b/docs/llm-workflow-runbooks.md
index c6ee768..0c518b3 100644
--- a/docs/llm-workflow-runbooks.md
+++ b/docs/llm-workflow-runbooks.md
@@ -788,8 +788,8 @@ The ledger must include a **blocker classification** from:
 `process/rule blocker`, `queue/lease blocker`,
 `duplicate/canonicalization blocker`, `no blocker`.
 
-Templates and worked examples:
-[`examples/two-comment-workflow-examples.md`](examples/two-comment-workflow-examples.md).
+Templates: [`two-comment-workflow.md`](two-comment-workflow.md).
+Worked examples: [`examples/two-comment-workflow-examples.md`](examples/two-comment-workflow-examples.md).
 
 Validation: `thread_state_ledger_validator.py` checks tagged comments at post
 time (`gitea_create_issue_comment`) and tagged final reports via
diff --git a/docs/two-comment-workflow.md b/docs/two-comment-workflow.md
new file mode 100644
index 0000000..8da1ace
--- /dev/null
+++ b/docs/two-comment-workflow.md
@@ -0,0 +1,123 @@
+# Two-comment workflow: Controller Handoff + Thread State Ledger
+
+After meaningful controller/workflow work, post **two separate Gitea comments**:
+
+1. **`[CONTROLLER HANDOFF]`** — detailed operational handoff for the next
+   LLM/controller session (proof-heavy; may be long).
+2. **`[THREAD STATE LEDGER]`** — short canonical truth readable in ~30 seconds.
+
+The ledger is the concise source of truth. The handoff is the detailed
+continuation artifact. This complements CTH (#505) and lifecycle state
+comments (#494/#495) without replacing them.
+
+## Controller Handoff template
+
+```markdown
+[CONTROLLER HANDOFF] PR #___ / Issue #___ — <short title>
+
+Purpose:
+This comment is the operational handoff for the next controller/LLM session.
+
+Identity/profile:
+- Active profile:
+- Authenticated identity:
+- Role:
+- Self-review / role-conflict proof:
+
+Target:
+- Repo:
+- Issue:
+- PR:
+- Branch:
+- Pinned head SHA:
+- Worktree:
+
+Work performed:
+- <step 1>
+- <step 2>
+
+Files touched or reviewed:
+- `<file>` — <why it matters>
+
+Validation:
+- `<command>` → <result>
+- Full suite: <result or not run + reason>
+
+Server-side mutation ledger:
+- <mutation 1, including tool/action/comment id if available>
+- Or: none — no server-side state changed
+
+Local-only changes:
+- <worktree created, files edited locally, etc.>
+- Or: none
+
+Blockers:
+- <none>
+- Or: <exact blocker, exact gate, exact reason>
+
+Controller prompt for next session:
+```markdown
+<ready-to-paste prompt>
+```
+```
+
+## Thread State Ledger template
+
+```markdown
+[THREAD STATE LEDGER] PR #___ / Issue #___ — <current state in one line>
+
+What is true now:
+- PR state:
+- Issue state:
+- Current head SHA:
+- Server-side decision state:
+- Local verdict/state:
+- Latest known validation:
+
+What changed:
+- <short summary since prior ledger>
+
+What is blocked:
+- Blocker classification: <see list below>
+
+Who/what acts next:
+- Next actor:
+- Required action:
+- Do not do:
+- Resume from:
+```
+
+### Blocker classifications
+
+- code blocker
+- test blocker
+- merge conflict
+- stale head
+- permission/capability blocker
+- environment/tooling blocker
+- process/rule blocker
+- queue/lease blocker
+- duplicate/canonicalization blocker
+- no blocker
+
+### Precise state language
+
+Prefer:
+
+- `APPROVE verdict prepared locally`
+- `APPROVED review posted to Gitea`
+- `REQUEST_CHANGES posted to Gitea`
+- `merge performed` / `merge not performed`
+- `lease acquired` / `lease attempt blocked`
+- `server-side state changed` / `no server-side state changed`
+
+Avoid ambiguous standalone claims (`approved`, `ready`, `merged`, `blocked`,
+`done`) without proof and server-side state separation.
+
+## Validation
+
+- `thread_state_ledger_validator.py` — comment and final-report checks
+- `gitea_create_issue_comment` — fail-closed gate on tagged comments
+- `assess_final_report_validator` — `shared.two_comment_workflow` rule
+
+Examples: [`examples/two-comment-workflow-examples.md`](examples/two-comment-workflow-examples.md)
\ No newline at end of file