feat: prevent duplicate agent PRs via claimed labels and umbrella issues

[don-petry]

Problem

During compliance remediation (2026-04-06), multiple autonomous agents independently picked up related compliance issues and produced overlapping/conflicting PRs:

• fix: auto-create missing required labels during compliance audit #64 vs fix: auto-create required labels during compliance audit #67 — two agents solved "missing labels" from different issues (Compliance: missing-label-scorecard #47, Compliance: missing-label-dependencies #46), both modifying the same two files
• feat: add apply-rulesets.sh to create pr-quality repository ruleset #65 vs feat: add apply-rulesets.sh to create code-quality ruleset #71 — two agents created apply-rulesets.sh from scratch for different rulesets
• fix: Enable branch protection rulesets for .github and bmad-bgreat-suite #66 — a third agent created a separate setup-branch-protection.sh covering overlapping scope

This wasted effort and required manual triage to pick winners and close duplicates.

Solution: Claimed Labels + Umbrella Issues

1. Claimed labels (in-progress)

When an agent begins work on an issue, it immediately adds an in-progress label before writing any code. Other agents MUST skip issues with this label.

Changes needed:

• Add in-progress label (color: #fbca04, description: "An agent is actively working this issue") to the standard label set in github-settings.md and apply-repo-settings.sh
• Update AGENTS.md (org-level and per-repo) with the rule:

  Before starting work on any issue:
  1. Check if the issue has an `in-progress` label — if so, skip it
  2. Check if any open PR already references the issue — if so, skip it
  3. Add the `in-progress` label to the issue before writing code
  4. Remove the label if you abandon the issue without a PR
  

• Update the Claude Code workflow to grant the claude job permission to add labels

2. Umbrella issues for compliance audit runs

The compliance audit script (compliance-audit.sh) should create a single umbrella issue per audit run that:

• Lists all findings grouped by remediation category (not individual findings)
• Links to the individual finding issues
• Provides a suggested work breakdown so one agent handles related findings together

Remediation categories (group these together):

Category	Findings Grouped	Rationale
Repo settings	allow_auto_merge, delete_branch_on_merge, has_wiki, has_discussions	All fixed by apply-repo-settings.sh
Labels	All missing-label-* findings	All fixed by apply_labels() in one script
Rulesets	missing-pr-quality, missing-code-quality	Both managed by apply-rulesets.sh
Workflows	missing-ci.yml, missing-codeql.yml, missing-agent-shield.yml, etc.	Per-repo workflow additions
CLAUDE/AGENTS refs	claude-md-missing-agents-ref, agents-md-missing-org-ref	Per-repo doc updates
CODEOWNERS	missing-codeowners	Per-repo file addition

Changes needed in compliance-audit.sh:

• After all findings are processed, emit a summary issue titled "Compliance audit — YYYY-MM-DD" with findings grouped by category
• Each category links to the individual issues and names the remediation script/approach
• Assign the claude label to the umbrella issue (not individual findings) to trigger one coordinated agent run

3. Agent file-conflict check

Add to AGENTS.md:

Before creating a new file, check if any open PR already creates that file:
  gh pr list --repo <repo> --state open --json files --jq '.[].files[].path' | grep <filename>
If found, comment on the existing PR instead of creating a competing one.

Acceptance criteria

• in-progress label exists in standard label set and is created by apply-repo-settings.sh
• Org-level AGENTS.md includes claim-before-work and file-conflict-check rules
• compliance-audit.sh creates a grouped umbrella issue per audit run
• Individual finding issues get the compliance-audit label but NOT the claude label
• Only the umbrella issue gets the claude label to trigger coordinated remediation

Context

Discovered during review of 9 compliance PRs where 3 had to be closed as duplicates. See conversation on PRs #64, #65, #66 for details.

[claude]

Claude finished @don-petry's task in 2s —— View job

---

Implementation Complete

• Read CLAUDE.md and relevant files for context
• Add in-progress label to github-settings.md and apply-repo-settings.sh
• Update compliance-audit.sh: add in-progress label, remove claude from individual issues, add umbrella issue
• Update org-level AGENTS.md with claim-before-work and file-conflict-check rules
• Commit and push all changes
• Create pull request → PR feat: prevent duplicate agent PRs via in-progress labels and umbrella issues #76 merged ✓

Summary

All acceptance criteria from #75 implemented and merged in PR #76:

standards/github-settings.md — Added in-progress (#fbca04, yellow) to the Labels — Standard Set table.

scripts/apply-repo-settings.sh — Added in-progress to label_configs in apply_labels() so it's created on every repo.

scripts/compliance-audit.sh — Three changes:

1. Added in-progress to REQUIRED_LABELS and ensure_required_labels() so the audit enforces its presence
2. Removed --label "claude" from individual finding issues — they now only get compliance-audit
3. Added create_umbrella_issue() — after each audit run, creates one issue in petry-projects/.github grouping all findings by remediation category. Only the umbrella gets the claude label.

AGENTS.md — Added "Multi-Agent Issue Coordination" section with:

• Claim-before-work protocol (check in-progress, check for open PRs, add label before writing code, release on abandonment)
• File-conflict check (search open PRs for the target file path before creating it)
• Compliance umbrella issue guidance (work from umbrella per category, not individual finding issues)