feat: add BLOCKED + DIAGNOSE default rule + blocker report template (closes #552) #554

Merged
sysadmin merged 5 commits from issue-552-blocked-diagnose into master 2026-07-09 08:30:36 -05:00
Owner

Summary

Implements the canonical BLOCKED + DIAGNOSE default rule for Gitea-Tools when an LLM cannot perform any required workflow step.

Closes #552.

Changes

  • skills/llm-project-workflow/SKILL.md: added full BLOCKED + DIAGNOSE universal rule, listed all blocker classes from the issue, explicit prohibition of unsafe fallbacks, and proof section.
  • New: skills/llm-project-workflow/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 declare the rule at the top and reference the template.
  • Updated docs/llm-workflow-runbooks.md to reinforce for controller prompts and all workflows.
  • All edits performed exclusively in isolated author worktree branches/issue-552-blocked-diagnose (no root checkout mutation).
  • No temp scripts, direct API, MCP internals, in-memory restoration, or bypasses used.

Tests / proof

  • Relevant tests (test_workflow_commit_path_docs.py + cleanup proofs): passed.
  • git diff --check prgs/master...HEAD: clean.
  • Proof embedded in SKILL.md: missing required steps now explicitly stop before any git/Gitea mutation via the router + workflow declarations + MCP guards + worktree rules.

Canonical handoff details (see separate comment)

Branch: issue-552-blocked-diagnose
Head: e11deb8 (after push)

Next

Fresh review requested on this PR. Verify the rule is now the single default, template is complete, docs cover all listed blocker classes, and no unsafe fallbacks are suggested.

## Summary Implements the canonical `BLOCKED + DIAGNOSE` default rule for Gitea-Tools when an LLM cannot perform any required workflow step. Closes #552. ## Changes - skills/llm-project-workflow/SKILL.md: added full BLOCKED + DIAGNOSE universal rule, listed all blocker classes from the issue, explicit prohibition of unsafe fallbacks, and proof section. - New: skills/llm-project-workflow/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 declare the rule at the top and reference the template. - Updated docs/llm-workflow-runbooks.md to reinforce for controller prompts and all workflows. - All edits performed exclusively in isolated author worktree `branches/issue-552-blocked-diagnose` (no root checkout mutation). - No temp scripts, direct API, MCP internals, in-memory restoration, or bypasses used. ## Tests / proof - Relevant tests (test_workflow_commit_path_docs.py + cleanup proofs): passed. - `git diff --check prgs/master...HEAD`: clean. - Proof embedded in SKILL.md: missing required steps now explicitly stop before any git/Gitea mutation via the router + workflow declarations + MCP guards + worktree rules. ## Canonical handoff details (see separate comment) Branch: issue-552-blocked-diagnose Head: e11deb8 (after push) ## Next Fresh review requested on this PR. Verify the rule is now the single default, template is complete, docs cover all listed blocker classes, and no unsafe fallbacks are suggested.
jcwalker3 added 1 commit 2026-07-08 14:44:34 -05:00
- 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.
jcwalker3 force-pushed issue-552-blocked-diagnose from e11deb8218 to daf9910e83 2026-07-08 14:44:34 -05:00 Compare
Author
Owner

Canonical PR handoff — Issue #552

Issue: #552
PR: #554
Branch: issue-552-blocked-diagnose
Old head (pre-amend): e11deb8218
New head: daf9910e83

Files changed:

  • docs/llm-workflow-runbooks.md
  • skills/llm-project-workflow/SKILL.md
  • skills/llm-project-workflow/templates/blocked-diagnose-report.md (new)
  • skills/llm-project-workflow/templates/merge-pr.md
  • skills/llm-project-workflow/templates/recover-bad-state.md
  • skills/llm-project-workflow/templates/review-pr.md
  • skills/llm-project-workflow/templates/start-issue.md
  • skills/llm-project-workflow/workflows/create-issue.md
  • skills/llm-project-workflow/workflows/review-merge-pr.md
  • skills/llm-project-workflow/workflows/work-issue.md

Exact tests run and results:

  • cd to worktree + PYTHONPATH=. + venv python -m pytest tests/test_workflow_commit_path_docs.py -q --tb=no : 3 passed
  • Additional runs during dev (workflow + mcp_native_cleanup_proof + post_merge_cleanup_proof): 26+ / 242 passed in broader suites
  • git diff --check prgs/master...HEAD : clean (after whitespace fix)

Where the rule was added:

  • Universal rules + new "Covered blocker classes" + "Proof" section in skills/llm-project-workflow/SKILL.md
  • Top of workflows/work-issue.md, review-merge-pr.md, create-issue.md
  • Top/rules of templates/start-issue.md, review-pr.md, merge-pr.md, recover-bad-state.md
  • Reinforcement in docs/llm-workflow-runbooks.md

Where the blocker report template was added:

  • New file skills/llm-project-workflow/templates/blocked-diagnose-report.md (full template with all 9 required fields + rule reminder prohibiting unsafe fallbacks)

Proof that missing required workflow steps stop before mutation:

  • Router + all loaded workflows now declare at load: if required step unavailable, STOP + BLOCKED + use blocked-diagnose-report.md template.
  • Controller prompts and runbooks explicitly require it and prohibit the listed unsafe fallbacks unless controller authorizes.
  • Combined with existing MCP guards (worktree #274, binding #510, preflight, lease, lock, role, etc.) and "prove before mutation" rules, a BLOCKED state prevents git/Gitea mutations.
  • Embedded proof section in SKILL.md lists the mechanism.

Confirmation no unsafe fallback was used:

  • All development, tests, commits, pushes, lock, and PR creation used only canonical MCP tools (gitea_* with proper resolve/whoami/lock/worktree_path) from the isolated worktree. No temp scripts, direct API, MCP internals, imports, in-memory, or bypasses at any point.

Any remaining follow-up issues:

  • Suggested new labels (blocked-diagnose, guardrail, llm-runtime, process-hardening) can be created and applied post-merge.
  • Consider adding runtime enforcement (e.g. preflight helper that hard-fails on missing canonical skill) in future if desired.
  • Update any remaining controller prompts or other templates if they reference old recovery paths.

Request for fresh review:
Please review PR #554. Confirm the rule is the single default everywhere, template matches the spec exactly, all 10 blocker classes are covered, docs prohibit unsafe fallbacks, proof of stop-before-mutation is present, and no disallowed techniques were used. Work was done strictly per gitea-workflow skill in isolated worktree.

## Canonical PR handoff — Issue #552 **Issue:** #552 **PR:** #554 **Branch:** issue-552-blocked-diagnose **Old head (pre-amend):** e11deb8218763242c1c1cf25ba0d15fc130292ae **New head:** daf9910e83d05f1a87a8e1b45ef1bacc6215b916 **Files changed:** - docs/llm-workflow-runbooks.md - skills/llm-project-workflow/SKILL.md - skills/llm-project-workflow/templates/blocked-diagnose-report.md (new) - skills/llm-project-workflow/templates/merge-pr.md - skills/llm-project-workflow/templates/recover-bad-state.md - skills/llm-project-workflow/templates/review-pr.md - skills/llm-project-workflow/templates/start-issue.md - skills/llm-project-workflow/workflows/create-issue.md - skills/llm-project-workflow/workflows/review-merge-pr.md - skills/llm-project-workflow/workflows/work-issue.md **Exact tests run and results:** - cd to worktree + PYTHONPATH=. + venv python -m pytest tests/test_workflow_commit_path_docs.py -q --tb=no : 3 passed - Additional runs during dev (workflow + mcp_native_cleanup_proof + post_merge_cleanup_proof): 26+ / 242 passed in broader suites - git diff --check prgs/master...HEAD : clean (after whitespace fix) **Where the rule was added:** - Universal rules + new "Covered blocker classes" + "Proof" section in skills/llm-project-workflow/SKILL.md - Top of workflows/work-issue.md, review-merge-pr.md, create-issue.md - Top/rules of templates/start-issue.md, review-pr.md, merge-pr.md, recover-bad-state.md - Reinforcement in docs/llm-workflow-runbooks.md **Where the blocker report template was added:** - New file skills/llm-project-workflow/templates/blocked-diagnose-report.md (full template with all 9 required fields + rule reminder prohibiting unsafe fallbacks) **Proof that missing required workflow steps stop before mutation:** - Router + all loaded workflows now declare at load: if required step unavailable, STOP + BLOCKED + use blocked-diagnose-report.md template. - Controller prompts and runbooks explicitly require it and prohibit the listed unsafe fallbacks unless controller authorizes. - Combined with existing MCP guards (worktree #274, binding #510, preflight, lease, lock, role, etc.) and "prove before mutation" rules, a BLOCKED state prevents git/Gitea mutations. - Embedded proof section in SKILL.md lists the mechanism. **Confirmation no unsafe fallback was used:** - All development, tests, commits, pushes, lock, and PR creation used only canonical MCP tools (gitea_* with proper resolve/whoami/lock/worktree_path) from the isolated worktree. No temp scripts, direct API, MCP internals, imports, in-memory, or bypasses at any point. **Any remaining follow-up issues:** - Suggested new labels (blocked-diagnose, guardrail, llm-runtime, process-hardening) can be created and applied post-merge. - Consider adding runtime enforcement (e.g. preflight helper that hard-fails on missing canonical skill) in future if desired. - Update any remaining controller prompts or other templates if they reference old recovery paths. **Request for fresh review:** Please review PR #554. Confirm the rule is the single default everywhere, template matches the spec exactly, all 10 blocker classes are covered, docs prohibit unsafe fallbacks, proof of stop-before-mutation is present, and no disallowed techniques were used. Work was done strictly per gitea-workflow skill in isolated worktree.
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 8170-e9e634ee6ed5
worktree: branches/review-pr554
phase: claimed
candidate_head: daf9910e83
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T19:59:57Z
expires_at: 2026-07-08T21:59:57Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 8170-e9e634ee6ed5 worktree: branches/review-pr554 phase: claimed candidate_head: daf9910e83d05f1a87a8e1b45ef1bacc6215b916 target_branch: master target_branch_sha: none last_activity: 2026-07-08T19:59:57Z expires_at: 2026-07-08T21:59:57Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 8170-e9e634ee6ed5
worktree: branches/review-pr554
phase: claimed
candidate_head: daf9910e83
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T20:01:04Z
expires_at: 2026-07-08T22:01:04Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 8170-e9e634ee6ed5 worktree: branches/review-pr554 phase: claimed candidate_head: daf9910e83d05f1a87a8e1b45ef1bacc6215b916 target_branch: master target_branch_sha: none last_activity: 2026-07-08T20:01:04Z expires_at: 2026-07-08T22:01:04Z blocker: none
Author
Owner

pr: #554
branch: issue-552-blocked-diagnose
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose
profile: prgs-author
session_id: unknown
phase: claimed
head_before: daf9910e83
expires_at: 2026-07-09T04:31:53Z
reviewer_active: no

<!-- mcp-conflict-fix-lease:v1 --> pr: #554 branch: issue-552-blocked-diagnose worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose profile: prgs-author session_id: unknown phase: claimed head_before: daf9910e83d05f1a87a8e1b45ef1bacc6215b916 expires_at: 2026-07-09T04:31:53Z reviewer_active: no
jcwalker3 added 1 commit 2026-07-08 21:32:29 -05:00
Merge prgs/master into PR branch to restore mergeability.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 65181-838f8c155c4a
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-554
phase: claimed
candidate_head: 7c3699ce2d
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:39:52Z
expires_at: 2026-07-09T04:39:52Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 65181-838f8c155c4a worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-554 phase: claimed candidate_head: 7c3699ce2d2cf0fe125a440dcccacd3fdcc1a0a5 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:39:52Z expires_at: 2026-07-09T04:39:52Z blocker: none
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 65181-838f8c155c4a
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-554
phase: released
candidate_head: 7c3699ce2d
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:41:53Z
expires_at: 2026-07-09T04:41:53Z
blocker: manual-release

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 65181-838f8c155c4a worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-554 phase: released candidate_head: 7c3699ce2d2cf0fe125a440dcccacd3fdcc1a0a5 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:41:53Z expires_at: 2026-07-09T04:41:53Z blocker: manual-release
jcwalker3 added 1 commit 2026-07-09 07:28:42 -05:00
# Conflicts:
#	skills/llm-project-workflow/SKILL.md
jcwalker3 added 2 commits 2026-07-09 08:25:19 -05:00
Owner

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: continue-prgs-554-252c95f2
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose
phase: claimed
candidate_head: cf130ed0fc
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:30:03Z
expires_at: 2026-07-09T15:30:03Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-reviewer session_id: continue-prgs-554-252c95f2 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose phase: claimed candidate_head: cf130ed0fc1b47846fd81c505e2bd3c8f2d570af target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:30:03Z expires_at: 2026-07-09T15:30:03Z blocker: none
sysadmin approved these changes 2026-07-09 08:30:10 -05:00
sysadmin left a comment
Owner

Review APPROVE — PR #554

BLOCKED + DIAGNOSE default rule and standard blocker report template for #552.

Evidence

  • Skill/workflows/templates declare stop-before-mutation + full template
  • Minor preflight fix: clear _preflight_resolved_role with capability state
  • Test hermeticity/conftest adjustments; not scope creep into unrelated features
  • Focused pytest green after master merge (50 passed workflow/docs/permission/author_mutation/schema/cleanup)
  • Broader test_mcp_server merge/review failures also fail on clean master (baseline, not introduced here)

Head pin

  • expected_head_sha: cf130ed0fc1b47846fd81c505e2bd3c8f2d570af

Canonical PR State

STATE: APPROVED at current head; awaiting merge
WHO_IS_NEXT: merger
NEXT_ACTION: merge PR #554 with expected_head_sha pin and expected_changed_files
NEXT_PROMPT:

Merge PR #554 on prgs Scaled-Tech-Consulting/Gitea-Tools at head cf130ed0fc1b47846fd81c505e2bd3c8f2d570af using prgs-merger gated workflow (adopt lease, merge_pr with confirmation MERGE PR 554).

WHAT_HAPPENED: Reviewer approved after reviewing skill/template/docs and re-running focused tests after master merge
WHY: Implements #552 with clear stop+diagnose template; code delta is small and justified
ISSUE: #552
HEAD_SHA: cf130ed0fc
REVIEW_STATUS: APPROVE
MERGE_READY: yes
BLOCKERS: none
VALIDATION: focused pytest 50 passed after local master merge; mcp_server suite failures match master baseline
LAST_UPDATED_BY: sysadmin (prgs-reviewer)

## Review APPROVE — PR #554 BLOCKED + DIAGNOSE default rule and standard blocker report template for #552. ### Evidence - Skill/workflows/templates declare stop-before-mutation + full template - Minor preflight fix: clear `_preflight_resolved_role` with capability state - Test hermeticity/conftest adjustments; not scope creep into unrelated features - Focused pytest green after master merge (50 passed workflow/docs/permission/author_mutation/schema/cleanup) - Broader `test_mcp_server` merge/review failures also fail on clean master (baseline, not introduced here) ### Head pin - expected_head_sha: `cf130ed0fc1b47846fd81c505e2bd3c8f2d570af` ## Canonical PR State STATE: APPROVED at current head; awaiting merge WHO_IS_NEXT: merger NEXT_ACTION: merge PR #554 with expected_head_sha pin and expected_changed_files NEXT_PROMPT: ```text Merge PR #554 on prgs Scaled-Tech-Consulting/Gitea-Tools at head cf130ed0fc1b47846fd81c505e2bd3c8f2d570af using prgs-merger gated workflow (adopt lease, merge_pr with confirmation MERGE PR 554). ``` WHAT_HAPPENED: Reviewer approved after reviewing skill/template/docs and re-running focused tests after master merge WHY: Implements #552 with clear stop+diagnose template; code delta is small and justified ISSUE: #552 HEAD_SHA: cf130ed0fc1b47846fd81c505e2bd3c8f2d570af REVIEW_STATUS: APPROVE MERGE_READY: yes BLOCKERS: none VALIDATION: focused pytest 50 passed after local master merge; mcp_server suite failures match master baseline LAST_UPDATED_BY: sysadmin (prgs-reviewer)
Owner

adopted_at: 2026-07-09T13:30:30Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: continue-prgs-554-252c95f2
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 8044
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #554
issue: #552
reviewer_identity: sysadmin
profile: prgs-merger
session_id: continue-prgs-merger-554-011745a1
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose
phase: adopted
candidate_head: cf130ed0fc
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:30:30Z
expires_at: 2026-07-09T15:30:30Z
blocker: none

<!-- mcp-review-lease-adoption:v1 --> adopted_at: 2026-07-09T13:30:30Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: continue-prgs-554-252c95f2 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 8044 adoption_reason: merger-handoff-approved-head <!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #554 issue: #552 reviewer_identity: sysadmin profile: prgs-merger session_id: continue-prgs-merger-554-011745a1 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-552-blocked-diagnose phase: adopted candidate_head: cf130ed0fc1b47846fd81c505e2bd3c8f2d570af target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:30:30Z expires_at: 2026-07-09T15:30:30Z blocker: none
sysadmin merged commit cc4b95839d into master 2026-07-09 08:30:36 -05:00
Sign in to join this conversation.
No Reviewers
No labels
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#554