Skip to content

docs(adr): record check precision defaults in an ADR that amends ADR 0003 #8537

Closed

Description

@kyle-sexton

Refs: #7572

Agent Brief

Type: Task
Summary: Write one new ADR that amends ADR 0003 with the precision defaults for checks: zero effective false positives for a blocking check, under 10% for an advisory one, plus the exception rules.

Current behavior:

  • docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md says a guard earns default-on by measured precision but states no number; its reference guard shipped at 57% precision (docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md:48-49).
  • No ADR carries an Amends: line for ADR 0003 on main. The newest ADR is docs/adr/0079-dispatch-tagged-phase-reviews-to-quality-gate-at-the-phase-boundary.md.
  • House style for the line is - Amends: [ADR 0049](0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md), in the header list (docs/adr/0074-review-risky-dependabot-updates-in-a-model-job-and-act-in-a-scripted-job.md:7).
  • feedback.disable_not_useful_ratio and exceptions.max_days exist only in the decision record: no file under docs, plugins or scripts mentions disable_not_useful or max_days.

Desired behavior:

  • A new docs/adr/NNNN-<kebab-title>.md, numbered one above the highest on main when the lane runs, in the shape of docs/adr/0079-dispatch-tagged-phase-reviews-to-quality-gate-at-the-phase-boundary.md (title, - Status: accepted, - Date:, Context, Decision, Consequences), written the way /architecture:record-decision writes one.
  • Its header list carries - Amends: [ADR 0003](0003-verification-guards-earn-default-on-by-measured-precision.md).
  • Decision text:
    • A blocking check ships with 0 effective false positives on its corpus.
    • An advisory check stays under 10% false positives; the 10% is named as a corpus-precision proxy, not a measured per-guard rate.
    • feedback.disable_not_useful_ratio is not adopted until guardrails: grade every default-on guard's precision from the per-session hook event log (ADR 0003) #3756 produces a per-guard signal.
    • Exceptions expire after 90 days by default, as a team setting.
    • Break glass is an inline exception that carries a reason, an expiry and a person's approval.
    • Existing guards keep their recorded justification; nothing is re-graded by this ADR.
  • Consequences name the enforcement ladder's guardrail criterion (docs/conventions/enforcement-ladder/README.md) as the reader of these numbers, and guardrails: grade every default-on guard's precision from the per-session hook event log (ADR 0003) #3756 as the open work that grades guards.

Key interfaces:

  • docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md (read; not edited).
  • scripts/check-adr-numbers.sh (the number must not collide).

Acceptance criteria:

  • Exactly one file under docs/adr has an Amends: line naming ADR 0003, the new ADR.
  • The new ADR contains 0 effective false positives, 10%, 90 days and #3756.
  • The PR's CI runs scripts/check-adr-numbers.sh --check (lint-repo) and it passes.
  • The diff touches only docs/adr/. The PR's CI checks changelog fragments and passes with no fragment, because no plugin's shipped files change.
  • CI's lint-repo job (which runs check-adr-numbers.sh and the markdown lint) passes.

Out of scope:

  • Editing ADR 0003 itself or any guard.
  • Adding the 90-day exception setting to a plugin; this ADR records the default only.
  • The ladder's guardrail criterion text (sibling slice ladder-v2).

Origin:

Do not run with: none. No other open slice edits docs/adr/ for ADR 0003; two ADR-writing PRs racing for one number is caught by check-adr-numbers.sh.


Slice of #7572, drafted by the Issue Triage session from the thread's recorded decisions.

Activity

  1. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Oct 20, 2026
  2. added theissue type on Oct 20, 2026
  3. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 20, 2026
  4. kyle-sexton commented on Oct 21, 2026

    @kyle-sexton
    MemberAuthor

    Decision recorded. The owner answered in the poteto-review session (2026-10-21, interview round 65, Q664, "Go with recommendations."): ADR 0080 keeps its rule that a break-glass exception filed against a blocking check counts as an effective false positive, so a blocking check that needs one misses its 0 bar. This matches the Tricorder paper's definition, "any report from the tool where a user chooses not to take action to resolve the report" (https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/43322.pdf). The ADR as merged in #8707 already says this; no change follows.

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

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions