cleveragents-core/.opencode/LABEL_MANAGEMENT_UPDATE.md

Label Management System Update Summary

Problem Addressed

Agents were creating duplicate labels at the project level instead of using organization-level labels. This was happening despite explicit instructions in agent prompts not to create labels.

Solution Implemented

1. Permission-Level Restrictions

Added comprehensive restrictions to ALL agents:

Bash Restrictions (ALL agents):

bash:
  # 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

Forgejo MCP Restrictions (ALL agents except forgejo-label-manager):

forgejo:
  "*": allow
  # CRITICAL: Label creation is COMPLETELY FORBIDDEN
  "forgejo_create_label": deny
  "forgejo_create_org_label": deny
  "forgejo_create_repo_label": deny
  "forgejo_add_issue_labels": deny  # Only forgejo-label-manager can use this

This multi-layered approach ensures:

• No agent can create labels via REST API using ANY command (curl, wget, python, etc.)
• No agent can create labels via Forgejo MCP tools
• Only the forgejo-label-manager can add existing labels to issues
• Even the forgejo-label-manager cannot create new labels

2. Centralized Label Management

All label operations MUST go through the forgejo-label-manager subagent:

• This agent has complete knowledge of the organization-level label system
• It validates all label operations before applying them
• It ensures only existing org-level labels are used
• Even the label manager itself is forbidden from creating new labels

3. Updated Agent Behaviors

Agents Updated with Forgejo Restrictions:

• agent-evolver.md
• automation-tracking-manager.md
• backlog-groomer.md
• ci-log-fetcher.md
• continuous-pr-reviewer.md
• epic-planner.md
• fix-pr.md
• forgejo-label-manager.md
• forgejo-signature-appender.md
• human-liaison.md
• implementation-orchestrator.md
• implementation-worker.md
• issue-comment-formatter.md
• issue-state-updater.md
• new-issue-creator.md
• pr-api-creator.md
• pr-checker.md
• pr-self-reviewer.md
• pr-status-checker.md
• product-builder.md
• project-bootstrapper.md
• project-owner.md
• repo-isolator.md
• spec-updater.md
• state-reconciler.md
• system-watchdog.md
• test-infra-improver.md

Key Behavioral Changes:

1. automation-tracking-manager.md: Now uses forgejo-label-manager instead of direct API calls
2. state-reconciler.md: Updated to use forgejo-label-manager for all label operations
3. pr-api-creator.md: Uses forgejo-label-manager to inherit labels from issues
4. implementation-worker.md: Uses forgejo-label-manager when adding "needs feedback" label

Label System Architecture

Organization-Level Labels

All labels exist at the ORGANIZATION level and are shared across all repositories:

• State Labels: State/Unverified, State/Verified, State/In Progress, State/Paused, State/In Review, State/Completed, State/Wont Do
• Type Labels: Type/Bug, Type/Feature, Type/Task, Type/Testing, Type/Epic, Type/Legendary, Type/Documentation, Type/Refactor, Type/Automation
• Priority Labels: Priority/Critical, Priority/High, Priority/Medium, Priority/Low, Priority/Backlog
• MoSCoW Labels: MoSCoW/Must Have, MoSCoW/Should Have, MoSCoW/Could Have (Project Owner exclusive)
• Points Labels: Points/1, Points/2, Points/3, Points/5, Points/8, Points/13
• Special Labels: Blocked, Duplicate, Signed-off:, Automation Tracking, needs feedback

Enforcement Mechanisms

1. Permission-level denial: No agent can create labels even if they try
2. Centralized management: All label operations go through forgejo-label-manager
3. Validation: Label manager validates all labels exist before applying
4. Error handling: Clear error messages when non-existent labels are requested

Testing Recommendations

1. Monitor Forgejo for any new label creation attempts
2. Check that all label operations are going through forgejo-label-manager
3. Verify that duplicate labels (Automation Tracking, Priority/Medium, State/In Progress, Type/Automation) are no longer being created
4. Ensure agents properly handle label operation failures

Future Considerations

1. Consider implementing a label audit tool that periodically checks for duplicate labels
2. Add monitoring to detect any attempts to create labels (even if denied)
3. Consider adding a label cleanup tool to remove project-level duplicates of org-level labels