Skip to main content
Status: draft v0.1 — body sourced from TriGraph spec entity. Docs-mirror file added by docs lane to surface ratified specs that lacked an on-disk mirror.

​
SPEC-083: ADR Rationalization Metadata and Ingestion Pipeline

​
SPEC-083 v0.1 — ADR Rationalization Metadata and Ingestion Pipeline

​
Status

Draft implementation spec for Plan #12.

​
Context

Plan #12 requires two capabilities:
  1. One-time ADR rationalization over the existing ADR corpus.
  2. Standing ingestion for every new ADR so recall does not drift back into stale, unclassified history.
The ADR ledger remains append-only. Rationalization data is derived metadata and review state.

​
Requirements

​
R1 — ADR Metadata

Each ADR row exposes derived rationalization fields:
  • current_state: active_current, active_partial, superseded, historical_context, proposed_backlog, draft_pending, probe_invalid, conflict_review.
  • doctrine_cluster: stable slug for the current doctrine cluster.
  • rationalization_state: ingested_indexed, needs_supersession_review, needs_conflict_review, needs_scope_review, needs_enforcement_review, doctrine_updated.
  • rationalization: JSON object for detected edges, authority flags, review reasons, source refs, and ingestion diagnostics.

​
R2 — Standing Ingestion

When an ADR is created or updated, Prism classifies it automatically without making authority-changing decisions. Automatic work:
  • classify non-binding proposed/draft/probe states
  • infer doctrine cluster
  • detect explicit supersedes ADR-# references
  • flag candidate conflict/scope/enforcement review based on text markers
  • write rationalization metadata
  • include metadata in semantic embedding content
Review-gated work:
  • accepted ADR supersession
  • conflict resolution
  • org/global promotion
  • enforcement strength changes
  • marking older accepted ADRs superseded

​
R3 — API Compatibility

Existing callers of /api/v1/adrs and prism_decide keep working. New metadata fields are optional on create/update and included in AdrOut.

​
R4 — Tests

Add focused tests for:
  • proposed ADRs become non-binding proposed_backlog
  • probe ADRs become probe_invalid
  • explicit supersession references create review-gated candidate edges
  • accepted ADRs with hard-enforcement language require enforcement review
  • metadata appears in ADR response schemas

​
Non-Goals

  • No deletion or rewriting of ADR bodies.
  • No automatic status mutation of older ADRs.
  • No full doctrine artifact type yet.
  • No cross-project/global promotion in this slice.

​
Acceptance

  • New ADR ingestion metadata is generated on create.
  • Metadata can be patched manually for reviewed cases.
  • Recall embedding content includes current_state, doctrine_cluster, rationalization_state, and edge hints.
  • Tests pass for service-level ingestion behavior.
Last modified on May 9, 2026