Skip to content

adr queue stays silent when a proposed record has a deadline but no routing tier #111

Description

@mbeacom

Found while ratifying ADR-0022 in #110.

What happened

ADR-0022 was proposed for two days carrying blastRadius: cross-team and no review block at all. It appeared in adr queue like this:

0022 | tier=None | tierLabel=None | findings=[]
0023 | tier='async' | tierLabel='asynchronous human review' | findings=[]

(Reproduced by running adr queue --format json against the corpus at 7d0d1a3.)

No finding. The ARB operations queue listed a cross-team decision, could not determine its routing tier, and said nothing about it — so it was ratified without one. That is the ADR-0016 shape: "could not determine" rendering identically to "nothing to report."

Why it happened — the carve-out is applied more broadly than it was written

This is deliberate, not an oversight. packages/core/src/queue/kernel.ts:109-112:

// No item finding is generated for the absence of `review` alone (spec §Edge cases):
// tier-absent fires only when a `review` block is present but omits `tier`.
if (review !== undefined && review.tier == null) {

And the spec rule it cites is real — specs/007-arb-queue/spec.md:446:

review block and top-level reviewBy both absent on a proposed record: treated as not-queued. This is a valid, expected state for records that have been proposed but not yet entered into the review workflow. No item finding is generated for absence of review alone. If reviewBy is present without a review block, its explicit deadline still produces within-sla, due, or overdue under FR-005.

The carve-out has two conditions — review absent and reviewBy absent — and its justification is "not yet entered into the review workflow." The implementation checks only the first.

ADR-0022 had reviewBy: 2027-02-08 and no review block. A record carrying an explicit review deadline has entered the review workflow by any reading, and the spec's very next sentence confirms it anticipated that exact combination and gives it SLA treatment. So the silence rule was applied to a record it was never written to cover.

Worth noting specs/007-arb-queue/research.md:137 describes the finding more broadly still:

item.tier-absent | info | review.tier is absent (not set in frontmatter); routing tier cannot be determined

Suggested fix

Fire item.tier-absent when the tier cannot be determined and the record shows any sign of having entered review — i.e. review present, or reviewBy present. Keep the genuine carve-out: a proposed record with neither stays silent, exactly as the spec intends.

Roughly:

const enteredReview = review !== undefined || frontmatter.reviewBy != null;
if (enteredReview && review?.tier == null) { /* item.tier-absent */ }

Whether the spec's two-condition rule should be narrowed to match today's implementation instead is the alternative, but that seems backwards: a cross-team decision with a deadline and no tier is precisely what an operations queue exists to surface.

Notes

  • Severity stays info; this is a completeness signal, not a blocker.
  • Under ADR-0016 the new case must be observed failing before it counts. The natural fixture is the real one: a proposed record with reviewBy set and no review block, asserted to produce item.tier-absent.
  • specs/007-arb-queue/spec.md:446 and research.md:137 should end up saying the same thing as the code, whichever way this lands.
  • The corpus itself is now clean — ADR-0022 carries review.tier: arb as of chore(release): v0.5.0 — ratify ADR-0022 and ADR-0023, retire ADR-0021 #110 — so this is about the next record, not a live gap.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions