{"slug":"business/LANGUAGE_CONSISTENCY_STATUS","title":"IntegrateWise — Language Consistency Status","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/LANGUAGE_CONSISTENCY_STATUS.mdx","bytes":13436,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Date:** 2026-06-09  \n> **Version:** 1.0.0  \n> **Authority:** Nirmal (Founder)  \n> **Status:** COMPLIANCE AUDIT\n\n---\n\n## The ONE LANGUAGE Principle\n\n**\"REPO LANGUAGE TO BE ONE IN TERMS OF ALL\"** means:\n\n1. **Code Language:** TypeScript ONLY (no Python, no other languages)\n2. **Architecture Language:** ONE consistent terminology across all docs\n3. **Documentation Voice:** ONE consistent explanation pattern\n4. **API Contracts:** ONE consistent interface (Gateway-first)\n5. **Conceptual Models:** ONE mental model (no conflicting metaphors)\n\n---\n\n## ✅ CODE LANGUAGE COMPLIANCE\n\n### Status: **PASS**\n\n**Rule:** TypeScript only. No Python anywhere in the codebase (excluding node_modules).\n\n**Verification:**\n\n```bash\nfind . -name \"*.py\" -type f -not -path \"*/node_modules/*\"\n# Result: ZERO Python files\n```\n\n**Source files checked:**\n\n- ✅ `services/*/` — All TypeScript\n- ✅ `apps/web/src/` — All TypeScript\n- ✅ `packages/*/` — All TypeScript\n- ✅ `scripts/` — All TypeScript/Bash\n- ✅ No Python in custom code\n\n**Enforcement:**\n\n- AGENTS.md hard rule in every workspace\n- CI/CD pre-commit hooks (if configured)\n\n---\n\n## ⚠️ ARCHITECTURE LANGUAGE COMPLIANCE\n\n### Status: **NEEDS CLEANUP**\n\n**Rule:** ONE consistent terminology across all documentation.\n\n### Current Issues:\n\n#### 1. **Twin Architecture Conflation** ⚠️\n\n**Location:** `services/twin-orchestrator/src/index.ts`\n\n**Problem:** File contains BOTH:\n\n- ✅ Correct cognitive-only architecture (scheduled observe loop, pure delegation)\n- ❌ Old infrastructure code (Hono app with chat endpoints, AI inference, RAG)\n\n**Evidence:**\n\n```typescript\n// CORRECT (Cognitive layer):\nexport async function scheduled(event: ScheduledEvent, env: Env): Promise<void>;\n\n// INCORRECT (Infrastructure layer - should be in intelligence worker):\napp.post(\"/v1/chat/completions\", async (c) => {\n  // This conflates Twin with AI infrastructure\n});\n```\n\n**Action Required:**\n\n- Remove Hono app and `/v1/chat/completions` endpoint from twin-orchestrator\n- Chat endpoints belong in `services/intelligence` worker\n- Twin should ONLY have: scheduled loop + /health + /observe + /state\n\n#### 2. **Memory Write Terminology** ⚠️\n\n**Issue:** Multiple terms used for the same concept.\n\n**Inconsistent Usage:**\n\n- \"Triage Bot\" (correct canonical term)\n- \"Governance\" (overlapping but different concept)\n- \"Memory Writer\" (too generic)\n- \"Proposal approver\" (correct for proposals, not memory writes)\n\n**Canonical Mapping:**\n\n```\nMemory Writes → ONLY via Triage Bot (governance-gated)\nProposals → ONLY via Governance Queue (HITL approval)\nSpine Writes → ONLY via Pipeline Worker (sole Supabase credential holder)\n```\n\n**Action Required:**\n\n- Update all docs to use \"Triage Bot\" consistently for org_memory writes\n- Update all docs to use \"Governance Queue\" for proposals\n- Never use \"Memory Writer\" without clarifying \"Triage Bot\"\n\n#### 3. **Spine vs Supabase Confusion** ⚠️\n\n**Issue:** Some docs refer to \"Supabase\" as the data layer.\n\n**Canonical Truth:**\n\n- **Spine** = The conceptual memory substrate (canonical entities + relationships)\n- **Supabase** = The fortress database (physical storage, never exposed)\n- **D1** = The active read layer (operational queries)\n- **KV** = The hot cache (60-300s TTL)\n\n**Incorrect phrasing:**\n\n- \"Query Supabase for entities\" ❌\n- \"Spine writes to Supabase\" ❌\n\n**Correct phrasing:**\n\n- \"Query Spine (via D1) for entities\" ✅\n- \"Pipeline worker writes to Spine (backed by Supabase)\" ✅\n\n**Action Required:**\n\n- Search/replace all docs: \"Supabase\" → \"Spine (Supabase-backed)\" when referring to data operations\n- Frontend docs: Always say \"CF Gateway → D1\" not \"Supabase\"\n\n#### 4. **MCP vs Continuity Bridge** ⚠️\n\n**Issue:** Overlapping terminology.\n\n**Canonical Mapping:**\n\n```\nMCP = Model Context Protocol (18 tools: memory.*, spine.*, signal.*, proposal.*)\nContinuity Bridge = MCP + Gateway + Spine + Memory + Governance (the system)\nTwin Runtime = Cognitive orchestrator using Continuity Bridge tools\n```\n\n**Incorrect usage:**\n\n- \"MCP server\" when referring to the entire system ❌\n- \"Continuity\" when referring to just MCP tools ❌\n\n**Correct usage:**\n\n- \"MCP connector\" = The worker exposing MCP tools ✅\n- \"Continuity Bridge\" = The architectural layer ✅\n- \"Twin uses MCP tools via Continuity Bridge\" ✅\n\n---\n\n## ⚠️ DOCUMENTATION VOICE COMPLIANCE\n\n### Status: **PARTIALLY COMPLIANT**\n\n**Rule:** ONE consistent explanation pattern across all documentation.\n\n### Current Issues:\n\n#### 1. **Architecture Explanation Levels** ⚠️\n\n**Problem:** Some docs explain from scratch, others assume deep context.\n\n**Examples:**\n\n- `AGENTS.md` = Assumes reader knows the system (correct for agent guidelines)\n- `TWIN_AS_COGNITIVE_ORCHESTRATOR.md` = Explains from first principles (correct for architecture)\n- `FRONTEND_LAYER_MAP.md` = Mix of both (needs separation)\n\n**Action Required:**\n\n- Split `FRONTEND_LAYER_MAP.md` into:\n  - `FRONTEND_ARCHITECTURE.md` (principles, high-level)\n  - `FRONTEND_API_CONTRACT.md` (concrete endpoints and hooks)\n\n#### 2. **Audience Targeting** ⚠️\n\n**Problem:** Not always clear who the doc is for.\n\n**Canonical Audience Labels:**\n\n- `[AGENT]` = AI agents (Hermes, Kiro, Claude, Copilot)\n- `[DEV]` = Human developers (IntegrateWise team)\n- `[ARCH]` = Architects / decision-makers (Nirmal + senior eng)\n- `[PUBLIC]` = External users / customers\n\n**Action Required:**\n\n- Add audience label to every doc filename or frontmatter\n- Example: `TWIN_AS_COGNITIVE_ORCHESTRATOR.md` → `[ARCH] TWIN_AS_COGNITIVE_ORCHESTRATOR.md`\n\n#### 3. **Version Tagging** ⚠️\n\n**Problem:** Not all docs show when they were last canonical.\n\n**Action Required:**\n\n- Add to every doc:\n  ```markdown\n  > **Date:** 2026-06-09  \n  > **Version:** 1.0.0  \n  > **Authority:** Nirmal (Founder)  \n  > **Status:** CANONICAL / DRAFT / DEPRECATED\n  ```\n\n---\n\n## ✅ API CONTRACTS COMPLIANCE\n\n### Status: **PASS (SPEC COMPLETE)**\n\n**Rule:** ONE consistent interface (Gateway-first for all frontend data).\n\n**Verification:**\n\n- ✅ All frontend data flows through `gateway.dev.integratewise.ai`\n- ✅ Zero direct Supabase from `apps/web/` (when `VITE_SPINE_PROVIDER=gateway-proxy`)\n- ✅ All auth via `auth.integratewise.ai` (OAuth 2.0 RS256)\n- ✅ All MCP tools via `mcp.integratewise.ai`\n\n**Spec Status:**\n\n- ✅ `.kiro/specs/cf-frontend-wiring/requirements.md` (13 requirements)\n- ✅ `.kiro/specs/cf-frontend-wiring/tasks.md` (14 tasks, ALL COMPLETE)\n\n**Implementation Status:**\n\n- ✅ AuthManager module\n- ✅ GatewayHttpClient module\n- ✅ SpineGatewayAdapter (drop-in replacement)\n- ✅ TanStack Query configuration\n- ✅ SSE real-time client\n- ✅ Onboarding flow API calls\n- ✅ Build-time Supabase enforcement\n\n**No action required.**\n\n---\n\n## ⚠️ CONCEPTUAL MODELS COMPLIANCE\n\n### Status: **NEEDS CONSOLIDATION**\n\n**Rule:** ONE mental model for how the system works.\n\n### Current Issues:\n\n#### 1. **Twin Identity Confusion** ⚠️\n\n**Problem:** Twin described differently across docs.\n\n**Conflicting descriptions:**\n\n- \"The Twin is a chat agent\" ❌\n- \"The Twin is an AI assistant\" ❌\n- \"The Twin is the cognitive orchestrator\" ✅\n\n**Canonical Definition:**\n\n```\nThe Twin = Cognitive Orchestrator\n├─ Observes (Memory, Objectives, Governance, Operations, Time)\n├─ Reasons (via Intelligence worker delegation)\n├─ Proposes (creates proposals, does NOT execute)\n├─ Coordinates (dispatches to Act, monitors outcomes)\n└─ Learns (proposes memory updates via Triage Bot)\n\nThe Twin is NOT:\n- An AI model (delegates to Intelligence worker)\n- A chat interface (OWUI is ONE interface to Twin)\n- An execution engine (Act worker executes)\n```\n\n**Action Required:**\n\n- Update `README.md` to use canonical definition\n- Update all product docs to use canonical definition\n- Add diagram: Twin (cognitive) vs Intelligence (infrastructure)\n\n#### 2. **Layer Naming Inconsistency** ⚠️\n\n**Problem:** Multiple names for the same layers.\n\n**Inconsistent usage:**\n\n- \"L0/L1/L2/L3/L4\" (correct numbered layers)\n- \"Onboarding/Workbench/Overlay/Twin/Memory\" (correct named layers)\n- \"Frontend/Cognitive/Memory\" (architectural layers, not UX layers)\n- \"Infrastructure/Orchestration\" (system layers, not UX layers)\n\n**Canonical Mapping:**\n\n```\nUX LAYERS (User-facing):\n├─ L0 = Onboarding (entry → setup → first value)\n├─ L1 = Workbench (personal + work daily use)\n├─ L2 = Overlay (awareness drawer, passive presence)\n├─ L3 = OWUI (full reasoning surface, voice, agent)\n└─ L4 = Memory (Coda knowledge projection)\n\nSYSTEM LAYERS (Architecture):\n├─ Infrastructure (Workers: pipeline, intelligence, gateway, connector)\n├─ Cognitive (Twin orchestrator)\n├─ Governance (Triage Bot, HITL approval)\n└─ Memory (Spine, org_memory, personal_memory, conversational_memory)\n```\n\n**Action Required:**\n\n- Never mix UX layer names (L0-L4) with system layer names (Infrastructure/Cognitive)\n- When discussing UX: use L0/L1/L2/L3/L4\n- When discussing architecture: use Infrastructure/Cognitive/Governance/Memory\n\n#### 3. **Data Flow Mental Model** ⚠️\n\n**Problem:** Not consistently explained.\n\n**Canonical Data Flow:**\n\n```\nUSER\n ↓\nL1 View (React component)\n ↓\nspineClient.from(\"entities\").select() (SpineGatewayAdapter)\n ↓\nGatewayHttpClient → gateway.dev.integratewise.ai\n ↓\nCF Gateway (auth + tenant + rate limit)\n ↓\nService binding → downstream worker (pipeline, intelligence, knowledge)\n ↓\nD1 query (integratewise-spine-cache)\n ↓\nKV cache check (if hot)\n ↓\nResponse (Supabase-compatible shape)\n ↓\nTanStack Query cache\n ↓\nReact component renders\n```\n\n**Write Flow (proposals):**\n\n```\nUSER approves proposal\n ↓\nL1 component calls spineClient\n ↓\nGateway → Proposal Queue\n ↓\nGovernance approves\n ↓\nAct worker executes\n ↓\nPipeline worker writes to Spine (Supabase)\n ↓\nD1 mirror updated\n ↓\nSSE signal to frontend\n ↓\nTanStack Query invalidates + refetches\n```\n\n**Action Required:**\n\n- Add canonical data flow diagram to `ARCHITECTURE_AND_DATA_FLOW.md`\n- Reference this diagram from all docs that discuss data operations\n\n---\n\n## 🎯 ACTION PLAN\n\n### Immediate (Today)\n\n1. ✅ **Create this status document**\n2. ⏳ **Clean up `services/twin-orchestrator/src/index.ts`:**\n   - Remove Hono app\n   - Remove `/v1/chat/completions` endpoint\n   - Remove all AI inference code\n   - Keep ONLY: scheduled loop, /health, /observe, /state\n3. ⏳ **Update canonical architecture docs:**\n   - Add audience labels `[AGENT]`, `[DEV]`, `[ARCH]`, `[PUBLIC]`\n   - Add version/date/authority frontmatter to all canonical docs\n   - Verify terminology consistency (Spine, Triage Bot, Governance Queue)\n\n### Short-term (This Week)\n\n4. ⏳ **Create missing architecture diagrams:**\n   - Twin (cognitive) vs Intelligence (infrastructure)\n   - Canonical data flow (read + write)\n   - MCP tools vs Continuity Bridge\n5. ⏳ **Split large docs:**\n   - `FRONTEND_LAYER_MAP.md` → `FRONTEND_ARCHITECTURE.md` + `FRONTEND_API_CONTRACT.md`\n6. ⏳ **Terminology search/replace across all docs:**\n   - \"Supabase queries\" → \"Spine queries (D1)\"\n   - \"Memory writer\" → \"Triage Bot\"\n   - \"MCP server\" → \"MCP connector\" (when appropriate)\n\n### Medium-term (Next Sprint)\n\n7. ⏳ **Create canonical glossary:**\n   - Single source of truth for all terms\n   - Cross-referenced from all docs\n   - Enforced via linter (future)\n8. ⏳ **Document review process:**\n   - All new docs must pass language consistency check\n   - All doc updates require canonical glossary alignment\n\n---\n\n## ✅ CURRENT COMPLIANCE SCORE\n\n| Category                 | Status                 | Score   |\n| ------------------------ | ---------------------- | ------- |\n| Code Language            | ✅ PASS                | 100%    |\n| Architecture Terminology | ⚠️ NEEDS CLEANUP       | 70%     |\n| Documentation Voice      | ⚠️ PARTIALLY COMPLIANT | 75%     |\n| API Contracts            | ✅ PASS                | 100%    |\n| Conceptual Models        | ⚠️ NEEDS CONSOLIDATION | 65%     |\n| **OVERALL**              | **⚠️ 82% COMPLIANT**   | **82%** |\n\n**Target:** 100% compliant by end of week.\n\n---\n\n## ENFORCEMENT GOING FORWARD\n\n### Code Language (TypeScript Only)\n\n1. **Pre-commit hook:**\n\n   ```bash\n   # .git/hooks/pre-commit\n   if git diff --cached --name-only | grep -E '\\.py$' | grep -v node_modules; then\n     echo \"ERROR: Python files detected. IntegrateWise is TypeScript-only.\"\n     exit 1\n   fi\n   ```\n\n2. **CI check:**\n   ```yaml\n   # .github/workflows/language-check.yml\n   - name: Verify no Python\n     run: |\n       if find . -name \"*.py\" -not -path \"*/node_modules/*\" | grep .; then\n         echo \"Python files found. Repo is TypeScript-only.\"\n         exit 1\n       fi\n   ```\n\n### Architecture Language (Terminology)\n\n1. **Canonical glossary:** `docs/GLOSSARY.md` (to be created)\n2. **Linter:** Custom ESLint rule checking for deprecated terms in comments/docs\n3. **Doc review checklist:** All PRs touching docs must verify terminology\n\n### Documentation Voice (Consistency)\n\n1. **Template:** `docs/templates/CANONICAL_DOC_TEMPLATE.md` (to be created)\n2. **Audience labels:** Required in frontmatter or filename\n3. **Version tracking:** All canonical docs must have date/version/authority\n\n---\n\n**Document Status:** LIVING DOCUMENT  \n**Next Review:** 2026-06-16  \n**Owner:** Nirmal (Founder) + Hermes (Operator)\n"}