{"slug":"architecture/TWIN_CONSTITUTION","title":"Twin Constitution","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/TWIN_CONSTITUTION.mdx","bytes":3018,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nStatus: SUPERSEDED / ABSORBED — historical subsystem constitution. Current authority: [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2.\nScope: Twin runtime behavior, OODA loop, context binding, memory, learning, and proposal grammar.\nCanonical Owner: IntegrateWise Platform\nLast Verified: 2026-07-20\n\n---\n\n## 1. Purpose\n\nThis document defines how the Twin operates.\n\nThe Twin is the silent cognitive partner inside the Adaptive Workbench. It observes, orients, decides, and proposes. It does not chat. It does not impersonate execution.\n\n---\n\n## 2. Core Rules\n\n1. Twin is always context-bound to the focused entity, view, or department.\n2. Twin never writes canonical state without governance approval.\n3. Twin proposals are immutable once emitted.\n4. Twin output is never mixed into Spine entities.\n5. Twin memory has distinct layers: User, Work, Org, Connector, Knowledge.\n\n---\n\n## 3. OODA Loop\n\n```text\nObserve\n  │\n  ▼\nOrient\n  │\n  ▼\nDecide\n  │\n  ▼\nAct → Proposal\n```\n\n- Observe: ingest signals from connectors, Spine, and events.\n- Orient: build context from memory, playbooks, and entity relationships.\n- Decide: score confidence, risk, and evidence.\n- Act: emit a proposal and wait for explicit human approval. Confidence and\n  policy may prioritize or deny a proposal, but never substitute for approval.\n\n---\n\n## 4. Twin Controls\n\n| Control | OODA    | Behavior                                                  |\n| ------- | ------- | --------------------------------------------------------- |\n| Store   | Observe | Capture truth — notes, decisions, evidence                |\n| Ask     | Orient  | Query focused context — no chat                           |\n| Assign  | Decide  | Delegate cognitive work — research, draft, analyze        |\n| Approve | Act     | Authorize gated execution — mint token, trigger execution |\n\n---\n\n## 5. Memory Layers\n\n| Layer            | Scope        | Governance                |\n| ---------------- | ------------ | ------------------------- |\n| User Memory      | Personal     | Private                   |\n| Work Memory      | Role         | Role-governed             |\n| Org Memory       | Organization | Founder approval required |\n| Twin Memory      | System       | System                    |\n| Connector Memory | Source       | Source-governed           |\n| Knowledge Memory | Curated      | Curator approval          |\n\n---\n\n## 6. Proposal Grammar\n\n```typescript\ninterface TwinProposal {\n  id: string;\n  confidence: number;\n  evidence: Evidence[];\n  action: CapabilityId;\n  input: Record<string, unknown>;\n  rollback: string;\n  governance: GovernanceToken;\n}\n```\n\n---\n\n## 7. Invariants\n\n1. Twin never exposes raw provider errors as operational truth.\n2. Twin never executes without an explicit human approval signal bound to the\n   exact proposal version.\n3. Twin performance is measured by detection, accuracy, proposal quality, and response time.\n4. Twin behavior is deterministic per view contract.\n"}