{"slug":"canonical/adr/ADR-2026-09-01-02-reference-execution-is-the-next-design-target","title":"ADR-2026-09-01-02 — Reference Execution is the next design target","section":"canonical","sectionLabel":"Canon","status":"canon","type":"adr","path":"canonical/adr/ADR-2026-09-01-02-reference-execution-is-the-next-design-target.md","bytes":8241,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Accepted — design target frozen\n**Date:** 2026-09-01\n**Authority:** Founder decision, 1 September 2026\n**Supersedes as next work:** `G-04` (Workbench terminology), explicitly deprioritized\n\n## The finding\n\nThe repository is further along than the gap register implied. The mechanisms largely exist. The\ndeeper issue is different:\n\n> **The code has many of the mechanisms, but the Business Context → Work → Human/AI → Execution →\n> Outcome → Spine loop is not yet proven as one continuous, production-grade system.**\n\nUntil that loop is traced end to end, **the architecture is asserted rather than demonstrated.**\nThat is the standard canon §28 already sets — *\"presence of code or a Wrangler manifest is not proof\nof production readiness\"* — applied to the whole loop rather than to individual services.\n\n## The decision\n\n**Freeze the next design target as the SpineWorkspace Reference Execution — Business Context to\nVerified Outcome.**\n\n### The scenario: a customer renewal at risk\n\nChosen because it exercises every actor and every hop in the loop, and because it is a real\nbusiness outcome rather than a technical exercise:\n\n| Actor | Role in the trace |\n|---|---|\n| **Human account owner** | Owns the relationship, commercial judgment, escalation decision and final commitment. |\n| **Twin** | Assembles CRM history, support issues, recent conversations, product usage, contract terms, prior commitments, account health, related internal decisions. |\n| **Research agent** | Identifies churn signals, compares similar renewals, gathers evidence. |\n| **Workflow agent** | Prepares follow-up steps, internal tasks, stakeholders, renewal plan. |\n| **Human approver** | Authorizes a discount, contract change, executive escalation or sensitive communication where policy requires. |\n| **Hermes + capabilities** | Executes only the approved actions. |\n| **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. |\n\nThe scenario's value is that the *interesting* assertion is negative: a provider returning success\nis **not** completion. The trace must show the difference between \"the API said 200\" and \"the\nrenewal record actually changed.\"\n\nOne real business scenario, traced across every actual service:\n\n```text\nBusiness Context → Human/AI Workbench → Work → Context Assembly\n  → Twin/Agent → Capability Fabric → Governance → Hermes\n  → MCP/Connector/External System → Outcome → Re-ingestion\n  → Verification → Reconciliation → Business Context Spine\n  → Projection → Workbench\n```\n\nProduced as **three synchronized views of the same trace** — matching the five-view separation in\ncanon §2A:\n\n1. **User Experience view**\n2. **Platform Execution view**\n3. **Agent Execution / OODA view**\n\nFor every hop, the Platform Execution view records: stage · actual implementation · contract ·\nauthority · evidence.\n\nThis becomes the backbone of both the architecture documentation and the engineering verification\nstrategy.\n\n**`G-04` is explicitly not next.** A terminology rename is too mechanical to lead with while the\nloop is unproven.\n\n## Supporting decisions frozen with it\n\n### Three pipelines, not one\n\nThe word *Pipeline* is used inconsistently across the repository — sometimes ingestion, sometimes\nmemory promotion, sometimes execution closure. These share infrastructure but **must not be\nconceptually collapsed**:\n\n| Pipeline | Flow |\n|---|---|\n| **A — Context** | Source → Load → Normalize → Resolve → Contextualize → Governed Spine Write |\n| **B — Work / Execution** | Intent → Context → Work → Plan → Capability → Governance → Execute → Outcome → Evidence → Verify → Reconcile → Spine |\n| **C — Continuity** | Outcome → Interpretation → Memory/Continuity → Projection Refresh → Next Work |\n\n### Spine Cache is never truth\n\n> **Cache accelerates access to Spine truth; cache never becomes canonical truth.**\n\nMust be proven for invalidation, freshness, tenant isolation, authorization boundary, stale-context\nhandling, and write-through/write-back rules if any exist.\n\n### Governance covers AI planning, not only execution\n\n```text\nAI proposes → Plan → Capability resolution → Governance\n  → Human approval when required → Execution\n```\n\n**Not** `AI thinks → AI decides → AI executes`. This is what \"Humans govern. AI helps.\" means\noperationally. The existing Capability → Governance → Hermes separation is among the strongest\nparts of the repository and **is not to be redesigned** — it is to be verified across the full AI\nlifecycle.\n\n### OODA is internal, but must be real\n\nThe user never needs to understand OODA. The platform does. OODA, context assembly, model routing,\nADK, MCP, capability resolution, orchestration and reconciliation are **implementation machinery,\nnot product vocabulary**.\n\n### One channel is a coordination fabric\n\nChat, Work, Email, Notification and UI are surfaces over one coordination fabric. The surface\nchanges; the underlying context and work identity remain continuous.\n\n### Agents collaborate through shared state\n\nSpine Agents coordinate through **Shared Work + Business Context + Evidence** — never\n`Agent A → explain everything → Agent B`.\n\n### Sequencing constraint on agents\n\n> **Do not build more agent functionality until the persistence authority for AI Continuity is\n> decided (`G-10`).**\n\nOtherwise Spine Agents get designed around a memory abstraction whose durability is undefined.\n\n## Priority stack\n\n| Priority | Area | Why |\n|---|---|---|\n| **P0** | Business Context end-to-end trace | Everything depends on it |\n| **P0** | Platform execution reference trace | Proves the architecture actually executes |\n| **P0** | Pipeline / closure E2E | Proves the Spine actually becomes current truth |\n| **P0** | AI Continuity persistence decision (`G-10`) | Required before mature agents |\n| **P1** | Personal Contextual Spine (`G-02`) | Required by the canonical participant model |\n| **P1** | Spine Agent first-class model (`G-05`) | Required for the AI Workbench |\n| **P1** | Discovery → Activation → runtime (`G-07`) | Completes the platform control plane |\n| **P1** | MCP Pool routing proof (`Q-2`) | Prevents accidental data-plane violation |\n| **P1** | One Auth decision (`Q-1`) | Removes identity ambiguity |\n| **P1** | Projection / Active Context contract (`G-12`) | Makes different experiences coherent |\n| **P2** | Spine Cache contract | Performance layer without truth ambiguity |\n| **P2** | Work / coordination fabric | Makes human-AI collaboration concrete |\n| **P2** | Mintlify restructuring | Presents the architecture cleanly |\n| **P2** | Codebase terminology cleanup (`G-04`) | Prevents future drift |\n\n## Documentation information architecture\n\nMintlify must **not** expose repository topology. Product story first, machinery after:\n\n```text\n01 What is SpineWorkspace?   02 Business Context        03 Human Workbench\n04 AI Workbench              05 Twin & Spine Agents     06 Work\n07 Pipeline                  08 Platform Execution      09 Agent Execution\n10 Integrations & MCP        11 Capability Fabric       12 Governance\n13 Spine & Memory            14 Projection & Context    15 Execution Closure\n16 Architecture              17 Developer Reference\n```\n\n## Consequences\n\n- The gap register's ranking is superseded by the priority stack above. Individual gap entries\n  remain accurate as measurements; their *ordering* now follows this ADR.\n- `17-IMPLEMENTATION-ALIGNMENT-AND-GAP-REGISTER.md` is stamped against commit `0ebc224c`, which is\n  **stale** — `origin/main` has since moved to `e167ede1`. Per this tree's own rule, an alignment\n  document is void without a current stamp. It must be re-surveyed before the Reference Execution\n  work uses it as a baseline.\n- The Reference Execution is a *verification* artifact, not a redesign. Canon already supplies the\n  principles and separations; this proves the loop and closes the gaps around continuity, agents,\n  activation, identity and routing.\n"}