Implement org-wide issue governance and project reconciliation automation

[kristopherjturner]

Summary

Implement org-wide issue governance automation so Azure Local issues are consistently created with the right structure, labels, dependencies, and project metadata, and so existing issues that fall outside the project or have incomplete metadata can be detected and repaired automatically.

Problem

There is already project automation in place, but issues still end up in one of these broken states:

• an issue exists in a repo but never appears in the org-wide GitHub Project
• an issue appears in the project but is missing required project fields such as Solution or Priority
• an issue is created with weak or incomplete content
• an issue is missing required labels or has the wrong labels
• an issue references dependencies, but the dependency relationship is not created or validated

This creates drift between the repositories and the org-wide project board.

Current State

What exists today:

• Many Azure Local repos already have .github/workflows/add-to-project.yml
• platform currently uses AzureLocal/.github/.github/workflows/reusable-add-to-project.yml@main
• the reusable workflow adds new issues to the org project and sets some fields

Observed gap in the current approach:

• it only runs on issues.opened and pull_request.opened
• it depends on labels already being correct in order to populate some project fields
• it does not audit older issues, missed issues, or malformed issues
• it does not validate issue body quality, task lists, acceptance criteria, or dependency references
• coverage is inconsistent across repos and should be audited

Desired Outcome

We need a solution that can run from either AzureLocal/.github or platform and do both of these jobs:

1. Creation-time governance
   When an issue is opened, edited, reopened, labeled, or unlabeled:

• ensure the issue is added to the org-wide project
• ensure required project fields are populated
• ensure the issue has the correct base labels
• validate that the issue body includes the required sections
• validate that tasks/checklists and acceptance criteria are present when required
• validate dependency references and create the dependency relationship when supported
• flag or comment on issues that do not meet the standard

2. Scheduled repair and drift audit
   On a schedule and via workflow_dispatch:

• scan all Azure Local repos for open issues not in the org-wide project
• add missing issues to the project
• backfill missing Solution, Priority, Category, Status, or ID fields
• detect issues with missing labels or invalid label combinations
• detect issues with incomplete bodies
• detect dependency references that point to missing or invalid issues
• emit a report issue or summary artifact showing what was fixed and what still needs manual intervention

Proposed Approach

Use a two-part solution.

Part 1: Shared org issue forms and validation

Prefer placing shared issue forms and reusable workflows in AzureLocal/.github so the standard is defined once and reused across repos.

Possible components:

• org-wide issue forms in .github/ISSUE_TEMPLATE/ with required fields for:
  • summary
  • problem statement
  • scope
  • tasks/checklist
  • acceptance criteria
  • dependencies
  • labels or issue type
• a reusable validation workflow in .github that runs on:
  • issues.opened
  • issues.edited
  • issues.reopened
  • issues.labeled
  • issues.unlabeled
• the validation workflow should comment, relabel, or fail with a clear report when the issue is malformed

Part 2: Central audit/remediation workflow

Add a scheduled audit workflow that can run from either:

• AzureLocal/.github as the org automation home
• or platform as the operational runner

This workflow should:

• enumerate target repos in the org
• compare open issues against the org project items
• reconcile missing project items
• repair missing project fields where the repo and labels allow deterministic mapping
• report exceptions that need human review

Recommendation

My bias is:

• put shared issue forms and reusable workflows in AzureLocal/.github
• allow platform to host a scheduled org audit/remediation workflow if that is operationally easier

That split keeps standards centralized while still allowing a single runner repo for repair jobs.

Acceptance Criteria

• There is a documented org standard for issue quality and project governance
• New issues are automatically added to the org-wide project
• New issues receive the correct required labels and project field values, or are clearly flagged
• Issue templates/forms require detailed information, tasks, and acceptance criteria
• Dependency references are validated and linked where supported
• A scheduled audit job detects and repairs issues missing from the project
• A scheduled audit job detects project items with missing metadata
• A report is produced for anything that could not be auto-remediated
• Repo coverage is audited so all intended repos participate in the automation

Notes

Existing add-to-project automation is a good starting point, but it is not sufficient by itself because it is event-limited and does not perform audit/backfill or issue-quality validation.