Skip to content
Spectral Codex
GitHub
Decisions

ADR-074: Retire scan pipeline

Context

Spectral is absorbing a strategic shift from sidecar measurement product to in-band executable decision-support compiler. World models compile to deployable decision modules per (org, domain, action); callers invoke POST /api/decide (or the MCP equivalent) and receive a binding { status, work_frame }. The world-model substrate carries forward; the scan-driven sidecar productization layer does not.

The scan pipeline is the largest single retirement thread under the shift: one Codex page-cluster, six ADRs, and ~40 Linear issues all dependent on it. The pipeline’s seven phases, its event-driven signal path to Worlds, its two-authority composite scoring, its failure-cluster signal stream, and the supporting LLM-provider adapter share a single rationale (sidecar observe-and-recommend product framing) and a single fate (retire wholesale).

This ADR consolidates that retirement into one supersession unit rather than chaining six independent supersession ADRs. Primitives retire with explicit fate; principles those primitives embodied are tracked separately so they can migrate to new mechanisms without smuggling stale design assumptions forward.

Decision

The scan pipeline retires wholesale. The six predecessor ADRs — ADR-008, ADR-017, ADR-020, ADR-023, ADR-056, ADR-057 — retire as a single unit. Each retired primitive’s principle is tracked to its migration target — none of the new mechanisms are renames of retired ones; conceptual resemblance does not imply structural inheritance.

What retires

The seven-phase scan pipeline (Observe → Detect → Cluster → Generate → Evaluate → Diagnose → Safety), its inputs (OTEL trace ingestion), its outputs (ChangeSet recommendations, VerdictResult advisory output), the two-authority scoring authority (world model + customer rubric → CompositeScore), the failure-cluster signal stream feeding operator triage, and the T3 memory routing path that fed world-model evolution from scan-derived observations. All of these dissolve together — no partial preservation.

Per-ADR disposition

ADR-008 — Pydantic AI for scan-pipeline LLM provider. Scope was “replace LiteLLMAdapter with PydanticAIAdapter for scan-pipeline LLM calls.” Scan-pipeline LLM calls do not exist under the shift. The LLM-provider boundary discipline (LLMProvider protocol, capability registry, cost-calculation fallback chain) is already governed by ADR-035 at the platform level and carries forward there. No new mechanism required.

ADR-017 — Event-driven signal path from Spectral to Worlds. Scope was the one-directional signal flow from spectral.platform to spectral.worlds, carrying scan-derived observations to Worlds for governed evolution. The signal source (scan execution outcomes) retires; the substrate (ADR-044 event substrate, ADR-065 producer-typed payload + consumer-ACL pattern) carries forward. Principle migration: the one-directional inter-context signal pattern is substrate; the new platform→worlds signal stream is the world agent’s pattern detection over approved operator overrides at decision time (per ADR-081), riding the same substrate.

ADR-020 — Tournament redesign with consistent composite metric. Scope was the tournament + verdict + system-card consistency contract around CompositeScore and VerdictResult. Tournament, verdict, CompositeScore, and VerdictResult retire wholesale. Principle migration: the Goodhart-defense principle (multi-axis evaluation as defense against single-metric gaming) migrates into the internal eval framework, which evaluates world-agent-generated code across predicate correctness, test fidelity, determinism, runtime safety, trace integrity, and readability (per ADR-081). New construct, not a rename.

ADR-023 — Holdout strategy. Scope was two-layer holdout (instance-level universal + rule-level conditional) with embedding-based sample hashing, layered on the customer-facing eval-set primitive. Customer-facing eval generation retires under the shift (see ADR-075 for eval-set retirement). Principle migration: the principle of distinguishing two purposes of holdout (instance-distribution-overfit detection vs rule-generalization detection) is sound and may resurface as a construct inside the internal eval framework; if it does, it will be authored fresh against the internal framework’s actual needs, not ported from this ADR.

ADR-056 — T3 memory → Worlds routing. Scope was the t3_memory_written event path from T3 owner to Worlds, with consumer-side relevance filtering and worlds-local projection. T3 memory itself (agent memory storage substrate per ADR-058) carries forward unchanged; the routing path that fed Worlds from scan-derived T3 memories retires because scan-derived T3 memories are gone. Principle migration: the semantic-coupling-stays-with-consumer principle and the opaque-payload-pattern principle are both substrate (governed by ADR-065). The new platform→worlds signal stream (override-pattern detection) uses these patterns; ADR-056’s specific payload shape and projection table do not.

ADR-057 — Failure cluster → rule candidate signal. Scope was the FailureClusterService + failure_cluster_detected event + platform.rule_candidates_pending operator triage queue, deriving rule-candidate signals from clustered scan failures. No scans → no failure clusters → entire mechanism retires. Principle migration: the pattern-detection-on-aggregated-signals shape (collect signal stream → detect emerging patterns → propose rule candidates → operator triage) migrates to the world agent’s override-pattern detection on approved operator overrides at decision time. Same shape (stream → pattern detection → candidate proposal → triage); new source (operator overrides instead of scan failures); new operator UX surface (per the eventual Spectral Agent reframe decision in Session 3c).

What does not retire

Substrate underneath the scan pipeline is well-isolated and carries forward without modification: ADR-044 event substrate, ADR-054 DLQ + retry semantics, ADR-058 agent memory storage, ADR-063 inter-context access pattern, ADR-064 notification-shaped reads, ADR-065 contract surface admission rules, ADR-070 mechanism-selection ladder. The new override-pattern signal stream is implemented on this substrate, not in place of it.

Alternatives considered

Piecemeal supersession (six independent ADRs). Rejected. The six predecessors share one rationale (sidecar observe-and-recommend) and one fate (retire under the in-band shift); splitting that into six supersession threads multiplies supersession-chain bookkeeping without adding clarity. A single consolidating ADR is the legible unit for a future reader trying to understand why this cluster left the system at once.

Status update on the existing ADRs without a new supersession ADR. Rejected. Status-line updates carry no rationale; future readers need the substantive “why” of the retirement and the principle-migration tracking. A new ADR is the canonical place for that material.

Wait until Session 3b’s anchor decisions (ADR-001 amendment + ADR-006 supersession) land first. Rejected. The retirement’s substantive grounding — the in-band decision-support shift and the fate of each retired primitive — is already settled. Waiting on anchor ADRs would cleanly cite “per ADR-001-amendment” instead, but that’s stylistic, not substantive — and drafting the anchors first would force them to carry retirement clauses for each of these six, cluttering positive-content ADRs with retirement bookkeeping. Retirements first keeps both kinds of ADRs focused.

Include ADR-018 (memory system — three tiers + world signal path) in this consolidation. Rejected. ADR-018’s supersession scope is surgical — the T3-into-worlds direction depends on the retired scan pipeline, but the T1/T2/T3 vocabulary survives in ADR-058 / ADR-059 unchanged. Folding ADR-018 here would muddy the consolidation with caveats about which parts survive. ADR-018 is handled separately in Session 3c.

Consequences

  • ADR-008, ADR-017, ADR-020, ADR-023, ADR-056, and ADR-057 are retired by this decision; those files were deleted and git history holds them.
  • Linear scope changes in Phase 4 follow naturally: ~40 scan-pipeline-cluster issues close with Fork-A-style closure-with-note (SPEC-240 + sub-issues, SPEC-241 + sub-issues, SPEC-352, SPEC-382, SPEC-383, SPEC-389–392, SPEC-406–409, SPEC-410, SPEC-411–413, SPEC-433, SPEC-472, and others in the scan-pipeline cluster).
  • Codex page retirements follow: system-design/platform/optimization-engine.mdx, get-started/scan-walkthrough.mdx, get-started/first-customer-walkthrough.mdx. Rewrites follow for welcome.mdx, how-spectral-works.mdx, system-design/index.mdx, reference/primitives.mdx, reference/domain-model.mdx, and the glossary cleanup.
  • The override-pattern detection mechanism (new platform→worlds signal stream) needs design work — captured as an open item and reserved for Session 3c (Spectral Agent reframe area) or its own follow-up.
  • The FailureClusterService codebase, the platform.rule_candidates_pending table, the OTEL trace ingestion path, the tournament and verdict engines, the rubric-scoring path, and the changeset PDF-export path become candidates for removal in Phase 4 build planning. Removal sequencing is build-plan territory, not ADR territory.
  • The Workflow Proof Report concept (carried as directional from spectral-dp) is a future product capability comparing proof-of-mechanism against a baseline on labeled cases; it does not revive any of the retired primitives. Its design space is open.