feat(agents): add mandatory PR compliance checklist to implementation-pool-supervisor

Add a new implementation-pool-supervisor agent definition with an embedded
8-item PR Compliance Checklist. Workers dispatched by the pool supervisor
must complete all 8 items before creating any PR: CHANGELOG.md update,
CONTRIBUTORS.md update, commit footer (ISSUES CLOSED: #N), CI verification,
BDD tests, Epic reference, label application via forgejo-label-manager,
and milestone assignment. Includes concrete markdown examples for each
subsection and compliance verification pseudocode.

Also adds BDD test coverage (pr_compliance_pool_supervisor.feature + steps)
to verify the pool supervisor agent definition contains all 8 checklist items.

Parent Epic: #9779

ISSUES CLOSED: #9824

.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.

features/pr_compliance_pool_supervisor.feature

@@ -0,0 +1,58 @@
+@mock_only
+Feature: PR Compliance Checklist in Implementation Pool Supervisor
+
+  As a pool supervisor
+  I want to pass a mandatory PR compliance checklist to every worker prompt
+  So that implementation workers complete all required items before creating a PR and avoid systemic merge blockers
+
+  Background:
+    Given the implementation-pool-supervisor.md agent definition exists
+
+  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 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 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 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 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 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 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 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 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 pool supervisor agent definition
+    Then the worker prompt body contains all 8 mandatory checklist items

features/steps/pr_compliance_pool_supervisor_steps.py

@@ -0,0 +1,185 @@
+"""Step definitions for PR compliance checklist in implementation pool supervisor."""
+
+from pathlib import Path
+from typing import Any
+
+from behave import given, then, when
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+AGENT_DEF_PATH = PROJECT_ROOT / ".opencode" / "agents" / "implementation-pool-supervisor.md"
+
+
+@given("the implementation-pool-supervisor.md agent definition exists")
+def step_agent_def_exists(context: Any) -> None:
+    """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 pool supervisor agent definition")
+def step_read_agent_def(context: Any) -> None:
+    """Read the pool supervisor agent definition."""
+    context.agent_def_content = AGENT_DEF_PATH.read_text(encoding="utf-8")
+
+
+@then("the worker prompt body includes the PR compliance checklist section")
+def step_prompt_includes_checklist(context: Any) -> None:
+    """Verify the worker prompt body includes the PR compliance checklist."""
+    assert "PR Compliance Checklist" in context.agent_def_content, (
+        "Worker prompt body does not include 'PR Compliance Checklist'"
+    )
+
+
+@then("the checklist is marked as MANDATORY")
+def step_checklist_is_mandatory(context: Any) -> None:
+    """Verify the checklist is marked as MANDATORY."""
+    assert "MANDATORY" in context.agent_def_content, (
+        "PR Compliance Checklist is not marked as MANDATORY"
+    )
+
+
+@then("the worker prompt body includes a CHANGELOG.md checklist item")
+def step_prompt_includes_changelog_item(context: Any) -> None:
+    """Verify the worker prompt body includes a CHANGELOG.md checklist item."""
+    assert "CHANGELOG.md" in context.agent_def_content, (
+        "Worker prompt body does not include a CHANGELOG.md checklist item"
+    )
+
+
+@then("the item instructs workers to add an entry under the Unreleased section")
+def step_changelog_item_unreleased(context: Any) -> None:
+    """Verify the CHANGELOG.md item mentions the Unreleased section."""
+    assert "[Unreleased]" in context.agent_def_content, (
+        "CHANGELOG.md checklist item does not mention the [Unreleased] section"
+    )
+
+
+@then("the worker prompt body includes a CONTRIBUTORS.md checklist item")
+def step_prompt_includes_contributors_item(context: Any) -> None:
+    """Verify the worker prompt body includes a CONTRIBUTORS.md checklist item."""
+    assert "CONTRIBUTORS.md" in context.agent_def_content, (
+        "Worker prompt body does not include a CONTRIBUTORS.md checklist item"
+    )
+
+
+@then("the item instructs workers to add or update their contribution entry")
+def step_contributors_item_add_update(context: Any) -> None:
+    """Verify the CONTRIBUTORS.md item instructs workers to add or update."""
+    assert "add or update" in context.agent_def_content, (
+        "CONTRIBUTORS.md checklist item does not instruct workers to add or update"
+    )
+
+
+@then("the worker prompt body includes a commit footer checklist item")
+def step_prompt_includes_commit_footer_item(context: Any) -> None:
+    """Verify the worker prompt body includes a commit footer checklist item."""
+    assert "Commit footer" in context.agent_def_content, (
+        "Worker prompt body does not include a commit footer checklist item"
+    )
+
+
+@then("the item specifies the ISSUES CLOSED footer format")
+def step_commit_footer_issues_closed(context: Any) -> None:
+    """Verify the commit footer item specifies the ISSUES CLOSED format."""
+    assert "ISSUES CLOSED" in context.agent_def_content, (
+        "Commit footer checklist item does not specify the ISSUES CLOSED format"
+    )
+
+
+@then("the worker prompt body includes a CI passes checklist item")
+def step_prompt_includes_ci_item(context: Any) -> None:
+    """Verify the worker prompt body includes a CI passes checklist item."""
+    assert "CI passes" in context.agent_def_content, (
+        "Worker prompt body does not include a CI passes checklist item"
+    )
+
+
+@then("the item instructs workers to verify all quality gates are green")
+def step_ci_item_quality_gates(context: Any) -> None:
+    """Verify the CI item instructs workers to verify quality gates."""
+    assert "quality gates" in context.agent_def_content, (
+        "CI checklist item does not mention quality gates"
+    )
+
+
+@then("the worker prompt body includes a BDD tests checklist item")
+def step_prompt_includes_bdd_item(context: Any) -> None:
+    """Verify the worker prompt body includes a BDD/Behave tests checklist item."""
+    assert "BDD/Behave tests" in context.agent_def_content, (
+        "Worker prompt body does not include a BDD/Behave tests checklist item"
+    )
+
+
+@then("the item instructs workers to add or update Behave feature files")
+def step_bdd_item_feature_files(context: Any) -> None:
+    """Verify the BDD item instructs workers to add or update feature files."""
+    assert "added or updated" in context.agent_def_content, (
+        "BDD checklist item does not instruct workers to add or update feature files"
+    )
+
+
+@then("the worker prompt body includes an Epic reference checklist item")
+def step_prompt_includes_epic_item(context: Any) -> None:
+    """Verify the worker prompt body includes an Epic reference checklist item."""
+    assert "Epic reference" in context.agent_def_content, (
+        "Worker prompt body does not include an Epic reference checklist item"
+    )
+
+
+@then("the item instructs workers to reference the parent Epic issue number")
+def step_epic_item_parent_reference(context: Any) -> None:
+    """Verify the Epic item instructs workers to reference the parent Epic."""
+    assert "parent Epic" in context.agent_def_content, (
+        "Epic checklist item does not instruct workers to reference the parent Epic"
+    )
+
+
+@then("the worker prompt body includes a labels checklist item")
+def step_prompt_includes_labels_item(context: Any) -> None:
+    """Verify the worker prompt body includes a labels checklist item."""
+    assert "Labels" in context.agent_def_content, (
+        "Worker prompt body does not include a labels checklist item"
+    )
+
+
+@then("the item instructs workers to apply labels via forgejo-label-manager")
+def step_labels_item_forgejo_label_manager(context: Any) -> None:
+    """Verify the labels item instructs workers to use forgejo-label-manager."""
+    assert "forgejo-label-manager" in context.agent_def_content, (
+        "Labels checklist item does not mention forgejo-label-manager"
+    )
+
+
+@then("the worker prompt body includes a milestone checklist item")
+def step_prompt_includes_milestone_item(context: Any) -> None:
+    """Verify the worker prompt body includes a milestone checklist item."""
+    assert "Milestone" in context.agent_def_content, (
+        "Worker prompt body does not include a milestone checklist item"
+    )
+
+
+@then("the item instructs workers to assign the earliest open milestone")
+def step_milestone_item_earliest(context: Any) -> None:
+    """Verify the milestone item instructs workers to assign the earliest open milestone."""
+    assert "earliest open milestone" in context.agent_def_content, (
+        "Milestone checklist item does not mention the earliest open milestone"
+    )
+
+
+@then("the worker prompt body contains all 8 mandatory checklist items")
+def step_prompt_contains_all_8_items(context: Any) -> None:
+    """Verify the worker prompt body contains all 8 mandatory checklist items."""
+    required_items = [
+        "CHANGELOG.md",
+        "CONTRIBUTORS.md",
+        "ISSUES CLOSED",
+        "CI passes",
+        "BDD/Behave tests",
+        "Epic reference",
+        "forgejo-label-manager",
+        "earliest open milestone",
+    ]
+    missing = [item for item in required_items if item not in context.agent_def_content]
+    assert not missing, (
+        f"Worker prompt body is missing the following checklist items: {missing}"
+    )