Version: 0.4 Date: 2026-05-25 Status: Working draft
Purpose. This document is the foundational architectural specification for Loomworks. It begins as a structural scaffold and grows with the project — like a building's master architectural drawing set that starts as the outline and accumulates layer after layer of detail as decisions are made and components are built.
How to read it. The sections below carry status badges showing what's built today versus what's planned or under investigation. Within sections, individual components carry their own inline status markers. Sparse sections are honest: where the project hasn't decided something, the section says so; where built reality is partial, the section says what's built and what's not.
How to maintain it. Each substantive change to Loomworks should update this document. Where the change makes a planned thing built, the status updates. Where the change surfaces a new component, a new subsection is added. Where the architecture itself evolves, the structural skeleton accommodates the change. Prior versions stay in the record per discovery-trajectory discipline; v0.4 lands alongside v0.3, not over it.
Status legend. Built today · Partially built · Planned · Under investigation.
v0.4 absorbs four substantive sets of changes since v0.3 (2026-05-21):
1. FORAY reframing — the load-bearing change. v0.3 framed FORAY as Loomworks' internal audit substrate — flow rows recorded for every state-changing action, narrative events extending into setting changes, the credit balance trigger reading from "the FORAY flow log." The substrate hygiene cleanup arc (Phases 61, 62, 63 — closed 2026-05-24/25) dismantled that framing. FORAY is now correctly framed as an external service Loomworks will call. Loomworks' substrate holds three Loomworks-native tables (audit.events, clean memory_events, credit.flows) plus a reserved-location pattern at 16 call sites awaiting actual FORAY integration. The src/loomworks/foray/ module exists as foundation for the integration when it opens. Section 09 carries the full reframing.
2. Methodology canon v0.1 landed (record commit de23c31, 2026-05-24). Four principles validated through the cleanup arc earn canonical status: per-call-site reserved emit, test-filename-to-current-substrate alignment, migration strategy (rename when downstream bindings exist; recreate when independent), inventory enumeration vs cognitive density. Section 12 references the canon as the authoritative source; Section 13 documents the consolidation pattern.
3. Voice modality matured beyond v0.3's framing. v0.3 noted voice listening had shipped; v0.4 reflects the fuller voice landscape — silence-submit threshold, recognizer E-prefix expansion, voice-provenance marker on conversation turns, voice-pill padding, the in-engagement voice listening surface. Section 10 carries the updated voice surfaces.
4. Workshop framing made explicit. v0.3 treated Workshop as an active surface alongside the Operator Layer. The grounding for v0.4 makes clear Workshop is intentionally frozen at the Phase 45 four-room engine-internals shape — opt-in advanced surface, read-only relative to the engine, with active product work happening on the Operator Layer (loomworks) repo. Section 10 says so.
What did not change: Sections 01-08 (Orientation, Core concepts, the four rooms, Engagement patterns, the Companion), Section 14 (Glossary), and Section 15 (Maintenance) carry forward from v0.3 substantially intact, with refinements where needed.
Status: Built (foundational framing); evolves with the project.
Loomworks is a system for accumulating, organizing, and shaping engagement knowledge so that work products emerge with their full lineage intact. It is a four-room pipeline — Memory, Manifestation, Shaping, Rendering — where each room performs one operation against the engagement's accumulated knowledge.
The Operator is the principal. The Companion is the instrument. The Engagement is the unit of work. The substrate carries the durable record. The protocol triangle (Loom · FORAY · OVA) provides the governance shape that distinguishes Loomworks from a chat tool with state.
What Loomworks is not: a one-shot generator, a chat interface with a database behind it, a workflow tool that orchestrates external services. Loomworks holds knowledge over time, lets multiple parties contribute under role-constrained access, makes derivations and renderings from accumulated knowledge, and preserves the trajectory of how each engagement reached its current state.
Status: Built (stable vocabulary); the methodology document v0.20 is the canonical reference.
The principal. The person on whose behalf the Engagement does its work. The Operator has final authority — the Companion proposes; the Operator commits. Engagements have at least one Operator and may have several; multi-Operator scenarios are designed for but not yet operationally exercised at scale.
The AI that mediates everything between Operator and substrate. The Companion is the instrument, not a party — it acts on the Operator's behalf and carries the Operator's authority through delegation contracts. The Companion has identity (a persistent voice, a recognizable posture) but does not have agency independent of the Operator. Two postures exist: Companion-mediated (Companion acts; Operator commits) and Operator-direct (Operator is the actor; no Companion delegation in between). Both are first-class.
The unit of work. An Engagement holds a seed (its frame of reference), a Memory (accumulated knowledge as assertions), and progresses through four rooms (Memory, Manifestation, Shaping, Rendering). Engagements are scoped — to a person, a topic, a domain. They compose: Memory from one Engagement can be referenced by another under N-domain composition rules.
The Engagement's frame of reference. What this Engagement is for, what's in scope, what's not. The seed is created at induction time; it lives as the Engagement's lens for relevance evaluation. The seed evolves with the Engagement; corrections to the seed are governance-bearing operations.
The atomic unit of Memory. An assertion carries a claim, attribution (who contributed it), provenance (how it entered Memory — typed, spoken, extracted from a document, derived from an image), lifecycle state (held, committed, retracted, superseded), and timestamps. Assertions are addressable by identifier. The lifecycle is governance-bearing: held-then-commit is the default ceremony; retraction before commit is silent; retraction after commit is part of the audit trail.
The engagement-scoped surfaces. Workspaces hold related Engagements; tags label them across workspace boundaries. The Operator's view of their work is organized along these axes.
Status: Built (substrate); ongoing investigation on stewardship and multi-backing scenarios.
Memory is the engagement's accumulated knowledge — everything that has been contributed, by everyone, over the life of the engagement. Memory does not forget; contributions that are corrected or superseded remain visible as part of the record. Every other operation in the system — Manifestation, Shaping, Rendering — draws from Memory.
Contributions enter Memory through several pathways: typed turns in the Companion chat, voice turns transcribed and provenanced, file uploads extracted by specialists, image-vision extraction, audio transcription, and the engagement-creation conversation itself. Each pathway records its provenance — the route through which the assertion entered Memory.
The substrate supports per-assertion identifiers (M-prefix scheme designed; surface affordance under investigation). Assertions can be referenced by identifier in conversation, in operations, and in audit trails. Surface affordance for addressable assertions — selection mode, spoken-and-typed addressing — is being scoped.
The held-then-commit ceremony is the default. New contributions enter the held state, attributable to a contributor, awaiting Operator commit. After commit, retraction is governance-bearing (the trail shows existence, contribution, retraction); before commit, retraction is silent (the assertion never existed). Supersession is the pattern where a new assertion supersedes a prior one without retracting it — the trajectory is preserved.
The seed is the frame of reference for relevance evaluation. Today, no evaluation happens; all contributions land regardless of relevance. Relevance evaluation against the seed is identified work — design questions include pre-extraction filtering vs post-extraction tagging, and Operator-elicitation vs silent extraction.
Every assertion carries provenance: the person who contributed it, the channel through which it entered (text, voice, file, image, audio), the timestamp, and any specialist that produced it. Voice turns now carry an input_mode provenance marker on conversation_turns (voice-provenance ship, 2026-05-20). Provenance is queryable.
An Engagement draws on Memory from however many scopes are relevant — its own scope, the Operator's personal scope, any subject-scope it shares (per the Shared-Subject Engagement Pattern v0.1, filed but not yet exercised), jurisdictional scopes, and so on. The composition is the load-bearing operation. The Companion composes across all relevant scopes at the moment of operation.
Memory has multiple backings: assertion-backed Memory (the default, held-then-commit, semantic retrieval), database-backed Memory (Credit Management as the existing instance — tabular, row-shaped, query-shaped), and binary-content-backed Memory (sketched, not built — for images, audio, video). The Memory architecture is neutral about backing; the contract is the operations Memory supports, not the storage shape.
Status: Built (substrate + surface).
A Manifestation is Memory organized at a moment in time. Memory accumulates continuously; at any given moment, the engagement's Memory is a body of knowledge with no structure beyond contribution order. Derivation is the act of organizing — the system reads the seed and all committed assertions and produces a structured ordering with groups, labels, and a coherent reading order. The result is a Manifestation: Memory made readable.
A Manifestation is not a copy. The assertions remain in Memory. The Manifestation is a reading of Memory — an organizing act. When Memory grows and the Operator re-derives, the body of knowledge has changed, so its best organization may have changed. Prior Manifestations are preserved; the new one reflects current state.
Status: Built (substrate + surface; declared shape types extending).
Shaping arranges organized knowledge for a specific reader. A Manifestation is organized knowledge in general; a Shaping selects, emphasizes, and leaves out for a particular audience and purpose. Shaping is where the Engagement decides what this reader needs to see.
The Shaping is grammar-indifferent — it does not know how the output will be produced. The grammar of the artifact (markdown vs HTML vs PowerPoint vs application code) is declared on the Shaping; the production of the artifact lives in the Rendering layer below.
Status: Built (substrate + surface; render specialists registry operational).
Rendering produces the artifact the reader receives. A Shaping is the specification of what the reader should receive; the Rendering is the production of it. Rendering takes the Shaping's content in its declared grammar and either produces the artifact directly (for simple grammars) or dispatches to a specialist that produces it.
Rendering operates in two modes:
The dual mode reflects that Rendering is the boundary at which Loomworks meets the rest of the world. Some artifacts are simple enough to produce in-engine; some require domain-specific specialists (an application builder, a 3D-print system, a presentation generator).
A Rendering is not the end of the engagement's life — it is one operation. The Engagement continues; new Memory enters; new Manifestations and Shapings derive; new Renderings produce. The trajectory accumulates.
Status: Built (operational and infrastructure both exercised); patterns extending.
Every Engagement follows the four-room pipeline, but Engagements vary by what they do and how they compose. Several engagement patterns have crystallized:
Operational Engagements wrap external work or domain knowledge. The Operator brings an intent (write a report, draft a contract, plan a curriculum); the Engagement holds the work as it develops; the Rendering produces the deliverable. Examples: marketing, education, geology fieldwork, legal drafting.
Infrastructure Engagements are part of Loomworks' own operation. Credit Management and Accounting are infrastructure Engagements that wrap the credit system. Personal Engagements wrap an Operator's personal Memory. Administrative Engagements wrap platform-level concerns.
The distinction is methodological, not architectural — both kinds use the same substrate. The distinction matters for understanding what each Engagement is for.
Some governance problems split naturally into two Engagements: an Authority that sets policy and issues decisions, and an Accounting that maintains state and reconciles. The credit system is the first instance — Credit Management as Authority (issues grants, decides eligibility), Accounting as bookkeeper (maintains balances, reconciles drift). The pattern generalizes to other governance domains.
A resident Engagement is one an Operator returns to over time — a domain practice, a long-running project, a personal Memory. A delivery Engagement is one that produces a deliverable and closes — a single report, a one-time contract, a defined-scope project. Both are first-class; the distinction shapes the Engagement's lifecycle expectations (resident: maintenance over time; delivery: progression to terminal state).
An Engagement may be used in three modes:
The three modes are not mutually exclusive in time; an Engagement progresses through them.
A property (or any subject) can have multiple independent Engagements each contributing to a shared subject-scoped knowledge layer under role-constrained access. An owner's Engagement, a real-estate agent's Engagement, a pool service's Engagement, a roofer's Engagement, an HVAC contractor's Engagement — each with their own Operator — all contribute to a shared knowledge layer about the same property. The Shared-Subject Engagement Pattern v0.1 is filed; OVA's role expands materially when this lands; not yet operationally exercised.
Every Operator has a personal Engagement. The personal Engagement holds the Operator's personal Memory — their preferences, their working context, their conversation history with the Companion. The personal Engagement is the substrate that lets the Companion's "ambient context" carry across other Engagements the Operator works in. Personal Engagement was built in Phase 41 (Companion identity + personal engagement).
Some Engagements are about Loomworks itself — the Loomworks Universal Commons Engagement (Phase 15), terms-of-use Engagements (filed at v0.2 investigation), platform-governance Engagements. These wrap platform-level concerns inside the Engagement pattern, exercising the universal-adapter property of Engagements.
Status: Built (substrate); Companion-as-Operator-system-interface principle ongoing.
The Companion is the AI that mediates everything between Operator and substrate. The Companion has identity — a persistent voice, a recognizable posture, a defined relationship to the Operator. The Companion is the instrument, not a party.
The Companion's voice was settled in Phase 41 (Companion identity + personal engagement). The Companion speaks in Operator vocabulary (project, note, specification, artifact) — never engine vocabulary (engagement, assertion, shape, render). The Companion's posture is lead expert — a domain authority that brings structural knowledge to the Operator's work, not a translator that routes intent to operations. The companion expertise note governs the principles.
Plain-English communication is the discipline: the Operator's path never contains technical vocabulary. Technical terms live in code, not in conversation.
The Companion classifies each Operator turn against an intent taxonomy (Phase 42 — intent classification + reactive Companion). Intents dispatch to handlers: navigate, contribute, propose, commit, retract, etc. The classifier-and-handler pattern is extensible; new intents land through the declare-and-register pattern.
When the Operator enters an Engagement, the Companion loads context: the seed, recent Memory, current state, any in-flight Manifestations or Shapings. The Companion's response to the next turn carries this context. Context loading is bounded by engagement boundaries (the Engagement's own scope + the Operator's personal scope by default).
Two postures:
The transition between postures is signaled by the surface the Operator is on. Cross-Engagement awareness (the standing Companion recognizing that something said in one Engagement might belong in another) is planned but not yet a behavior.
The Companion's "ambient context" — what the Operator has said in personal Memory, working preferences, the Operator's vocabulary — carries across Engagements through the personal Engagement substrate (Phase 41). Personal Memory contribution (Phase 43) is the surface for adding to ambient context.
The Companion acts on the Operator's behalf through delegation contracts (Phase 45 — delegation contract + approval cards, closing Arc 2). A delegation contract scopes what the Companion can do without further Operator approval; high-stakes operations require explicit Operator commitment via approval cards. The contract is the architectural locus of Companion authority; the Operator can read it, narrow it, or extend it.
Delegation contracts carry: the scope of authority delegated, the duration, the operations included, the operations excluded (require explicit approval), and the audit trail of operations performed under the contract. The contract is part of the engagement substrate; it persists with the Engagement. Default contracts are conservative; the Operator can broaden them per Engagement.
A principle that surfaced after Phase 60: the Companion is the primary surface for all Operator-system interaction, not just conversational work. This includes preferences, configuration, policy adjustments, and other Operator-system concerns that historically lived in settings UIs. Phase 60's tune_setting handler is the first instance — the Companion adjusts backdrop blur, voice listening thresholds, and other Companion settings through conversation. The principle generalizes; it shapes Phase 61+ work.
Status: Loom built; FORAY external (Loomworks-side reserved-location pattern in place); OVA via seam-and-stub.
Three protocols compose to give Loomworks its governance properties. They are adjacent rather than nested. Each does its own work; the composition is load-bearing.
"Loom remembers. FORAY proves. OVA scopes."
Status: Built.
Loom is the engagement-memory wire layer. Its job is the durable record of what each Engagement holds — assertions, events, relationships, state. The methodology's plain-terms vocabulary lives in Loom's structures. Without Loom there is no substrate to reason over. Loom is at v0.1 spec (2026-04-12), built underneath Loomworks, rests on PROV.
Status: External service; Loomworks-side integration substrate reserved but not yet active.
This subsection's framing was substantively revised in v0.4. v0.3 framed FORAY as Loomworks' internal substrate, with flow rows recorded on every state-changing action and narrative events extending into setting changes. The substrate hygiene cleanup arc (Phases 61, 62, 63 — closed 2026-05-25) replaced that framing.
The correct framing: FORAY is an external service Loomworks will eventually call. Loomworks does not implement FORAY internally; Loomworks' substrate is Loomworks-native. When external FORAY integration opens, Loomworks calls FORAY through a defined boundary at each business event that deserves attestation. The boundary is the reserved-location pattern.
FORAY itself (the external service): Universal transaction grammar; patent pending; Kaspathon 2026 Top 10. The FORAY protocol records what happened, who did it, when, against what authorization. The Loomworks team developed FORAY's protocol shape; the operational FORAY service is built and reachable but Loomworks is not yet calling it.
Loomworks' FORAY-readiness substrate. The engine holds a src/loomworks/foray/ module foundation with three pieces:
__init__.py — re-exports _foray_reserved_emit and _ANCHOR_PRIORITYreserved_emit.py — the no-op emitter that future integration replacesanchor_priority.py — the 19-entry registry (relocated from memory/events.py in CR-B)
Sixteen reserved-location call sites across the codebase carry the _foray_reserved_emit("<namespace>.<event_kind>", payload) pattern plus a # FORAY_RESERVED_LOCATION comment marker: 3 in audit (CR-A), 1 in memory (CR-B), 12 in credit (CR-C). The emitter is a no-op today; it does nothing on call. When external FORAY integration opens, the emitter is replaced with a real client call; every reserved location becomes a live attestation point without further code changes at the call sites.
The cleanup arc that established this shape replaced three FORAY-shaped tables:
audit.foray_events → audit.events (CR-A, Phase 61)memory_events Phase 25 wiring → cleaned schema with commit_webauthn_attestation rename of the Memory-essential WebAuthn proof column (CR-B, Phase 62)credit.foray_action_flows → credit.flows with 9-value typed event_kind taxonomy + typed columns replacing JSONB-extract reader queries (CR-C, Phase 63)
The substrate hygiene scoping note v0.2, the inventory, the three CR designs, the three Phase implementation notes, and the methodology canon v0.1 are all in the record at substrate/cleanup/ and operations/ — the trajectory of how Loomworks reached this framing is preserved.
Status: Seam-and-stub; full spec hardens before deployment.
OVA (provisional patent, March 2026) provides agent identity and authorization through cryptographic indistinguishability, path-branching topology concealment, and zero-knowledge least-privilege verification. Designed for the case of an AI agent that needs to prove authorization to act without revealing more about the authorizing person than necessary.
OVA's per-Operator credentials gate every consequential operation — reading from a Memory scope, writing to one, invoking a render specialist, calling an external service, committing a held assertion, dispatching a delegation contract. The enforcement happens upstream of implementation. Denials are FORAY-attested alongside permits (when FORAY integration opens).
Loomworks integrates OVA via seam-and-stub progression: the seam (the place OVA will attach) ships now as Loomworks evolves; the stub (a minimal implementation) exercises the seam's contract; the full OVA hardens later. Kaspa vProgs (the substrate OVA requires) are not yet ready. The seam-and-stub posture commits to OVA without forcing it to ship complete.
Status: Principle named; instances multiple.
The three protocols compose into a structural defensibility property that filtering alone cannot match: rules are explicit (in Memory); enforcement happens upstream of implementation (at OVA, when it lands); audit is mechanical (via FORAY, when called). Harms that the rules prohibit become architecturally impossible — not detected-and-refused but never reaching the implementation layer.
Failures look like missing rules (which can be added) or enforcement gaps (which can be closed). They don't look like model jailbreaks. The held-then-commit ceremony, OVA per-Operator credentials, FORAY's append-only attestation, the content-vs-shape boundary at instance emission, and the jurisdiction-governance triangle all instantiate structural defensibility.
The Loomworks-side reserved-location pattern is part of this — Loomworks is positioned to participate in structural defensibility without having shipped the cross-protocol integrations yet.
Status: Pattern named; implementation pending OVA hardening.
OVA's enforcement adapts to the Engagement's current authorization needs without requiring the Engagement to manage credentials directly. When an actor takes on a new role (becomes an Operator, gains Contributor access, claims domain expertise), OVA emits the credentials that role requires. When the role retires, the credentials retire. The Engagement specifies the role-to-permission mapping; OVA executes the credential lifecycle.
Status: Operator Layer in active development; Workshop intentionally frozen at Phase 45.
Status: Built.
Two-step sign-in. Step 1: passkey or organization SSO. Step 2: authenticator code (passkey path only; SSO path completes after Step 1). Auto-submit on sixth digit. No email-credential path. The substrate carries WebAuthn passkey attestation (the commit_webauthn_attestation column on memory_events preserves Operator commit proofs — renamed in CR-B to clarify role).
Status: Built; voice modality layered on top.
A microphone in the engagement-navigation top bar captures audio via Web Speech API; trailing "send" word triggers route (silence-submit threshold Companion-tunable, default 2.5s). Voice provenance is recorded on conversation turns via an input_mode marker; a brass microphone glyph appears on voice-origin turns. Navigational utterances act client-side; others get an inline Companion reply card above main content.
Status: Built (read-only; conversation history + composer + room navigation).
The in-engagement surface is the surface the Operator lives in when working an Engagement. It carries: the conversation history with the Companion (chronologically ordered, voice-provenance marked), the composer (text + voice input), the Engagement's room navigation (Memory, Manifestation, Shaping, Rendering as tabs or panes), and the engagement's seed/identity in a header. Phase 60's Upload Pathway v1 is in flight on the Operator Layer (engine-side not yet shipped) — when complete, files can be brought in through the same in-engagement composer rather than through a separate surface.
Status: Built (Workshop frontend only — read-only relative to engine).
The four-room surface is the engine's internals surface — Memory, Manifestation, Shaping, Rendering as separate rooms with their own views. The Workshop frontend (loomworks-ui) exposes this surface and is intentionally frozen at the Phase 45 shape — read-only relative to the engine, opt-in advanced view for Operators who want to see engine internals. Most Operators never open Workshop; some do, and when they do, it works exactly as it did at Phase 45 close.
Workshop's framing in v0.4 is explicit: Workshop is the engine-internals read-only surface, frozen at Phase 45. Active product development happens in the Operator Layer (loomworks repo). This is not neglect; this is positioning.
Status: Built (conversational; voice-tuned).
Engagement creation happens through a conversation. The Operator opens "new engagement" and the Companion conducts a Discovery dialog — what is this for, what's in scope, who's involved, what's the deliverable. The Discovery dialog produces a seed; the seed is reviewed and committed; the Engagement is born. Phase 53 (Discovery-to-seed skill) and Phase 55 (engagement creation assistance) close this surface end-to-end. Phase 56 voice-tuned the surface — the Operator can conduct Discovery by voice.
Status: Built (loomworks.doneinseven.com, deployed via Cloudflare Pages from the loomworks-marketing repo).
The Loomworks marketing site is a separate repo at /Users/dunin7/loomworks-marketing (Astro / Cloudflare Pages). Last tagged ship: phase-51-marketing-site-and-companion-email (2026-05-09). The site is the public-facing introduction to Loomworks for prospective Operators; the marketing-engagement-creation work landed at Phase 51 ties the marketing site to the Companion-composed email flow for invitations and grant claims.
A marketing-page observation cluster (filed 2026-05-17) named specific corrections needed to the marketing site's room ordering and descriptions; whether those have been applied is operational hygiene state worth tracking.
Status: Investigating (queued).
A first-class mobile experience for Loomworks is queued — investigation document filed (loomworks-mobile-presence-investigation-v0_1). Web-on-mobile works today; a native or PWA mobile experience that handles voice modality well, runs Companion turns offline-ish, and presents the in-engagement surface for thumb interaction is identified work, not yet started.
Status: Built (substrate + Companion-as-Authority); Phase 60 Upload Pathway v1 in flight; reconciliation evaluator built.
The credit system meters Loomworks operations. Each consequential operation (model invocation, render, external service call) costs credits. The credit system is itself two Engagements following the universal-adapter pattern — Credit Management as the Authority that issues grants and decides eligibility, Accounting as the bookkeeper that maintains balances.
Status: Built.
Credits carry model identity. loomworks_credit_haiku, loomworks_credit_sonnet, loomworks_credit_opus are distinct assets. Each represents the right to use a specific tier of model intelligence. The same operation costs different credits depending on which credit type funds it.
Provider tokens (per-model input/output), Whisper seconds, and USD cents are also tracked. An oracle answers per-credit-type rates at query time. Balances are derived artifacts maintained by a database trigger (credit.update_balance_on_flow) on the credit.flows table — the trigger survived CR-C's in-place rename transparently. (Prior versions of this spec referred to "the FORAY flow log"; the cleanup arc replaced that table with credit.flows. The trigger continues to fire on inserts to the renamed table.)
Status: Built.
Credits are not requested as freeform codes; credits are delivered to specific email addresses. The Authority binds a grant to an email at issuance and registers the email hash. Three grant kinds: form-initiated (anyone can request via the public form), Operator-curated (DUNIN7 issues directly), referrer-initiated (existing Operator refers a friend).
Future requests from the same email-hash are recognized — eligible for grants only at the Authority's discretion. Casual abuse (multiple Gmail addresses) becomes self-defeating because each email is consumed against the registry on first grant.
Status: Built (substrate); Phase 48 evaluator built.
A person's relationship with Loomworks is not binary. States: trial, active, suspended, departed. When trial credits exhaust, the user is offered three paths: add their own key (convert to Maker), suspend (hold for N weeks, reactivate via original auth), or delete now. Suspension expires to deletion if not reactivated. Deletion writes to a FORAY-reserved location for future attestation when external FORAY integration opens.
Status: Built (Phase 50).
The Companion on the Credit Management Engagement reads Memory assertions (model profile knowledge, campaign data, referral policy) and proposes grant decisions for Operator approval. This is the first delivery-class instance of the proposer/committer pattern: the Companion proposes; the Operator commits. The substrate supports the full flow; voice templates carry the proposal rationale in Operator-vocabulary.
Status: Operative; methodology canon v0.1 establishes four canonized principles; consolidation ongoing.
Loomworks operates under a set of disciplines that have crystallized through the build process. Some are foundational; some are named patterns that emerge across multiple instances; some are candidates being evaluated for promotion. This section names the operative ones.
The methodology canon is the standing surface for principles that have been earned through execution evidence. Each canon principle has been validated across multiple instances of real CR execution. The canon lives at record.dunin7.com/view/operations/loomworks-methodology-canon-v0_1.html and evolves via additions (new principles meeting evidence threshold), refinements (boundary condition sharpening), and rare corrections.
Foundational disciplines (always operative):
Status: Operative.
The Operator has final authority over their Engagements. Companion proposals require Operator commitment to become durable. Automatic state transitions on artifacts the Operator has authority over are a category error; the machine surfaces and signals, the Operator approves.
Status: Operative.
Renders are never edited in place. New memory is the new write. When a render needs to change, the Shape that produced it changes (new assertion in Memory); the render is regenerated. The audit trail flows continuously through Memory; nothing slips outside.
Status: Operative.
The Operator's path never contains technical vocabulary. The Companion uses Operator vocabulary throughout — project, note, specification, artifact — not engine vocabulary — engagement, assertion, shape, render. Decisions are requested in plain English. Technical terms live in code, not in conversation.
Status: Operative.
No disabled buttons, no grayed-out options, no "you don't have permission" states. If you can't do it, it doesn't exist on your surface. The interface reshapes itself to the role, silently. A Contributor's dashboard has no "New engagement" button — not disabled, absent.
Status: Operative.
Memory contributions don't enter Memory immediately. They sit in a held state, attributable to a contributor, awaiting commit. The Operator's commit action is what makes the contribution durable. Retraction before commit is silent — the assertion never existed. Retraction after commit is governance-bearing — the trail shows existence, contribution, retraction.
Status: Operative.
The trajectory of how the project arrived at a decision matters as much as the decision itself. Corrections, alternatives considered and set aside, rejected paths, and moments of crystallization are preserved alongside chosen directions. This document itself is structured around the principle.
Status: Operative (named; multiple instances).
During a phase's build, friction surfaces. Three paths handle different scales: naming-only resolution for small friction, halt-and-amend for large friction, and Operator-elective amendment scoping for friction that exceeds naming-only but does not breach halt-thresholds individually. The three paths form a deliberate discipline.
Status: Operative.
Some methodology pieces are too large to ship in a single phase but too important to defer indefinitely. The seam (where the future capability will attach) ships now, with a stub (a minimal implementation that exercises the seam's contract). The seam is real; the stub is provisional; the progression replaces the stub with the full implementation when the time comes. OVA integration follows this pattern; FORAY integration's reserved-location pattern is a generalization (the call site is the seam; the no-op is the stub; the real client call is the future replacement).
Status: Operative.
The Companion's relationship to Operator authority can take two shapes. Companion-mediated: the Companion acts on the Operator's behalf; the Operator's commit closes the loop. Operator-direct: the Operator is the actor; no Companion delegation in between. Both are first-class. Some actions don't fit Companion-mediated cleanly — the Companion is not always between the Operator and their own state.
Status: Operative (credit system instance).
Some governance problems split naturally into two Engagements: an Authority that sets policy and issues decisions, and an Accounting that maintains state and reconciles. The credit system is the first instance.
Status: Investigating (pattern named).
Every Engagement draws on domain from however many Memory scopes are relevant for that Engagement, in that jurisdiction, for that Operator, at that moment. The architecture is neutral about the count; the composition is the load-bearing operation. The Companion composes across all relevant scopes at the moment of operation.
Status: Operative.
Many extensions to Loomworks follow the same pattern: declare the new type, register the actor that handles it, the engine matches at runtime. Specification grammars, transformation skills, render specialists, content types, action types, integration types, authorization types — all surface this shape. The pattern is reusable.
Status: Operative (Phase 60 first instance; principle named).
The Companion is the primary surface for all Operator-system interaction including preferences, configuration, and policy — not just conversational work. Phase 60's tune_setting handler is the first instance. The principle generalizes; future Operator-system surfaces should be conversational by default.
The methodology canon at record.dunin7.com/view/operations/loomworks-methodology-canon-v0_1.html holds four principles validated through the substrate hygiene cleanup arc. Brief summaries here; the canon is the authoritative source.
Per-call-site reserved emit (Operative; canon v0.1). When a code path is being prepared for future external integration, the reserved-location marker lives at each business-event site, not centralized in helper writers. Validated at 3 + 1 + 12 sites across CR-A, CR-B, CR-C.
Test-filename-to-current-substrate alignment (Operative; canon v0.1). When a test's filename framing references a cleaned-up origin, rename to reflect what the test verifies today, or delete if the underlying functionality is gone. Four-instance evidence including a negative case at CR-C.
Migration strategy: rename when downstream bindings exist; recreate when independent (Operative; canon v0.1). In-place rename preserves downstream bindings (triggers, FKs, indexes that bind to underlying identity); drop-and-recreate requires re-establishment. Choose by what binds, not by default preference.
Inventory enumeration vs cognitive density (Operative; canon v0.1). Inventories enumerate references but undercount cognitive density per reference. Design steps should grep for assertion patterns and reader sites directly, not inherit inventory counts; per-test-function enumeration is more reliable than per-file enumeration.
Status: Active investigation.
Questions where the architecture is not yet settled. These are areas where the next substantial work will land.
Resolved since v0.3: The FORAY-as-substrate framing has been replaced by FORAY-as-external-service. See Section 09.
Status: Investigating (Phase 60 in flight on Operator Layer).
The upload pathway works in substrate but is unmounted on the in-engagement surface. Operators cannot bring materials in through the surface they actually use. Phase 60's Upload Pathway v1 (Operator Layer side in flight; engine side not yet shipped) is the work to mount this. Until Phase 60 ships end-to-end, Operators upload through a separate older surface.
Status: Identified, not started.
Memory accumulates over time and may grow stale, duplicate, drift. Stewardship is the discipline of recognizing duplicates (and near-duplicates), surfacing staleness, and offering consolidation. Project memory frames this as a Companion responsibility — the Companion sweeps Memory periodically, surfaces candidates, the Operator commits or declines. Substrate, surface, and Companion behavior are all to be designed. Memory stewardship is part of Phase C of the development assessment.
Status: Investigating.
The seed is treated as a one-time creation rather than as the Engagement's living frame of reference. The Operator can't see it, refine it, or use it as the relevance frame for filtering contributions. Making the seed a permanent first-class affordance — creation surfaced when absent; viewable and editable when present — is identified work.
Status: Investigation filed.
Whether the seed-creation conversation is itself an Engagement (with prefix S#### sibling-numbered to the target E####) or whether it lives as a dedicated surface separate from the Engagement model. Recursion model has methodological coherence; practical implications need evaluation. Deferred-direction document filed.
Status: Investigating.
The substrate supports assertion lifecycle operations; the surface affordance for addressing — M-prefix identifiers, selection mode, spoken-and-typed addressing — is being scoped.
Status: Planned (identified, not started).
The Companion should evaluate contributions for relevance against the Engagement's seed, mitigating drift and bulk. Today, no evaluation happens; all contributions land regardless of relevance. Pre-extraction filtering vs post-extraction tagging is one design question. Operator-elicitation vs silent extraction is another.
Status: Planned.
When an Operator says something in one Engagement that might belong elsewhere, the Companion should recognize the mismatch and offer to redirect. Not yet a Companion behavior; the substrate supports redirect at the lifecycle level (Phase 17), but the awareness layer that triggers it is missing.
Status: Planned.
The substrate distinguishes Operator from Contributor at the membership level, but the surface treats all turns as if they're from the Engagement's primary Operator. A Contributor speaking gets labeled as if they were the Operator. Role-aware author labels need wiring. (The Shared-Subject Engagement Pattern v0.1 amplifies the urgency; OVA's eventual landing transforms what's possible here.)
Status: Planned (identified close-out work).
The Discovery dialog that births a new Engagement leaves its conversation at engagement_id IS NULL. The new Engagement's surface fetches its own conversation history and returns empty. The conversation that birthed the Engagement is unreachable from that Engagement's surface. Either re-parent on commit, or surface the audit event's turn references in the Engagement's UI.
Status: Planned (prerequisite for addressable assertions).
Collapse display_identifier into operator_sequence_number; let the frontend render the E prefix and pad as needed. Eliminates the format break at E9999 and aligns the codebase to a cleaner pattern.
Status: Investigating (newly named in v0.4).
Several operational items have accumulated and warrant a dedicated maintenance pass:
test_api_assertion_retract (JSON-encoding bug at app.py:461) and test_phase_44_evaluator::test_concern_scan_does_not_re_fire_within_dedup_window (dedup-window flake). Both filed across Phase 61/62/63 implementation notes as future-ledger items.Status: Phase A complete (substrate hygiene cleanup arc closed); Phase B and Phase C identified, not started.
The development assessment v0.1 (filed in substrate/where-we-are-in-loomworks-development-assessment-v0_1.html) framed three phases of work necessary for Memory management to reach satisfactory status:
The next horizon decision (post-CR-C) is Phase B vs Phase C vs operational hygiene cluster. No selection has been made yet.
Status: Stable; extends as new concepts crystallize.
_foray_reserved_emit marker awaiting actual FORAY integrationThe Companion uses Operator vocabulary throughout. The engine vocabulary above is internal; the Operator does not see it. Operator-facing equivalents:
Status: Convention established; honored across v0.1 → v0.4.
This document carries a version in both filename and title. Working drafts are v0.x; the first declared-released version is v1.0. Patch versions (v1.0.1) are for small fixes; minor versions (v1.1) are for additions; major versions (v2.0) are for substantive reworkings. Bump on substantive change; an unnecessary increment is cheap, but a collision with an older version destroys history.
Prior versions stay in the record per discovery-trajectory discipline. v0.3 stays at architecture/loomworks-architecture-specification-v0_3.html; v0.4 lands alongside it.
Sparse sections are honest. Where the project hasn't decided something, the section says so. Where built reality is partial, the section says what's built and what's not. Where future work is anticipated, the section holds the slot and notes "to be developed." Pretending sections are complete when they aren't creates the same drift this document was created to prevent.
When a change to one component constrains or enables work in another, that should be noted in both places — through cross-references and through explicit cross-cutting-implications notes. Most of the project's accumulated friction has come from changes whose cross-cutting implications weren't surfaced at the time.
DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks Architecture Specification — v0.4 — 2026-05-25 Foundational scaffold — designed to grow