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

feat: require canonical next-action state comments (Closes #495) #499

Merged
sysadmin merged 4 commits from feat/issue-495-canonical-next-action-comments into master 2026-07-09 08:02:14 -05:00
Conversation 6 Commits 4 Files Changed 8
+754 -1
jcwalker3 commented 2026-07-08 02:18:28 -05:00
Owner
Copy Link
Copy Source

Summary

Closes #495.

Adds canonical state comment templates and final-report validation for workflow-changing state updates, so issue/PR/discussion handoffs carry the next actor, next action, and paste-ready next prompt.

Changes

  • canonical_state_comments.py — pure parser/validator for canonical issue, PR, and discussion state blocks
  • final_report_validator.py — shared final-report rule that blocks claimed canonical state updates missing required state fields
  • docs/canonical-state-comments.md — lifecycle guidance and templates
  • skills/llm-project-workflow/templates/canonical-state-comments.md — reusable prompt/template snippets
  • skills/llm-project-workflow/SKILL.md and docs/llm-workflow-runbooks.md — links to the new templates
  • Tests for missing WHO_IS_NEXT, missing NEXT_PROMPT, vague next actions, ready-to-merge contradictions, supersession proof, blocked-state unblock proof, and final-report integration

Validation

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m py_compile canonical_state_comments.py final_report_validator.py tests/test_canonical_state_comments.py tests/test_final_report_validator.py
# passed

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_canonical_state_comments.py tests/test_final_report_validator.py -q
# 45 passed, 3 subtests passed

git diff --check
# passed

git diff --cached --check
# passed

Full suite:

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/ -q
# 1 failed, 1775 passed, 6 skipped, 1 warning, 33 subtests passed

The failing test is pre-existing on clean prgs/master:

git worktree add --detach branches/baseline-master-issue-495 prgs/master
/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_mcp_server.py::TestMergePR::test_merge_blocked_on_stale_approval_head -q
# same failure: AssertionError: None is not true

Secret/provenance scan over staged diff found no matches for token/password/private-key/auth/provenance markers.

Scope notes

This PR intentionally does not wire validation into MCP comment posting paths; issue #496 owns comment-posting enforcement.

Worktree

/Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments @ 9235f3a23caf9531191380bbaf09b88740a92894

LLM Handoff Metadata

  • LLM-Agent-SHA: llm-9235f3a23caf
  • LLM-Role: implementer
  • Authenticated-Gitea-User: jcwalker3
  • MCP-Profile: prgs-author
  • Branch: feat/issue-495-canonical-next-action-comments
  • Worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments
  • Self-review allowed: no
## Summary Closes #495. Adds canonical state comment templates and final-report validation for workflow-changing state updates, so issue/PR/discussion handoffs carry the next actor, next action, and paste-ready next prompt. ## Changes - `canonical_state_comments.py` — pure parser/validator for canonical issue, PR, and discussion state blocks - `final_report_validator.py` — shared final-report rule that blocks claimed canonical state updates missing required state fields - `docs/canonical-state-comments.md` — lifecycle guidance and templates - `skills/llm-project-workflow/templates/canonical-state-comments.md` — reusable prompt/template snippets - `skills/llm-project-workflow/SKILL.md` and `docs/llm-workflow-runbooks.md` — links to the new templates - Tests for missing `WHO_IS_NEXT`, missing `NEXT_PROMPT`, vague next actions, ready-to-merge contradictions, supersession proof, blocked-state unblock proof, and final-report integration ## Validation ```bash /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m py_compile canonical_state_comments.py final_report_validator.py tests/test_canonical_state_comments.py tests/test_final_report_validator.py # passed /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_canonical_state_comments.py tests/test_final_report_validator.py -q # 45 passed, 3 subtests passed git diff --check # passed git diff --cached --check # passed ``` Full suite: ```bash /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/ -q # 1 failed, 1775 passed, 6 skipped, 1 warning, 33 subtests passed ``` The failing test is pre-existing on clean `prgs/master`: ```bash git worktree add --detach branches/baseline-master-issue-495 prgs/master /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_mcp_server.py::TestMergePR::test_merge_blocked_on_stale_approval_head -q # same failure: AssertionError: None is not true ``` Secret/provenance scan over staged diff found no matches for token/password/private-key/auth/provenance markers. ## Scope notes This PR intentionally does **not** wire validation into MCP comment posting paths; issue #496 owns comment-posting enforcement. ## Worktree `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments` @ `9235f3a23caf9531191380bbaf09b88740a92894` ## LLM Handoff Metadata - LLM-Agent-SHA: llm-9235f3a23caf - LLM-Role: implementer - Authenticated-Gitea-User: jcwalker3 - MCP-Profile: prgs-author - Branch: feat/issue-495-canonical-next-action-comments - Worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments - Self-review allowed: no
jcwalker3 added 1 commit 2026-07-08 02:18:28 -05:00
feat: require canonical next-action state comments (#495) 9235f3a23c 
Add canonical issue/PR/discussion state comment templates and validators,
final-report rules for STATE/WHO_IS_NEXT/NEXT_ACTION/NEXT_PROMPT, and
queue-controller guidance. Posting enforcement remains in #496.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
jcwalker3 added 1 commit 2026-07-08 10:10:18 -05:00
fix: resolve conflicts for PR #499 560cfa8f47 
Merge prgs/master into feat/issue-495-canonical-next-action-comments and preserve PR intent
alongside compatible master guardrails.
jcwalker3 commented 2026-07-08 21:31:00 -05:00
Author
Owner
Copy Link
Copy Source

pr: #499
branch: feat/issue-495-canonical-next-action-comments
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments
profile: prgs-author
session_id: unknown
phase: claimed
head_before: 560cfa8f47
expires_at: 2026-07-09T04:31:00Z
reviewer_active: no

<!-- mcp-conflict-fix-lease:v1 --> pr: #499 branch: feat/issue-495-canonical-next-action-comments worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments profile: prgs-author session_id: unknown phase: claimed head_before: 560cfa8f4721b9b9962501bf8fc0a2bfe3db744c expires_at: 2026-07-09T04:31:00Z reviewer_active: no
jcwalker3 added 1 commit 2026-07-08 21:32:23 -05:00
fix: resolve conflicts for PR #499 c3452ce866 
Merge prgs/master into PR branch to restore mergeability.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
jcwalker3 added 1 commit 2026-07-09 07:28:03 -05:00
Merge remote-tracking branch 'prgs/master' into feat/issue-495-canonical-next-action-comments 7cb024d4a5 
# Conflicts:
#	skills/llm-project-workflow/SKILL.md
sysadmin commented 2026-07-09 07:59:50 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #499
issue: #495
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 15822-365779d40ee7
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-499-canonical-state
phase: claimed
candidate_head: 7cb024d4a5
target_branch: master
target_branch_sha: b14b1a9663
last_activity: 2026-07-09T12:59:50Z
expires_at: 2026-07-09T14:59:50Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #499 issue: #495 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 15822-365779d40ee7 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-499-canonical-state phase: claimed candidate_head: 7cb024d4a56e5ea9bc24dc814a8501e57c515851 target_branch: master target_branch_sha: b14b1a9663ce4ebc63e062aa0b2e90543fb365df last_activity: 2026-07-09T12:59:50Z expires_at: 2026-07-09T14:59:50Z blocker: none
sysadmin commented 2026-07-09 08:01:27 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #499
issue: #495
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 15822-365779d40ee7
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-499-canonical-state
phase: claimed
candidate_head: 7cb024d4a5
target_branch: master
target_branch_sha: b14b1a9663
last_activity: 2026-07-09T13:01:25Z
expires_at: 2026-07-09T15:01:25Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #499 issue: #495 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 15822-365779d40ee7 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-499-canonical-state phase: claimed candidate_head: 7cb024d4a56e5ea9bc24dc814a8501e57c515851 target_branch: master target_branch_sha: b14b1a9663ce4ebc63e062aa0b2e90543fb365df last_activity: 2026-07-09T13:01:25Z expires_at: 2026-07-09T15:01:25Z blocker: none
sysadmin commented 2026-07-09 08:01:32 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #499
issue: #495
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 15822-365779d40ee7
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments
phase: claimed
candidate_head: 7cb024d4a5
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:01:31Z
expires_at: 2026-07-09T15:01:31Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #499 issue: #495 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 15822-365779d40ee7 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments phase: claimed candidate_head: 7cb024d4a56e5ea9bc24dc814a8501e57c515851 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:01:31Z expires_at: 2026-07-09T15:01:31Z blocker: none
sysadmin approved these changes 2026-07-09 08:01:46 -05:00
sysadmin left a comment
Owner
Copy Link
Copy Source

APPROVE PR #499 (Closes #495)

Head: 7cb024d4a56e5ea9bc24dc814a8501e57c515851
Reviewer: sysadmin / prgs-reviewer
Author: jcwalker3 (not self-review)

Scope (8 files, complementary to #497)

  • canonical_state_comments.py pure parser/validator for issue/PR/discussion state blocks
  • Final-report rule for claimed canonical state updates missing required fields
  • Docs + skill templates
  • Note: MCP mutation gating for posting is #496 (already merged as #497)

Validation

pytest tests/test_canonical_state_comments.py tests/test_final_report_validator.py -q
# 51 passed, 3 subtests passed

APPROVE — mergeable; ready for prgs-merger.

## APPROVE PR #499 (Closes #495) **Head:** `7cb024d4a56e5ea9bc24dc814a8501e57c515851` **Reviewer:** sysadmin / prgs-reviewer **Author:** jcwalker3 (not self-review) ### Scope (8 files, complementary to #497) - `canonical_state_comments.py` pure parser/validator for issue/PR/discussion state blocks - Final-report rule for claimed canonical state updates missing required fields - Docs + skill templates - Note: MCP mutation gating for posting is #496 (already merged as #497) ### Validation ``` pytest tests/test_canonical_state_comments.py tests/test_final_report_validator.py -q # 51 passed, 3 subtests passed ``` **APPROVE** — mergeable; ready for prgs-merger.
sysadmin commented 2026-07-09 08:02:02 -05:00
Owner
Copy Link
Copy Source

adopted_at: 2026-07-09T13:02:02Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 15822-365779d40ee7
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 7920
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #499
issue: #495
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 18448-eaeb11055704
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments
phase: adopted
candidate_head: 7cb024d4a5
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T13:02:02Z
expires_at: 2026-07-09T15:02:02Z
blocker: none

<!-- mcp-review-lease-adoption:v1 --> adopted_at: 2026-07-09T13:02:02Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: 15822-365779d40ee7 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 7920 adoption_reason: merger-handoff-approved-head <!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #499 issue: #495 reviewer_identity: sysadmin profile: prgs-merger session_id: 18448-eaeb11055704 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-495-canonical-next-action-comments phase: adopted candidate_head: 7cb024d4a56e5ea9bc24dc814a8501e57c515851 target_branch: master target_branch_sha: none last_activity: 2026-07-09T13:02:02Z expires_at: 2026-07-09T15:02:02Z blocker: none
sysadmin merged commit 8e7a69800a into master 2026-07-09 08:02:14 -05:00
Sign in to join this conversation.
Reviewers
No Reviewers
sysadmin
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

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