{"slug":"architecture/UNIFIED_GOVERNANCE_SPEC","title":"Unified Governance Specification","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/UNIFIED_GOVERNANCE_SPEC.mdx","bytes":14177,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** Canonical governance architecture  \n> **Date:** July 12, 2026  \n> **Authority:** Nirmal (Founder)  \n> **Canonical Reference:** [CANONICAL_PLATFORM_ARCHITECTURE.md](./CANONICAL_PLATFORM_ARCHITECTURE.md)  \n> **Reconciles:** Document 1 (confidence-based governance) and Document 3 (authority-based governance)  \n> **Cross-Reference:** [PLANE_LAYER_CROSS_REFERENCE.md](./PLANE_LAYER_CROSS_REFERENCE.md)\n\n---\n\n## The Problem\n\nTwo governance models exist across the architecture documents:\n\n1. **Document 1 (Confidence-Based):** AI proposals are scored 0.0–1.0. Thresholds determine disposition:\n   - `< 0.70 → discard`\n   - `0.70–0.85 → queue for HITL`\n   - `≥ 0.85 → prioritize for HITL; never auto-approve`\n\n2. **Document 3 (Authority-Based):** Every action is evaluated against policy, authority, evidence, risk, scope, and approval requirements. Three outcomes: `ALLOW · DENY · REQUIRE APPROVAL`.\n\nThese are not conflicting — they are orthogonal dimensions of the same governance problem. A complete governance system needs both.\n\n---\n\n## The Unified Model: Three-Layer Governance\n\n```\n                    GOVERNANCE ENGINE\n                          │\n          ┌───────────────┼───────────────┐\n          │               │               │\n     AUTHORITY        CONFIDENCE       EVIDENCE\n     GOVERNANCE       GOVERNANCE       GOVERNANCE\n          │               │               │\n   Who can do what   How sure is the   What proof exists\n   under what policy  system about      for this action?\n          │           this proposal?        │\n          │               │               │\n          └───────────────┼───────────────┘\n                          │\n                    UNIFIED OUTCOME\n                          │\n              ┌───────────┼───────────┐\n              │           │           │\n           ALLOW       DENY      REQUIRE\n                                  APPROVAL\n```\n\n### Layer 1: Authority Governance (Who)\n\n**Question:** Is this user authorized to perform this action under this policy?\n\n**Inputs:**\n\n- User identity (JWT claims)\n- User role (RBAC)\n- Tenant policy (configuration)\n- Action scope (which entity, which field, which system)\n- Time window (business hours, deadline constraints)\n- Delegation chain (is this user acting on behalf of someone?)\n\n**Evaluation:**\n\n```typescript\ninterface AuthorityCheck {\n  userId: string;\n  tenantId: string;\n  action: string; // e.g., \"capability:invoke\", \"spine:write\", \"proposal:approve\"\n  entity?: string; // which entity this action targets\n  scope?: string; // field-level or system-level scope\n  delegationChain?: string[]; // who delegated this action\n}\n\ninterface AuthorityResult {\n  allowed: boolean;\n  reason: string; // why allowed or denied\n  policyRef: string; // which policy was applied\n  requiresApproval: boolean; // even if allowed, does it need approval?\n  approver?: string; // who must approve\n}\n```\n\n**Rules:**\n\n1. Authority is checked BEFORE confidence. If authority denies, the action stops.\n2. Authority can REQUIRE APPROVAL even when confidence is high.\n3. Authority can ALLOW auto-execution when confidence is high.\n4. Authority can DENY regardless of confidence level.\n\n### Layer 2: Confidence Governance (How Sure)\n\n**Question:** How confident is the AI system in this proposal?\n\n**Inputs:**\n\n- Model confidence score (0.0–1.0)\n- Proposal complexity (single action vs. multi-step workflow)\n- Historical accuracy (how often has this model been right for this action type?)\n- Context quality (how complete is the input data?)\n\n**Evaluation:**\n\n```typescript\ninterface ConfidenceCheck {\n  proposalId: string;\n  confidence: number; // 0.0–1.0\n  modelId: string; // which model generated this\n  actionType: string; // simple vs. complex\n  contextCompleteness: number; // 0.0–1.0\n}\n\ninterface ConfidenceResult {\n  disposition: \"auto_approve\" | \"hitl_review\" | \"discard\";\n  reason: string;\n  threshold: number; // which threshold was applied\n}\n```\n\n**Thresholds (Configurable per Tenant):**\n\n```typescript\ninterface ConfidenceThresholds {\n  autoApprove: number; // default: 0.85\n  hitlReview: number; // default: 0.70\n  // below hitlReview → discard\n}\n```\n\n**Rules:**\n\n1. Confidence is checked AFTER authority. Authority must allow first.\n2. High confidence + authority allowed = prioritize and prepare for human\n   approval; confidence never mints authority.\n3. Medium confidence + authority allowed = HITL review required.\n4. Low confidence = discard (regardless of authority).\n\n### Layer 3: Evidence Governance (What Proof)\n\n**Question:** What evidence exists to support this action and its outcome?\n\n**Inputs:**\n\n- Intent (what was the user trying to do?)\n- Action (what did the system do?)\n- Evidence (what proof exists that the action was performed correctly?)\n- Outcome (what was the result?)\n- Audit trail (who approved, when, under what policy?)\n\n**Evaluation:**\n\n```typescript\ninterface EvidenceCheck {\n  intentId: string;\n  actionId: string;\n  evidence: EvidenceRecord[];\n  outcome: OutcomeRecord;\n}\n\ninterface EvidenceResult {\n  valid: boolean;\n  auditRef: string; // reference to audit log\n  promotionEligible: boolean; // can this outcome be promoted to Spine?\n}\n```\n\n**Rules:**\n\n1. Evidence is collected AFTER execution. It does not gate the action.\n2. Evidence is required for Spine promotion. No evidence = no promotion.\n3. Evidence is required for audit. All actions must have evidence.\n4. Evidence quality determines promotion confidence.\n\n---\n\n## The Governance Flow\n\n```\nUSER / TWIN INTENT\n        │\n        ▼\n┌───────────────────┐\n│  AUTHORITY CHECK  │ ◄── Who is this user? What policy applies?\n│                   │     What scope? What delegation?\n│  ALLOW / DENY /   │\n│  REQUIRE APPROVAL │\n└────────┬──────────┘\n         │\n    DENY? ──► STOP (return denial reason)\n         │\n    ALLOW? │\n         ▼\n┌───────────────────┐\n│ CONFIDENCE CHECK  │ ◄── How sure is the AI? What threshold?\n│                   │     What action complexity? What context quality?\n│  AUTO / HITL /    │\n│  DISCARD          │\n└────────┬──────────┘\n         │\n    DISCARD? ──► STOP (return discard reason)\n         │\n    HITL? │\n         ▼\n┌───────────────────┐\n│  HITL REVIEW      │ ◄── Present proposal to human\n│                   │     Show intent, confidence, evidence, impact\n│  APPROVE / REJECT │\n│  / MODIFY         │\n└────────┬──────────┘\n         │\n    REJECT? ──► STOP (return rejection reason)\n         │\n    APPROVE? │\n         ▼\n┌───────────────────┐\n│    EXECUTION      │ ◄── Hermes orchestrates\n│                   │     Capability Fabric resolves how\n│  LOCAL / API /    │     Sync Policy determines when\n│  DISTRIBUTED      │\n└────────┬──────────┘\n         │\n         ▼\n┌───────────────────┐\n│ EVIDENCE CAPTURE  │ ◄── Record intent, action, evidence, outcome\n│                   │     Write to audit log\n│  AUDIT LOG        │     Prepare for Spine promotion\n└────────┬──────────┘\n         │\n         ▼\n┌───────────────────┐\n│ SPINE PROMOTION   │ ◄── Promote outcome to canonical truth\n│                   │     Invalidate cache\n│  CONTINUITY       │     Trigger rehydration\n│  PIPELINE         │     Next OODA loop begins\n└───────────────────┘\n```\n\n---\n\n## Governance State Machine\n\n```typescript\ninterface GovernanceState {\n  id: string;\n  proposalId: string;\n\n  // Authority layer\n  authority: {\n    status: \"pending\" | \"allowed\" | \"denied\" | \"requires_approval\";\n    userId: string;\n    policyRef: string;\n    reason?: string;\n    approver?: string;\n  };\n\n  // Confidence layer\n  confidence: {\n    status: \"pending\" | \"auto_approve\" | \"hitl_review\" | \"discard\";\n    score: number;\n    modelId: string;\n    threshold: number;\n    reason?: string;\n  };\n\n  // Evidence layer\n  evidence: {\n    status: \"pending\" | \"captured\" | \"validated\" | \"promoted\";\n    intentId: string;\n    actionId: string;\n    records: EvidenceRecord[];\n    auditRef?: string;\n  };\n\n  // Overall disposition\n  disposition:\n    | \"pending\"\n    | \"auto_approved\"\n    | \"hitl_pending\"\n    | \"approved\"\n    | \"rejected\"\n    | \"discarded\"\n    | \"executed\"\n    | \"promoted\";\n\n  // Timeline\n  createdAt: string;\n  updatedAt: string;\n  resolvedAt?: string;\n}\n```\n\n---\n\n## Integration with Document 1's Capability Registry\n\nDocument 1's Capability Registry already stores governance fields per capability:\n\n```typescript\ninterface CapabilityDefinition {\n  // ... other fields ...\n  governance: {\n    requiresApproval: boolean;\n    minConfidence: number;\n    autoApproveThreshold: number;\n    requiredRoles: string[];\n    requiredScopes: string[];\n  };\n}\n```\n\nThe unified governance model extends this:\n\n```typescript\ninterface GovernancePolicy {\n  // Authority layer\n  authority: {\n    requiredRoles: string[]; // who can invoke\n    requiredScopes: string[]; // what scope is needed\n    delegationAllowed: boolean; // can this be delegated?\n    timeWindow?: TimeWindow; // when can this be invoked\n    approverRole?: string; // who must approve (if requiresApproval)\n  };\n\n  // Confidence layer\n  confidence: {\n    autoApproveThreshold: number; // default: 0.85\n    hitlThreshold: number; // default: 0.70\n    minConfidence: number; // below this = discard\n    contextCompletenessRequired: number; // minimum context quality\n  };\n\n  // Evidence layer\n  evidence: {\n    required: boolean; // must evidence be captured?\n    promotionEligible: boolean; // can this outcome be promoted to Spine?\n    auditRetention: number; // days to retain audit records\n  };\n}\n```\n\nThis preserves Document 1's registry structure while adding the authority and evidence dimensions from Document 3.\n\n---\n\n## The HITL Review Contract\n\nThe approval UX needs a technical contract. Here is the proposal:\n\n```typescript\ninterface HITLProposal {\n  id: string;\n  proposalId: string;\n\n  // What the user/Twin wants to do\n  intent: {\n    description: string;\n    targetEntity?: string;\n    targetSystem?: string;\n    capabilityId: string;\n  };\n\n  // What the system will do\n  execution: {\n    plan: ExecutionStep[];\n    estimatedImpact: ImpactSummary;\n    rollbackPlan?: ExecutionStep[];\n  };\n\n  // AI confidence\n  confidence: {\n    score: number;\n    modelId: string;\n    reasoning: string; // why the AI proposed this\n    alternatives: string[]; // what else could have been done\n  };\n\n  // Evidence\n  evidence: {\n    contextUsed: string[]; // what data informed this proposal\n    sourceEntities: string[]; // which entities are involved\n    precedentActions: string[]; // similar past actions\n  };\n\n  // Governance\n  governance: {\n    authorityStatus: string;\n    confidenceDisposition: string;\n    requiredApprover: string;\n    expiresAt: string; // proposal expiration\n  };\n\n  // UI contract\n  ui: {\n    summary: string; // one-line summary\n    detail: string; // full explanation\n    preview: string; // execution preview (diff, preview, etc.)\n    riskLevel: \"low\" | \"medium\" | \"high\" | \"critical\";\n    canPartialApprove: boolean;\n    canModify: boolean;\n  };\n}\n```\n\n### Proposal Lifecycle\n\n```\nPROPOSED → PENDING_AUTHORITY → PENDING_CONFIDENCE → PENDING_REVIEW →\n  → APPROVED → EXECUTING → COMPLETED → PROMOTED\n  → REJECTED → ARCHIVED\n  → EXPIRED → ARCHIVED\n  → MODIFIED → RE-PROPOSED\n```\n\n### Expiration Rules\n\n| Risk Level | Default Expiration | Configurable |\n| ---------- | ------------------ | ------------ |\n| Low        | 7 days             | Yes          |\n| Medium     | 3 days             | Yes          |\n| High       | 24 hours           | Yes          |\n| Critical   | 4 hours            | Yes          |\n\n---\n\n## Four-Button OODA → Governance Mapping\n\n| OODA Button               | Governance Layer                                                         | Auto-Executes?                                       |\n| ------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------- |\n| **Store in Spine**        | Authority: user can write to Spine                                       | Yes (user action, no AI)                             |\n| **Ask Your Twin**         | Authority: user can query Twin; Confidence: N/A (read-only)              | Yes (read-only, no governance gate)                  |\n| **Assign Your Twin**      | Authority: user can delegate to Twin; Confidence: Twin's proposal scored | No (produces proposal for approval)                  |\n| **Approve Twin's Action** | Authority: user can approve; Confidence: HITL review; Evidence: capture  | Yes (after approval, executes and captures evidence) |\n\nThe four buttons are the user-facing entry points. All capability invocations flow through one of these four paths. The governance engine applies the appropriate layer(s) based on which button was pressed.\n\n---\n\n## Implementation Priorities\n\n1. **P0:** Unify the governance state machine (this document)\n2. **P0:** Extend CapabilityRegistry with GovernancePolicy\n3. **P0:** Define HITLProposal contract for the approval UX\n4. **P1:** Implement authority check service\n5. **P1:** Implement confidence check service (already partially exists)\n6. **P1:** Implement evidence capture pipeline\n7. **P2:** Build approval UI using HITLProposal contract\n8. **P2:** Add configurable thresholds per tenant\n"}