Canonadr

ADR-2026-09-01-02 — Reference Execution is the next design target

Status: Accepted — design target frozen
Date: 2026-09-01
Authority: Founder decision, 1 September 2026
Supersedes as next work: G-04 (Workbench terminology), explicitly deprioritized

The finding

The repository is further along than the gap register implied. The mechanisms largely exist. The
deeper issue is different:

The code has many of the mechanisms, but the Business Context → Work → Human/AI → Execution →
Outcome → Spine loop is not yet proven as one continuous, production-grade system.

Until that loop is traced end to end, the architecture is asserted rather than demonstrated.
That is the standard canon §28 already sets — "presence of code or a Wrangler manifest is not proof
of production readiness" — applied to the whole loop rather than to individual services.

The decision

Freeze the next design target as the SpineWorkspace Reference Execution — Business Context to
Verified Outcome.

The scenario: a customer renewal at risk

Chosen because it exercises every actor and every hop in the loop, and because it is a real
business outcome rather than a technical exercise:

Actor	Role in the trace
Human account owner	Owns the relationship, commercial judgment, escalation decision and final commitment.
Twin	Assembles CRM history, support issues, recent conversations, product usage, contract terms, prior commitments, account health, related internal decisions.
Research agent	Identifies churn signals, compares similar renewals, gathers evidence.
Workflow agent	Prepares follow-up steps, internal tasks, stakeholders, renewal plan.
Human approver	Authorizes a discount, contract change, executive escalation or sensitive communication where policy requires.
Hermes + capabilities	Executes only the approved actions.
Verification / reconciliation	Confirms the email was actually sent, records actually changed, tasks actually created, approvals actually captured — and writes the verified result back as continuity.

The scenario's value is that the interesting assertion is negative: a provider returning success
is not completion. The trace must show the difference between "the API said 200" and "the
renewal record actually changed."

One real business scenario, traced across every actual service:

Business Context → Human/AI Workbench → Work → Context Assembly
  → Twin/Agent → Capability Fabric → Governance → Hermes
  → MCP/Connector/External System → Outcome → Re-ingestion
  → Verification → Reconciliation → Business Context Spine
  → Projection → Workbench

Produced as three synchronized views of the same trace — matching the five-view separation in
canon §2A:

User Experience view
Platform Execution view
Agent Execution / OODA view

For every hop, the Platform Execution view records: stage · actual implementation · contract ·
authority · evidence.

This becomes the backbone of both the architecture documentation and the engineering verification
strategy.

G-04 is explicitly not next. A terminology rename is too mechanical to lead with while the
loop is unproven.

Supporting decisions frozen with it

Three pipelines, not one

The word Pipeline is used inconsistently across the repository — sometimes ingestion, sometimes
memory promotion, sometimes execution closure. These share infrastructure but must not be
conceptually collapsed:

Pipeline	Flow
A — Context	Source → Load → Normalize → Resolve → Contextualize → Governed Spine Write
B — Work / Execution	Intent → Context → Work → Plan → Capability → Governance → Execute → Outcome → Evidence → Verify → Reconcile → Spine
C — Continuity	Outcome → Interpretation → Memory/Continuity → Projection Refresh → Next Work

Spine Cache is never truth

Cache accelerates access to Spine truth; cache never becomes canonical truth.

Must be proven for invalidation, freshness, tenant isolation, authorization boundary, stale-context
handling, and write-through/write-back rules if any exist.

Governance covers AI planning, not only execution

AI proposes → Plan → Capability resolution → Governance
  → Human approval when required → Execution

Not AI thinks → AI decides → AI executes. This is what "Humans govern. AI helps." means
operationally. The existing Capability → Governance → Hermes separation is among the strongest
parts of the repository and is not to be redesigned — it is to be verified across the full AI
lifecycle.

OODA is internal, but must be real

The user never needs to understand OODA. The platform does. OODA, context assembly, model routing,
ADK, MCP, capability resolution, orchestration and reconciliation are implementation machinery,
not product vocabulary.

One channel is a coordination fabric

Chat, Work, Email, Notification and UI are surfaces over one coordination fabric. The surface
changes; the underlying context and work identity remain continuous.

Agents collaborate through shared state

Spine Agents coordinate through Shared Work + Business Context + Evidence — never
Agent A → explain everything → Agent B.

Sequencing constraint on agents

Do not build more agent functionality until the persistence authority for AI Continuity is
decided (G-10).

Otherwise Spine Agents get designed around a memory abstraction whose durability is undefined.

Priority stack

Priority	Area	Why
P0	Business Context end-to-end trace	Everything depends on it
P0	Platform execution reference trace	Proves the architecture actually executes
P0	Pipeline / closure E2E	Proves the Spine actually becomes current truth
P0	AI Continuity persistence decision (`G-10`)	Required before mature agents
P1	Personal Contextual Spine (`G-02`)	Required by the canonical participant model
P1	Spine Agent first-class model (`G-05`)	Required for the AI Workbench
P1	Discovery → Activation → runtime (`G-07`)	Completes the platform control plane
P1	MCP Pool routing proof (`Q-2`)	Prevents accidental data-plane violation
P1	One Auth decision (`Q-1`)	Removes identity ambiguity
P1	Projection / Active Context contract (`G-12`)	Makes different experiences coherent
P2	Spine Cache contract	Performance layer without truth ambiguity
P2	Work / coordination fabric	Makes human-AI collaboration concrete
P2	Mintlify restructuring	Presents the architecture cleanly
P2	Codebase terminology cleanup (`G-04`)	Prevents future drift

Documentation information architecture

Mintlify must not expose repository topology. Product story first, machinery after:

01 What is SpineWorkspace?   02 Business Context        03 Human Workbench
04 AI Workbench              05 Twin & Spine Agents     06 Work
07 Pipeline                  08 Platform Execution      09 Agent Execution
10 Integrations & MCP        11 Capability Fabric       12 Governance
13 Spine & Memory            14 Projection & Context    15 Execution Closure
16 Architecture              17 Developer Reference

Consequences

The gap register's ranking is superseded by the priority stack above. Individual gap entries
remain accurate as measurements; their ordering now follows this ADR.
17-IMPLEMENTATION-ALIGNMENT-AND-GAP-REGISTER.md is stamped against commit 0ebc224c, which is
stale — origin/main has since moved to e167ede1. Per this tree's own rule, an alignment
document is void without a current stamp. It must be re-surveyed before the Reference Execution
work uses it as a baseline.
The Reference Execution is a verification artifact, not a redesign. Canon already supplies the
principles and separations; this proves the loop and closes the gaps around continuity, agents,
activation, identity and routing.