Enforce self-propagating canonical handoffs through final controller closure #626

New Issue

2026-07-10T11:20:01-05:00

jcwalker3 commented

2026-07-10 11:20:01 -05:00

Problem

Current author, reviewer, and merger reports may include a ready-to-paste next prompt, but the workflow does not reliably enforce that each actor:

reads and verifies the live canonical state;
performs only its assigned role;
updates the durable issue and PR state after acting;
posts a complete prompt for the next actor;
continues the handoff chain until the authorized controller verifies completion and records final closure.

The gap was demonstrated by the merger handoff produced after review of PR #625 / Issue #601. The prompt included basic merge instructions but did not require:

verification that the inherited approval still applied to the live head;
complete post-merge verification;
canonical issue-state and thread-ledger updates;
controller-boundary handling;
durable handling of workflow failures;
generation and posting of the next complete handoff;
continuation until final controller acceptance and closure.

This means the workflow still depends on a human copying reports into another chat and expanding the next prompt manually.

Desired behavior

Every workflow actor should consume one canonical handoff, perform one authorized workflow role, update Gitea as the durable system of record, and emit the next complete canonical handoff.

The chain should end only when:

the authorized controller verifies the outcome;
all acceptance criteria are satisfied;
required cleanup and reconciliation are complete;
canonical final state is posted;
the issue is closed through the sanctioned workflow.

Relationship to prior work

This issue does not re-spec the foundational templates already tracked (and largely closed) under:

#494 — canonical state handoff ledger
#495 — canonical next-action comments
#496 — fail-closed canonical comment validation
#500 — controller issue-acceptance gate
#501 — reject contradictory reviewer handoffs
#505 — Canonical Thread Handoff (CTH) protocol
#507 — controller handoff + thread state ledger

Those issues define schemas, docs, and partial validators. This issue owns the systemic enforcement gap: self-propagating handoffs across all roles, live-state recovery, mandatory Gitea posting, final-report schema integration that makes the next handoff non-optional, merger → merged-awaiting-controller transition, controller accept/reject continuation, and workflow-failure escalation until durable final closure.

PR #625 / Issue #601 is a concrete example of the gap, not the sole scope.

Scope

The durable solution should cover the author, reviewer, merger, controller, operator, and reconciliation paths where applicable.

It should define and enforce:

1. Canonical handoff contract

Each handoff must include at least:

repository;
issue number;
PR number, when applicable;
current workflow state;
current head and relevant base or merge SHA;
acting role and identity;
completed actions;
validation evidence;
mutation ledger;
active blockers;
next actor;
exact next action;
prohibited actions;
complete next-session prompt;
durable workflow-failure issue references;
last-updated timestamp.

2. Live-state recovery

The receiving actor must verify the live Gitea and Git state rather than treating the inherited handoff as authoritative.

The workflow must detect:

changed PR head;
stale approval;
closed or reopened issue;
merged PR;
stale or foreign lease;
missing or dirty worktree;
namespace mismatch;
stale runtime;
changed base;
conflicting canonical comments.

3. Role-limited continuation

The receiving actor must perform only the role assigned by the current state.

Examples:

author fixes requested changes;
reviewer independently reviews the current head;
merger verifies approval parity and merges;
controller verifies acceptance and closes or requests more work;
operator resolves infrastructure blockers;
reconciler performs sanctioned cleanup.

4. Mandatory durable state update

A successful actor session must not end with only a chat report.

It must post or update the canonical Gitea state and thread ledger before completion.

5. Mandatory next handoff

Unless the issue is durably complete, every actor must post a complete ready-to-run prompt for the next actor.

The prompt must be stored in Gitea, not only returned in chat output.

6. Controller completion boundary

A merged PR must not automatically be treated as fully accepted unless the configured workflow authorizes that behavior.

The workflow must represent states such as:

needs-author
needs-review
approved-awaiting-merge
merged-awaiting-controller
blocked
complete

The controller must be able to:

accept and close;
request additional tests;
request clearer proof;
request feature corrections;
reopen or return the issue to an earlier actor;
leave the next canonical handoff.

7. Workflow-failure escalation

Any tooling or workflow failure discovered while processing a work item must be captured in durable issue work.

The current work item should contain:

failure classification;
linked issue;
temporary impact;
next valid actor;
recovery prompt.

The actor should not silently fold an unrelated workflow defect into the active feature issue.

8. Validation before posting

Canonical handoff comments should be schema-validated before Gitea accepts them.

Missing or ambiguous fields should fail closed with actionable feedback.

9. Final-report integration

Author, reviewer, merger, controller, operator, and reconciler final-report schemas should generate or require the canonical next handoff consistently.

The next prompt should not be an optional prose section.

Acceptance criteria

A canonical schema exists for cross-role handoffs.
Applicable workflow final-report schemas require that handoff.
A validator rejects incomplete handoffs.
Successful actor workflows post the handoff into Gitea.
The receiving actor can recover the task using only:
- the issue or PR thread;
- workflow documentation;
- live repository state.
No outside chat history is required.
Head changes invalidate stale review or merge handoffs.
Merge success transitions to the configured controller state.
Controller acceptance or rejection generates the appropriate final or next state.
Workflow failures produce a separate durable issue reference.
Completed workflows terminate without generating an unnecessary next prompt.
Tests cover at least:
- author to reviewer;
- reviewer to merger;
- merger to controller;
- controller back to author;
- stale-head rejection;
- blocked infrastructure path;
- final successful closure;
- incomplete handoff rejection;
- duplicate workflow-failure issue handling.

Non-goals

Do not hard-code Issue #601 or PR #625 behavior.
Do not place project-specific acceptance criteria into generic workflow prompts.
Do not require humans to paste reports through ChatGPT between roles.
Do not solve unrelated lease, worktree, or namespace defects inside this issue unless needed for handoff enforcement.
Do not bypass existing capability, role, or controller gates.
Do not re-open the foundational schema/docs work already closed under #494–#507 unless a regression or missing enforcement wire-up is discovered.

Evidence / example

Use PR #625 / Issue #601 as a concrete example of the gap:

author produced a detailed reviewer handoff;
reviewer successfully approved the current head;
reviewer’s next merger prompt was operationally too narrow;
the missing requirements had to be added manually outside Gitea.

Describe this as an example, not as the sole scope.

## Problem Current author, reviewer, and merger reports may include a ready-to-paste next prompt, but the workflow does not reliably enforce that each actor: 1. reads and verifies the live canonical state; 2. performs only its assigned role; 3. updates the durable issue and PR state after acting; 4. posts a complete prompt for the next actor; 5. continues the handoff chain until the authorized controller verifies completion and records final closure. The gap was demonstrated by the merger handoff produced after review of PR #625 / Issue #601. The prompt included basic merge instructions but did not require: * verification that the inherited approval still applied to the live head; * complete post-merge verification; * canonical issue-state and thread-ledger updates; * controller-boundary handling; * durable handling of workflow failures; * generation and posting of the next complete handoff; * continuation until final controller acceptance and closure. This means the workflow still depends on a human copying reports into another chat and expanding the next prompt manually. ## Desired behavior Every workflow actor should consume one canonical handoff, perform one authorized workflow role, update Gitea as the durable system of record, and emit the next complete canonical handoff. The chain should end only when: * the authorized controller verifies the outcome; * all acceptance criteria are satisfied; * required cleanup and reconciliation are complete; * canonical final state is posted; * the issue is closed through the sanctioned workflow. ## Relationship to prior work This issue does **not** re-spec the foundational templates already tracked (and largely closed) under: * #494 — canonical state handoff ledger * #495 — canonical next-action comments * #496 — fail-closed canonical comment validation * #500 — controller issue-acceptance gate * #501 — reject contradictory reviewer handoffs * #505 — Canonical Thread Handoff (CTH) protocol * #507 — controller handoff + thread state ledger Those issues define schemas, docs, and partial validators. **This issue owns the systemic enforcement gap:** self-propagating handoffs across all roles, live-state recovery, mandatory Gitea posting, final-report schema integration that makes the next handoff non-optional, merger → `merged-awaiting-controller` transition, controller accept/reject continuation, and workflow-failure escalation until durable final closure. PR #625 / Issue #601 is a concrete example of the gap, not the sole scope. ## Scope The durable solution should cover the author, reviewer, merger, controller, operator, and reconciliation paths where applicable. It should define and enforce: ### 1. Canonical handoff contract Each handoff must include at least: * repository; * issue number; * PR number, when applicable; * current workflow state; * current head and relevant base or merge SHA; * acting role and identity; * completed actions; * validation evidence; * mutation ledger; * active blockers; * next actor; * exact next action; * prohibited actions; * complete next-session prompt; * durable workflow-failure issue references; * last-updated timestamp. ### 2. Live-state recovery The receiving actor must verify the live Gitea and Git state rather than treating the inherited handoff as authoritative. The workflow must detect: * changed PR head; * stale approval; * closed or reopened issue; * merged PR; * stale or foreign lease; * missing or dirty worktree; * namespace mismatch; * stale runtime; * changed base; * conflicting canonical comments. ### 3. Role-limited continuation The receiving actor must perform only the role assigned by the current state. Examples: * author fixes requested changes; * reviewer independently reviews the current head; * merger verifies approval parity and merges; * controller verifies acceptance and closes or requests more work; * operator resolves infrastructure blockers; * reconciler performs sanctioned cleanup. ### 4. Mandatory durable state update A successful actor session must not end with only a chat report. It must post or update the canonical Gitea state and thread ledger before completion. ### 5. Mandatory next handoff Unless the issue is durably complete, every actor must post a complete ready-to-run prompt for the next actor. The prompt must be stored in Gitea, not only returned in chat output. ### 6. Controller completion boundary A merged PR must not automatically be treated as fully accepted unless the configured workflow authorizes that behavior. The workflow must represent states such as: * `needs-author` * `needs-review` * `approved-awaiting-merge` * `merged-awaiting-controller` * `blocked` * `complete` The controller must be able to: * accept and close; * request additional tests; * request clearer proof; * request feature corrections; * reopen or return the issue to an earlier actor; * leave the next canonical handoff. ### 7. Workflow-failure escalation Any tooling or workflow failure discovered while processing a work item must be captured in durable issue work. The current work item should contain: * failure classification; * linked issue; * temporary impact; * next valid actor; * recovery prompt. The actor should not silently fold an unrelated workflow defect into the active feature issue. ### 8. Validation before posting Canonical handoff comments should be schema-validated before Gitea accepts them. Missing or ambiguous fields should fail closed with actionable feedback. ### 9. Final-report integration Author, reviewer, merger, controller, operator, and reconciler final-report schemas should generate or require the canonical next handoff consistently. The next prompt should not be an optional prose section. ## Acceptance criteria * A canonical schema exists for cross-role handoffs. * Applicable workflow final-report schemas require that handoff. * A validator rejects incomplete handoffs. * Successful actor workflows post the handoff into Gitea. * The receiving actor can recover the task using only: * the issue or PR thread; * workflow documentation; * live repository state. * No outside chat history is required. * Head changes invalidate stale review or merge handoffs. * Merge success transitions to the configured controller state. * Controller acceptance or rejection generates the appropriate final or next state. * Workflow failures produce a separate durable issue reference. * Completed workflows terminate without generating an unnecessary next prompt. * Tests cover at least: * author to reviewer; * reviewer to merger; * merger to controller; * controller back to author; * stale-head rejection; * blocked infrastructure path; * final successful closure; * incomplete handoff rejection; * duplicate workflow-failure issue handling. ## Non-goals * Do not hard-code Issue #601 or PR #625 behavior. * Do not place project-specific acceptance criteria into generic workflow prompts. * Do not require humans to paste reports through ChatGPT between roles. * Do not solve unrelated lease, worktree, or namespace defects inside this issue unless needed for handoff enforcement. * Do not bypass existing capability, role, or controller gates. * Do not re-open the foundational schema/docs work already closed under #494–#507 unless a regression or missing enforcement wire-up is discovered. ## Evidence / example Use PR #625 / Issue #601 as a concrete example of the gap: * author produced a detailed reviewer handoff; * reviewer successfully approved the current head; * reviewer’s next merger prompt was operationally too narrow; * the missing requirements had to be added manually outside Gitea. Describe this as an example, not as the sole scope.