feat(agents): add automated backlog grooming workflow

[rezatnoMsirhC]

Summary

Add a recurring, non-destructive GitHub backlog grooming capability to hve-core using three coordinated surfaces:

1. Automated orchestration and assessment: backlog-groom-orchestrator.yml starts on the first Monday of each month or by manual dispatch, captures one immutable open-issue snapshot, plans priority-first cursor waves, dispatches bounded runs of the repository-only backlog-grooming.agent.md worker, validates each result, and retains a deterministic final aggregate.
2. Authenticated core publication: backlog-groom-publisher.yml starts after a completed orchestrator run or an authenticated manual replay, validates default-branch producer metadata and the aggregate artifact, then creates or replaces the compact trusted tracker body. This tracker update is the core delivery path.
3. Interactive review and writeback: GitHub Backlog Manager applies the reusable grooming instruction directly to ordinary issue inventory, supports maintainer review, and routes only explicitly approved non-closing Update or Comment operations through GitHub Backlog Executor with fresh-state validation.

Report history, the backlog-grooming-reports branch, and Pages deployment are a separate optional capability. They remain disabled unless the repository variable BACKLOG_GROOM_PUBLISH_GH_PAGES is exactly true, and their failure does not roll back or block core tracker publication.

Design Principles

• Every open non-pull-request issue is eligible for eventual assessment. Inactivity age, recent activity, labels, assignees, milestones, and ownership claims provide evidence or prioritization context; they do not exclude an issue.
• Issues are never automatically closed, edited, relabeled, assigned, or moved by the assessment worker.
• All issue content is treated as untrusted inert data during analysis.
• The repository-only worker has no tracker mutation authority. Deterministic workflows own validation, aggregation, provenance, digesting, artifacts, checkpoints, and publication.
• Duplicate and staleness signals identify candidates for qualitative assessment. Each assessed issue receives exactly one Match, Similar, Distinct, or Uncertain outcome with evidence and an advisory next step; final disposition remains a human decision.
• Deferred assessments use Uncertain similarity and disposition, include a non-empty deferral reason, and contain no definitive lineage claims.
• The adjacent single-issue Issue Triage Agent retains ownership of duplicate, stale, do-not-close, and related status-label judgments.
• One shared grooming instruction is the workflow-neutral policy authority. Backlog Manager applies it without depending on shard, cursor, artifact, safe-output, or publication contracts.
• Report history and Pages are optional/TBC operational surfaces, not prerequisites for core delivery.

Backlog Coverage

• Paginate the complete open-issue metadata inventory before selecting the deep-assessment cohort.
• Prioritize issues created, materially changed, assigned, or claimed since the previous successful run.
• Fill remaining capacity from a stable issue-number cursor and wrap after the end of the inventory so continuously open issues are not starved.
• Preserve the priority-first cursor candidate order through wave slicing, shard manifests, validation, checkpoints, aggregation, and final cursor derivation.
• Size deep assessment according to remaining workflow time and AI-credit budget, not a semantic age threshold or fixed issue-count limit.
• Record inventory size, priority and round-robin cohort counts, deferred count, stop reason, and next cursor on every run.

Core Tracker Contract

The orchestrator captures the trusted tracker state with the immutable snapshot. After the terminal aggregate is available, the publisher:

• authenticates the completed default-branch orchestrator run and derives source and artifact identity from run metadata;
• validates the final aggregate, predecessor digest, manifest digest, and artifact provenance;
• re-resolves the trusted tracker immediately before mutation and fails closed on ambiguity, stale state, changed identity, or an invalid predecessor;
• creates the bot-owned marker-bearing tracker when none exists, or replaces its compact body when one trusted tracker exists;
• publishes one idempotent aggregate per sweep and performs no per-candidate issue mutation.

The compact tracker body contains the run metadata and a scan-friendly issue index:

Issue	Disposition	Status	Recommended next step

Detailed evidence remains in the authenticated aggregate artifact. SARIF, Code Scanning upload, and security-events: write are not used.

Optional Report History and Pages

When BACKLOG_GROOM_PUBLISH_GH_PAGES is exactly true, separate optional jobs may:

• persist immutable detailed history to the backlog-grooming-reports branch;
• stage accessible report and history pages with explicit table captions and header scopes;
• dispatch the existing documentation deployment with the exact authenticated report-branch head SHA.

Branch names, stale report heads, unrelated commits, and unauthenticated producer runs are rejected. Optional history or deployment failure leaves the already-published core tracker intact and can be replayed independently after its prerequisite is corrected.

Interactive Writeback

• GitHub Backlog Manager recognizes groom, grooming, staleness, and backlog health requests and distinguishes recurring multi-issue grooming from closure-capable Triage and issue-scoped actions.
• Backlog Manager applies github-backlog-grooming.instructions.md directly and produces a compact issue index plus labeled per-issue details.
• Approved grooming handoffs contain at most one mutating operation per issue. Separately approved title and body fields are combined into one Update; Comment is an alternative operation.
• Grooming handoffs permit Update and Comment only. Close is prohibited.
• Every approved Update or Comment records the issue's RFC 3339 updated_at value.
• Immediately before mutation, the executor re-reads the issue and requires an exact updated_at match.
• A mismatch makes no mutation call, records Skipped: stale approval with expected and observed values, and requires rehydration and renewed approval.

Acceptance Criteria

• github-backlog-grooming.instructions.md is the reusable grooming-policy authority and defines evidence collection, qualitative outcomes, dispositions, compact reporting, deferred invariants, and approved writeback without workflow-only mechanics.
• backlog-grooming.agent.md remains repository-only, non-user-invocable, and read-only; it treats issue content as inert data and has no execution or tracker mutation authority.
• backlog-groom-orchestrator.yml starts assessment only on the first Monday of the month or by manual dispatch, captures one immutable complete inventory, and supports authenticated continuation.
• Priority selection plus cursor continuation and wraparound remain canonical through all waves and provide starvation-free progress across a 100-plus issue fixture.
• Every shard result is deterministically validated before aggregation, including conservative Deferred outcomes, lineage invariants, timestamps, provenance, and digest ownership.
• backlog-groom.lock.yml is generated with gh-aw v0.86.2 by bare gh aw compile, committed, and reproducible without drift alongside all other generated locks.
• backlog-groom-publisher.yml accepts only authenticated default-branch producer runs, derives artifact identity from run metadata, and rejects successful feature-branch or caller-forged replay inputs.
• The publisher re-resolves the trusted tracker immediately before mutation and enforces uniqueness, identity, predecessor, freshness, and idempotency checks.
• Core publication creates or replaces one compact bot-owned tracker body and does not depend on report history, Docusaurus, or Pages.
• BACKLOG_GROOM_PUBLISH_GH_PAGES == 'true' is the exact gate for report-history persistence, the backlog-grooming-reports branch, Pages staging, deployment dispatch, and their additional permissions.
• Optional publication accepts only the exact authenticated report-branch head SHA; branch names, stale heads, and unrelated commits are rejected.
• Optional history or Pages failure cannot roll back, overwrite, or block a successful core tracker publication.
• Generated report tables expose captions, column scopes, row scopes, and issue-specific disclosure names, with deterministic markup tests.
• No SARIF generation, Code Scanning upload, security-events: write, automatic candidate closure, label mutation, or per-candidate comment path exists in unattended execution.
• GitHub Backlog Manager applies the reusable policy directly and never requires the repository-only worker or its automation contract.
• Title and body changes require explicit per-field approval, approved fields are grouped into at most one Update per issue, and Comment remains an alternative operation; Close is prohibited.
• GitHub Backlog Executor validates exact updated_at immediately before an approved grooming Update or Comment and suppresses stale operations until renewed approval.
• Focused tests cover schedule and continuation trust, feature-branch rejection, multi-wave ordering and wraparound, Deferred validation parity, tracker freshness and ambiguity, output ownership, optional-mode isolation, accessible markup, manager routing, and stale executor preconditions.
• Workflow, generated-lock, plugin, extension, documentation, frontmatter, Markdown, and eval validation pass with the repository-only worker excluded from distribution and the reusable instruction retained.

Rollout

Core tracker delivery

• Confirm Copilot entitlement, repository token and workflow permissions, and capacity/cost approval.
• Run a manual smoke sweep and verify the immutable snapshot, accepted checkpoints, terminal aggregate, and compact trusted tracker body.
• Disable or roll back by disabling the orchestrator schedule or workflow while preserving the last trusted tracker and retained artifacts.

Optional report publication

• Keep BACKLOG_GROOM_PUBLISH_GH_PAGES unset for tracker-only operation.
• Separately approve report-branch ownership, Pages permissions, retention, and deployment cost before setting it to exact lowercase true.
• Roll back optional publication by unsetting or changing the variable; core tracker publication remains active.

Related

• PR feat(workflows): automate GitHub backlog grooming #2778 delivers the orchestrator, repository-only worker, deterministic validators and reducer, authenticated publisher, compact tracker, and optional report-history/Pages path.
• issue-triage.md and issue-triage.lock.yml provide the established gh-aw source and generated-lock implementation pattern.
• GitHub Backlog Manager and the shared planning and update instructions provide the interactive orchestration, approval, and execution contracts.
• issue-triage.agent.md retains ownership of duplicate, stale, and do-not-close label judgments; grooming does not apply these labels.