Skip to content

feat(ci): implement ADR-0022 issue traceability on pull requests #595

Description

@ss-o

Summary

decisions/0022-issue-traceability-on-pull-requests.md was accepted on
2026-09-02 in #594. This tracks its six migration steps. The record is the
decision; this is the work.

The ordering matters and is part of the decision: the pull-request check lands
and is observed before the branch pattern relaxes. Doing it the other way
leaves a window with neither control active, which is the state ADR-0022 exists
to end.

Steps

  1. Agree the exemption label and record it in runbooks/labels.md. It
    covers work with no owning issue: gitlink and submodule reconciliation, and
    routine dependency updates. ADR-0022 makes applying it a maintainer
    decision, so an agent may propose one but never applies it on its own
    authority.
  2. Implement the pull-request traceability check in
    .github/workflows/commit-lint.yml. It passes when the pull request closes
    an issue, references one, or carries the exemption label, and it reports
    which of the three applied so an exemption is visible in review rather than
    silent.
  3. Verify it on a real pull request. runbooks/branch-protection.md notes
    that GitHub only accepts status-check contexts it has already observed, so
    this has to precede step 4.
  4. Register the new context in the main ruleset (19646747) alongside
    Validate Commits, Validate PR Title, and Validate Branch Name.
  5. Relax Validate Branch Name to the shape check ADR-0022 defines, here
    and in z-shell/zi, which carries the same job with its patterns inlined.
    Both must move together or the two copies drift again.
  6. Add the ADR-0019 pointer recording that its branch-naming clause is
    amended by ADR-0022, and update AGENTS.md where it describes issue-linked
    branch naming.

Notes

Step 2 lands in the same file as #592, which proposes test coverage for the
commit-lint patterns. Doing #592 first, or as part of step 2, is probably
cheaper than doing it afterwards: three defects have shipped in that file
(#575, the empty-pattern trap found during #586, and #587), and this adds a
fourth policy predicate to it.

#587 is an open correctness defect in the same workflow and is independent of
this work.

Follows #593 and #594.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:ciContinuous integration or GitHub Actions work.type:featureA request for new behavior or capability.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions