LearnNewsExamplesServices
Frontmatter
id11785
titleCodify ADR successor-risk and challenge classification
stateClosed
labels
documentationenhancementaiagent-task:reviewarchitecturemodel-experience
assigneesneo-gpt
createdAtMay 22, 2026, 10:56 PM
updatedAtMay 22, 2026, 11:50 PM
githubUrlhttps://github.com/neomjs/neo/issues/11785
authorneo-gpt
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 22, 2026, 11:50 PM

Codify ADR successor-risk and challenge classification

Closed v13.0.0/archive-v13-0-0-chunk-13 documentationenhancementaiagent-task:reviewarchitecturemodel-experience
neo-gpt
neo-gpt commented on May 22, 2026, 10:56 PM

Context

The operator surfaced a workflow gap while reviewing #11730 closeout and the #11731 / ADR 0014 discussion path: ADRs are accepted decision snapshots, not immutable law. Later V-B-A evidence, high-blast Discussions, or better repo reality can legitimately challenge an accepted ADR. Older tickets created before a later ADR are trickier: they may be superseded by the ADR rather than valid backlog work.

Existing substrate already covers adjacent pieces:

  • #10758 added the general age-aware successor-risk audit to ticket-intake.
  • #11370 / ADR 0005 added Decision Record plumbing for Ideation Sandbox graduations.
  • learn/agentos/decisions/0005-adr-at-graduation-for-ideation-sandbox.md makes ADRs the authority target when a graduation produced one.

This ticket adds the missing ADR-specific classifier so agents do not misread accepted ADRs as hard blockers, or old tickets as still-valid merely because they remain open.

Existing-Enforcement Sufficiency Audit

Current enforcement is close but incomplete. successor-risk-audit.md handles age and missing close-links, but not ADR chronology. ADR 0005 handles Discussion-origin Decision Record requirements, but not later ADR challenges or pre-ADR tickets superseded by accepted ADRs. Adding one focused reference payload plus map pointers is sufficient; a new top-level skill or AGENTS.md rule would be broader than the friction.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
ticket-intake ADR successor-risk gate #11785, #10758, ADR 0005 Classify ticket/ADR chronology before valid-as-written If ADR relation is unclear, halt for ADR challenge path instead of implementing adr-successor-risk-audit.md plus intake pointer Markdown grep for classifier and intake trigger
ticket-create Decision Record impact ADR 0005 plus #11785 Architecture/substrate tickets declare whether they create, depend on, amend, supersede, or challenge an ADR Mark not-applicable only with rationale ticket-create-workflow.md Fat Ticket field present
Ideation ADR challenge path Ideation Sandbox workflow plus ADR 0005 High-blast proposals conflicting with accepted ADRs choose keep/amend/supersede/retire If no consensus, remain Discussion-only ideation-sandbox-workflow.md Pointer to audit and decision outcomes
Epic review and resolution Epic lifecycle skills Check later ADRs before declaring work open, complete, or superseded If conflict remains, create/link missing ADR amendment ticket epic-review / epic-resolution workflow text One-line map pointers
PR lifecycle review PR body/review workflows PRs conflicting with accepted ADRs name ADR amendment/supersession or merge-order dependency Review blocks unresolved ADR conflict pull-request / pr-review workflow text One-line map pointers

The Problem

Current workflow text can catch stale tickets and Discussion-origin ADR requirements, but it does not explicitly classify the chronological relationship between a ticket/Discussion/PR and an accepted ADR:

  • A pre-ADR ticket may now be superseded-by-adr and should not be implemented as written.
  • A post-ADR proposal may be a valid adr-challenge if it brings fresh evidence and routes the decision change explicitly.
  • A PR can conflict with an accepted ADR and still be legitimate if the same lane updates, amends, or supersedes the ADR before merge.
  • Epic review and epic closeout need the same distinction: ADRs can close old premises, but later high-blast evidence can also reopen or reshape an ADR.

Architectural Reality

  • ticket-intake is the natural home for the detailed audit because it fires before agents accept existing work as executable.
  • ticket-create, ideation-sandbox, epic-review, epic-resolution, pr-review, and pull-request should get one-line map pointers where the lifecycle needs the same distinction.
  • AGENTS.md should not absorb the classifier unless a repeated failure proves it needs a turn-loaded trigger. The detailed mechanics belong in skill payloads per Progressive Disclosure and turn-memory pre-flight discipline.
  • ADR 0005 remains authoritative for Discussion graduation / Decision Record requirements; this ticket layers ADR chronology and challenge handling on top.

The Fix

Add an ADR Successor-Risk / Challenge Audit reference payload and wire it into the workflow maps that create, intake, review, or close architecture-bearing work.

Expected classifier vocabulary:

  • no-adr-impact
  • adr-aligned
  • superseded-by-adr
  • adr-challenge
  • adr-amendment-required
  • adr-authority-pending

The classifier must distinguish accepted ADRs as current authority from immutable blockers: the right response to new evidence is explicit amendment / supersession, not bypass.

Acceptance Criteria

  • ticket-intake references an ADR-specific successor-risk audit before accepting architecture/substrate tickets as valid-as-written.
  • The audit records artifact chronology against related ADR status/date and distinguishes pre-ADR supersession from post-ADR challenge.
  • The audit defines the classifier vocabulary and the evidence required for each verdict.
  • ticket-create prompts architecture/substrate tickets to declare Decision Record impact when they create, depend on, amend, supersede, or challenge an ADR.
  • ideation-sandbox routes high-blast proposals that conflict with accepted ADRs through explicit keep/amend/supersede/retire decision handling.
  • epic-review and epic-resolution check later ADRs before declaring work still open, complete, or superseded.
  • pr-review and/or pull-request include a one-line audit that PRs conflicting with accepted ADRs must include the ADR amendment/supersession path or name the merge-order dependency.
  • AGENTS.md remains unchanged unless the implementation discovers a concrete need for a turn-loaded pointer; if touched, it is one-line only.
  • The implementation preserves Map-vs-Atlas shape: detailed mechanics in a reference payload; maps only point to it.

Out of Scope

  • Rewriting existing ADR content.
  • Closing old tickets or epics as part of this patch.
  • Adding a new top-level skill.
  • Mechanical CI enforcement for ADR challenge compliance.
  • Treating ADRs as immutable blockers.

Avoided Traps

  • Do not duplicate the full classifier into every workflow map.
  • Do not reopen #10758; this is a narrower ADR-specific companion, not the generic age-aware audit.
  • Do not reopen #11370; this extends Decision Record handling after ADR 0005, not the original ADR-at-graduation implementation.
  • Do not add always-loaded AGENTS.md bloat for a lifecycle-specific classifier.
  • Do not classify old tickets as invalid by age alone; require ADR conflict evidence.

Related

Handoff Retrieval Hint: ADR successor risk challenge classifier ticket-intake Decision Record impact superseded by ADR amend supersede retire

tobiu referenced in commit b308cfe - "feat(agentos): codify ADR successor-risk workflow (#11785) (#11786) on May 22, 2026, 11:50 PM
tobiu closed this issue on May 22, 2026, 11:50 PM