Canonadr

ADR-2026-09-01-01 — The four context actions are ambient, not a toolbar

Status: Accepted
Date: 2026-09-01
Authority: Founder decision, 1 September 2026
Related: Founder Canon §10 (Experience Principles), §11 (OODA), Appendix C item 25

The decision

Store in Spine, Ask your Twin, Assign your Twin and Approve are not top buttons. They are
inbuilt in every action.

And business context is the primary dimension of every one of them — not the UI object the
action happens to sit on.

Two things follow, and the second is the more important one.

They are not a toolbar. No global control strip, header bar, or fixed button row. The four
appear wherever the work is, and only where they legitimately apply.

They are governed by business context, not by UI selection. A record, section, selection,
signal or canvas object is only the carrier — the place the action surfaces. What gives the
action meaning, availability and priority is the business context behind it: the entity and its
relationships, its place in the intent chain, the KPIs it moves, the lifecycle state it sits in,
and the evidence supporting it.

This is canon §13, stated directly:

Departments, roles, pages and Twin actions are projections over this operating reality.

Mission → Objectives → Goals → KPIs → Initiatives → Work
       → Decisions → Actions → Outcomes → Learning

An action detached from that chain is not a smaller action — it is a meaningless one. "Store in
Spine" with no business context is an untyped write. "Ask your Twin" with no business context is a
chatbot. "Assign your Twin" with no objective is busywork. "Approve" with no KPI or lifecycle
consequence is a rubber stamp.

So the resolution order is business context first, carrier second:

Business Context  (entity · relationships · goals · KPIs · lifecycle state · evidence)
        ↓  gives the action its meaning, availability and priority
Carrier           (record · section · selection · signal · canvas)
        ↓  gives the action a place to appear
Governed path     (proposal → policy → approval → execution → reconciliation)

Why this matters

These four are the OODA grammar made operable:

OBSERVE  →  Store in Spine        →  organizational truth
ORIENT   →  Ask your Twin         →  understanding
DECIDE   →  Assign your Twin      →  proposal / prepared work
ACT      →  Approve               →  governed execution

Canon calls this "the constitution of the human-agent system," and the load-bearing rule inside it
is:

Twin does not own ACT. The human owns consequential authority. Twin can prepare the action;
the capability layer can execute it; Governance determines whether approval is required.

A toolbar breaks this in a specific way. A global control strip implies the four actions are modes
of the application — always available, uniformly meaningful, detached from any object. But their
meaning is entirely contextual: "Store in Spine" is meaningless on a record that is already
canonical, and "Approve" is meaningless without a pending proposal matching the user's authority.
Rendering them globally forces the interface to either lie about availability or disable four
buttons most of the time.

Making them ambient also keeps the experience promise in canon §10 — the user performs natural
work actions, not OODA ceremony. Appendix C item 25 states the constraint negatively:

OODA is retained as internal operating grammar rather than a requirement that the interface
expose four literal controls everywhere.

This ADR states the positive form: OODA is not exposed as four global controls because the
four actions live inside every action, governed per context.

Consequences

  • Every surface that renders work must host the four actions against business context, not
    against a UI selection. The carrier identifies where the action appears; the business context
    determines whether it applies, what it means, and how it ranks.
  • Business context is carried, not re-derived. An action must reach the governed path with its
    business context attached — entity, relationships, goals/KPIs, lifecycle state and evidence. A
    surface that can only say "the user clicked this row" has not supplied enough to act on.
  • Availability is a governed decision with four outcomes, not a boolean: available, hidden,
    disabled, or already canonical — each carrying a reason the user can read. The reason is
    a business reason ("this record is already canonical", "the pending proposal does not match this
    authority"), not a UI-state reason.
  • Priority follows business context. Where several actions or work items compete for a user's
    attention, the ranking comes from objectives, goals and KPIs — not from recency or screen
    position.
  • No surface may implement these actions with local component state. They route through the
    governed path: Intent → Twin Proposal → Capability Resolution → Policy Check → Approval (if
    required) → Execution → Provider Acceptance → Reconciliation → Spine Update.
  • New surfaces get these actions by hosting the shared slot, not by rebuilding the buttons.

Implementation status

The placement conforms; the business context does not

An earlier revision of this ADR said the architecture "already conforms." That was assessed
against the UI-carrier framing and is wrong under the business-context framing. Corrected below.

Conforming — the ambient placement.
apps/web/components/context-actions/context-action-slot.tsx implements exactly this model:

  • it binds to a ContextActionOwner whose kind is section | record | selection | signal | canvas
    — an owner, never the page;
  • it resolves each of the four to available | hidden | disabled (and already_canonical for
    Store in Spine) from the ActiveContextBundle and InteractionControl, with human-readable
    reasons;
  • it is hosted at four nesting levels in domain-view-shell.tsx, plus entity-context-panel.tsx
    and projection-twin-pane.tsx.

Its header already states the governed path this ADR requires.

Not conforming — business context never reaches the action surface.

The four actions resolve against ActiveContextBundle. That contract carries principal,
projection, selection, entityContext, entity360, formation, knowledge, memory,
evidence, capabilities, policy, freshness, uncertainty and returnState — and no
objectives, goals or KPIs. There is no match for those terms anywhere in
packages/context-contracts.

KPI measures do exist, but only as entity-level fields in the Projection Engine
(target_value, current_value, health_score, probability, stage, target_date, under a
comment reading "Canonical KPI & Business Context dimensions (§11.1a)" in
packages/projection-engine/src/types.ts:137). They are assembled at entity level and stop there.

So today an action can see what this record is, but not which goal it serves or how it
ranks. That is precisely the dimension this ADR makes primary, and it is absent from the contract
the actions read. Recorded as G-12 — and given canon §1A, this is the central gap between the
product thesis and the code, not a peripheral one.

One non-conforming surface. apps/web/app/app/workbench/sales/page.tsx renders "Store in
Spine" three times (lines 117, 155, 194) driven by local setShowStoreModal state rather than the
governed slot. The placement is right — per-card, not a toolbar — but the path is not: no
governance decision, no evidence requirement, no proposal or approval. It has no inbound links and
appears to be an orphaned demo page. Recorded as G-11.

Not decided here

The visual treatment — whether ambient actions surface on hover, in an overflow menu, in a
persistent inline row, or some mix per owner kind. That is a design decision. This ADR fixes
where the actions belong and what governs them, not how they are drawn.