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

Merge master into issue-552-blocked-diagnose to resolve conflicts

Browse Source
This commit is contained in:
sysadmin
2026-07-09 09:06:59 -04:00
parent 92fc913cad 8e7a69800a
commit c35f713291
45 changed files with 4439 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/llm-project-workflow/SKILL.md
+1
View File
@@ -184,6 +184,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
skills/llm-project-workflow/templates/blocked-review-handoff.md
+22
View File
@@ -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
```
skills/llm-project-workflow/templates/canonical-state-comments.md
+148
View File
@@ -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>
```
skills/llm-project-workflow/templates/canonical-thread-handoff.md
+36
View File
@@ -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`
skills/llm-project-workflow/templates/merge-pr.md
+3
View File
@@ -11,6 +11,9 @@ Final report schema: `schemas/review-merge-final-report.md`.
Rules (llm-project-workflow):
- **BLOCKED + DIAGNOSE default (required):** If any required step (load workflow, lease, profile/role, capability, worktree under branches/, preflight, tool, instruction, etc.) cannot be performed, STOP. State BLOCKED. Use [`blocked-diagnose-report.md`](../templates/blocked-diagnose-report.md) template exactly. Only safe non-mutating recovery. Report. Do not continue or fallback.
- 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
skills/llm-project-workflow/templates/review-pr.md
+3
View File
@@ -37,6 +37,9 @@ Final report schema: `schemas/review-merge-final-report.md`.
Rules (llm-project-workflow):
- **BLOCKED + DIAGNOSE default (required):** If any required step (load workflow, lease, profile/role, capability, worktree under branches/, preflight, tool, instruction, etc.) cannot be performed, STOP. State BLOCKED. Use [`blocked-diagnose-report.md`](../templates/blocked-diagnose-report.md) template exactly. Only safe non-mutating recovery. Report. Do not continue or fallback.
- 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
skills/llm-project-workflow/templates/start-issue.md
+3
View File
@@ -11,6 +11,9 @@ Router: skills/llm-project-workflow/SKILL.md (task mode: work-issue)
Rules (llm-project-workflow):
- **BLOCKED + DIAGNOSE default (required):** If any required step (load workflow, acquire lease, prove worktree under branches/, capability, profile, tool, instruction, preflight, etc.) cannot be performed, STOP. State BLOCKED. Use [`blocked-diagnose-report.md`](../templates/blocked-diagnose-report.md) template exactly. Only safe non-mutating recovery. Report. Do not continue or fallback.
- 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
skills/llm-project-workflow/workflows/review-merge-pr.md
+6
View File
@@ -28,6 +28,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:
skills/llm-project-workflow/workflows/work-issue.md
+36 -1
View File
@@ -28,6 +28,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:
@@ -617,10 +623,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