Version. 0.1
Date. 2026-06-09
Status. Foundation note. Records the Companion architecture settled in design discussion, as the reviewed ground for a forthcoming comprehensive Companion functional spec. This is not the spec — it captures what was settled, why, the trajectory of getting there, and what remains open. Operator-facing. HTML primary, this Markdown source alongside.
Author posture. Written in Discovery posture: the reasoning and the alternatives set aside are preserved alongside the conclusions, so a later reader can reconstruct how the architecture was reached, not only where it landed.
Source grounding. This note consolidates and reconciles existing committed material rather than inventing: the Companion Expertise Note v0.1 (the de-facto behavioral spec), the Product Identity standing note, the architecture specification v0.4 (§02, §08, §09, §12), the Phase 41/42/44/45/50 CRs, the Companion-as-agent investigation v0.1, the engagement-addressing Stream-1 handoff v0.1, and the engine contract on main (the /operator/converse flow, the delegation/approval module, tune_setting, the persona asset). Where this note states a settled position, it extends those sources; where it states an open question, the sources do not yet decide it.
The Companion is one thing with one behavioral contract, described along two independent axes. Scope says how wide the Companion's view is — one engagement, a named group of engagements, or your whole working set — addressed through engagement identity. Driver says who is at the controls — a present human, or an agent acting on your behalf. Underneath both axes is a single behavioral contract: the Companion gathers, confirms what it understood, submits to Memory, organizes and arranges, produces, and delivers — always subordinate to the Engine, always preserving provenance, always leaving final authority with the Operator. The two axes are independent: any combination is valid. This note records that architecture, the reasoning that produced it, and the two decisions still open.
The architecture's older framing carried an unresolved tension: the Companion described in one place as "the instrument, not a party… does not have agency independent of the Operator," and in another as "the Companion as agent… an entity with agency… makes judgments." Those framings were written before the Companion was understood as a separate, multi-construction entity, and the tension dissolves once the relationship is stated correctly.
The Engine is the authority. The Companion is subordinate to it. The Engine holds the disciplines, the provenance, and the bound at the API — it governs every caller equally and can only ever know a caller's identity, its authorized reach, and the nature of each action it takes. The Companion is one kind of caller. It feeds the Engine (submits to Memory) and leverages what the Engine does (initiates Shaping and Rendering, reads what the Engine knows). Its entire behavioral surface is bounded by what the Engine's API and provenance permit.
This resolves the "agency" confusion. The Companion has operational agency — it does things, including things you did not ask for in the moment — but never sovereign agency. It has no will of its own. Every action it takes traces to authority the Operator granted, exercised within what the Engine permits any caller to do. The earlier confusion came from comparing the Companion to the Operator (party or instrument?); the correct comparison is to the Engine (the Companion is a caller; the Engine is the governor of all callers).
This is the same insight as the settled glossary correction — "the Companion is a role a caller occupies" — stated from the other side: and the thing it is subordinate to is the Engine.
Whatever the scope and whatever the driver, the Companion performs one behavioral sequence. This is the template; the axes are bindings of it.
Three disciplines bind the whole sequence, inherited from settled commitments and not re-litigated here: Operator-final-authority (the Companion proposes; the Operator commits; automatic state transitions on Operator-authority artifacts are a category error); the vocabulary wall (the Companion speaks Operator vocabulary — project, note, specification, artifact — never engine vocabulary); and provenance (every contribution carries its origin; the Companion never invents provenance and never claims to remember conversations it did not have).
Scope is how wide the Companion's view is: a selection over the Loomworks engagement space. It is not a binary. It is a range.
This axis began the discussion modeled as a binary — personal scope versus engagement scope. That was set aside. The executive-coach case broke it: a coach working across "my clients" operates at a scope wider than one engagement but narrower than their entire personal world, and the binary had no home for it. The named-group band was promoted to first-class, and scope became a range. The decision to model it as a genuine range (rather than treating the middle as "personal, filtered") was made deliberately, grounded in the fact that the addressing primitives to support the range already exist.
Engagement identity has two handles, and the Companion must use the right one for the context. This is settled.
E#### (e.g. E4729). Global across the entire Loomworks space; the same value for everyone. This is the register for anything that must mean the same thing beyond you: external reference, shared documents, cross-person disambiguation, and any multi-party engagement.Rule the spec carries: the Companion uses the personal register for the Operator's own navigation, and the universal register whenever a reference must hold beyond the Operator. "Your project 23 needs attention" (personal, to you) versus "this belongs with E4729" (universal, because that reference may travel or be shared).
The scope range (one → group → all) runs on the personal register for your own world; the universal register is what lets scope ever reach beyond you. The universal handle is also the identity layer any future multi-party / multi-Operator work will stand on (that future remains gated; the register is forward-compatible with it).
The engagement identity is a monotonic integer; E#### is a presentation of it that zero-pads to four digits today. The number is not ceilinged at 9,999 — the system already flags the four-digit display break and plans to let the frontend render the prefix and pad as needed. The spec must not bake the four-digit width into anything load-bearing; it uses "E-number" / "engagement identifier" structurally, and E#### only as illustrative presentation. (This intersects a planned refactor: collapse display_identifier into the per-Operator sequence and render the prefix at the surface.)
The addressing primitives are built substrate: the global identifier, the per-Operator number, tags-as-aliases, and a resolver that accepts all forms. But the Companion cannot navigate this space conversationally today. /operator/converse is UUID-bound — each turn carries one engagement UUID, resolved on the frontend before the engine acts; the engine's resolver is nearly unused; engagement switching is a surface act (the frontend changes the URL), not a Companion act; cross-engagement reference is unbuilt. So a spec that has the Companion scope, switch, or cross-reference engagements conversationally ("open E4729," "is this also in engagement 23?", "move this to my Loomworks commons") is specifying net-new wiring of an existing-but-unused primitive, and it intersects the planned identifier refactor. The spec defines the target; the build reaches it in stages.
Driver is who is at the controls: a human, or an agent acting on the Operator's behalf. This is a genuine second axis, independent of scope and independent of autonomy.
Driver governs presence, medium, and identity:
Driver does not govern autonomy. Autonomy — how much the Companion does without checking — is a separate setting on the delegation contract (per_action versus pre_authorized).
This was stress-tested. The skeptical view held that "human vs. agent" is not a separate axis at all but merely where the delegation dial is set: a human-driven Companion is one where everything is per_action (always waits for you), an agent-driven one is pre_authorized (acts and reports). The skeptic had real evidence — the engine today authenticates only a human session ("whoever holds the verified session cookie is the Operator, full stop"); there is no agent-driver path in code; the agent is theoretical.
The dial view was set aside because it captures autonomy but misses presence, medium, and identity — which differ in kind, not degree. The deciding test was crossing: a human can be pre_authorized (you tell it "just do the small things, don't ask me") and an agent can be per_action (it queues a card and waits for your return). Both crossed cases are real and useful. Because driver and autonomy cross freely, they are independent dimensions; if they were the same thing, you could not cross them.
The human binding is largely built (the conversation, the approval cards, session auth). The agent binding is specified-ahead-of-build: the engine has no agent-driver path today, and OVA (the agent's carried-authorization mechanism) is designed, not built. The settled approach (from the deferred Tension 3, refined): the spec defines both bindings of each contract point; the human binding is built now; the agent binding is specified precisely enough that it is a clean future build, not a retrofit. Defining the confirmation checkpoint abstractly (with a human card-binding and an agent protocol-binding) is exactly what prevents the retrofit.
When scope is at its widest — the personal / Standing posture — the Companion is yours, and "personal" carries four facets, all settled as in-scope for the spec to define:
remember_about_me / forget_about_me paths). This is the personal scope's content.tune_setting), surfacing things proactively across your engagements, being your interface to the whole Loomworks system. This is the personal scope's function, and it is the home the "Companion-as-Operator-system-interface" principle was reaching for.The two axes are independent, so any combination is valid. Four corners, to make the model concrete:
Scope and driver vary separately; the named-group scope and the autonomy dial add further real positions between these corners (e.g. an agent operating across the coach's client group under pre-authorization).
Two decisions were deliberately deferred and are now framable precisely, because the architecture is settled. The forthcoming spec needs both resolved.
Four tensions surfaced in grounding are resolved and will be stated in the spec, not re-decided:
approval_mode vocabulary — layered: per_action / pre_authorized describe the contract's standing rule; explicit is the dispatch record of an individually-approved action.Settled and grounded: the founding axiom, the behavioral contract, both axes (scope as an addressing range with two registers; driver as human/agent governing presence-medium-identity), the four personal facets, and four of six tensions. Open: the two deferred decisions in §7. Next step: resolve those two, then write the comprehensive Companion functional spec on this foundation.
The spec, when written, will be descriptive where behaviors exist (documenting the built human-binding Companion) and prescriptive where they do not (the agent binding, conversational scope-navigation, the personal-scope facets not yet built), with each contract point carrying its scope binding and its driver binding.