docs(governance): expand operating fabric index and governance library

Made-with: Cursor

.cursor/commands/architecture-map.md

@@ -0,0 +1,21 @@
+# architecture-map
+
+Run repository discovery spine check from repo root:
+
+```bash
+python scripts/architecture_brief.py
+```
+
+On Windows if `python` is missing from PATH:
+
+```bash
+py -3 scripts/architecture_brief.py
+```
+
+Then read and summarize:
+
+- [MASTER_OPERATING_PROMPT.md](../../MASTER_OPERATING_PROMPT.md) (TOC + relevant sections for the task)
+- [docs/ai-operating-model.md](../../docs/ai-operating-model.md)
+- [docs/governance/README.md](../../docs/governance/README.md)
+
+Output a **code-backed** bullet map: backend, frontend, agents, prompts path, launch/verify scripts, CI — citing real paths only (no guessed integrations).

.cursor/commands/generate-evidence.md

@@ -0,0 +1,19 @@
+# generate-evidence
+
+Build an **Evidence Pack** for the current task: link intent → claims → verification artifacts.
+
+## Minimum contents
+
+1. **Sources** — commits, files touched, PR link if any.
+2. **Assumptions** — explicit list; mark unverified assumptions.
+3. **Freshness** — timestamps or commit SHAs for docs and code reviewed.
+4. **Verification** — commands run and results (e.g. `pytest`, `verify-launch`, lint); paste exit summary or log pointers.
+5. **Contradictions** — any claim vs observed behavior; mark `contradicted` until resolved (see [docs/governance/trust-fabric.md](../../docs/governance/trust-fabric.md)).
+6. **Rollback / compensation** — one paragraph for Class B or R1+ changes.
+
+## Tie-in
+
+- Decision memos must reference this pack: [docs/governance/approval-policy.md](../../docs/governance/approval-policy.md).
+- Structured reporting: section 20-point list in [docs/governance/discovery-and-output-checklist.md](../../docs/governance/discovery-and-output-checklist.md).
+
+Output as structured markdown or JSON-shaped bullets so machines and humans can scan it.

.cursor/commands/release-gate.md

@@ -0,0 +1,27 @@
+# release-gate
+
+Pre-flight before promotion to staging/canary/prod or before declaring a release candidate.
+
+## Steps (run from repo root)
+
+1. Backend tests:
+
+   ```bash
+   cd salesflow-saas/backend && pytest -v --tb=short
+   ```
+
+2. Launch / hardening script (Windows):
+
+   ```powershell
+   powershell -NoProfile -ExecutionPolicy Bypass -File salesflow-saas/verify-launch.ps1
+   ```
+
+   Add flags as your runbook requires, e.g. `-WithOpenApiGate` — see [salesflow-saas/verify-launch.ps1](../../salesflow-saas/verify-launch.ps1).
+
+3. Read [salesflow-saas/docs/LAUNCH_CHECKLIST.md](../../salesflow-saas/docs/LAUNCH_CHECKLIST.md) and tick mentally each item that applies.
+
+4. Security gate mindset: [docs/governance/trust-fabric.md](../../docs/governance/trust-fabric.md) (auth, webhooks, uploads, AI surfaces, MCP).
+
+## Output
+
+Summarize pass/fail, open critical findings, and **block release** if any Class C violation or unresolved contradicted evidence remains.

.cursor/commands/review-policy.md

@@ -0,0 +1,18 @@
+# review-policy
+
+Scan the current change or branch against the policy library before commit or PR.
+
+## Required reading
+
+1. [docs/governance/approval-policy.md](../../docs/governance/approval-policy.md) — A/R/S, Class A/B/C, evidence packs.
+2. [docs/governance/trust-fabric.md](../../docs/governance/trust-fabric.md) — security gate, tool verification, audit.
+3. [docs/governance/github-and-release.md](../../docs/governance/github-and-release.md) — branch and environment rules.
+
+## Output
+
+Produce a short table:
+
+| Item | Classification (A/R/S if applicable) | Action class (A/B/C) | Gap or OK |
+|------|----------------------------------------|----------------------|-----------|
+
+Flag any **Class B** work missing approval path, any **S2/S3** exposure to new tools/providers, and any **R2/R3** without HITL. Do not approve merge narration without mapping to evidence (tests, checklist, or run artifacts).

AGENTS.md

@@ -2,48 +2,97 @@
 
 This constitution dictates the behavioral, architectural, and operational rules for any AI Agent (Claude, Cursor, Goose, LangGraph, etc.) interacting with this repository.
 
-## 1. ⚖️ The Big Rule
+## 1. The Big Rule
+
 **Agentic by design, governed by policy, proven by evidence**
+
 - AI may explore, analyze, and recommend.
 - Systems commit durable processes.
 - Humans approve critical or irreversible decisions.
 - Everything runs on an Evidence Trace, not just LLM narration.
 
-## 2. 🔀 Decision Plane vs. Execution Plane
-- **Decision Plane**: Agents perform cognition, analysis loops, scenario building, and Memo Generation. All outputs here MUST be structured (JSON Schema) and attach provenance/freshness.
-- **Execution Plane**: Only deterministic workflows (e.g. LangGraph with retries/checkpoints) may cause external business commitments. Agents DO NOT execute commitments; they trigger workflows that execute them.
+## 2. Decision Plane vs. Execution Plane
+
+- **Decision Plane**: Agents perform cognition, analysis loops, scenario building, and Memo Generation. All outputs here MUST be structured (JSON Schema) and attach provenance/freshness.
+- **Execution Plane**: Only deterministic workflows (e.g. LangGraph with retries/checkpoints, durable workers) may cause external business commitments. Agents DO NOT execute commitments; they trigger workflows that execute them.
+
+## 3. Absolute Boundaries (Forbidden Zones)
 
-## 3. 🛡️ Absolute Boundaries (Forbidden Zones)
 Agents MUST NOT:
+
 - Exfiltrate secrets or modify `**/*.env`/production API keys.
 - Bypass branch protection or execute silent destructive changes.
 - Bypass the `Shannon` Security Gate for canary/production releases.
 - Make public claims without generating a verifiable Evidence Pack.
 
-## 4. 🧠 Memory & Routing
-- **Provider Routing**: Use `provider_router.py` to route logic. Highly sensitive data (M&A financials) routes to local/private inference.
+## 4. Memory & Routing
+
+- **Provider Routing**: Use `provider_router.py` / model router in app code for logic. Highly sensitive data (M&A financials) routes to local/private inference per policy.
 - **Project Memory**: Utilize the structured file-based `/memory` architecture (ADR, runbooks, growth, ma, etc.). No unstructured "dumps" allowed.
 
-## 5. 🤖 Agent Role Restrictions
+## 5. Agent Role Restrictions
+
 Any AI acting in this system must strictly adopt one of these roles:
+
 - `Observer`: Monitors and scores (No commit).
 - `Recommender`: Proposes and generates memos (No direct commit).
 - `Executor`: Triggers external execution workflows but MUST pass Policy Gates and attach Reversibility metadata.
 
-## 6. 📜 Master operating prompt (canonical)
+## 6. Master operating prompt (canonical long form)
 
-The full institutional constitution lives in **[`MASTER_OPERATING_PROMPT.md`](MASTER_OPERATING_PROMPT.md)** (planes, trust fabric, events, GitHub governance, Arabic-first, output checklist). This `AGENTS.md` is the **short constitution**; the master file is the **long-form reference** for serious projects and Dealix.
+Full institutional constitution: **[`MASTER_OPERATING_PROMPT.md`](MASTER_OPERATING_PROMPT.md)** — three layers, five planes, absolute rules, events, connectors, trust fabric, GitHub, design, Arabic-first, action classes, 20-point reporting, bootstrap text.
 
-## 7. 🏷️ Policy classes (A / R / S)
+This `AGENTS.md` is the **entry constitution**; the master file remains the **single long-form source** to avoid drift.
 
-Every material action MUST carry **Approval class (A0–A3)**, **Reversibility class (R0–R3)**, and **Sensitivity class (S0–S3)**. See **[`docs/governance/approval-policy.md`](docs/governance/approval-policy.md)**.
+## 7. Governance library (full topical index)
 
-## 8. 📐 AI operating model (planes)
+Use these for depth, onboarding, and review. Each expands themes from the master prompt.
 
-Decision vs execution vs control vs data vs trust — see **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)** and the implementation pointers inside it (e.g. `salesflow-saas/backend/app/services/agents/`).
+| Document | Contents |
+|----------|----------|
+| [docs/governance/README.md](docs/governance/README.md) | Index of all governance docs |
+| [docs/governance/planes-and-runtime.md](docs/governance/planes-and-runtime.md) | Five planes, three layers, repo/graph/workflow runtimes |
+| [docs/governance/approval-policy.md](docs/governance/approval-policy.md) | A0–A3, R0–R3, S0–S3, actors, Class A/B/C, cross-matrices, evidence packs |
+| [docs/governance/events-and-schema.md](docs/governance/events-and-schema.md) | CloudEvents-style envelopes, JSON Schema, AsyncAPI, no silent drift |
+| [docs/governance/trust-fabric.md](docs/governance/trust-fabric.md) | Trust substrate, tool verification, observability, security gate |
+| [docs/governance/connectors-and-data-plane.md](docs/governance/connectors-and-data-plane.md) | Connector facades, data plane, semantic metrics, lineage |
+| [docs/governance/github-and-release.md](docs/governance/github-and-release.md) | Branch protection, CI, environments, OIDC, audit retention |
+| [docs/governance/design-and-arabic.md](docs/governance/design-and-arabic.md) | Design system, IBM Plex / 29LT Azal, RTL, Arabic-first |
+| [docs/governance/discovery-and-output-checklist.md](docs/governance/discovery-and-output-checklist.md) | Repo discovery, capability maps, phasing, 20-point checklist, Arabic bootstrap |
+| [docs/governance/strategic-ops-pmi.md](docs/governance/strategic-ops-pmi.md) | Strategic ops, M&A, PMI / post-close |
 
-## 9. ✅ Action classes (ship discipline)
+Operating overview with diagram: **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)**.
+
+## 8. Three governing layers (quick reference)
+
+1. **Exploration intelligence** — discovery, analysis, memos, scenarios (structured + provenance).
+2. **Committed execution** — durable workflows, external actions, long-lived processes.
+3. **Trust fabric** — policy, approvals, audit, tool verification, evidence, security gate, evals.
+
+**Primary rule:** AI may recommend; systems commit; humans approve critical decisions.
+
+## 9. Policy classes (every material action)
+
+Carry **Approval (A0–A3)**, **Reversibility (R0–R3)**, and **Sensitivity (S0–S3)**. Details: [docs/governance/approval-policy.md](docs/governance/approval-policy.md).
+
+## 10. Action classes (ship discipline)
 
 - **Class A** — Auto-allowed: discovery, maps, internal drafts, tests, lint, read-only analysis.
 - **Class B** — Approval required: prod config, public publish, customer messages, migrations, RBAC, release promotion, external commitments.
 - **Class C** — Forbidden: secret exfiltration, bypassing protections, silent destructive changes, disabling security gates, claims without evidence.
+
+## 11. Absolute rules (non-negotiable, abbreviated)
+
+Do not: rebuild working systems without justification; assume integrations without code evidence; claim features without proof; ship to prod without staged validation; use AI as source of truth for business data; trust narration without execution evidence; skip tests/security/approvals/rollback; add dependencies without license/security/rollback review; confuse community patterns with production dependencies; let design quality lag engineering; put **core** policy only in prompts; run long-lived commitments only in ephemeral agent graphs; allow external commitment without classification + audit + reversibility awareness; redefine metrics in multiple places.
+
+Full numbered list: [MASTER_OPERATING_PROMPT.md](MASTER_OPERATING_PROMPT.md).
+
+## 12. Tooling and automation entry points
+
+- **Cursor** slash commands (see `.cursor/commands/`): `/architecture-map`, `/review-policy`, `/generate-evidence`, `/release-gate`.
+- **Claude Code** custom commands: [.claude/settings.json](.claude/settings.json) — `architecture-map`, `canary-check`, `security-preflight`.
+- **Quick path check:** `python scripts/architecture_brief.py` (or `py -3 scripts/architecture_brief.py` on Windows).
+
+## 13. Dealix application root
+
+Product-specific stack and conventions: **[`salesflow-saas/AGENTS.md`](salesflow-saas/AGENTS.md)** — must stay aligned with this file and with the governance library above.

CLAUDE.md

@@ -3,33 +3,50 @@
 You are the Chief Hybrid AI Systems Architect editing this repository.
 Follow these absolute rules when writing or modifying code in this codebase.
 
-## 1. 🏗️ Start with Discovery
+## 1. Start with Discovery
+
 - NEVER write code blindly.
 - ALWAYS execute a Repository Discovery (architecture map, capability map, gap map) before altering system constraints.
+- Procedure: [docs/governance/discovery-and-output-checklist.md](docs/governance/discovery-and-output-checklist.md). Quick spine check: `python scripts/architecture_brief.py` (or `py -3` on Windows).
+
+## 2. Decision Memo & Output Formats
 
-## 2. 📝 Decision Memo & Output Formats
 Whenever modifying an Agent logic flow, it MUST interface through the execution plane.
 Agent logic outputs MUST follow the `DecisionMemo` structured contract (JSON Schema). Narration is forbidden without structure. Every action requires an `Evidence Pack`.
 
-## 3. ⌨️ Development & Slash Commands
-* `/architecture-map`: Analyzes and outputs the current architecture footprint.
-* `/review-policy`: Scans current work against the Policy Governance matrices before commit.
-* `/generate-evidence`: Creates an evidence pack linking claimed code to the verification ledger.
-* `/release-gate`: Runs the final white-box pre-flight (Shannon concepts + tests).
+Policy tables and classes: [docs/governance/approval-policy.md](docs/governance/approval-policy.md).
+
+## 3. Commands (Cursor vs Claude Code)
+
+**Cursor (IDE):** use slash commands defined under [`.cursor/commands/`](.cursor/commands/) — same names as below.
+
+**Claude Code:** custom commands are defined in [`.claude/settings.json`](.claude/settings.json):
+
+| Command | Role |
+|---------|------|
+| `architecture-map` | Runs `python scripts/architecture_brief.py` — constitution + spine path check |
+| `canary-check` | `cd salesflow-saas/backend && pytest -v --tb=short` |
+| `security-preflight` | `powershell ... -File salesflow-saas/verify-launch.ps1` |
+
+For policy scanning, evidence packs, and release gates in Cursor, use `/review-policy`, `/generate-evidence`, and `/release-gate` (see `.cursor/commands/*.md`).
+
+## 4. Design Quality & Arabic
 
-## 4. 🎨 Design Quality & Arabic
 - Design quality must match engineering quality.
 - **RTL-safe / Arabic First**: Use `IBM Plex Sans Arabic` for primary UI. Only use `29LT Azal` for hero/Display texts.
 - Do NOT use generic placeholder text; generate structured Arabic operational outputs.
+- Details: [docs/governance/design-and-arabic.md](docs/governance/design-and-arabic.md).
+
+## 5. Integration & Connectors
 
-## 5. 🔌 Integration & Connectors
 - Do NOT integrate directly with vendor APIs from Agent scripts.
 - Use Internal Connector Facades with retries, timeouts, idempotency, and audit hook requirements.
+- Details: [docs/governance/connectors-and-data-plane.md](docs/governance/connectors-and-data-plane.md).
 
-## 6. 📜 Canonical master prompt & docs
+## 6. Canonical master prompt & docs
 
-- **[`MASTER_OPERATING_PROMPT.md`](MASTER_OPERATING_PROMPT.md)** — full Master Operating Prompt (enterprise fabric: planes, trust, events, GitHub, Arabic-first).  
-- **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)** — planes summary and repo pointers.  
-- **[`docs/governance/approval-policy.md`](docs/governance/approval-policy.md)** — A/R/S classes and action classes A/B/C.
+- **[MASTER_OPERATING_PROMPT.md](MASTER_OPERATING_PROMPT.md)** — full Master Operating Prompt (enterprise fabric).
+- **[docs/ai-operating-model.md](docs/ai-operating-model.md)** — planes overview + mermaid + product routing.
+- **[docs/governance/README.md](docs/governance/README.md)** — governance library index.
 
 Discovery before code; Phase 1 only until evidence; no policy logic in prompts where it belongs in policy systems.

MASTER_OPERATING_PROMPT.md

@@ -3,6 +3,24 @@
 This document is the **canonical operating constitution** for AI-assisted engineering in this repository.  
 Root [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md) summarize and enforce it; details live here and in [`docs/ai-operating-model.md`](docs/ai-operating-model.md) and [`docs/governance/approval-policy.md`](docs/governance/approval-policy.md).
 
+## Table of contents — expanded governance library
+
+Deep-dive topics live under [`docs/governance/`](docs/governance/) (keep this file canonical; use links for navigation and onboarding).
+
+| Topic | Expanded doc |
+|-------|----------------|
+| Governance index | [`docs/governance/README.md`](docs/governance/README.md) |
+| Planes, layers, runtimes | [`docs/governance/planes-and-runtime.md`](docs/governance/planes-and-runtime.md) |
+| Approvals, reversibility, sensitivity, action classes | [`docs/governance/approval-policy.md`](docs/governance/approval-policy.md) |
+| Events, schemas, contracts | [`docs/governance/events-and-schema.md`](docs/governance/events-and-schema.md) |
+| Trust fabric, tool verification, observability, security gate | [`docs/governance/trust-fabric.md`](docs/governance/trust-fabric.md) |
+| Data plane, connectors, semantic metrics | [`docs/governance/connectors-and-data-plane.md`](docs/governance/connectors-and-data-plane.md) |
+| GitHub, CI/CD, environments, retention | [`docs/governance/github-and-release.md`](docs/governance/github-and-release.md) |
+| Design system, Arabic-first / bilingual | [`docs/governance/design-and-arabic.md`](docs/governance/design-and-arabic.md) |
+| Discovery, phasing, 20-point checklist, Arabic bootstrap | [`docs/governance/discovery-and-output-checklist.md`](docs/governance/discovery-and-output-checklist.md) |
+| Strategic ops, M&A, PMI | [`docs/governance/strategic-ops-pmi.md`](docs/governance/strategic-ops-pmi.md) |
+| Planes + product routing (overview) | [`docs/ai-operating-model.md`](docs/ai-operating-model.md) |
+
 ---
 
 ## Roles (operating stance)

docs/ai-operating-model.md

@@ -2,28 +2,91 @@
 
 This repository follows the **Master Operating Prompt** ([`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md)): a governed hybrid stack, not “agents only.”
 
-## Planes (summary)
+## Governance library (full index)
+
+| Document | Purpose |
+|----------|---------|
+| [governance/README.md](governance/README.md) | Table of all governance topics |
+| [governance/planes-and-runtime.md](governance/planes-and-runtime.md) | Five planes, three layers, runtime choice |
+| [governance/approval-policy.md](governance/approval-policy.md) | A / R / S, actors, Class A/B/C, evidence packs |
+| [governance/events-and-schema.md](governance/events-and-schema.md) | Events, JSON Schema, AsyncAPI, versioning |
+| [governance/trust-fabric.md](governance/trust-fabric.md) | Trust substrate, tool verification, security gate |
+| [governance/connectors-and-data-plane.md](governance/connectors-and-data-plane.md) | Facades, data plane, semantic metrics |
+| [governance/github-and-release.md](governance/github-and-release.md) | Branch rules, CI, environments, OIDC |
+| [governance/design-and-arabic.md](governance/design-and-arabic.md) | Design system, RTL, Arabic-first |
+| [governance/discovery-and-output-checklist.md](governance/discovery-and-output-checklist.md) | Discovery, phasing, 20-point report, Arabic bootstrap |
+| [governance/strategic-ops-pmi.md](governance/strategic-ops-pmi.md) | M&A, PMI, strategic ops |
+
+## Planes at a glance
 
 | Plane | Owns | Must not |
 |-------|------|-----------|
-| **Decision** | Analysis, memos, structured recommendations, scenarios | Durable external commitments |
-| **Execution** | Workflows, retries, idempotency, compensation, side effects | Unstructured “trust me” narration |
-| **Control** | Policy, approvals, RBAC, secrets, promotion, audit | Ad-hoc rules in prompts |
+| **Decision** | Analysis, memos, structured recommendations, scenarios | Durable external commitments as narration-only |
+| **Execution** | Workflows, retries, idempotency, compensation, side effects | Unstructured “trust me” execution |
+| **Control** | Policy, approvals, RBAC, secrets, promotion, audit | Ad-hoc rules only in prompts |
 | **Data** | Operational truth, contracts, metrics definitions, lineage | Duplicate conflicting metric meanings |
 | **Trust** | Evidence packs, tool verification, security gate, evals | Claims without proof |
 
+## Flow (conceptual)
+
+```mermaid
+flowchart LR
+  subgraph decisionPlane [DecisionPlane]
+    Cognition[CognitionAndMemos]
+    StructuredOut[StructuredOutputs]
+  end
+  subgraph controlPlane [ControlPlane]
+    Policy[PolicyAndApprovals]
+    AuthZ[Authorization]
+  end
+  subgraph executionPlane [ExecutionPlane]
+    Workflows[DurableWorkflows]
+    SideEffects[ExternalCommitments]
+  end
+  subgraph dataPlane [DataPlane]
+    OpsData[OperationalData]
+    Contracts[ContractsAndMetrics]
+  end
+  subgraph trustPlane [TrustPlane]
+    Evidence[EvidenceAndVerification]
+    Obs[ObservabilityAndSecurityGate]
+  end
+  decisionPlane --> controlPlane
+  controlPlane --> executionPlane
+  executionPlane --> dataPlane
+  trustPlane -.-> decisionPlane
+  trustPlane -.-> executionPlane
+  trustPlane -.-> controlPlane
+  trustPlane -.-> dataPlane
+```
+
+Trust wraps every plane: verification, audit, telemetry, and gates apply to cognition outputs, policy decisions, workflow steps, and data mutations.
+
+## Starting path by product type
+
+Sequence explicitly when multiple rows apply; do not mix chaotically.
+
+| Product shape | Prioritize first | Deep dive |
+|---------------|------------------|-----------|
+| **SaaS** | Auth, billing, admin, analytics, onboarding, release | [github-and-release.md](governance/github-and-release.md), [connectors-and-data-plane.md](governance/connectors-and-data-plane.md) |
+| **AI / agentic** | Provider routing, memory, orchestration, tool verification, evals, observability | [planes-and-runtime.md](governance/planes-and-runtime.md), [trust-fabric.md](governance/trust-fabric.md) |
+| **CRM / lead / ops** | Workflow safety, approvals, messaging, audit, connector facades | [approval-policy.md](governance/approval-policy.md), [events-and-schema.md](governance/events-and-schema.md) |
+| **Strategic / corpdev** | Contracts, evidence packs, deterministic workflows, executive views | [strategic-ops-pmi.md](governance/strategic-ops-pmi.md), [discovery-and-output-checklist.md](governance/discovery-and-output-checklist.md) |
+
+**Dealix** spans SaaS, agentic, CRM, and strategic modules — pick the dominant thread for the current milestone, then pull in cross-cutting trust and GitHub rules.
+
 ## Dealix implementation pointers
 
 - **Agents / routing / pipeline:** [`salesflow-saas/backend/app/services/agents/`](../salesflow-saas/backend/app/services/agents/) — `router.py`, `executor.py`, `autonomous_pipeline.py`.
 - **Prompts (runtime path):** [`salesflow-saas/ai-agents/prompts/`](../salesflow-saas/ai-agents/prompts/) — loaded by `AgentExecutor` (`PROMPTS_DIR`); policy stays in code/services, not inside markdown prompts.
-- **Core OS (memos / governance direction):** [`salesflow-saas/backend/app/services/core_os/`](../salesflow-saas/backend/app/services/core_os/) — e.g. decision memo and related structures where present.
+- **Core OS (memos / governance direction):** [`salesflow-saas/backend/app/services/core_os/`](../salesflow-saas/backend/app/services/core_os/).
 - **Launch & evidence discipline:** [`salesflow-saas/docs/LAUNCH_CHECKLIST.md`](../salesflow-saas/docs/LAUNCH_CHECKLIST.md), [`salesflow-saas/verify-launch.ps1`](../salesflow-saas/verify-launch.ps1).
 
 ## Operating sequence for any major change
 
-1. Repository discovery (architecture + capability + gap + risk + trust).  
+1. Repository discovery (architecture + capability + gap + risk + trust). See [governance/discovery-and-output-checklist.md](governance/discovery-and-output-checklist.md).  
 2. Smallest phase that proves value with tests and rollback.  
 3. Evidence: tests, logs, or contract checks — as defined in the phase.  
 4. Only then expand scope.
 
-See also: [`approval-policy.md`](governance/approval-policy.md).
+Primary policy reference: [governance/approval-policy.md](governance/approval-policy.md).

docs/governance/README.md

@@ -0,0 +1,18 @@
+# Governance library — Dealix operating fabric
+
+Canonical constitution: [`../../MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).  
+This folder expands each major theme for navigation, review, and agent onboarding.
+
+| Document | Topic |
+|----------|--------|
+| [approval-policy.md](approval-policy.md) | Approval (A), reversibility (R), sensitivity (S), actor types, action classes A/B/C, evidence packs |
+| [planes-and-runtime.md](planes-and-runtime.md) | Five planes, three layers, runtime choice (repo agents / graph / durable workflows) |
+| [events-and-schema.md](events-and-schema.md) | Event envelopes, JSON Schema, AsyncAPI, versioning, no silent drift |
+| [trust-fabric.md](trust-fabric.md) | Trust substrate, tool verification, observability, security gate |
+| [connectors-and-data-plane.md](connectors-and-data-plane.md) | Connector facades, operational data, semantic metrics, lineage |
+| [github-and-release.md](github-and-release.md) | Branch protection, CI, environments, OIDC, audit retention |
+| [design-and-arabic.md](design-and-arabic.md) | Design system, RTL, Arabic-first / bilingual product rules |
+| [discovery-and-output-checklist.md](discovery-and-output-checklist.md) | Repository discovery, capability maps, 20-point reporting, Arabic bootstrap |
+| [strategic-ops-pmi.md](strategic-ops-pmi.md) | Strategic ops, M&A, PMI / post-close governance |
+
+Repo entry points: [`../../AGENTS.md`](../../AGENTS.md), [`../../CLAUDE.md`](../../CLAUDE.md), [`../ai-operating-model.md`](../ai-operating-model.md).

docs/governance/approval-policy.md

@@ -1,6 +1,6 @@
 # Approval, reversibility, sensitivity — policy model
 
-Canonical context: [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md). This file is the **short operational reference** for classifying work before it ships.
+Canonical context: [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md). This file is the **operational reference** for classifying work before it ships. Expanded topics: [README.md](README.md).
 
 ## Approval class (A)
 
@@ -22,6 +22,17 @@ Canonical context: [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.
 
 **Rule of thumb:** R2/R3 require explicit HITL (human-in-the-loop) or committee path before execution-plane runs.
 
+### Reversibility vs approval (cross-check)
+
+| Reversibility | Typical minimum approval | Notes |
+|---------------|-------------------------|--------|
+| **R0** | A0–A1 | Auto or lead sign-off per team policy |
+| **R1** | A1 | Revert still needs accountable owner |
+| **R2** | A2 | Legal/finance/functional head as appropriate |
+| **R3** | A3 | Exec/board path for binding or public commitments |
+
+Higher sensitivity (below) can **raise** the required approval even when reversibility is R0–R1 (e.g. S3 bulk export is never A0).
+
 ## Sensitivity class (S)
 
 | Class | Data |
@@ -33,6 +44,15 @@ Canonical context: [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.
 
 **Rule:** No S2/S3 across tools, providers, or LLM endpoints without policy review and routing (e.g. local/private inference where required).
 
+### Sensitivity vs action class
+
+| Data / context | Default action class | Approval note |
+|----------------|---------------------|----------------|
+| **S0** | Class A possible | Still follow repo conventions |
+| **S1** | Class A for read-only; Class B for writes affecting others | Team policy |
+| **S2** | Class B minimum for export, integration, or model routing | No silent tool/provider hops |
+| **S3** | Class B minimum; often A2–A3 | No LLM or third-party tool without explicit routing review |
+
 ## Actor type
 
 `human` | `observer_agent` | `recommender_agent` | `executor_system` | `automated_workflow`
@@ -45,6 +65,18 @@ Observers and recommenders do **not** commit. Executors and workflows act only t
 - **Class B** — Approval required: prod config, public publish, customer messages, migrations, RBAC, release promotion, external APIs.  
 - **Class C** — Forbidden: exfiltration, bypass protections, silent destructive changes, disabling gates, claims without evidence.
 
+### Mapping A / R / S to Class A / B / C
+
+| Pattern | Class | Rationale |
+|---------|-------|-----------|
+| Read-only discovery, local drafts, unit tests, lint | **A** | No durable external commitment |
+| R2/R3 or external side effect (message send, contract, money, public URL) | **B** or blocked until A met | Execution plane + HITL |
+| R3 with inadequate A (e.g. board doc at S3 with A1 only) | **C** (do not ship) | Policy violation |
+| Any claim of “done” without tests/logs/artifact | **C** | Evidence discipline |
+| S2/S3 sent to new vendor, model, or MCP without review | **B** minimum | Data residency and tool governance |
+
+**Executor systems and automated workflows** may only perform Class A actions autonomously where policy explicitly allows; otherwise they enqueue or pause for approval.
+
 ## Evidence pack (minimum)
 
 For Class B and any R2/R3 decision: sources, assumptions, timestamps/freshness, compliance notes where relevant, alternatives, rollback/compensation, provenance score, pointers to tests or run artifacts.
@@ -53,4 +85,4 @@ A **decision memo without an evidence pack is incomplete.**
 
 ## GitHub governance (surface)
 
-Protected `main`; required reviews and checks; CODEOWNERS as team scales; secret scanning and dependency review; prefer OIDC for cloud deploy keys. Align branch rules with environment promotion (dev → staging → canary → prod).
+See [github-and-release.md](github-and-release.md) for the full model. Summary: protected `main`, required reviews and checks, CODEOWNERS as team scales, secret scanning and dependency review, OIDC for deploy keys where possible, environment promotion (dev → staging → canary → prod).

docs/governance/connectors-and-data-plane.md

@@ -0,0 +1,47 @@
+# Data plane and connector facades
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+## Data and knowledge layer
+
+- **Operational store:** relational DB as system of record for business entities; strict tenant boundaries (`tenant_id` and access checks).
+- **Embeddings:** colocate or pipeline near operational data when semantic search or routing benefits; do not let embeddings become an ungoverned shadow DB of PII.
+- **Graph stores:** add only when relationship-heavy reasoning is a proven requirement (cost and ops complexity are real).
+- **Document ingestion:** contracts, DD materials, board packs, PDFs — through controlled pipelines with retention and sensitivity classes.
+- **Lineage / metadata catalog:** choose **one** primary cataloging path; a second overlapping system needs explicit justification.
+
+## Semantic metrics
+
+Do **not** let multiple systems independently define “revenue”, “pipeline velocity”, “contribution margin”, “synergy realization”, or other executive metrics.
+
+Prefer:
+
+- Central semantic definitions (single module or analytics layer).  
+- Data quality checks and documented downstream impact.  
+- Visible lineage from metric definition to dashboards and agent outputs.
+
+## Connector facade rule
+
+Agents and ad-hoc scripts must **not** sprawl direct calls to many vendor APIs.
+
+Each connector facade should specify:
+
+- Contract (inputs/outputs, error model)  
+- Version  
+- Retry policy  
+- Timeout policy  
+- Idempotency key handling  
+- Approval policy linkage (Class B where needed)  
+- Audit field mapping  
+- Observability hooks (logs, metrics, traces)  
+- Rollback or compensation notes when side effects are possible  
+
+Treat every external API as a **changing contract**, not a fixed truth.
+
+## Dealix pointers
+
+- Model / provider routing: `salesflow-saas/backend/app/services/model_router.py`.
+- LLM provider abstraction: `salesflow-saas/backend/app/ai/llm_provider.py`, `salesflow-saas/backend/app/services/local_inference.py`.
+- Integrations and CRM direction: search `integrations` and `services` for connector-style modules; extend via facades rather than new raw SDK calls from agent nodes.
+
+See also: [events-and-schema.md](events-and-schema.md), [approval-policy.md](approval-policy.md), [trust-fabric.md](trust-fabric.md).

docs/governance/design-and-arabic.md

@@ -0,0 +1,50 @@
+# Design system and Arabic-first / bilingual layer
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+## Design system goals
+
+- **Premium** and **restrained** — engineering-grade polish, not noisy marketing chrome.  
+- **Conversion-aware** — clarity of primary actions and trust-building patterns.  
+- **RTL-safe** — layout, icons, and animations must not assume LTR-only.  
+- **Culturally aware** — GCC-relevant tone, imagery, and business context where applicable.  
+- **Accessible** — contrast, focus order, semantics, motion preferences.  
+- **Performant** — avoid unnecessary font and bundle bloat; measure Core Web Vitals where relevant.
+
+## Typography (Dealix rule)
+
+- **IBM Plex Sans Arabic** — primary UI font.  
+- **29LT Azal** — hero / display only; do not use for dense UI body.  
+- App-specific secondary fonts (e.g. Tajawal in `salesflow-saas`) must remain consistent with product design decisions; new surfaces should align with root constitution for Arabic-first products.
+
+## Components
+
+Each significant component should define:
+
+- Purpose and invariants  
+- States (default, hover, active, disabled, read-only)  
+- Loading, empty, and error states  
+- Accessibility expectations  
+- Mobile behavior  
+- Analytics hooks only when product metrics require them (avoid leaking PII)
+
+## Arabic-first / bilingual (GCC relevance)
+
+When the product targets Saudi or broader GCC:
+
+- **RTL-safe UI** — `dir`, logical properties, mirrored layouts tested.  
+- **Arabic copy QA** — gender, formality, product terminology; avoid machine-glossy placeholder Arabic.  
+- **Bilingual consistency** — API messages and UI strings stay aligned across AR/EN.  
+- **Arabic summarization/classification** — routed per sensitivity (S2/S3 to private/local paths per policy).  
+- **Local market vocabulary** — real estate, healthcare, etc., as appropriate.  
+- **Trust cues** — licenses, support channels, PDPL consent patterns in UX.  
+- **Notifications** — Arabic-first templates where the user locale is Arabic.  
+- **SEO / content** — Arabic content strategy where public marketing applies.
+
+## Dealix pointers
+
+- Frontend: `salesflow-saas/frontend/` (App Router, Tailwind, RTL patterns).  
+- Arabic NLP services: `salesflow-saas/backend/app/services/ai/arabic_nlp.py`.  
+- Prompts (tone, not policy): `salesflow-saas/ai-agents/prompts/`.
+
+See also: [approval-policy.md](approval-policy.md) (sensitivity classes), [trust-fabric.md](trust-fabric.md).

docs/governance/discovery-and-output-checklist.md

@@ -0,0 +1,97 @@
+# Repository discovery, phasing, and reporting checklist
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+## Before writing code
+
+Produce a **code-backed** map (paths, modules, configs), not guesses:
+
+- Frontend and backend stacks, APIs, DB models and migrations  
+- Queues, workers, schedulers  
+- Auth, permissions, tenant isolation  
+- Messaging, CRM/lead integrations  
+- AI modules, model/provider usage  
+- `AGENTS.md`, `CLAUDE.md`, `.claude/`, Cursor rules, skills, hooks  
+- Observability, CI/CD, deployment topology  
+- Feature flags, admin tools, backup/restore  
+- Security boundaries, long-running workflows, external integrations  
+- **Current metric definitions** and audit/approval surfaces  
+
+**Map first; do not code blindly.**
+
+## Capability classification
+
+Bucket capabilities into:
+
+- **Verified** — proven in code + tests or production evidence  
+- **Partial** — exists but incomplete or flaky  
+- **Missing critical** — blocks safe scale or compliance  
+- **Optional accelerators** — nice-to-have for this product type  
+- **Community patterns** — adopt selectively after review  
+- **Risky / experimental** — pilots only; out of default production path until benchmarked  
+
+Deliver: architecture map, capability map, gap map, risk map, trust map, workflow map, opportunity map.
+
+## Correct starting path (by product type)
+
+- **SaaS** — scaffold hardening, auth, billing, admin, analytics, onboarding, release flow.  
+- **AI / agentic** — provider routing, memory, orchestration, tool verification, evals, observability.  
+- **CRM / lead / ops** — workflow safety, approvals, messaging controls, audit, connector facades, release gating.  
+- **Strategic ops / partnerships / corpdev** — contracts, approvals, evidence packs, deterministic workflows, executive views, financial models.  
+
+If several apply: **sequence explicitly**; do not interleave chaotically.
+
+## Agent operating files (discipline)
+
+Maintain: `AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`, `.claude/settings.local.json` (gitignored when local-only), Cursor commands, skills, hooks. Encode: install/run/test, boundaries, forbidden actions, review and release expectations, memory rules, tools, providers, rollout, approvals, reversibility, evidence, **no claim without proof**.
+
+## Decision plane outputs (summary)
+
+Schema-first; provenance and freshness; decision memos and evidence packs; next-best-actions; alternatives; assumptions; machine-readable classifications.
+
+Decision memo should support fields such as: objective, context, assumptions, recommendation, alternatives, financial impact, risk register, provenance/freshness/confidence scores, approval and reversibility classes, next action, rollback/compensation notes, evidence pack references.
+
+**A decision memo without an evidence pack is incomplete** for governed work.
+
+## Execution plane (summary)
+
+Owns retries, idempotency, compensation, worker versioning, survival across failures. Used for approvals, contracts, partner activation, launches, diligence orchestration, DD rooms, signatures, PMI steps, release promotion, customer messaging **when approved**. Agents recommend; **only execution workflows commit**.
+
+## Twenty-point reporting format
+
+For major planning or review threads, structure output as:
+
+1. Code-backed architecture map  
+2. Verified capabilities  
+3. Missing capabilities  
+4. Gap map  
+5. Safest integration points  
+6. Target operating architecture  
+7. Exact phase being executed  
+8. File/module plan  
+9. Contract/event plan  
+10. Policy / approval / reversibility plan  
+11. Testing plan  
+12. Security gate plan  
+13. Memory plan  
+14. Provider routing plan  
+15. Tool verification plan  
+16. Design system decisions  
+17. Rollout and rollback plan  
+18. Evidence collected  
+19. Unresolved risks  
+20. Next safest step  
+
+## Work style
+
+Prefer small safe phases; be explicit about uncertainty; be strict about evidence; do not advance phases without proof.
+
+## Arabic bootstrap (paste for Cursor sessions)
+
+ابدأ بدون كتابة كود. أريد أولاً: (1) code-backed architecture map (2) verified capability map (3) gap map (4) safest integration points (5) target operating architecture (6) policy + approval + reversibility model (7) phased implementation plan. بعدها فقط: نفّذ المرحلة الأولى فقط؛ لا تنتقل للمرحلة التالية قبل evidence واضح؛ لا تفترض أي تكامل خارجي غير موجود فعليًا؛ افصل decision plane عن execution plane؛ عامل أي long-running commitment كـ deterministic workflow لا agent narration؛ عامل community catalogs كمكتبات أنماط؛ عامل memory products الواعدة كخيارات pilot تحتاج benchmark داخلي؛ عامل tool verification products كنمط معماري حتى تثبت صلاحيتها التشغيلية؛ لا تضع policy logic داخل prompts إذا كان مكانها الصحيح في policy system؛ لا تسمح بأي external commitment بدون approval class + reversibility class + evidence pack.
+
+## Quick mechanical discovery
+
+From repo root: `python scripts/architecture_brief.py` (or `py -3 scripts/architecture_brief.py` on Windows) — verifies key constitution and spine paths.
+
+See also: [README.md](README.md), [planes-and-runtime.md](planes-and-runtime.md), [approval-policy.md](approval-policy.md).

docs/governance/events-and-schema.md

@@ -0,0 +1,41 @@
+# Events, contracts, and schema governance
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+## Principles
+
+- Do not rely on ad hoc string event names alone without documentation and versioning.
+- Prefer **CloudEvents**-style envelopes for cross-service and async boundaries.
+- Validate payloads with **JSON Schema** at publish and/or consume boundaries where feasible.
+- Document channels (queues, HTTP callbacks, WebSockets) with **AsyncAPI** or equivalent when multiple consumers exist.
+- Maintain a **single source of truth** for schema versions (registry, repo folder, or generated artifacts — pick one path; avoid two overlapping catalogs without justification).
+
+## Minimum envelope fields
+
+Every published event should minimally support traceability and policy classification:
+
+- `event_id`
+- `event_type`
+- `spec_version`
+- `schema_version`
+- `tenant_id`
+- `entity_id`
+- `correlation_id`
+- `causation_id`
+- `source`
+- `actor_type` (see [approval-policy.md](approval-policy.md))
+- `approval_class`, `reversibility_class`, `sensitivity_class` (where the event represents or precedes a governed action)
+- `trace_id`
+- `timestamp` (ISO-8601, explicit timezone)
+
+## Drift and breaking changes
+
+- **No silent schema drift** — version bumps must be visible in code, registry, or changelog.
+- **No silent breaking changes** — consumers must be updated or compatibility shims documented.
+- Deprecation windows and dual-read/dual-write phases belong in the execution plane plan, not in prompt text.
+
+## Dealix alignment
+
+When adding new integration or workflow events, align names and payloads with existing backend patterns and tenant isolation (`tenant_id`). Prefer explicit correlation IDs through agent and API paths for observability.
+
+See also: [connectors-and-data-plane.md](connectors-and-data-plane.md), [trust-fabric.md](trust-fabric.md).

docs/governance/github-and-release.md

@@ -0,0 +1,43 @@
+# GitHub and release governance
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+Treat GitHub as a **governance surface**, not only file hosting.
+
+## Repository rules
+
+- **Protected branches** for `main` (and release branches if used).  
+- **No direct push** to protected branches; work through PRs.  
+- **Required reviews** and **required status checks** before merge.  
+- **CODEOWNERS** as the team grows for critical paths.  
+- **Conversation resolution** on review threads before merge where policy requires it.  
+- **Signed commits** where org policy demands non-repudiation.  
+- **Linear history** or merge strategy per team convention — document the choice.  
+- **Merge queue** when CI is mature enough to serialize green merges.
+
+## Environments and promotion
+
+Use explicit promotion: **dev → staging → canary → prod** (names may vary; semantics must not).
+
+- Deployment **protection rules** and environment **approvals** for production and production-like environments.  
+- Gates aligned with [trust-fabric.md](trust-fabric.md) (security, tests, evidence).
+
+## Security SDLC on GitHub
+
+- Static analysis (SAST) on PRs where available.  
+- **Dependency review** and automated update workflows (Renovate/Dependabot) with human policy for major bumps.  
+- **Secret scanning** and push protection.  
+- **Artifact provenance / attestations** where supply-chain risk warrants it.  
+- **OIDC federation** to cloud deploy roles instead of long-lived cloud secrets when possible.
+
+## Audit retention
+
+Do not rely on GitHub (or any single SaaS) **retention alone** for audit-critical evidence. Plan streaming or export for long-lived audit trails where legal or enterprise customers require it.
+
+## Dealix pointers
+
+- CI workflows: `salesflow-saas/.github/` (if present) or repo-root `.github/`.  
+- Local preflight: `salesflow-saas/verify-launch.ps1` delegating to `salesflow-saas/scripts/grand_launch_verify.ps1`.  
+- Launch checklist: `salesflow-saas/docs/LAUNCH_CHECKLIST.md`.
+
+See also: [approval-policy.md](approval-policy.md), [discovery-and-output-checklist.md](discovery-and-output-checklist.md).

docs/governance/planes-and-runtime.md

@@ -0,0 +1,40 @@
+# Planes and runtime guidance
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md) (same rules; this file is navigable detail).
+
+## Three governing layers (stack posture)
+
+1. **Exploration intelligence** — discovery, analysis, triage, scenarios, recommendations, decision memos, risk synthesis, forecasting. Outputs are structured (schema-first) with provenance and freshness.
+2. **Committed execution** — the only layer that may create durable commitments, long-lived workflows, and external business actions (signatures, rollouts, partner flows, release promotion, PMI steps, etc.).
+3. **Trust fabric** — policy, approvals, authorization, audit, security gates, tool verification, evidence packs, model/provider governance, traceability, evaluation.
+
+**Primary rule:** AI may recommend; systems commit; humans approve critical decisions.
+
+## Five planes (reference architecture)
+
+| Plane | Owns | Must not |
+|-------|------|----------|
+| **Decision** | Cognition, memos, structured outputs, scenarios, review interrupts | Durable external side effects as “narration only” |
+| **Execution** | Deterministic workflows, retries, compensation, idempotency, versioning, external commitments | Unstructured trust-me execution |
+| **Control** | Policy, approvals, RBAC/ReBAC, secrets, environment promotion, audit, release gates | Ad-hoc rules living only in prompts |
+| **Data** | Operational truth, semantic metrics, embeddings, contracts, lineage, quality, ingestion | Conflicting definitions of the same business metric |
+| **Trust** | Verification, security evidence, model evaluation, provenance, freshness, reversibility | Claims without proof |
+
+**Rule:** cognition loops belong in the decision layer; commitments belong in the execution layer.
+
+## Technology mapping (when to use what)
+
+- **Repo-native coding agents** — repository inspection, edits, refactors, tests, release prep, architecture discovery.
+- **Agent runtimes** — analysis loops, memos, recommendations, structured outputs, tool-based exploration, review interrupts.
+- **Stateful graph runtimes** — persisted cognition, checkpoints, interrupts, resumable reasoning, human-in-the-loop pauses.
+- **Durable workflow runtimes** — flows lasting hours/days/weeks; retries, rollback, compensation; cross-system commitments; must survive crashes, restarts, and deployments.
+
+Long-running **business** workflows must not live only inside ephemeral agent graphs without a durable execution owner.
+
+## Dealix code pointers (illustrative)
+
+- Agent routing / execution: `salesflow-saas/backend/app/services/agents/` (`router.py`, `executor.py`).
+- Graph-style flows: `salesflow-saas/backend/app/agents/`, `salesflow-saas/backend/app/flows/`.
+- Policy direction in code: `salesflow-saas/backend/app/services/dealix_os/` (e.g. policy engine) — keep policy out of markdown prompts.
+
+See also: [approval-policy.md](approval-policy.md), [trust-fabric.md](trust-fabric.md), [discovery-and-output-checklist.md](discovery-and-output-checklist.md).

docs/governance/strategic-ops-pmi.md

@@ -0,0 +1,27 @@
+# Strategic operations, M&A, and PMI
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+This section applies when the product or module touches **corporate development**, **partnerships**, **diligence**, or **post-close integration**.
+
+## Do not defer integration thinking until after close
+
+Require early alignment between **deal thesis** and **integration thesis**:
+
+- **Day-1 readiness** — systems, data, customer comms, support, and access control.  
+- **IMO / PMO structure** — accountable owners for streams (technology, people, revenue, legal).  
+- **Clean team / controlled pre-close analysis** — only where law and contracts permit.  
+- **Synergy realization tracking** — metrics tied to semantic definitions (see [connectors-and-data-plane.md](connectors-and-data-plane.md)).  
+- **Post-close milestone governance** — execution-plane workflows with approvals and evidence, not chat-only tracking.
+
+## Relationship to planes
+
+- **Decision plane** — scenarios, memos, risk registers, comparables, structured recommendations.  
+- **Execution plane** — diligence workflows, data room access, signature flows, PMI task orchestration, regulated communications.  
+- **Control / trust** — S3/board materials, A3/R3 gates, full audit and evidence packs.
+
+## Dealix note
+
+Dealix spans SaaS CRM and strategic modules. When implementing strategic-deals features, enforce the same **A / R / S** classification and **Class B** defaults for anything that could create external or customer-visible commitment.
+
+See also: [approval-policy.md](approval-policy.md), [events-and-schema.md](events-and-schema.md), [trust-fabric.md](trust-fabric.md).

docs/governance/trust-fabric.md

@@ -0,0 +1,56 @@
+# Trust fabric — verification, observability, security
+
+**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
+
+The trust fabric is **operating substrate**, not a product feature checklist item. It wraps decision and execution planes.
+
+## Components (minimum conceptual set)
+
+1. **Policy gate** — rules evaluated before promotion or external commitment.
+2. **Approval routing** — human or committee paths per approval class (see [approval-policy.md](approval-policy.md)).
+3. **Authorization** — RBAC/ReBAC for memos, rooms, launches, admin actions.
+4. **Audit logging** — durable records of who/what/when for governed actions.
+5. **Tool verification** — evidence between intent, claim, and actual tool execution (pattern over vendor lock-in).
+6. **Evidence packs** — tied to decision memos for Class B / R2+ work.
+7. **Security validation** — white-box review before higher environments; stored findings; release blockers for critical issues.
+8. **Traces, logs, metrics** — correlation IDs across API, workers, and workflows.
+9. **Continuous evaluation** — offline datasets, online trace review, regression reviews.
+10. **Red-team workflows** — for agent, RAG, tool, and MCP surfaces.
+11. **Rollback review** — explicit compensation/rollback notes for risky changes.
+12. **Metadata** — provenance, freshness, reversibility on outputs and events where applicable.
+
+## Tool verification layer (per interaction)
+
+Capture where possible:
+
+- Request ID, run ID, agent or workflow ID  
+- Intended action vs claimed action vs actual tool call  
+- Parameters, outputs, material side effects  
+- Timestamps  
+- **Verification status:** `verified` | `partially_verified` | `unverified` | `contradicted`
+
+If the system claims something happened but evidence is insufficient, treat as **contradicted** until corrected.
+
+## Evaluation and observability
+
+Require:
+
+- Distributed tracing or correlation IDs end-to-end  
+- Workflow step telemetry (start, success, failure, retry)  
+- Tool-call, approval, rollback, and provider-routing telemetry  
+- Structured output validation and I/O guardrails where LLMs drive branches  
+- Periodic regression reviews for prompt/model/router changes  
+
+## Security gate scope
+
+Before shipping or promoting: auth, permissions, API routes, admin flows, uploads, webhooks, customer-facing messaging, AI-triggered action surfaces, connectors, release surfaces, MCP/tool surfaces, RAG and document ingestion paths.
+
+Expect: severity classification, stored findings, and **release-blocking** rules for critical classes of issues.
+
+## Dealix pointers
+
+- Security-related services: `salesflow-saas/backend/app/services/security_gate.py`, `salesflow-saas/backend/app/utils/security.py`.
+- Audit models: e.g. `salesflow-saas/backend/app/models/audit_log.py`.
+- Launch discipline: `salesflow-saas/docs/LAUNCH_CHECKLIST.md`, `salesflow-saas/verify-launch.ps1`.
+
+See also: [planes-and-runtime.md](planes-and-runtime.md), [github-and-release.md](github-and-release.md).

salesflow-saas/AGENTS.md

@@ -123,12 +123,29 @@ cd frontend && npm run dev
 
 ## Repository constitution (monorepo root)
 
-The **institutional** operating prompt and governance docs live at the **repository root** (parent of `salesflow-saas/`):
+The **institutional** operating prompt and governance library live at the **repository root** (parent of `salesflow-saas/`). This app must stay aligned with those files.
 
-- [`../MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md) — Master Operating Prompt (planes, trust fabric, events, GitHub, Arabic-first).
-- [`../AGENTS.md`](../AGENTS.md) — short agents constitution (references master + A/R/S).
-- [`../CLAUDE.md`](../CLAUDE.md) — Claude/repo-native rules.
-- [`../docs/ai-operating-model.md`](../docs/ai-operating-model.md) — decision / execution / control / data / trust summary + pointers into this app.
-- [`../docs/governance/approval-policy.md`](../docs/governance/approval-policy.md) — approval, reversibility, sensitivity, action classes.
+**Entry points**
 
-This file (`salesflow-saas/AGENTS.md`) is **app-specific** (stack, conventions, Class A/B/C for shipping). Align both layers: app rules must not contradict root policy.
+- [`../MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md) — canonical Master Operating Prompt (TOC links to all topics).
+- [`../AGENTS.md`](../AGENTS.md) — repo agents constitution + full governance index.
+- [`../CLAUDE.md`](../CLAUDE.md) — Claude/repo-native rules; Cursor slash commands live under [`../.cursor/commands/`](../.cursor/commands/).
+
+**Operating overview**
+
+- [`../docs/ai-operating-model.md`](../docs/ai-operating-model.md) — five planes, mermaid flow, product-type routing, Dealix code pointers.
+
+**Governance library** (`../docs/governance/`)
+
+- [`../docs/governance/README.md`](../docs/governance/README.md) — index of governance docs.
+- [`../docs/governance/planes-and-runtime.md`](../docs/governance/planes-and-runtime.md) — planes, layers, runtimes.
+- [`../docs/governance/approval-policy.md`](../docs/governance/approval-policy.md) — A/R/S, Class A/B/C, evidence packs, cross-matrices.
+- [`../docs/governance/events-and-schema.md`](../docs/governance/events-and-schema.md) — events, JSON Schema, AsyncAPI.
+- [`../docs/governance/trust-fabric.md`](../docs/governance/trust-fabric.md) — trust substrate, tool verification, security gate.
+- [`../docs/governance/connectors-and-data-plane.md`](../docs/governance/connectors-and-data-plane.md) — facades, data plane, semantic metrics.
+- [`../docs/governance/github-and-release.md`](../docs/governance/github-and-release.md) — GitHub SDLC, environments, OIDC.
+- [`../docs/governance/design-and-arabic.md`](../docs/governance/design-and-arabic.md) — design system, RTL, Arabic-first.
+- [`../docs/governance/discovery-and-output-checklist.md`](../docs/governance/discovery-and-output-checklist.md) — discovery, phasing, 20-point report, Arabic bootstrap.
+- [`../docs/governance/strategic-ops-pmi.md`](../docs/governance/strategic-ops-pmi.md) — strategic ops, M&A, PMI.
+
+This file (`salesflow-saas/AGENTS.md`) is **app-specific** (stack, conventions, Class A/B/C for shipping). It must **not** contradict root policy or the governance library.

scripts/architecture_brief.py

@@ -6,13 +6,30 @@ from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
 
-# Paths that should exist for Dealix + constitution wiring
-KEY_PATHS = [
+# Constitution + governance library + Cursor command stubs
+CONSTITUTION_PATHS = [
     "MASTER_OPERATING_PROMPT.md",
     "AGENTS.md",
     "CLAUDE.md",
     "docs/ai-operating-model.md",
+    "docs/governance/README.md",
     "docs/governance/approval-policy.md",
+    "docs/governance/planes-and-runtime.md",
+    "docs/governance/events-and-schema.md",
+    "docs/governance/trust-fabric.md",
+    "docs/governance/connectors-and-data-plane.md",
+    "docs/governance/github-and-release.md",
+    "docs/governance/design-and-arabic.md",
+    "docs/governance/discovery-and-output-checklist.md",
+    "docs/governance/strategic-ops-pmi.md",
+    ".cursor/commands/architecture-map.md",
+    ".cursor/commands/review-policy.md",
+    ".cursor/commands/generate-evidence.md",
+    ".cursor/commands/release-gate.md",
+]
+
+# Dealix application spine (sample)
+SPINE_PATHS = [
     "salesflow-saas/AGENTS.md",
     "salesflow-saas/backend/app/main.py",
     "salesflow-saas/backend/app/services/agents/router.py",
@@ -27,14 +44,14 @@ KEY_PATHS = [
 
 def main() -> None:
     print(f"Repository root: {ROOT}\n")
-    print("--- Constitution & governance ---")
-    for rel in KEY_PATHS[:6]:
+    print("--- Constitution, governance library, Cursor commands ---")
+    for rel in CONSTITUTION_PATHS:
         p = ROOT / rel
         tag = "OK" if p.exists() else "MISS"
         print(f"  [{tag}] {rel}")
 
     print("\n--- Application spine (sample) ---")
-    for rel in KEY_PATHS[6:]:
+    for rel in SPINE_PATHS:
         p = ROOT / rel
         tag = "OK" if p.exists() else "MISS"
         extra = ""
@@ -46,7 +63,10 @@ def main() -> None:
                 pass
         print(f"  [{tag}] {rel}{extra}")
 
-    print("\nNext: read MASTER_OPERATING_PROMPT.md + docs/ai-operating-model.md; then map stack per AGENTS.md before coding.")
+    print(
+        "\nNext: read MASTER_OPERATING_PROMPT.md (TOC) + docs/governance/README.md; "
+        "then docs/ai-operating-model.md; map stack per AGENTS.md before coding."
+    )
 
 
 if __name__ == "__main__":