# Backlog Triage Dependency Supersession Workflow V01 Issue: [#277](https://github.com/pinklon/ai-capability-discipline/issues/277) Branch: `codex/backlog-triage-dependency-supersession-workflow-v01` ## Governance Boundary This artifact is repo operating-model guidance for GitHub backlog hygiene. It is not approved package authority, policy, product doctrine, runtime behavior, source approval, source activation, implementation authorization, issue closure evidence, or production approval. This workflow does not close, reopen, approve, supersede, relabel, prioritize, or replace any GitHub issue by itself. It creates a repeatable triage method for Codex, Claude Code, Cursor, local IDE agents, GitHub-native agents, and future agent tooling. Any material issue-state change still requires the approval gates below. ## Backlog Triage Agent The Backlog Triage Agent is a tool-agnostic operating-model role. It may be performed by a human maintainer, Codex, Claude Code, Cursor, a local IDE agent, a GitHub-native agent, or a future agent tool if the same evidence and approval boundaries are followed. Responsibilities: - scans open issues and recent PRs - groups related issues - detects duplicate or near-duplicate issues - detects superseded issues - detects stale acceptance criteria - detects missing or weak labels - detects missing dependencies - detects parent, child, and epic relationships - recommends next-best execution order - identifies blocked, ready, deferred, and needs-clarification issues - proposes issue updates but does not apply destructive changes without approval ## When Triage Must Run Run backlog triage: - after a burst of issue creation - after source activation, source rollback, or current/public source governance work - after architecture, operating-model, documentation strategy, or product-posture changes - before starting a new development batch - before selecting the next Codex, Claude Code, Cursor, IDE-agent, or GitHub-native agent ticket - before closing a parent issue or epic - before marking issues as superseded, duplicate, not planned, or completed - when an active ticket changes execution order for runtime, source, access, provider, package, or production work For issue bursts, triage must run before new issues are treated as ready for execution. For runtime-sensitive lanes, triage must happen before work starts, not as a cleanup step after code lands. ## Issue Creation Completeness Issue creation is not complete unless the issue has: - clear title - clear scope - explicit acceptance criteria - correct labels from the existing repo taxonomy - dependency notes where applicable - parent or child relationship where applicable - supersession notes where applicable - clear close semantics - clear non-goals - owner or execution lane when applicable If any item is missing, the issue remains `needs-clarification` for triage purposes even if it has enough prose for discussion. Child issue creation is incomplete unless required labels are present at creation or immediately repaired before implementation starts and before any PR is opened. A draft PR does not make an unlabeled child issue acceptable. The #350 child issue was initially created without required labels and then repaired after creation; that is the defect pattern this workflow now treats as a process defect, not normal cleanup. Codex-ready tickets must include a `## Required Labels` section with exact labels to apply from the existing repo taxonomy. Generic label families such as `priority:`, `area:`, and `type:` are placeholders only and do not satisfy execution readiness for a concrete ticket. ## Label Taxonomy Requirements Labels are metadata, not approval. Correct labeling makes work discoverable and sequenceable, but it does not authorize implementation, source activation, package authority, issue closure, or production changes. Label rules: - Use existing repository labels first. - Do not invent new labels unless explicitly approved. - Refuse or stop on invented labels until the owner approves taxonomy expansion. - Record whether labels were present at creation, whether label repair was needed, and who or what performed the repair. - Apply `enhancement`, `bug`, `documentation`, `governance`, `validation`, or equivalent top-level labels when they are supported by issue evidence. - Apply the most specific `area:*` labels supported by the issue title and body. - Apply the most specific `type:*` labels supported by the issue title and body. - Apply a priority label only when the issue itself or an owner decision supports that priority. - Do not remove or replace priority labels without explicit approval. - Do not apply resolution labels to open issues unless the owner explicitly approves that state. - Record taxonomy gaps in a triage report instead of creating labels. Recommended label evidence: | Label family | Evidence needed | |---|---| | `priority:*` | owner priority, issue title, explicit sequencing statement, or parent issue requirement | | `area:*` | repo surface, product surface, runtime lane, doc lane, validation lane, or source-governance lane named in the issue | | `type:*` | work shape such as architecture, governance, operations, UX, CI, QA, documentation, release, or spike | | `resolution:*` | owner-approved final disposition only | ## Triage Inputs Use deterministic inputs whenever possible: - open issue inventory - recently closed issue inventory - recent merged PR inventory - current open PR inventory - live label taxonomy - relevant product architecture notes - validation receipts - runtime and source-governance receipts when the issue touches runtime, current/public sources, Access, provider behavior, package authority, or production readiness For GitHub-backed runs, capture the command, timestamp, and query scope in the receipt or triage report. For tool-native runs without GitHub CLI access, capture equivalent issue, PR, label, and receipt evidence. ## Detection Model ### Duplicate Detection Flag a duplicate candidate when two issues share the same intended outcome, acceptance criteria, target files, runtime surface, or source-governance decision. Do not close a duplicate candidate automatically. Record: - candidate duplicate issue - possible canonical issue - matching evidence - material differences - recommended owner decision ### Dependency Detection Flag a dependency when an issue cannot be safely executed until another decision, artifact, validation gate, or runtime boundary is settled. Dependency examples: - source activation depends on owner authorization and runtime smoke gates - admin or upload work depends on access posture and data-boundary decisions - implementation depends on architecture sequencing - issue closure depends on validation receipt review - source-profile work depends on parent source-governance sequencing Dependency notes must state whether the dependency is blocking, sequencing, informational, or owner-decision based. ### Supersession Detection Flag a supersession candidate when later work appears to replace, narrow, complete, or invalidate the issue. Supersession evidence can include: - a merged PR that implements the same scope - a newer issue that explicitly narrows the work - a receipt showing the original behavior changed - an architecture decision that makes the original approach obsolete - a production posture change that invalidates an older deployment target Supersession is only a recommendation until explicitly approved. The triage report must avoid wording that treats the issue as already closed or obsolete. ### Stale Issue Detection Flag a stale issue when its acceptance criteria no longer match repo reality. Common stale signals: - obsolete domain, deployment, or hosting target - references to old package names, release versions, source sets, or artifact paths - acceptance criteria already covered by later validation - priority label no longer aligned with current execution sequence - issue still open after a linked PR merged but no residual work is clear Stale does not mean invalid. It means the issue needs owner review, re-scope, closure, or replacement. ### Blocked, Ready, Deferred, And Needs-Clarification Classification Classify every reviewed issue: | Classification | Meaning | |---|---| | `ready` | scope, labels, acceptance criteria, dependencies, and non-goals are clear enough to execute | | `blocked` | a prerequisite decision, dependency, validation gate, or owner approval is missing | | `deferred` | the issue is valid but should wait because sequence, risk, or priority points elsewhere | | `needs-clarification` | required completeness fields are missing or ambiguous | If an issue touches runtime, source sets, Access/WAF, provider/model config, package authority, or production readiness, classify it as blocked unless those boundaries and approval gates are explicit. ## Parent, Child, And Epic Grouping Recommend parent, child, or epic grouping when: - multiple child issues implement a staged parent objective - a parent issue should remain open while child issue work lands - a child issue would accidentally close a parent issue if close semantics are unclear - old implementation tickets should be grouped under a current operating-model or source-governance epic Every parent/child recommendation must state close semantics: - closes child only - references parent without closing - closes parent only after all named child acceptance criteria pass - remains planning-only and requires owner approval before closure ## Execution Sequencing The Backlog Triage Agent recommends execution order but does not own execution order. Recommendations must include: - next-best issue - prerequisite issues or decisions - risks if executed out of order - issues that should not start yet - active runtime, source, access, provider, and package-authority boundaries Do not use backlog triage to start OWASP substantive extraction, create additional source-profile child issues, activate CISA / NSA / NCSC in Production, mutate Preview or Production source sets, change Access/WAF, change provider/model config, change package authority, or add browser-side provider or current-source calls. ## Approval Boundaries Allowed without explicit approval: - identify missing labels - identify possible duplicates - identify dependency suggestions - identify supersession candidates - produce triage report - recommend issue updates Requires explicit approval: - closing issues - changing issue state - changing issue body materially - changing priority labels - adding or removing labels in bulk - creating new parent epics - marking issues as superseded - changing execution sequence in a way that affects active runtime work When in doubt, produce a candidate update plan and stop before mutation. ## Suggested Triage Report Format Each triage report should include: - input inventory and timestamp - issue set reviewed - label taxonomy source - duplicate candidates - dependency map - supersession candidates - stale issue candidates - blocked, ready, deferred, and needs-clarification table - parent, child, and epic recommendations - recommended next execution order - updates allowed without approval - updates requiring approval - non-goals and runtime/source/access/provider/package boundaries ## Discoverability And Validation This workflow is linked from the product architecture index because existing backlog governance artifacts live there and because the folder boundary states that these notes do not create runtime behavior or production approval. Issue creation can use `.github/ISSUE_TEMPLATE/backlog_work_item.md` to capture scope, acceptance criteria, labels, dependency notes, parent/child relationships, supersession notes, close semantics, non-goals, and owner or execution lane. `validation/scripts/check_backlog_triage_workflow.py` keeps the workflow, issue template, and product-architecture links discoverable. It validates presence of the role, completeness rules, detection model, classification terms, approval boundaries, non-goals, and receipt anchors. `validation/scripts/check_backlog_label_enforcement_ticket_compliance.py` validates that templates, docs, deterministic fixtures, Codex ceremony output, and PR closeout language preserve the Required Labels rule, no-new-label rule, #350 incident lesson, child issue label-state reporting, and `codex-automerge` refusal posture without live GitHub API calls. ## Explicit Non-Goals - Do not mutate Preview runtime source set. - Do not mutate Production runtime source set. - Do not enable new sources. - Do not activate CISA / NSA / NCSC in Production. - Do not change Access/WAF. - Do not change provider/model config. - Do not change package authority. - Do not add browser-side provider calls. - Do not add browser-side current-source calls. - Do not close, relabel, or supersede issues in bulk without explicit approval. - Do not invent new labels unless explicitly approved. - Do not create a giant backlog cleanup PR that mixes unrelated issue changes.