Explainability

Spectral returns binding decisions. The customer’s agent acts on the work frame Spectral sent back. Explainability is what lets the customer audit any decision after the fact, understand why a YELLOW or RED came back, and verify that the system is doing what the world model says it should.

Every decision must be backed by reasoning. Every rule match must be traceable. Every deployed module must be inspectable.

Why explainability is non-negotiable

Decisions are binding by construction (per ADR-077). The caller’s agent receives a work_frame it cannot override; the operator must be able to defend any decision the system produced. Three audiences depend on this:

• The customer’s reviewer needs to understand why a specific decision came back the way it did. Did a T1 rule fire? Which applies_when filter let this rule into the evaluation? What was the authenticated_caller? Did a predicate error short-circuit?
• The operator needs to understand the population of decisions in a deployment — status distribution, override-pattern signals from customers, regions of the input space that reach YELLOW more often than expected.
• External auditors need to verify that the system’s claims about methodology hold: rules trace to authoritative sources, content hashes verify, version pinning is honored.

Without explainability, a binding decision system is asking for blind trust. With it, the system is an artifact whose every output is defensible from inputs to authority to code.

The atomic unit — a decision

Every /decide invocation produces a fully-structured decision. The response payload returned to the caller carries three components per ADR-077 D3:

• status — the audit-grade headline. One of GREEN / GREEN-SKIP / YELLOW / RED.
• work_frame — the structured contract bounding the agent’s behavior after receipt. Fields: mode, next_action, allowed_actions, forbidden_actions, required_output, missing_evidence, next_human_owner. Names explicit anti-patterns by construction (llm_policy_decision: false; forbidden_actions includes "reinterpret_policy" and "override_spectral").
• decision_metadata — the structured trace: which rules matched, suppression chain, aggregation outcome, predicate traces, errored predicates, request ID, request time.

Decision metadata is enough — on its own, returned synchronously to the caller — to explain a single decision without leaving the response payload. The richer trace lives in the audit chain (below).

Where explainability lives

Five surfaces, each backed by the same substrate.

Audit chain (substrate)

Every decision the platform serves writes a structured record to the deployment-scoped audit chain per ADR-076 D3. Each entry captures the full decision trace (request context, matched rules, suppression chain, aggregation outcome, predicate traces, errored predicates, work frame, response). The audit chain is the source of truth for every higher-level view; retention discipline anchors on ADR-042 and is catalogued in Retention Registry.

Per-decision inspection (Customer Dashboard)

The customer’s primary inspection surface. The Customer Dashboard Decisions tab is a live feed filterable by status; each decision’s detail panel shows the three-source request context, the rule evaluation trace, the work-frame contract, and predicate-level trace for errored or matched rules. The dashboard reads audit-chain entries through api’s surviving routes per ADR-077 D6.

Customers can flag a decision for operator review or mark it noteworthy from this panel; the override-pattern signal routes to the operator side per the Customer Dashboard interaction primitives.

Per-rule provenance (Ruleset Card)

Every rule in a world-model version carries two-dimensional provenance:

• Authoritative source dimension — statute, regulatory guidance, scholarly publication. Operator-authored at rule-candidate time; verified at the conformity gate; preserved across restatement.
• Code dimension — the generated predicate’s lineage to the natural-language rule it was generated from. Regenerated when the natural-language form or configuration dependencies change; verified at the implementation-readiness gate.

The Ruleset Card (the customer-facing display name for the World Model Card) is the version-scoped methodology disclosure: scope, sources, decision log, authority basis, two-dimensional provenance summary. Operator-authored per ADR-082 D2. Customers reach the Ruleset Card for any deployed version from the version-history timeline on the dashboard’s Trust tab — a version-scoped surface, not a live tab. The active ruleset itself, rule by rule, is on the dashboard’s “The rules” tab.

Population view (System Card)

The deployment-scoped operational record per ADR-082 D3: totals, p50/p95/p99 latency, four-state status distribution, per-action breakdown, and the version-history timeline. Customer-surfaced through the dashboard’s Trust tab. Operators see the same data through their own Operations-app view alongside aggregate override-pattern signals.

Natural-language walkthrough (post-release)

Just after v0 ships, the World Agent gains a customer-facing explain-this-decision chat affordance per ADR-081 D5: chat surface keyed to the customer’s current (org_id, domain_id) world, riding through the World Agent with a read-only tool subset. The agent walks through rule traces, decision metadata, and Ruleset Card methodology disclosure in natural language.

The deterministic surfaces (response payload, audit chain, dashboard inspection, cards) ship at v0. The chat affordance is the legibility convenience layered on top — it adds nothing the deterministic surfaces don’t already cover; it just narrates them. See Customer Dashboard — Post-release.

What the customer cannot do

The dashboard explainability surface is read-only by design. The customer:

• Cannot override a decision — decisions are binding per ADR-077.
• Cannot edit rules — authoring is operator-side; world-model evolution flows through the Evolution Loop.
• Cannot approve modules — operator approval is part of module integrity per ADR-080 D3.

What the customer can do is flag a decision for operator review or mark it noteworthy. Both primitives route to the operator side as override-pattern signals. The pattern enforces authority-direction: customers consume binding decisions and surface signals about them; operators read the signals as evidence during evolution-loop work.

What’s next

• Customer Dashboard — the v0 inspection surface that consumes audit-chain entries.
• Decision Execution — the five-phase decomposition of every decision the audit chain records.
• System Card — methodology disclosure (World Model Card + System Card) per ADR-082.
• Retention Registry — retention discipline for audit-chain entries, decision records, override-pattern signals, and the System Card snapshot.