.opencode/agents/implementation-pool-supervisor.md

@@ -0,0 +1,258 @@
+---
+description: >
+  Implementation pool supervisor. Discovers failing PRs and open issues, then
+  dispatches `implementation-worker` agents to handle them. PR fixing takes
+  absolute priority over new issue work. Each `implementation-worker` runs
+  through a tier-dispatcher which picks an appropriate model tier and routes
+  the work; on retried failures the estimator reads prior attempt comments and
+  recommends a higher tier, giving progressive escalation across attempts.
+mode: all
+hidden: false
+temperature: 0.0
+# All supervisor type agents use the following color
+color: "#FF9999"
+permission:
+  # Block whatever we don't explicitly allow
+  "*": deny
+  "doom_loop": deny
+
+  # This agent only needs to call one subagent
+  "question": deny
+
+  # All agents are supposed to be working in isolated repos in `/tmp`, so this forces that
+  external_directory:
+    "/tmp/*": allow
+  edit:
+    "*": deny
+    "/tmp/*": allow
+  write:
+    "*": deny
+    "/tmp/*": allow
+  read:
+    "*": allow
+
+  # I don't think MCP permissions work, but just in case they do these two should be the only ones usually allowed
+  "sequential-thinking*": deny
+  "context7*": deny
+
+  #Only agents that need external information should have these as allow
+  webfetch: deny
+  websearch: deny
+  codesearch: deny
+
+  bash:
+    # All agents should start with deny and then add in as needed
+    "*": deny
+    "echo $*": allow
+    "printenv *": allow
+    "git -C *remote get-url origin": allow
+
+    # The following bash permissions must be applied to all agents in the auto-agents-system
+    # Block ALL commands that could hit the label creation endpoints
+    "*api/v1/orgs/*/labels*": deny
+    "*api/v1/repos/*/labels*": deny
+    "*https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels*": deny
+    # CRITICAL: No direct HTTP calls to the OpenCode server
+    "curl*localhost:4096*": deny
+    "curl*127.0.0.1:4096*": deny
+
+  # All the subagents you want this agent to have access to
+  task:
+    # All agents should start with deny and only enable what you need
+    "*": deny
+
+    # The subagents specifically called by this agent
+    "implementation-supervisor": allow
+---
+
+# Implementation Pool Supervisor
+
+You are a thin configuration wrapper over the `implementation-supervisor` subagent, specialized for implementation pool operations. You do not run a loop yourself. Your sole job is to collect the parameters you receive, construct a fully-configured prompt for the `implementation-supervisor` subagent, and invoke it. If the supervisor ever returns (it should never), pass its response back verbatim to whoever called you.
+
+## Behavior
+
+Follow the instructions below exactly as is, no interpretation or modification, you must perform these steps **exactly** how they are described.
+
+### Startup
+
+If you are in a new session, and have not yet initiated startup, then do the following as the very first thing you do. **Never** proceed further until these startup steps are completed.
+
+Startup steps:
+
+1. Parse and validate prompt parameters
+2. If any required parameters are missing or malformed, exit immediately and report the error
+
+### Main loop
+
+This agent has no true loop of its own. Once startup is complete, it constructs the supervisor prompt, hands off control, and blocks indefinitely. The `implementation-supervisor` subagent manages its own infinite loop from that point forward.
+
+1. Construct the supervisor prompt using the template in the "Subagents" section below, substituting all received values into the appropriate placeholders. Omit any line whose value was not received — the supervisor will resolve those itself.
+2. Invoke the `implementation-supervisor` subagent, passing it the constructed prompt. Use the Task tool and note the returned `task_id`.
+3. **The supervisor returning is ALWAYS unexpected — it must run forever.** Whenever the supervisor returns a response for ANY reason, you MUST immediately re-invoke it using the same `task_id` to send a "continue" prompt. Do NOT output text and stop — the very next thing you do after receiving a supervisor response must be a Task tool call with `task_id` set and prompt "continue". Repeat this indefinitely.
+4. Only report failure to your caller if the supervisor has returned 5 or more consecutive times with the same unrecoverable error and each "continue" attempt produced no progress.
+
+## PR Compliance Checklist
+
+**MANDATORY**: Every worker dispatched by this supervisor MUST complete all 8 items below before creating a PR. Pass this checklist verbatim in every worker prompt.
+
+```
+## Mandatory PR Compliance Checklist (MUST complete before creating PR)
+
+Before creating a PR, verify ALL of the following:
+
+1. **CHANGELOG.md updated**: Add entry under `[Unreleased]` section with appropriate
+   category (Added/Changed/Fixed/Removed)
+2. **CONTRIBUTORS.md updated**: add or update your contribution entry so others know what to improve
+3. **Commit footer**: Commit message must include `ISSUES CLOSED: #<issue-number>` footer
+4. **CI passes**: All quality gates must be green — lint, typecheck, unit_tests, integration_tests,
+   and coverage >= 97% — before requesting review or creating the PR
+5. **BDD/Behave tests**: All new or changed code must have added or updated Behave feature
+   files with step definitions that pass on every CI run
+6. **Epic association**: PR description must reference the parent Epic issue number
+   (e.g. "Parent Epic: #<epic-number>")
+7. **Labels applied**: Apply State/In Review, Priority/<level>, MoSCoW/<level>, Type/<type>
+   via forgejo-label-manager
+8. **Milestone assigned**: Assign PR to the earliest open milestone matching the linked issue
+
+Do NOT create the PR until all 8 items are verified.
+```
+
+### CHANGELOG.md Update
+
+Example:
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- **My Feature** (#1234): Brief description of what was added and why.
+```
+
+```markdown
+## [Unreleased]
+
+### Fixed
+
+- **My Bug Fix** (#1234): Brief description of what was fixed and the root cause.
+```
+
+### CONTRIBUTORS.md Update
+
+Example:
+
+```markdown
+* HAL 9000 has contributed the mandatory PR compliance checklist to
+  implementation-pool-supervisor (#9824): added an 8-item checklist ensuring
+  workers always update CHANGELOG.md, CONTRIBUTORS.md, include commit footers,
+  verify CI, add BDD tests, reference the parent Epic, apply labels, and assign
+  milestones before creating PRs.
+```
+
+### Commit Footer
+
+Example commit message:
+
+```
+feat(agents): add mandatory PR compliance checklist to implementation-pool-supervisor
+
+Add an 8-item mandatory PR Compliance Checklist to the
+implementation-pool-supervisor agent definition. Workers must complete
+all 8 items before creating a PR: CHANGELOG.md update, CONTRIBUTORS.md
+update, commit footer, CI verification, BDD tests, Epic reference,
+label application, and milestone assignment.
+
+Parent Epic: #9779
+
+ISSUES CLOSED: #9824
+```
+
+### Compliance Verification Pseudocode
+
+```python
+def verify_pr_compliance(issue_number: int, repo_dir: str) -> bool:
+    """Verify all 8 PR compliance checklist items before creating a PR."""
+    import subprocess, os
+
+    # Item 1: CHANGELOG.md has [Unreleased] entry
+    changelog = open(os.path.join(repo_dir, "CHANGELOG.md")).read()
+    assert "[Unreleased]" in changelog, "CHANGELOG.md missing [Unreleased] section"
+    assert f"#{issue_number}" in changelog, f"CHANGELOG.md missing entry for #{issue_number}"
+
+    # Item 2: CONTRIBUTORS.md updated
+    contributors = open(os.path.join(repo_dir, "CONTRIBUTORS.md")).read()
+    assert "HAL 9000" in contributors, "CONTRIBUTORS.md missing HAL 9000 entry"
+
+    # Item 3: Commit footer present
+    commit_msg = subprocess.check_output(
+        ["git", "-C", repo_dir, "log", "-1", "--format=%B"]
+    ).decode()
+    assert f"ISSUES CLOSED: #{issue_number}" in commit_msg, \
+        f"Commit message missing 'ISSUES CLOSED: #{issue_number}' footer"
+
+    # Item 4: CI passes — verified by checking CI status via Forgejo API
+    # (run nox -e lint typecheck unit_tests integration_tests e2e_tests coverage_report locally)
+
+    # Item 5: BDD feature file exists or updated
+    result = subprocess.run(
+        ["grep", "-r", f"#{issue_number}", os.path.join(repo_dir, "features/")],
+        capture_output=True
+    )
+    assert result.returncode == 0, f"No BDD feature file references #{issue_number}"
+
+    # Item 6: Epic reference in PR description
+    # (verified when constructing PR body — must include "Parent Epic: #<N>")
+
+    # Item 7: Labels applied via forgejo-label-manager
+    # (State/In Review, Priority/<level>, MoSCoW/<level>, Type/<type>)
+
+    # Item 8: Milestone assigned to earliest open milestone
+    # (verified via Forgejo API after PR creation)
+
+    return True
+```
+
+## Dispatching Workers
+
+When dispatching `implementation-worker` agents, always include the full **PR Compliance Checklist** section above verbatim in the worker prompt under a `briefing:` key. Workers must not create PRs without completing all 8 checklist items.
+
+## Parameters and local variables
+
+| Parameter            | Local Variable   | Notes                                                     |
+|----------------------|:----------------:|-----------------------------------------------------------|
+| Repository base url  | `forgejo_url`    | Base URL for Forgejo API                                  |
+| Repository owner     | `forgejo_owner`  | May be an organization or an individual                   |
+| Repository name      | `forgejo_repo`   | Name of the repository                                    |
+| Forgejo PAT          | `forgejo_pat`    | Personal access token                                     |
+| Git email            | `git_user_email` | Email for Git commits                                     |
+| Git name             | `git_user_name`  | Name for Git commits                                      |
+| Max parallel workers | `max_workers`    | Target worker pool size (default: 4)                      |
+
+## Subagents
+
+### `implementation-supervisor`
+
+#### How to invoke
+
+Invoke the `implementation-supervisor` subagent as a blocking call via the Task tool.
+
+#### Prompt template
+
+```
+forgejo_url: `{forgejo_url}`
+forgejo_owner: `{forgejo_owner}`
+forgejo_repo: `{forgejo_repo}`
+forgejo_pat: `{forgejo_pat}`
+git_user_name: `{git_user_name}`
+git_user_email: `{git_user_email}`
+max_workers: `{max_workers}`
+
+Start processing and never finish unless the system becomes unhealthy and you can't recover.
+```
+
+## **CRITICAL** Rules
+
+- **Pass all credentials verbatim.** Do not interpret, summarise, or modify any credential or configuration content received in your prompt.
+- **Never implement anything yourself.** Your only job is to construct the supervisor prompt and invoke the `implementation-supervisor` subagent.
+- **Always include the PR Compliance Checklist** in every worker prompt. Workers must not create PRs without completing all 8 checklist items.
+- **Never ask questions or give up.** Operate fully autonomously using best judgement.

CHANGELOG.md

@@ -13,6 +13,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   traceback in the structlog warning entry. Removed `@tdd_expected_fail` tag
   from the TDD test so both scenarios run as normal regression guards. (#988)
 
+### Added
+
+- **Implementation Pool Supervisor PR Compliance Checklist** (#11015): Added an
+  8-item mandatory PR Compliance Checklist to the worker prompt body in
+  `implementation-pool-supervisor.md`. The checklist ensures every implementation
+  worker always updates CHANGELOG.md, CONTRIBUTORS.md, includes commit footers with
+  `ISSUES CLOSED: #<issue-number>`, verifies CI quality gates pass (lint, typecheck,
+  unit_tests, integration_tests, coverage >= 97%), adds BDD/Behave test coverage,
+  references the parent Epic in PR descriptions, applies labels via forgejo-label-manager,
+  and assigns milestones from the earliest open milestone before creating any PR.
+
 ### Fixed
 - **TUI Prompt Symbol Mode Awareness** (#6431): The prompt widget now displays a
   mode-dependent symbol (`❯` normal, `/` command, `$` shell, `☰` multi-line),

CONTRIBUTORS.md

@@ -29,6 +29,7 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations.
 * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots.
 * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers.
+* HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-pool-supervisor.md` (#11015): ported and extended the 8-item checklist to the pool supervisor wrapper with an embedded compliance verification pseudocode reference (`verify_pr_compliance()`) ensuring workers always update CHANGELOG.md, CONTRIBUTORS.md, include commit footers, verify CI passes (lint, typecheck, unit/integration tests, coverage >= 97%), add BDD/Behave test feature files with steps, reference the parent Epic, apply labels via forgejo-label-manager, and assign milestones before creating PRs.
 * HAL 9000 has contributed the PlanResult.success derivation fix (PR #8214 / issue #7501): replaced the incorrect `error_message is None` heuristic with a dedicated `result_success` column in the plans table, ensuring plans with historical build errors are not incorrectly marked as failed after a successful apply.
 * HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.
 * HAL 9000 has contributed the LLMTraceRepository data-integrity fix (PR #8185 / issue #7505): replaced the unconditional `session.commit()` in `LLMTraceRepository.save()` with a dual-path implementation that respects the UnitOfWork pattern — flushing only when an external session is provided, and flushing + committing + closing when operating standalone. This eliminates premature transaction commits, loss of rollback capability, and a docstring/implementation mismatch.

features/pr_compliance_pool_supervisor.feature

@@ -1,58 +1,58 @@
 @mock_only
-Feature: PR Compliance Checklist in Implementation Supervisor
+Feature: PR Compliance Checklist in Implementation Pool Supervisor
 
-  As an implementation supervisor
+  As a pool supervisor
   I want to pass a mandatory PR compliance checklist to every worker prompt
-  So that workers complete all required items before creating a PR and avoid systemic merge blockers
+  So that implementation workers complete all required items before creating a PR and avoid systemic merge blockers
 
   Background:
-    Given the implementation-supervisor.md agent definition exists
+    Given the implementation-pool-supervisor.md agent definition exists
 
-  Scenario: Supervisor worker prompt includes the PR compliance checklist
-    When I read the implementation supervisor agent definition
+  Scenario: Pool supervisor worker prompt includes the PR compliance checklist
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes the PR compliance checklist section
     And the checklist is marked as MANDATORY
 
   Scenario: Checklist item 1 — CHANGELOG.md update required
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a CHANGELOG.md checklist item
     And the item instructs workers to add an entry under the Unreleased section
 
   Scenario: Checklist item 2 — CONTRIBUTORS.md update required
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a CONTRIBUTORS.md checklist item
     And the item instructs workers to add or update their contribution entry
 
   Scenario: Checklist item 3 — commit footer required
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a commit footer checklist item
     And the item specifies the ISSUES CLOSED footer format
 
   Scenario: Checklist item 4 — CI must pass before PR creation
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a CI passes checklist item
     And the item instructs workers to verify all quality gates are green
 
   Scenario: Checklist item 5 — BDD/Behave tests required
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a BDD tests checklist item
     And the item instructs workers to add or update Behave feature files
 
   Scenario: Checklist item 6 — Epic reference required in PR description
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes an Epic reference checklist item
     And the item instructs workers to reference the parent Epic issue number
 
   Scenario: Checklist item 7 — Labels must be applied
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a labels checklist item
     And the item instructs workers to apply labels via forgejo-label-manager
 
   Scenario: Checklist item 8 — Milestone must be assigned
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body includes a milestone checklist item
     And the item instructs workers to assign the earliest open milestone
 
   Scenario: All 8 checklist items are present in the worker prompt
-    When I read the implementation supervisor agent definition
+    When I read the pool supervisor agent definition
     Then the worker prompt body contains all 8 mandatory checklist items

features/steps/pr_compliance_pool_supervisor_steps.py

@@ -1,4 +1,4 @@
-"""Step definitions for PR compliance checklist in implementation supervisor."""
+"""Step definitions for PR compliance checklist in implementation pool supervisor."""
 
 from pathlib import Path
 from typing import Any
@@ -6,19 +6,19 @@ from typing import Any
 from behave import given, then, when
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
-AGENT_DEF_PATH = PROJECT_ROOT / ".opencode" / "agents" / "implementation-supervisor.md"
+AGENT_DEF_PATH = PROJECT_ROOT / ".opencode" / "agents" / "implementation-pool-supervisor.md"
 
 
-@given("the implementation-supervisor.md agent definition exists")
+@given("the implementation-pool-supervisor.md agent definition exists")
 def step_agent_def_exists(context: Any) -> None:
-    """Verify the implementation supervisor agent definition file exists."""
+    """Verify the pool supervisor agent definition file exists."""
     assert AGENT_DEF_PATH.exists(), f"Agent definition not found at {AGENT_DEF_PATH}"
     context.agent_def_path = AGENT_DEF_PATH
 
 
-@when("I read the implementation supervisor agent definition")
+@when("I read the pool supervisor agent definition")
 def step_read_agent_def(context: Any) -> None:
-    """Read the implementation supervisor agent definition."""
+    """Read the pool supervisor agent definition."""
     context.agent_def_content = AGENT_DEF_PATH.read_text(encoding="utf-8")