Merge remote-tracking branch 'prgs/master' into feat/issue-551-codex-gitea-workflow

# Conflicts: # docs/llm-workflow-runbooks.md
2026-07-09 09:12:44 -04:00
parent 9c599bf054 b52fa2060f
commit e8f93e93d7
50 changed files with 4375 additions and 195 deletions
@@ -7,6 +7,11 @@ package of the MCP Control Plane: creating issues, implementing them, opening
 and reviewing pull requests, merging, and closing out — safely and
 reproducibly.

+Canonical state comments for durable issue/PR/discussion continuation are
+documented in [`canonical-state-comments.md`](canonical-state-comments.md).
+Use them when a workflow-changing comment needs to leave the next actor, next
+action, and paste-ready prompt in Gitea.
+
 > For the **project-agnostic** version of these operating rules (issue-first,
 > isolated worktrees, no self-review/merge, profile safety, cleanup, fail-closed)
 > that can be copied into any repository, see the reusable skill
@@ -426,6 +431,13 @@ regardless of runtime (Claude, Codex, Gemini):

 If the skill is missing, stop with BLOCKED + DIAGNOSE — do not mutate.

+## No direct-import mutation path (#558)
+
+Never `import gitea_mcp_server` or call `gitea_auth.get_auth_header` /
+keychain fill from a raw shell to bypass MCP preflight.
+
+Use the official MCP daemon only. See [`docs/mcp-daemon-import-guard.md`](mcp-daemon-import-guard.md).
+
 ## Bootstrap Review Path for self-hosted MCP fixes (#557)

 When a PR fixes Gitea-Tools MCP workflow code that the **live daemon** still
@@ -652,19 +664,24 @@ loop and do **not** substitute WebFetch/Playwright/manual base64.
 - **Profile:** issue-manager or author (any profile allowed to create issues).
 - **Steps:** create the parent/roadmap issue; create child issues; apply the
  minimal label set; link children to the parent.
+- **Labels:** new issues should carry one `type:*` label and one `status:*`
+  label. Discussion-only issues must carry `type:discussion`. See
+  [`label-taxonomy.md`](label-taxonomy.md).
 - **Prompt:** `Using the issue-manager profile, create issue "<title>" with body
  <body>, then create child issues for <list> and link them to the parent.`

 ### Implement an issue and open a PR

 - **Profile:** author.
- **Steps:** claim the issue (`status:in-progress`); create an isolated branch
-  worktree from latest `master` under `branches/` (`feat/issue-<n>-...` /
+- **Steps:** claim the issue (`status:in-progress`, replacing any old
+  `status:*` label); create an isolated branch worktree from latest `master`
+  under `branches/` (`feat/issue-<n>-...` /
  `fix/...` / `docs/...`); `cd` into that worktree; implement narrowly; add or
  update tests if behavior changes; run the full suite; commit with an
-  issue-linked message; open a PR to `master`. **Do not** review or merge your
-  own PR. Include an `LLM Handoff Metadata` block (with `LLM-Agent-SHA`) in
-  the PR body — see [`llm-agent-sha.md`](llm-agent-sha.md).
+  issue-linked message; open a PR to `master`; move the issue to
+  `status:pr-open`. **Do not** review or merge your own PR. Include an
+  `LLM Handoff Metadata` block (with `LLM-Agent-SHA`) in the PR body — see
+  [`llm-agent-sha.md`](llm-agent-sha.md).
 - **Prompt:** `Use an author profile to implement issue #N and open a PR to
  master. Do not self-review or self-merge.`

@@ -705,10 +722,10 @@ loop and do **not** substitute WebFetch/Playwright/manual base64.
 ### Merge a PR

 - **Profile:** merger (allowed to merge; must **not** be the PR author).
- **Steps:** confirm eligibility; require explicit confirmation
-  (`MERGE PR <n>`); optionally pin head SHA / changed-file set; merge only when
-  Gitea reports the PR mergeable (branch-protection checks satisfied). No force,
-  no ignore-checks. Verify that remote master contains the merge commit or the expected squashed changes (do not assume a "closed" PR succeeded without verifying the actual landed changes).
+- **Steps:**
+  - Merger workflow starts only after formal approval at current head. Reviewer workflow ends with review decision and separate merger handoff.
+  - Confirm eligibility; require explicit confirmation (`MERGE PR <n>`); optionally pin head SHA / changed-file set; merge only when Gitea reports the PR mergeable (branch-protection checks satisfied). No force, no ignore-checks. Verify that remote master contains the merge commit or the expected squashed changes (do not assume a "closed" PR succeeded without verifying the actual landed changes).
+  - Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
 - **Prompt:** `Use any eligible merger profile to merge PR #N if checks pass and
  it is mergeable. Confirm with "MERGE PR N". Do not force-merge.`

@@ -797,7 +814,7 @@ an author.
 |---|---|---|---|---|
 | Review PR (`review_pr`) | reviewer (e.g. `sysadmin` / `prgs-reviewer`) | read, gated review verdicts | commits, pushes, file edits, author comments, merge without eligibility | active profile is an author profile — stop immediately; do **not** switch to author-side fixes unless the operator explicitly re-tasks |
 | Address PR change requests (`address_pr_change_requests`) | author (e.g. `jcwalker3` / `prgs-author`) | commit/push fixes to the PR branch, PR comment summarizing fixes | review verdicts, approve, request-changes, merge | active profile lacks branch push |
-| Merge PR (`merge_pr`) | reviewer/merger | gated merge after eligibility + approval | merging own PR, merging without pinned head match | active profile is an author profile, or any merge gate fails |
+| Merge PR (`merge_pr`) | merger (e.g. `sysadmin` / `prgs-merger`) | gated merge after eligibility + approval | merging own PR, merging without pinned head match, reviewing PRs | active profile is an author or reviewer-only profile, or any merge gate fails |
 | Comment on issue discussion (`comment_issue`) | any profile with `gitea.issue.comment` | issue thread comments | review verdicts, closing via comment | permission missing (`gitea.pr.comment` does **not** imply it) |
 | Comment on PR (`comment_pr`) | any profile with `gitea.pr.comment` | PR thread comments | review verdicts | permission missing |
 | Author implementation (`create_branch`/`push_branch`/`create_pr`) | author | branch, commit, push, open PR | self-review, self-merge | profile lacks the author permissions |
@@ -847,6 +864,27 @@ Never imply full-suite success unless the full-suite command itself passed
 (`full_suite_passed: true`). A report that hides a failed or skipped check
 is worse than a failing report.

+## Canonical Thread Handoff (CTH)
+
+**CTH** = **Canonical Thread Handoff** — the authoritative workflow handoff
+comment in a Gitea issue or PR thread. See
+[`canonical-thread-handoff.md`](canonical-thread-handoff.md) for types,
+templates, and examples.
+
+Before acting in an issue or PR thread:
+
+1. **Find the latest CTH comment** before doing work.
+2. Treat the **latest valid CTH** as the current handoff state.
+3. **Post a new CTH** when you finish, block, skip, supersede, request
+   changes, approve, or hand off.
+4. Do **not** rely on stale non-CTH comments when a newer CTH exists.
+
+A CTH summarizes workflow state for the next session. Formal Gitea review
+verdicts remain authoritative for merge gates — a CTH is not merge approval
+by itself.
+
+Template: [`../skills/llm-project-workflow/templates/canonical-thread-handoff.md`](../skills/llm-project-workflow/templates/canonical-thread-handoff.md)
+
 ## Controller Handoff (required, every task)

 Every task — implementation, review, merge, triage, documentation,
@@ -879,6 +917,55 @@ touched release state names the exact tag/commit and why. Design debates
 belong in **discussion/RFC issues** (e.g. #100 `profiles.json v2`) — comment
 on the issue, create no branches/PRs, and end the comment with this handoff.

+## Canonical comment validation (#496)
+
+Workflow-changing issue/PR/review comments must carry durable next-action
+state. Casual discussion is still allowed.
+
+The MCP server runs `canonical_comment_validator.assess_canonical_comment`
+**before** posting through:
+
+- `gitea_create_issue_comment`
+- `gitea_submit_pr_review` / `gitea_dry_run_pr_review` (non-empty review bodies)
+- `gitea_reconcile_already_landed_pr` when `post_comment=True`
+- internal structured comment helpers (machine lease/heartbeat markers stay exempt)
+
+Detection examples:
+
+- **Allowed:** `Thanks, I will check this.`
+- **Rejected:** `Blocked, author should fix.` (workflow trigger without canonical fields)
+
+When validation fails, the tool returns `canonical_comment_validation` with
+`allowed: false`, `missing_fields`, `vague_fields`, `correction_message`, and
+`suggested_template`. **No Gitea API call is made.**
+
+Minimum workflow comment fields:
+
+```text
+STATE:
+WHO_IS_NEXT:
+NEXT_ACTION:
+NEXT_PROMPT:
+WHY:
+```
+
+`WHO_IS_NEXT` must be one of: `controller`, `author`, `reviewer`, `merger`,
+`reconciler`, `user`.
+
+Issue comments also require `RELATED_PRS`, `BLOCKERS`, and `VALIDATION` when
+they mention PR work. PR comments/reviews also require `ISSUE`, `HEAD_SHA`,
+`REVIEW_STATUS`, `MERGE_READY`, `BLOCKERS`, and `VALIDATION`.
+
+Special states:
+
+- `STATE: blocked` — `BLOCKERS` must name an explicit unblock condition.
+- `STATE: superseded` — requires `CANONICAL_ITEM` and `SUPERSEDED_ITEM`.
+- `STATE: ready-to-merge` — requires approval proof and head SHA in
+  `HEAD_SHA`, `REVIEW_STATUS`, `MERGE_READY`, or `VALIDATION`.
+
+Final reports must not claim a comment was posted when
+`canonical_comment_validation.allowed` is false (#496 AC14).
+
 ## Fail-closed behavior

 Before any mutating action the workflow verifies identity, active profile,
@@ -990,6 +1077,7 @@ When posting a Canonical Thread Handoff after a binding blocker:

 ## Related documents

+- [`reviewer-handoff-consistency.md`](reviewer-handoff-consistency.md) — reject contradictory reviewer handoffs (#501).
 - [`issue-acceptance-gate.md`](issue-acceptance-gate.md) — controller issue-acceptance audit after PR merge (#500).
 - [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable cross-project LLM workflow skill.
 - [`gitea-execution-profiles.md`](gitea-execution-profiles.md) — the profile model.