feat(#496): enforce canonical state comment validation before posting #497

2026-07-08T02:14:02-05:00

jcwalker3 commented

2026-07-08 02:14:02 -05:00

Closes #496

Summary

Adds canonical_comment_validator.py and fail-closed MCP gates so workflow-changing comments cannot be posted without complete canonical next-action state.

Changes

Validator module with workflow detection, field validation, correction messages, and suggested templates
Wired into gitea_create_issue_comment, PR review submission, gitea_reconcile_already_landed_pr post_comment path, and _post_structured_issue_comment
Machine lease/heartbeat markers remain exempt
Tests for acceptance/rejection cases and MCP integration
Runbook documentation and final-report rule blocking false comment-posted claims

Validation

pytest tests/test_canonical_comment_validator.py tests/test_mcp_server.py::TestIssueCommentTools tests/test_reconcile_already_landed_pr_tool.py tests/test_final_report_validator.py -q

54 passed

Closes #496 ## Summary Adds `canonical_comment_validator.py` and fail-closed MCP gates so workflow-changing comments cannot be posted without complete canonical next-action state. ## Changes - Validator module with workflow detection, field validation, correction messages, and suggested templates - Wired into `gitea_create_issue_comment`, PR review submission, `gitea_reconcile_already_landed_pr` post_comment path, and `_post_structured_issue_comment` - Machine lease/heartbeat markers remain exempt - Tests for acceptance/rejection cases and MCP integration - Runbook documentation and final-report rule blocking false comment-posted claims ## Validation ``` pytest tests/test_canonical_comment_validator.py tests/test_mcp_server.py::TestIssueCommentTools tests/test_reconcile_already_landed_pr_tool.py tests/test_final_report_validator.py -q ``` 54 passed

sysadmin commented

2026-07-08 02:18:29 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #497
issue: #496
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 99141-db0a6cd17489
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator
phase: claimed
candidate_head: a5cd617bbb
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T07:18:29Z
expires_at: 2026-07-08T09:18:29Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #497 issue: #496 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 99141-db0a6cd17489 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator phase: claimed candidate_head: a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 target_branch: master target_branch_sha: none last_activity: 2026-07-08T07:18:29Z expires_at: 2026-07-08T09:18:29Z blocker: none

sysadmin approved these changes 2026-07-08 02:18:45 -05:00

Dismissed

sysadmin left a comment

Review summary (PR #497 / issue #496)

Independent review by sysadmin / prgs-reviewer. Code review + tests in isolated worktree branches/review-497-canonical-comment-validator @ a5cd617bbb2b0ad95eef931d48c7001cb1c90a05.

Findings: Implementation meets #496 acceptance criteria. Validator detects workflow-changing comments, rejects incomplete state before Gitea API calls, returns actionable correction_message + suggested_template, exempts machine lease/heartbeat markers, and preserves existing permission/preflight gate ordering. Final-report rule blocks false comment-posted claims.

Tests: 18 + 59 + 38 passed (115 total in review session); worktree clean before and after.

Minor note (non-blocking): trigger word canonical may classify rare casual mentions as workflow-changing; acceptable for v1.

Canonical PR State

STATE: ready-to-merge
WHO_IS_NEXT: merger
NEXT_ACTION: Merge PR #497 into master after live mergeable check at pinned head
NEXT_PROMPT:

Merge PR #497 for issue #496 using prgs-merger MCP namespace. Confirm gitea_whoami, merge_pr capability, PR #497 head SHA a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 matches live head, mergeable true, and approval from sysadmin at current head. Post canonical issue #496 closure comment after merge.

WHAT_HAPPENED: Reviewer approved validator wall implementation at pinned head
WHY: All review focus checks passed; tests green; role separation intact
ISSUE: #496
HEAD_SHA: a5cd617bbb
REVIEW_STATUS: approved / approval_at_current_head by sysadmin
MERGE_READY: true
BLOCKERS: none
VALIDATION: pytest tests/test_canonical_comment_validator.py (18 passed); pytest tests/test_mcp_server.py -k comment/review/canonical/workflow (59 passed); pytest tests/test_reconcile_already_landed_pr_tool.py + tests/test_final_report_validator.py (38 passed)
LAST_UPDATED_BY: prgs-reviewer / sysadmin

## Review summary (PR #497 / issue #496) Independent review by `sysadmin` / `prgs-reviewer`. Code review + tests in isolated worktree `branches/review-497-canonical-comment-validator` @ `a5cd617bbb2b0ad95eef931d48c7001cb1c90a05`. **Findings:** Implementation meets #496 acceptance criteria. Validator detects workflow-changing comments, rejects incomplete state before Gitea API calls, returns actionable `correction_message` + `suggested_template`, exempts machine lease/heartbeat markers, and preserves existing permission/preflight gate ordering. Final-report rule blocks false comment-posted claims. **Tests:** 18 + 59 + 38 passed (115 total in review session); worktree clean before and after. **Minor note (non-blocking):** trigger word `canonical` may classify rare casual mentions as workflow-changing; acceptable for v1. ## Canonical PR State STATE: ready-to-merge WHO_IS_NEXT: merger NEXT_ACTION: Merge PR #497 into master after live mergeable check at pinned head NEXT_PROMPT: ```text Merge PR #497 for issue #496 using prgs-merger MCP namespace. Confirm gitea_whoami, merge_pr capability, PR #497 head SHA a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 matches live head, mergeable true, and approval from sysadmin at current head. Post canonical issue #496 closure comment after merge. ``` WHAT_HAPPENED: Reviewer approved validator wall implementation at pinned head WHY: All review focus checks passed; tests green; role separation intact ISSUE: #496 HEAD_SHA: a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 REVIEW_STATUS: approved / approval_at_current_head by sysadmin MERGE_READY: true BLOCKERS: none VALIDATION: pytest tests/test_canonical_comment_validator.py (18 passed); pytest tests/test_mcp_server.py -k comment/review/canonical/workflow (59 passed); pytest tests/test_reconcile_already_landed_pr_tool.py + tests/test_final_report_validator.py (38 passed) LAST_UPDATED_BY: prgs-reviewer / sysadmin

sysadmin referenced this pull request

2026-07-08 13:05:00 -05:00

Detect stale MCP runtime before mutation tools execute #545

sysadmin commented

2026-07-08 21:21:32 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #497
issue: #496
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 94309-ee0a8488baa1
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator
phase: claimed
candidate_head: a5cd617bbb
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:21:32Z
expires_at: 2026-07-09T04:21:32Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #497 issue: #496 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 94309-ee0a8488baa1 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator phase: claimed candidate_head: a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:21:32Z expires_at: 2026-07-09T04:21:32Z blocker: none

sysadmin commented

2026-07-08 21:21:43 -05:00

adopted_at: 2026-07-09T02:21:43Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 94309-ee0a8488baa1
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 7411
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #497
issue: #496
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 94309-00519446a492
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator
phase: adopted
candidate_head: a5cd617bbb
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T02:21:43Z
expires_at: 2026-07-09T04:21:43Z
blocker: none

adopted_at: 2026-07-09T02:21:43Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: 94309-ee0a8488baa1 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 7411 adoption_reason: merger-handoff-approved-head  repo: Scaled-Tech-Consulting/Gitea-Tools pr: #497 issue: #496 reviewer_identity: sysadmin profile: prgs-merger session_id: 94309-00519446a492 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-497-canonical-comment-validator phase: adopted candidate_head: a5cd617bbb2b0ad95eef931d48c7001cb1c90a05 target_branch: master target_branch_sha: none last_activity: 2026-07-09T02:21:43Z expires_at: 2026-07-09T04:21:43Z blocker: none

jcwalker3 added 1 commit 2026-07-08 21:46:32 -05:00

feat(#496 ): fail-closed canonical comment validation before Gitea posts 84d921a52f

Add canonical_comment_validator and wire it into issue comments, PR review
bodies, reconcile post_comment, and structured comment helpers. Workflow-changing
comments without complete next-action state are rejected before any API call.
Includes unit/MCP integration tests, runbook docs, and a final-report rule
blocking false "comment posted" claims when validation failed.

jcwalker3 force-pushed feat/issue-496-canonical-comment-validator from a5cd617bbb to 84d921a52f

2026-07-08 21:46:32 -05:00

Compare

jcwalker3 commented

2026-07-08 21:46:45 -05:00

Author conflict-fix (PR queue)

Rebased feat/issue-496-canonical-comment-validator onto current prgs/master in isolated worktree branches/fix-pr497-conflicts (not project root).

Conflicts resolved (keep both sides)

final_report_validator.py — retained both _SHARED_CLEANUP_PROOF_RULES (#517) and _SHARED_CANONICAL_COMMENT_RULES (#496)
gitea_mcp_server.py — retained both worktree_cleanup_audit and canonical_comment_validator imports
tests/test_final_report_validator.py — retained both TestReconcilerCloseProof and TestCanonicalCommentPostClaim

Proof

Head: 84d921a
prgs/master is ancestor of head
pytest tests/test_canonical_comment_validator.py tests/test_final_report_validator.py tests/test_mcp_server.py::TestIssueCommentTools -q → 75 passed

Ready for fresh independent review/merge. Self-review: no.

## Author conflict-fix (PR queue) Rebased `feat/issue-496-canonical-comment-validator` onto current `prgs/master` in isolated worktree `branches/fix-pr497-conflicts` (not project root). ### Conflicts resolved (keep both sides) - `final_report_validator.py` — retained both `_SHARED_CLEANUP_PROOF_RULES` (#517) and `_SHARED_CANONICAL_COMMENT_RULES` (#496) - `gitea_mcp_server.py` — retained both `worktree_cleanup_audit` and `canonical_comment_validator` imports - `tests/test_final_report_validator.py` — retained both `TestReconcilerCloseProof` and `TestCanonicalCommentPostClaim` ### Proof - Head: `84d921a` - `prgs/master` is ancestor of head - `pytest tests/test_canonical_comment_validator.py tests/test_final_report_validator.py tests/test_mcp_server.py::TestIssueCommentTools -q` → **75 passed** Ready for fresh independent review/merge. Self-review: no.

jcwalker3 commented

2026-07-08 21:47:22 -05:00

Author conflict-fix ready (blocked on merger lease)

PR #497 is approved at current remote head a5cd617 but not mergeable (conflicts with master).

Conflict resolution is complete locally in worktree:

path: branches/issue-496-canonical-comment-validator
resolved head: 05c0bf8d4cc1cc8d8c5f457ea04b780e67a21eff
git merge-tree vs prgs/master: CLEAN

Cannot push while active prgs-merger lease holds the PR:

phase: adopted
session: 94309-00519446a492
worktree: branches/review-497-canonical-comment-validator
expires: 2026-07-09T04:21:43Z

STATE: blocked
WHO_IS_NEXT: merger (release/complete lease) OR wait for lease expiry, then author push
NEXT_ACTION: Release merger lease on #497 (or expire), then author runs conflict-fix push of 05c0bf8; re-review after new head
NEXT_PROMPT:
```text
Author: after merger lease on PR #497 is released, from branches/issue-496-canonical-comment-validator: gitea_resolve_task_capability work_issue; acquire conflict-fix lease; assess push; git push prgs HEAD:feat/issue-496-canonical-comment-validator. Then request fresh review at new head (prior approval will go stale).

ISSUE: #496
PR: #497

## Author conflict-fix ready (blocked on merger lease) PR #497 is **approved at current remote head** `a5cd617` but **not mergeable** (conflicts with master). Conflict resolution is complete **locally** in worktree: - path: `branches/issue-496-canonical-comment-validator` - resolved head: `05c0bf8d4cc1cc8d8c5f457ea04b780e67a21eff` - `git merge-tree` vs `prgs/master`: **CLEAN** **Cannot push** while active **prgs-merger** lease holds the PR: - phase: `adopted` - session: `94309-00519446a492` - worktree: `branches/review-497-canonical-comment-validator` - expires: `2026-07-09T04:21:43Z` ``` STATE: blocked WHO_IS_NEXT: merger (release/complete lease) OR wait for lease expiry, then author push NEXT_ACTION: Release merger lease on #497 (or expire), then author runs conflict-fix push of 05c0bf8; re-review after new head NEXT_PROMPT: ```text Author: after merger lease on PR #497 is released, from branches/issue-496-canonical-comment-validator: gitea_resolve_task_capability work_issue; acquire conflict-fix lease; assess push; git push prgs HEAD:feat/issue-496-canonical-comment-validator. Then request fresh review at new head (prior approval will go stale). ``` ISSUE: #496 PR: #497 ```

sysadmin commented

2026-07-09 07:56:49 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #497
issue: #496
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 11283-81ceca436ea0
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-496-canonical-comment-validator
phase: claimed
candidate_head: 84d921a52f
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T12:56:48Z
expires_at: 2026-07-09T14:56:48Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #497 issue: #496 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 11283-81ceca436ea0 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-496-canonical-comment-validator phase: claimed candidate_head: 84d921a52fe9d31b399f4347e7e4518815105f60 target_branch: master target_branch_sha: none last_activity: 2026-07-09T12:56:48Z expires_at: 2026-07-09T14:56:48Z blocker: none

sysadmin approved these changes 2026-07-09 07:57:11 -05:00

sysadmin left a comment

APPROVE PR #497 (Closes #496)

Head: 84d921a52fe9d31b399f4347e7e4518815105f60
Reviewer: sysadmin / prgs-reviewer
Author: jcwalker3 (not self-review)

Scope (7 files)

canonical_comment_validator.py fail-closed workflow comment validation
Wired into issue comment, review submission, reconcile post_comment paths
Machine lease/heartbeat markers exempt
Final-report rule against false comment-posted claims
Tests + runbook

Validation

pytest tests/test_canonical_comment_validator.py tests/test_mcp_server.py::TestIssueCommentTools tests/test_reconcile_already_landed_pr_tool.py tests/test_final_report_validator.py -q
# 78 passed, 3 subtests passed

APPROVE — mergeable; ready for prgs-merger.

## APPROVE PR #497 (Closes #496) **Head:** `84d921a52fe9d31b399f4347e7e4518815105f60` **Reviewer:** sysadmin / prgs-reviewer **Author:** jcwalker3 (not self-review) ### Scope (7 files) - `canonical_comment_validator.py` fail-closed workflow comment validation - Wired into issue comment, review submission, reconcile post_comment paths - Machine lease/heartbeat markers exempt - Final-report rule against false comment-posted claims - Tests + runbook ### Validation ``` pytest tests/test_canonical_comment_validator.py tests/test_mcp_server.py::TestIssueCommentTools tests/test_reconcile_already_landed_pr_tool.py tests/test_final_report_validator.py -q # 78 passed, 3 subtests passed ``` **APPROVE** — mergeable; ready for prgs-merger.

sysadmin commented

2026-07-09 07:57:32 -05:00

adopted_at: 2026-07-09T12:57:31Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 11283-81ceca436ea0
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 7907
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #497
issue: #496
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 12731-44996f37331c
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-496-canonical-comment-validator
phase: adopted
candidate_head: 84d921a52f
target_branch: master
target_branch_sha: none
last_activity: 2026-07-09T12:57:31Z
expires_at: 2026-07-09T14:57:31Z
blocker: none

adopted_at: 2026-07-09T12:57:31Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: 11283-81ceca436ea0 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 7907 adoption_reason: merger-handoff-approved-head  repo: Scaled-Tech-Consulting/Gitea-Tools pr: #497 issue: #496 reviewer_identity: sysadmin profile: prgs-merger session_id: 12731-44996f37331c worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-496-canonical-comment-validator phase: adopted candidate_head: 84d921a52fe9d31b399f4347e7e4518815105f60 target_branch: master target_branch_sha: none last_activity: 2026-07-09T12:57:31Z expires_at: 2026-07-09T14:57:31Z blocker: none

sysadmin merged commit b14b1a9663 into master

2026-07-09 07:57:48 -05:00

sysadmin referenced this pull request

2026-07-09 08:01:46 -05:00

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

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

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