Merge remote-tracking branch 'prgs/master' into feat/issue-514-branch-delete-guard

# Conflicts: # final_report_validator.py
2026-07-09 09:12:33 -04:00
parent 62ab4b4d95 b52fa2060f
commit 7acd55d2d2
53 changed files with 4880 additions and 196 deletions
@@ -167,6 +167,7 @@ Ready-to-copy task prompts live in [`templates/`](templates/):
 - [`reconcile-closed-not-merged-pr.md`](templates/reconcile-closed-not-merged-pr.md)
 - [`worktree-cleanup.md`](templates/worktree-cleanup.md)
 - [`release-tag.md`](templates/release-tag.md)
+- [`canonical-state-comments.md`](templates/canonical-state-comments.md)

 ## Adapting to a project

@@ -195,4 +196,3 @@ If and only if a controller posts a durable `BOOTSTRAP REVIEW AUTHORIZATION
 `docs/bootstrap-review-path.md`

 Otherwise stop with BLOCKED + DIAGNOSE. Bootstrap never weakens normal PR gates.
-
@@ -0,0 +1,22 @@
+# Blocked review submission handoff
+
+Use when `gitea_submit_pr_review` or the terminal mutation gate blocks review
+submission.
+
+```text
+## Blocked Review Submission Handoff
+
+- Tool called: gitea_submit_pr_review
+- Mutation attempted: yes
+- Mutation rejected: yes
+- No server-side state changed: confirmed
+- Proof/source: <paste exact tool error or gate reason>
+- Prior terminal mutation that consumed budget: <exact prior mutation or none>
+- Review decision (local intent): <approve | request_changes | comment only>
+- Server-side final decision marked: <yes with tool proof | no>
+- Gitea review submitted: no
+- Gitea review blocked because: <exact gate/error>
+- Review mutations: none (submission blocked)
+- MCP/Gitea mutations: <only mutations that actually occurred>
+- Safe next action: rewrite handoff with consistent ledger before posting
+```
@@ -0,0 +1,148 @@
+# Template: canonical state comments
+
+Use these only for workflow-changing comments. Casual discussion does not need
+the full template.
+
+## Issue
+
+```text
+## Canonical Issue State
+
+STATE:
+<ready-for-author | in-progress | blocked | PR-open | needs-review | ready-to-merge | merged | closed | superseded>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | merger | reconciler | user>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+WHAT_HAPPENED:
+<latest meaningful event>
+
+WHY:
+<decision rationale>
+
+RELATED_DISCUSSION:
+<link/reference or none>
+
+RELATED_PRS:
+- #...
+
+BRANCH:
+<branch or none>
+
+HEAD_SHA:
+<40-character SHA or none>
+
+VALIDATION:
+<tests/proofs or none>
+
+BLOCKERS:
+<blocker and unblock condition, or none>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```
+
+## PR
+
+```text
+## Canonical PR State
+
+STATE:
+<needs-review | changes-requested | approved | stale-approval | ready-to-merge | merged | blocked | superseded>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | merger | reconciler | user>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+WHAT_HAPPENED:
+<latest meaningful event>
+
+WHY:
+<decision rationale>
+
+ISSUE:
+#...
+
+BASE:
+<branch>
+
+HEAD:
+<branch>
+
+HEAD_SHA:
+<40-character SHA>
+
+REVIEW_STATUS:
+<none | approved | changes-requested | stale | contaminated>
+
+VALIDATION:
+<tests/proofs>
+
+BLOCKERS:
+<blockers or none>
+
+SUPERSEDES:
+<PRs or none>
+
+SUPERSEDED_BY:
+<PR or none>
+
+MERGE_READY:
+<yes/no and why>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```
+
+## Discussion
+
+```text
+## Canonical Discussion Summary
+
+STATE:
+<needs-more-discussion | ready-for-issues | issues-created | closed>
+
+WHO_IS_NEXT:
+<controller | author | reviewer | user>
+
+DECISION:
+<what was decided>
+
+WHY:
+<reasoning and tradeoffs>
+
+SUBSTANTIVE_COMMENTS:
+<count and summary>
+
+ISSUES_TO_CREATE_OR_CREATED:
+- #...
+
+DEPENDENCY_ORDER:
+<order or none>
+
+NON_GOALS:
+<non-goals>
+
+OPEN_QUESTIONS:
+<questions or none>
+
+NEXT_ACTION:
+<specific one-sentence action>
+
+NEXT_PROMPT:
+<paste-ready prompt for the next role>
+
+LAST_UPDATED_BY:
+<identity/profile/date>
+```
@@ -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`
@@ -1,4 +1,4 @@
-# Template: merge a PR (eligible reviewer only)
+# Template: merge a PR (eligible merger only)

 Copy, fill the `<...>` fields, and paste as the task prompt.

@@ -10,12 +10,16 @@ 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
  and is blocked when it disagrees with the local git remote URL.
- Only an eligible, NON-author reviewer merges. If authenticated user == PR
+- Only an eligible, NON-author merger merges. If authenticated user == PR
  author → STOP.
+- Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
 - Do not merge unless the PR is open, mergeable, and its checks/review pass.
 - No force-merge, no bypassing branch protections.
 - If the PR is closed but `merged=false`, STOP and run reconciliation. Do not clean up.
@@ -63,10 +67,12 @@ Then run the cleanup template (worktree-cleanup.md) in a reconciler session:
 - fetch/prune; confirm main checkout is clean and current (0 0).

 Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
-§K (long form — a merge is always high-risk), including the review/merge role
-fields (Selected PR, Reviewer eligibility, Pinned reviewed head, Review
+§K (long form — a merge is always high-risk), including the merger role
+fields (Selected PR, Merger eligibility, Pinned reviewed head, Review
 decision, Merge result, Linked issue status, Cleanup status) plus: merge
 commit, PR metadata state/merged flag/hash, remote master hash, and the
 post-merge verification method used & verification results. Reports missing
 the handoff are downgraded (review_proofs.assess_controller_handoff).
+
+Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
 ```
@@ -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
@@ -110,8 +113,9 @@ Steps:
   - base branch unchanged
   - no undismissed REQUEST_CHANGES / blocking review state left unaccounted
   If anything moved → STOP, re-pin, re-validate before any verdict.
-10. Post the review verdict: approve only if scope is clean and checks pass;
-    otherwise request changes with specifics. Never merge from this review step.
+ 10. Post the review verdict: approve only if scope is clean and checks pass;
+     otherwise request changes with specifics. Never merge from this review step.
+     Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
   Include a "Review Metadata" block (attribution only — docs/llm-agent-sha.md):

   Review Metadata:
@@ -128,6 +132,8 @@ Pinned reviewed head, Review decision, Merge result, Linked issue status,
 Cleanup status. If you could not merge, name the exact gate. Reports missing
 the handoff are downgraded (review_proofs.assess_controller_handoff).

+Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
+
 Baseline failure proof (#533): if a validation command exits non-zero, do NOT
 call it a clean pass. Only label a failure "baseline"/"pre-existing" with
 pre-merge proof — the failure reproduced on the PR's pre-merge base commit, or a
@@ -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
@@ -26,6 +26,12 @@ workflow rules exactly.

 ## 0. Load the canonical workflow first

+Before starting PR work, **find the latest CTH comment** on the PR or linked
+issue thread. Treat that CTH as the current handoff state. Post a new
+**CTH: Reviewer Handoff**, **CTH: Merger Handoff**, **CTH: Blocker**, or
+**CTH: Supersession Notice** when you finish, block, skip, supersede,
+approve, request changes, or hand off. See `docs/canonical-thread-handoff.md`.
+
 Before starting PR work, check whether the project provides a canonical PR review/merge workflow through a project skill, runbook, or MCP helper.

 If available, load it first and report:
@@ -26,6 +26,12 @@ This is an author/coder workflow. It is not a reviewer workflow.

 ## 0. Load the canonical workflow first

+Before starting issue work, **find the latest CTH comment** on the target
+issue or linked PR thread. Treat that CTH as the current handoff state unless
+a newer authoritative gate supersedes it. Post a new **CTH: Author Handoff**
+(or `CTH: Blocker`) when you finish, block, or hand off.
+See `docs/canonical-thread-handoff.md`.
+
 Before starting issue work, check whether the project provides a canonical work-on-issue workflow through a project skill, runbook, or MCP helper.

 If available, load it first and report:
@@ -615,10 +621,39 @@ After push, report:

 If push fails, stop and produce a recovery handoff.

-## 20A. Conflict-fix lease and push gate (#399)
+## 20A. Live head re-pin before conflict-fix classification (#522)
+
+Open PR inventory `mergeable` / `head_sha` fields are **advisory and may be
+stale**. Before classifying a PR as conflicted or creating a conflict-fix
+worktree:
+
+1. Re-fetch the live PR (`gitea_view_pr` or equivalent) and record:
+   * inventory head SHA (if any)
+   * inventory mergeable (if any)
+   * **live** head SHA (full 40-char)
+   * **live** mergeable
+2. Call `gitea_assess_conflict_fix_classification` with those values.
+3. Act only on the returned classification and **pinned live head**:
+   * `stale_inventory_skip` / `live_mergeable_skip` → **do not** create a
+     conflict-fix worktree; do not mutate the PR branch for conflicts.
+   * `conflict_fix_needed` → conflict-fix worktree allowed for the pinned
+     live head only.
+   * `incomplete_live_repin` → stop; re-fetch live state.
+4. If inventory head ≠ live head, report both SHAs and use the live head only.
+5. If inventory says `mergeable:false` but live says `mergeable:true`, classify
+   as stale inventory and skip author conflict-fix mutation.
+
+Conflict-fix final reports that claim conflict-fix work must include:
+
+* citation of `gitea_assess_conflict_fix_classification`
+* `Live head SHA: <40-char hex>` (or Pinned head SHA / Live PR head SHA)
+* `Conflict-fix classification: <stale_inventory_skip|conflict_fix_needed|live_mergeable_skip|incomplete_live_repin>`
+
+## 20B. Conflict-fix lease and push gate (#399)

 When pushing to an existing PR branch to resolve merge conflicts:

+0. Complete §20A live-head re-pin / classification first.
 1. Call `gitea_acquire_conflict_fix_lease` before any push.
 2. Call `gitea_assess_conflict_fix_push` immediately before `git push` with:
   * branch head before push