feat: add BLOCKED + DIAGNOSE default rule and blocker report template (closes #552)
- Updated llm-project-workflow/SKILL.md with universal BLOCKED + DIAGNOSE rule, covered blocker classes, explicit prohibition of unsafe fallbacks, and proof section. - Added templates/blocked-diagnose-report.md (standard template with all required fields). - Updated workflows/work-issue.md, review-merge-pr.md, create-issue.md and templates/start-issue.md, review-pr.md, merge-pr.md, recover-bad-state.md to require and reference the rule at load. - Updated docs/llm-workflow-runbooks.md to reinforce the rule for controller prompts and all workflows. - All changes in isolated worktree branches/issue-552-blocked-diagnose. No root mutation. No unsafe fallbacks used. - Tests (workflow + cleanup proofs): 26+ passed in run. - git diff --check prgs/master...HEAD: clean.
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# Blocker Report Template (BLOCKED + DIAGNOSE)
|
||||
|
||||
Use this exact structure whenever a required workflow step cannot be performed. Emit this report and stop. Do not proceed to mutation or fallback unless a controller explicitly authorizes an exception in writing.
|
||||
|
||||
## Required step
|
||||
<Describe the exact step, skill, tool, capability, instruction, profile, or preflight that was required. Include the canonical name and where it is defined (e.g. gitea-workflow skill, specific workflow file, gitea_xxx tool).>
|
||||
|
||||
## Observed failure
|
||||
<Exact symptom, error message, missing output, guard error, 404, schema error, dirty state, wrong profile, etc. Quote relevant output or tool response.>
|
||||
|
||||
## Expected behavior
|
||||
<What the workflow/docs/prompts say should happen. Reference the specific rule, template, or preflight that requires this step.>
|
||||
|
||||
## Checks performed
|
||||
- List every verification attempted (e.g. gitea_whoami, resolve_task_capability, ls skills/, git status, mcp_list_*, worktree list, etc.)
|
||||
- Note any discrepancies found (e.g. skill not mounted for this runtime, capability not in profile, cwd not under branches/, etc.)
|
||||
|
||||
## Safe recovery attempted
|
||||
- Only non-mutating actions (reads, lists, views, status, whoami, resolve, fetch --dry, etc.)
|
||||
- List what was tried and the result.
|
||||
- If no safe recovery possible, state that explicitly.
|
||||
|
||||
## Likely classification
|
||||
Choose one or more:
|
||||
- missing required skill or workflow guide
|
||||
- broken terminal/tool runner
|
||||
- MCP capability failure or deadlock
|
||||
- wrong profile or role
|
||||
- dirty or misbound worktree
|
||||
- root checkout mutation risk
|
||||
- mutation guard failure
|
||||
- missing required MCP tool/schema
|
||||
- stale or inconsistent runtime state
|
||||
- unavailable project instructions
|
||||
- other: <describe>
|
||||
|
||||
## Durable fix recommendation
|
||||
<Specific, actionable recommendation that fixes the root process/tooling issue (e.g. "Mount gitea-workflow skill for Codex under canonical name in ~/.codex/skills/", "Add preflight in llm-project-workflow/SKILL.md that hard-stops before any gitea_ call if X is unavailable", "Update controller prompt to require BLOCKED + this report before any fallback", "Grant capability in profile config", etc.). Do not suggest temp workarounds.>
|
||||
|
||||
## Mutation occurred?
|
||||
- No (preferred and required unless explicitly authorized)
|
||||
- Yes — describe exactly what was mutated and why it was unavoidable after diagnosis. (This should be rare and will trigger additional review.)
|
||||
|
||||
## Single next action
|
||||
<One concrete next step for the current actor (e.g. "Controller to approve or reject recovery", "File follow-up issue #XXX for skill mounting", "Re-launch session from clean branches/ worktree after skill installed", "Stop and wait for profile update").>
|
||||
|
||||
---
|
||||
|
||||
**Rule reminder (do not bypass):**
|
||||
If the required step is unavailable, you are BLOCKED. Diagnose using this template. Report. Stop. Unsafe fallbacks (temp scripts, direct API, MCP internals, direct imports, in-memory restoration, manual bypasses) are prohibited unless a controller has authorized them for this specific instance in a prior handoff.
|
||||
|
||||
This report must appear in the final output / handoff before any further action.
|
||||
@@ -10,6 +10,7 @@ Load the canonical workflow first:
|
||||
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.
|
||||
- Only an eligible, NON-author reviewer merges. If authenticated user == PR
|
||||
author → STOP.
|
||||
- Do not merge unless the PR is open, mergeable, and its checks/review pass.
|
||||
|
||||
@@ -3,12 +3,15 @@
|
||||
Copy, fill the `<...>` fields, paste as the task prompt. Recovery is read-then-
|
||||
act: gather facts first, never discard unmerged work.
|
||||
|
||||
**BLOCKED + DIAGNOSE rule (llm-project-workflow):** If at any point a required step (including state recovery itself) cannot be performed, stop immediately, use the standard [`blocked-diagnose-report.md`](blocked-diagnose-report.md) template, attempt only safe non-mutating recovery, and report. Do not continue or fallback.
|
||||
|
||||
```text
|
||||
Task: recover repo state for <situation>. Do not lose unmerged work.
|
||||
|
||||
Rules (llm-project-workflow):
|
||||
- Fail closed: if state is unclear or a step would delete unmerged work, STOP.
|
||||
- BLOCKED + DIAGNOSE default: if state is unclear, a required check fails, or a step would delete unmerged work or bypass a guard, STOP and emit a full blocked-diagnose-report.md using the template. Clearly state BLOCKED. Diagnose. Only non-mutating recovery.
|
||||
- Never push master. Never discard commits not safely pushed to <remote>.
|
||||
- Prove you are in a branches/ worktree before any recovery mutation.
|
||||
|
||||
Diagnose first:
|
||||
1. git fetch <remote> --prune
|
||||
@@ -16,8 +19,19 @@ Diagnose first:
|
||||
3. git rev-list --left-right --count <remote>/master...master # ahead/behind
|
||||
4. For any PR involved: confirm state (open/closed/merged) AND whether
|
||||
<remote>/master actually contains its commits ("closed" != "merged").
|
||||
5. Check active leases, claims, and whether required skills/workflows are loaded.
|
||||
|
||||
Act per case:
|
||||
If a required diagnostic or recovery step itself is unavailable (e.g. terminal broken, skill missing, guard blocks, wrong profile), emit:
|
||||
|
||||
## Required step
|
||||
<the step>
|
||||
|
||||
## Observed failure
|
||||
<...>
|
||||
|
||||
(complete the full blocked-diagnose-report.md template)
|
||||
|
||||
Act per case (only after clean diagnosis; if blocked, use the template and stop):
|
||||
- Dirty worktree from another issue: leave it; start yours in a new worktree.
|
||||
- Local master ahead of remote: confirm the extra commits live on a branch
|
||||
pushed to <remote>, THEN git reset --hard <remote>/master. Verify with
|
||||
@@ -26,6 +40,7 @@ Act per case:
|
||||
- Branch deleted before merge: recover commits from a local branch/reflog (or
|
||||
git fsck --lost-found), re-push, reopen the PR.
|
||||
- Unauthorized untracked file: do not commit it; leave pre-existing artifacts.
|
||||
- Any blocker: use blocked-diagnose-report.md template and stop.
|
||||
|
||||
Handoff: what was wrong, evidence, action taken, current state, what remains.
|
||||
Handoff: what was wrong, evidence, action taken, current state, what remains. If BLOCKED, include the full blocker report.
|
||||
```
|
||||
|
||||
@@ -35,6 +35,7 @@ Load the canonical workflow first:
|
||||
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.
|
||||
- Review in a SEPARATE detached review worktree, never the author's folder.
|
||||
- Worktree safety (#233): before checkout, diff, validation, review, or merge,
|
||||
report the starting worktree path and whether it was dirty. If unrelated
|
||||
|
||||
@@ -10,6 +10,7 @@ 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):
|
||||
- **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.
|
||||
- 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
|
||||
|
||||
Reference in New Issue
Block a user