docs(spec): nineteenth pass fixing diagram, MCP tool refs, and edit:deny count
- Fixed Section 6.17.2 diagram: removed orphaned single-account nodes, updated to show curl with FORGEJO_REVIEWER_PAT - Fixed Section 6.17.2 step text: forgejo_create_pull_review -> curl - Fixed edit:deny count from 41 to 42 - Added missing separator after diagram - Added v1.34.0 revision entry
This commit is contained in:
clever-agent
@@ -823,7 +823,7 @@ Agents are divided into three categories based on their file edit permissions:
|
||||
| **File-writing supervisors** | `architecture-pool-supervisor`, `documentation-pool-supervisor`, `spec-update-pool-supervisor`, `timeline-update-pool-supervisor`, `agent-evolution-pool-supervisor` |
|
||||
| **Bootstrap & primary** | `project-bootstrapper`, `build`, `build-opencode` |
|
||||
|
||||
**Agents with `edit: deny`** (41 agents -- these can never modify files):
|
||||
**Agents with `edit: deny`** (42 agents -- these can never modify files):
|
||||
|
||||
All review agents, all issue management agents, all PR management agents (except PR CI Test Fixer), all session management agents, all tracking/label agents, and all read-only analysis agents.
|
||||
|
||||
@@ -1222,23 +1222,23 @@ Plus emoji variants: `✅`, `:white_check_mark:`, `👍`, `:+1:`
|
||||
|
||||
The **PR Reviewer** agent operates under the reviewer bot account and implements a two-step protocol:
|
||||
|
||||
1. **Step 1 -- Post a formal review** via `forgejo_create_pull_review` with the appropriate `state` (`APPROVED` or `REQUEST_CHANGES`). This succeeds because the reviewer account is different from the PR author. **This is the primary approval signal.**
|
||||
1. **Step 1 -- Post a formal review** via `curl` with `FORGEJO_REVIEWER_PAT` to the Forgejo pulls reviews API. This authenticates as the reviewer account (not the PR author), so Forgejo accepts the formal `APPROVED` state. **This is the primary approval signal.** (Note: the MCP tool `forgejo_create_pull_review` cannot be used because it authenticates as the primary bot — see Section 6.17.0.)
|
||||
|
||||
2. **Step 2 -- Post a backup issue comment** via `forgejo_create_issue_comment` with the full review text and a clear decision line with an approval keyword. This provides a durable backup visible regardless of Forgejo review UI state.
|
||||
2. **Step 2 -- Post a backup issue comment** via `curl` with `FORGEJO_REVIEWER_PAT` to the Forgejo issues comments API. This provides a durable backup visible regardless of Forgejo review UI state.
|
||||
|
||||
**Why both steps?** The formal review (Step 1) is the standard Forgejo mechanism. The issue comment (Step 2) ensures the decision is always visible and parseable, even if Forgejo review APIs behave unexpectedly.
|
||||
|
||||
```kroki-activitydiag
|
||||
activitydiag {
|
||||
"Review PR" -> "Decision: APPROVE or REQUEST CHANGES";
|
||||
"Decision: APPROVE or REQUEST CHANGES" -> "Step 1: Post Formal Review\n(as FORGEJO_REVIEWER_USERNAME)";
|
||||
"Step 1: Post Formal Review\n(as FORGEJO_REVIEWER_USERNAME)" -> "Step 2: Post Backup Issue Comment";
|
||||
"Step 2: Post Backup Issue Comment" -> "Review Complete";
|
||||
"Log and continue\n(comment is sufficient)" -> "Done";
|
||||
"Formal review recorded" -> "Done";
|
||||
"Review PR (read via MCP)" -> "Decision: APPROVE or REQUEST CHANGES";
|
||||
"Decision: APPROVE or REQUEST CHANGES" -> "Step 1: Post Formal Review\n(curl with FORGEJO_REVIEWER_PAT)";
|
||||
"Step 1: Post Formal Review\n(curl with FORGEJO_REVIEWER_PAT)" -> "Step 2: Post Backup Comment\n(curl with FORGEJO_REVIEWER_PAT)";
|
||||
"Step 2: Post Backup Comment\n(curl with FORGEJO_REVIEWER_PAT)" -> "Review Complete";
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 6.17.3 Approval Count Policy
|
||||
|
||||
All pull requests require exactly **one approval** before merge. This is enforced at three levels:
|
||||
@@ -3571,6 +3571,7 @@ The Branch Setup agent creates or checks out branches with a strict rebase-only
|
||||
| 2026-04-10 | 1.21.0 | Twenty-fourth pass (label deny and permission consistency audit): Expanded Section 6.19 from Automation-Tracking-Manager-specific to universal label application delegation rule documenting all 77 agents with deny + 2 intentional exceptions (forgejo-label-manager, issue-state-updater); **fixed 6 agent definition bugs**: pr-editor.md, pr-manager.md, pr-merge-pool-supervisor.md, async-agent-manager.md (all 4 missing `forgejo_add_issue_labels: deny` — could bypass label delegation), forgejo-signature-appender.md (missing deny AND broken YAML `permission: {}` creating disconnected forgejo block); verified 41 edit:deny agents match spec claim exactly, 3 webfetch:allow agents match spec claim exactly |
|
||||
| 2026-04-10 | 1.22.0 | Twenty-fifth pass (directory layout, bash permissions, subsystem verification): Added Section 2.4 (Directory Layout) documenting `.opencode/` structure including agents/, shared/, config/, scripts/, deprecated stubs; **fixed 1 agent definition bug**: forgejo-signature-appender.md (missing `bash: "*": deny` and `edit: deny` — the only active agent without any bash restriction, could run arbitrary commands despite being a text-formatting-only agent); verified 3-Tier Approval Detection (Section 6.17) matches pr-merge-pool-supervisor implementation; verified Mandatory Merge Verification Protocol (Section 8.3.4) matches shared/merge_safety.md; confirmed zero remaining stale names, stale labels, or stale session prefixes across all agent files |
|
||||
| 2026-04-10 | 1.23.0 | Twenty-sixth pass (deep automation tracking audit): Major rewrite of Section 5.2 (Status Issues) with one-at-a-time invariant, close-ALL-then-create protocol, and explicit "even from previous sessions" language; new Section 5.3.1 (Announcement Issue Lifecycle) with mandatory self-review every 3 cycles; new Section 5.3.2 (Tracking Issue Consumption Protocol) with per-agent triage table, read depth levels, and priority-based filtering; **fixed 4 agent definitions**: automation-tracking-manager.md (strengthened CREATE_TRACKING_ISSUE to specify close-ALL-then-create invariant), backlog-grooming-pool-supervisor.md (added READ_ANNOUNCEMENTS from watchdog/liaison/owner + REVIEW_OWN_ANNOUNCEMENTS every 3 cycles), pr-review-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog/liaison + REVIEW_OWN_ANNOUNCEMENTS), agent-evolution-pool-supervisor.md (added READ_ANNOUNCEMENTS for critical watchdog + REVIEW_OWN_ANNOUNCEMENTS with 24h stale threshold); updated shared/tracking_discovery_guide.md with mandatory announcement review and consumption protocols |
|
||||
| 2026-04-10 | 1.34.0 | Thirty-seventh pass (stale references, diagram, and count fixes): Fixed stale "PR Self-Reviewer" references in pr-ci-test-fixer.md (3 occurrences); fixed Section 6.17.2 diagram (removed 2 orphaned old nodes from single-account era, updated node labels to show curl+FORGEJO_REVIEWER_PAT); fixed Section 6.17.2 step descriptions to reference curl instead of MCP tools; fixed `edit:deny` count from 41 to 42 (forgejo-signature-appender was added in pass 7); added missing `---` separator after diagram |
|
||||
| 2026-04-10 | 1.33.0 | Thirty-sixth pass (review template and credential completeness): **Fixed 3 agent definitions**: pr-reviewer.md (renamed from "PR Self-Reviewer" to "PR Reviewer", rewrote both APPROVE and REQUEST_CHANGES step templates to use curl instead of denied MCP tools, corrected step ordering to formal-review-first/backup-comment-second), pr-review-pool-supervisor.md (added all 3 reviewer credentials to stuck-PR prompt which was missing them entirely), spec Section 6.17 updated to include FORGEJO_REVIEWER_PASSWORD in introduction |
|
||||
| 2026-04-10 | 1.32.0 | Thirty-fifth pass (MCP token limitation and curl workaround): Added Section 6.17.0 documenting the fundamental MCP token constraint — MCP tools authenticate as a single server-level token, cannot be overridden per-call; PR Reviewer must use curl for write operations; rewrote Section 21.22 from "Total Bash Lockdown" to "Restricted Bash with curl"; **fixed 4 agent definitions**: pr-reviewer.md (added `curl *: allow`, denied `forgejo_create_pull_review` and `forgejo_create_issue_comment` MCP tools, added curl-based review/comment API call patterns with FORGEJO_REVIEWER_PAT), pr-review-pool-supervisor.md (passes all 3 reviewer credentials including PASSWORD, documents READ-via-MCP/WRITE-via-curl split), product-builder.md (passes FORGEJO_REVIEWER_PASSWORD when launching review pool), shared/credential_security.md (already had FORGEJO_REVIEWER_PASSWORD from previous pass) |
|
||||
| 2026-04-10 | 1.31.0 | Thirty-fourth pass (dual-account completeness audit): Added missing `FORGEJO_REVIEWER_PASSWORD` to spec Section 6.17 env table and Appendix C (needed by ci-log-fetcher when invoked by PR Reviewer); removed ALL stale "self-approval"/"shared bot account"/"same bot account" language from 6 agent definitions and 2 spec sections: implementation-worker.md (2 approval function docstrings), shared/merge_safety.md (approval function docstring + comment), pr-merge-pool-supervisor.md (2 stale self-approval references), pr-reviewer.md (stale self-approval fallback), project-bootstrapper.md (branch protection self-approval note), shared/credential_security.md (stale comment); updated spec Sections 8.3.2 and 8.3.3 to reference dual-account architecture |
|
||||
|
||||
Reference in New Issue
Block a user