{"slug":"canonical/adr/ADR-2026-09-01-01-context-actions-are-ambient","title":"ADR-2026-09-01-01 — The four context actions are ambient, not a toolbar","section":"canonical","sectionLabel":"Canon","status":"canon","type":"adr","path":"canonical/adr/ADR-2026-09-01-01-context-actions-are-ambient.md","bytes":8158,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Accepted\n**Date:** 2026-09-01\n**Authority:** Founder decision, 1 September 2026\n**Related:** Founder Canon §10 (Experience Principles), §11 (OODA), Appendix C item 25\n\n## The decision\n\n> **Store in Spine, Ask your Twin, Assign your Twin and Approve are not top buttons. They are\n> inbuilt in every action.**\n>\n> **And business context is the primary dimension of every one of them** — not the UI object the\n> action happens to sit on.\n\nTwo things follow, and the second is the more important one.\n\n**They are not a toolbar.** No global control strip, header bar, or fixed button row. The four\nappear wherever the work is, and only where they legitimately apply.\n\n**They are governed by business context, not by UI selection.** A record, section, selection,\nsignal or canvas object is only the *carrier* — the place the action surfaces. What gives the\naction meaning, availability and priority is the **business context** behind it: the entity and its\nrelationships, its place in the intent chain, the KPIs it moves, the lifecycle state it sits in,\nand the evidence supporting it.\n\nThis is canon §13, stated directly:\n\n> Departments, roles, pages and **Twin actions are projections over this operating reality.**\n\n```text\nMission → Objectives → Goals → KPIs → Initiatives → Work\n       → Decisions → Actions → Outcomes → Learning\n```\n\nAn action detached from that chain is not a smaller action — it is a meaningless one. \"Store in\nSpine\" with no business context is an untyped write. \"Ask your Twin\" with no business context is a\nchatbot. \"Assign your Twin\" with no objective is busywork. \"Approve\" with no KPI or lifecycle\nconsequence is a rubber stamp.\n\nSo the resolution order is **business context first, carrier second**:\n\n```text\nBusiness Context  (entity · relationships · goals · KPIs · lifecycle state · evidence)\n        ↓  gives the action its meaning, availability and priority\nCarrier           (record · section · selection · signal · canvas)\n        ↓  gives the action a place to appear\nGoverned path     (proposal → policy → approval → execution → reconciliation)\n```\n\n## Why this matters\n\nThese four are the OODA grammar made operable:\n\n```text\nOBSERVE  →  Store in Spine        →  organizational truth\nORIENT   →  Ask your Twin         →  understanding\nDECIDE   →  Assign your Twin      →  proposal / prepared work\nACT      →  Approve               →  governed execution\n```\n\nCanon calls this \"the constitution of the human-agent system,\" and the load-bearing rule inside it\nis:\n\n> **Twin does not own ACT.** The human owns consequential authority. Twin can *prepare* the action;\n> the capability layer can *execute* it; Governance determines whether approval is required.\n\nA toolbar breaks this in a specific way. A global control strip implies the four actions are modes\nof the *application* — always available, uniformly meaningful, detached from any object. But their\nmeaning is entirely contextual: \"Store in Spine\" is meaningless on a record that is already\ncanonical, and \"Approve\" is meaningless without a pending proposal matching the user's authority.\nRendering them globally forces the interface to either lie about availability or disable four\nbuttons most of the time.\n\nMaking them ambient also keeps the experience promise in canon §10 — the user performs *natural\nwork actions*, not OODA ceremony. Appendix C item 25 states the constraint negatively:\n\n> OODA is retained as internal operating grammar rather than a requirement that the interface\n> expose four literal controls everywhere.\n\n**This ADR states the positive form:** OODA is not exposed as four global controls *because* the\nfour actions live inside every action, governed per context.\n\n## Consequences\n\n- Every surface that renders work must host the four actions **against business context**, not\n  against a UI selection. The carrier identifies *where* the action appears; the business context\n  determines *whether it applies, what it means, and how it ranks*.\n- **Business context is carried, not re-derived.** An action must reach the governed path with its\n  business context attached — entity, relationships, goals/KPIs, lifecycle state and evidence. A\n  surface that can only say \"the user clicked this row\" has not supplied enough to act on.\n- Availability is a governed decision with four outcomes, not a boolean: **available**, **hidden**,\n  **disabled**, or **already canonical** — each carrying a reason the user can read. The reason is\n  a business reason (\"this record is already canonical\", \"the pending proposal does not match this\n  authority\"), not a UI-state reason.\n- **Priority follows business context.** Where several actions or work items compete for a user's\n  attention, the ranking comes from objectives, goals and KPIs — not from recency or screen\n  position.\n- No surface may implement these actions with local component state. They route through the\n  governed path: *Intent → Twin Proposal → Capability Resolution → Policy Check → Approval (if\n  required) → Execution → Provider Acceptance → Reconciliation → Spine Update.*\n- New surfaces get these actions by hosting the shared slot, not by rebuilding the buttons.\n\n## Implementation status\n\n### The placement conforms; the business context does not\n\nAn earlier revision of this ADR said the architecture \"already conforms.\" **That was assessed\nagainst the UI-carrier framing and is wrong under the business-context framing.** Corrected below.\n\n**Conforming — the ambient placement.**\n`apps/web/components/context-actions/context-action-slot.tsx` implements exactly this model:\n\n- it binds to a `ContextActionOwner` whose kind is `section | record | selection | signal | canvas`\n  — an owner, never the page;\n- it resolves each of the four to `available | hidden | disabled` (and `already_canonical` for\n  Store in Spine) from the `ActiveContextBundle` and `InteractionControl`, with human-readable\n  `reasons`;\n- it is hosted at four nesting levels in `domain-view-shell.tsx`, plus `entity-context-panel.tsx`\n  and `projection-twin-pane.tsx`.\n\nIts header already states the governed path this ADR requires.\n\n**Not conforming — business context never reaches the action surface.**\n\nThe four actions resolve against `ActiveContextBundle`. That contract carries `principal`,\n`projection`, `selection`, `entityContext`, `entity360`, `formation`, `knowledge`, `memory`,\n`evidence`, `capabilities`, `policy`, `freshness`, `uncertainty` and `returnState` — and **no\nobjectives, goals or KPIs**. There is no match for those terms anywhere in\n`packages/context-contracts`.\n\nKPI *measures* do exist, but only as entity-level fields in the Projection Engine\n(`target_value`, `current_value`, `health_score`, `probability`, `stage`, `target_date`, under a\ncomment reading \"Canonical KPI & Business Context dimensions (§11.1a)\" in\n`packages/projection-engine/src/types.ts:137`). They are assembled at entity level and stop there.\n\nSo today an action can see **what this record is**, but not **which goal it serves or how it\nranks**. That is precisely the dimension this ADR makes primary, and it is absent from the contract\nthe actions read. Recorded as `G-12` — and given canon §1A, this is the central gap between the\nproduct thesis and the code, not a peripheral one.\n\n**One non-conforming surface.** `apps/web/app/app/workbench/sales/page.tsx` renders \"Store in\nSpine\" three times (lines 117, 155, 194) driven by local `setShowStoreModal` state rather than the\ngoverned slot. The *placement* is right — per-card, not a toolbar — but the path is not: no\ngovernance decision, no evidence requirement, no proposal or approval. It has no inbound links and\nappears to be an orphaned demo page. Recorded as `G-11`.\n\n## Not decided here\n\nThe visual treatment — whether ambient actions surface on hover, in an overflow menu, in a\npersistent inline row, or some mix per owner kind. That is a design decision. This ADR fixes\n*where the actions belong and what governs them*, not how they are drawn.\n"}