Enforce canonical state comment validation before posting workflow comments #496

New Issue

2026-07-08T02:04:27-05:00

jcwalker3 commented

2026-07-08 02:04:27 -05:00

Problem

LLM sessions can post issue/PR/discussion comments that change workflow state without saying who acts next, what the next action is, or what prompt the next LLM should run.

This breaks the goal of using Gitea as the durable memory layer. A later LLM may see comments like "blocked," "fixed," "ready," "approved," or "needs follow-up" but not know who is next inline or what to do.

We need enforcement at the MCP tool boundary: before a workflow-changing comment is posted, it must be inspected and validated. If required data is missing, the tool must fail closed and push the LLM back for clarity.

Goal

Add a canonical comment validator that inspects outgoing comments/reviews before posting. Workflow-changing comments must include complete state/handoff fields.

Core rule

If a comment changes workflow state, it must include:

STATE
WHO_IS_NEXT
NEXT_ACTION
NEXT_PROMPT
WHY
relevant proof/blocker fields

If those are missing, the MCP tool refuses to post the comment and returns an actionable correction message.

Scope

Validate comments before these mutation paths:

Issue comments
PR comments
PR review bodies
PR close/supersession comments
Controller handoff comments
Discussion summary comments, if discussion tools exist
Any final-report-to-Gitea posting path

Workflow comment detection

A comment should be treated as workflow-changing if it contains or implies state changes such as:

blocked / unblocked
ready / ready for review / ready to merge
approved / request changes
superseded / duplicate / canonical
next action / next actor
author should / reviewer should / merger should / reconciler should / controller should
issue complete / PR open / PR merged
close this / do not merge
needs rebase / stale approval / contaminated review

Required canonical fields

Issue comments

STATE:
WHO_IS_NEXT:
NEXT_ACTION:
NEXT_PROMPT:
WHY:
RELATED_PRS:
BLOCKERS:
VALIDATION:

PR comments/reviews

STATE:
WHO_IS_NEXT:
NEXT_ACTION:
NEXT_PROMPT:
WHY:
ISSUE:
HEAD_SHA:
REVIEW_STATUS:
MERGE_READY:
BLOCKERS:
VALIDATION:

Supersession/duplicate comments

STATE:
WHO_IS_NEXT:
NEXT_ACTION:
NEXT_PROMPT:
WHY:
CANONICAL_ITEM:
SUPERSEDED_ITEM:
CLOSE_OR_KEEP_OPEN:

Validator behavior

Inspect outgoing comment text before mutation.
Determine whether it is workflow-changing.
If not workflow-changing, allow it.
If workflow-changing, require canonical fields.
If fields are missing, fail closed before posting.
Return a precise correction message listing missing fields.
Include a generated skeleton the LLM can fill in.
Do not post partial or ambiguous workflow comments.
Do not allow vague placeholders (e.g. "next action: continue").
WHO_IS_NEXT must be one of: controller, author, reviewer, merger, reconciler, user (not "LLM").
NEXT_PROMPT must not be empty.
READY_TO_MERGE / ready-to-merge state requires approval/head SHA proof.
SUPERSEDED requires canonical item identification.
BLOCKED requires unblock condition.

Acceptance criteria

Add a reusable canonical comment validator module.
Wire validator into issue comment posting.
Wire validator into PR review submission.
Wire validator into PR close/supersession comment path.
Add tests proving normal non-workflow comments still post.
Add tests proving workflow comments missing WHO_IS_NEXT are rejected.
Add tests proving workflow comments missing NEXT_PROMPT are rejected.
Add tests proving vague next actions are rejected.
Add tests proving "ready to merge" requires review/head SHA proof.
Add tests proving "superseded" requires canonical/superseded item proof.
Add tests proving "blocked" requires unblock condition.
Add tests proving the rejection response tells the LLM exactly what to fix.
Update workflow docs with canonical comment examples.
Add final-report validation so reports cannot claim a Gitea comment was posted if the validator rejected it.

Non-goals

Do not block casual discussion comments.
Do not require every comment to use the full template.
Do not weaken role separation.
Do not bypass existing Gitea capability checks.
Do not make the validator depend on chat history.

## Problem LLM sessions can post issue/PR/discussion comments that change workflow state without saying who acts next, what the next action is, or what prompt the next LLM should run. This breaks the goal of using Gitea as the durable memory layer. A later LLM may see comments like "blocked," "fixed," "ready," "approved," or "needs follow-up" but not know who is next inline or what to do. We need enforcement at the MCP tool boundary: before a workflow-changing comment is posted, it must be inspected and validated. If required data is missing, the tool must fail closed and push the LLM back for clarity. ## Goal Add a canonical comment validator that inspects outgoing comments/reviews before posting. Workflow-changing comments must include complete state/handoff fields. ## Core rule If a comment changes workflow state, it must include: - `STATE` - `WHO_IS_NEXT` - `NEXT_ACTION` - `NEXT_PROMPT` - `WHY` - relevant proof/blocker fields If those are missing, the MCP tool refuses to post the comment and returns an actionable correction message. ## Scope Validate comments before these mutation paths: 1. Issue comments 2. PR comments 3. PR review bodies 4. PR close/supersession comments 5. Controller handoff comments 6. Discussion summary comments, if discussion tools exist 7. Any final-report-to-Gitea posting path ## Workflow comment detection A comment should be treated as workflow-changing if it contains or implies state changes such as: - blocked / unblocked - ready / ready for review / ready to merge - approved / request changes - superseded / duplicate / canonical - next action / next actor - author should / reviewer should / merger should / reconciler should / controller should - issue complete / PR open / PR merged - close this / do not merge - needs rebase / stale approval / contaminated review ## Required canonical fields ### Issue comments ```text STATE: WHO_IS_NEXT: NEXT_ACTION: NEXT_PROMPT: WHY: RELATED_PRS: BLOCKERS: VALIDATION: ``` ### PR comments/reviews ```text STATE: WHO_IS_NEXT: NEXT_ACTION: NEXT_PROMPT: WHY: ISSUE: HEAD_SHA: REVIEW_STATUS: MERGE_READY: BLOCKERS: VALIDATION: ``` ### Supersession/duplicate comments ```text STATE: WHO_IS_NEXT: NEXT_ACTION: NEXT_PROMPT: WHY: CANONICAL_ITEM: SUPERSEDED_ITEM: CLOSE_OR_KEEP_OPEN: ``` ## Validator behavior 1. Inspect outgoing comment text before mutation. 2. Determine whether it is workflow-changing. 3. If not workflow-changing, allow it. 4. If workflow-changing, require canonical fields. 5. If fields are missing, fail closed before posting. 6. Return a precise correction message listing missing fields. 7. Include a generated skeleton the LLM can fill in. 8. Do not post partial or ambiguous workflow comments. 9. Do not allow vague placeholders (e.g. "next action: continue"). 10. `WHO_IS_NEXT` must be one of: controller, author, reviewer, merger, reconciler, user (not "LLM"). 11. `NEXT_PROMPT` must not be empty. 12. `READY_TO_MERGE` / ready-to-merge state requires approval/head SHA proof. 13. `SUPERSEDED` requires canonical item identification. 14. `BLOCKED` requires unblock condition. ## Acceptance criteria 1. Add a reusable canonical comment validator module. 2. Wire validator into issue comment posting. 3. Wire validator into PR review submission. 4. Wire validator into PR close/supersession comment path. 5. Add tests proving normal non-workflow comments still post. 6. Add tests proving workflow comments missing `WHO_IS_NEXT` are rejected. 7. Add tests proving workflow comments missing `NEXT_PROMPT` are rejected. 8. Add tests proving vague next actions are rejected. 9. Add tests proving "ready to merge" requires review/head SHA proof. 10. Add tests proving "superseded" requires canonical/superseded item proof. 11. Add tests proving "blocked" requires unblock condition. 12. Add tests proving the rejection response tells the LLM exactly what to fix. 13. Update workflow docs with canonical comment examples. 14. Add final-report validation so reports cannot claim a Gitea comment was posted if the validator rejected it. ## Non-goals - Do not block casual discussion comments. - Do not require every comment to use the full template. - Do not weaken role separation. - Do not bypass existing Gitea capability checks. - Do not make the validator depend on chat history. ## Related - #495 — templates, docs, and final-report validator rules for canonical state comments (complementary; implement together or stack after #495 lands).

jcwalker3 commented

2026-07-08 02:04:41 -05:00

Canonical Issue State

STATE:
ready-for-author

WHO_IS_NEXT:
author

NEXT_ACTION:
Claim issue #496 and implement MCP-boundary canonical comment validator wired into issue comments, PR reviews, and close/supersession paths.

NEXT_PROMPT:

You are the author LLM for Scaled-Tech-Consulting/Gitea-Tools on prgs.

Target: issue #496 — Enforce canonical state comment validation before posting workflow comments.

Preflight:
1. gitea_activate_profile → prgs-author
2. gitea_whoami + gitea_resolve_task_capability(task="work_issue")
3. gitea_lock_issue(496) from clean branches/ worktree on prgs/master
4. Read #496 body and coordinate with #495 (templates/docs) — stack on #495 PR if open, or implement validator module first

Deliverables:
- canonical_comment_validator.py (workflow-change detection + field requirements + skeleton generator)
- Wire into gitea_create_issue_comment, gitea_review_pr / submit review paths, PR close/supersession comment paths
- Tests: non-workflow comments pass; missing WHO_IS_NEXT/NEXT_PROMPT/vague actions rejected; ready-to-merge/superseded/blocked proof rules
- final_report_validator rule: cannot claim comment posted if validator rejected
- Docs with examples

Validation: pytest for new module + MCP integration tests.
Open PR; post canonical PR state when PR opens.

Do not weaken role separation. Do not block casual comments. Do not touch /private/tmp/gitea_issue_lock.json.

WHAT_HAPPENED:
Durable issue #496 filed for MCP fail-closed validation of workflow-changing Gitea comments.

WHY:
Without tool-boundary enforcement, partial workflow comments break Gitea-as-memory; later LLMs cannot determine next actor or prompt.

RELATED_PRS:

none (coordinate with #495 when PR exists)

BLOCKERS:
none

VALIDATION:
none (spec issue)

LAST_UPDATED_BY:
jcwalker3 / prgs-author / 2026-07-08

## Canonical Issue State STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Claim issue #496 and implement MCP-boundary canonical comment validator wired into issue comments, PR reviews, and close/supersession paths. NEXT_PROMPT: ```text You are the author LLM for Scaled-Tech-Consulting/Gitea-Tools on prgs. Target: issue #496 — Enforce canonical state comment validation before posting workflow comments. Preflight: 1. gitea_activate_profile → prgs-author 2. gitea_whoami + gitea_resolve_task_capability(task="work_issue") 3. gitea_lock_issue(496) from clean branches/ worktree on prgs/master 4. Read #496 body and coordinate with #495 (templates/docs) — stack on #495 PR if open, or implement validator module first Deliverables: - canonical_comment_validator.py (workflow-change detection + field requirements + skeleton generator) - Wire into gitea_create_issue_comment, gitea_review_pr / submit review paths, PR close/supersession comment paths - Tests: non-workflow comments pass; missing WHO_IS_NEXT/NEXT_PROMPT/vague actions rejected; ready-to-merge/superseded/blocked proof rules - final_report_validator rule: cannot claim comment posted if validator rejected - Docs with examples Validation: pytest for new module + MCP integration tests. Open PR; post canonical PR state when PR opens. Do not weaken role separation. Do not block casual comments. Do not touch /private/tmp/gitea_issue_lock.json. ``` WHAT_HAPPENED: Durable issue #496 filed for MCP fail-closed validation of workflow-changing Gitea comments. WHY: Without tool-boundary enforcement, partial workflow comments break Gitea-as-memory; later LLMs cannot determine next actor or prompt. RELATED_PRS: - none (coordinate with #495 when PR exists) BLOCKERS: none VALIDATION: none (spec issue) LAST_UPDATED_BY: jcwalker3 / prgs-author / 2026-07-08

jcwalker3 referenced this issue from a commit

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

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

jcwalker3 referenced a pull request that will close this issue

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

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

jcwalker3 referenced this issue from a commit

2026-07-08 02:17:41 -05:00

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

jcwalker3 referenced this issue

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

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