docs(governance): implement Master Operating Prompt rules as Repo Governance

.claude/settings.json

@@ -1,20 +1,20 @@
 {
   "theme": "dark",
-  "projectInstructions": "Follow Dealix OS Sovereign architecture. Do not execute DB changes directly; use action dispatchers. Ensure Universal JSON Output Contract.",
+  "projectInstructions": "Follow Dealix OS Sovereign architecture. Agentic by design, governed by policy, proven by evidence. No Action without Evidence Pack. Enforce Separation of Decision and Execution.",
   "customCommands": [
     {
-      "name": "repo-map",
+      "name": "architecture-map",
-      "description": "Generates a comprehensive layout of the core OS structure including agents and memory.",
+      "description": "Generates a comprehensive layout of the core OS structure including decision/execution planes.",
       "command": "python scripts/repo_mapper.py"
     },
     {
       "name": "canary-check",
-      "description": "Runs local tests before allowing any production deployment simulation.",
+      "description": "Runs local security, format, and unit tests before promotion.",
       "command": "pytest tests/ --cov"
     },
     {
       "name": "security-preflight",
-      "description": "Pre-commit security validation against known PDPL patterns.",
+      "description": "White-box security stage and audit verification mapping (Shannon style).",
       "command": "python scripts/security_gate.py"
     }
   ],
@@ -23,14 +23,14 @@
       {
         "pattern": "git push .*",
         "command": "pytest tests/ && python scripts/audit_changelog.py",
-        "description": "Require unit tests and audit logging before interacting directly with code promotion."
+        "description": "Prevent code pushing without verification ledger proof and policy compliance checks."
       }
     ],
     "PostToolUse": [
       {
         "pattern": "write_to_file",
-        "command": "python scripts/reformat_and_validate.py",
+        "command": "python scripts/validate_universal_contract.py",
-        "description": "Ensure newly written markdown or python files follow architectural constraints."
+        "description": "Check if agent scripts adhere to Decision Memo structured outputs."
       }
     ]
   }

AGENTS.md

@@ -1,49 +1,31 @@
-# Dealix Sovereign Growth OS: Agent Constitution
+# Dealix Sovereign Growth OS: AI Operating Doctrine & Agents Constitution
 
-This file conforms to the public `AGENTS.md` specification. It defines the rules of engagement, architectural boundaries, and absolute laws for any AI Agent (Claude, Cursor, Goose, etc.) reading or executing within the `Dealix Sovereign Growth OS` repository.
+This constitution dictates the behavioral, architectural, and operational rules for any AI Agent (Claude, Cursor, Goose, LangGraph, etc.) interacting with this repository.
 
-## 1. 🛡️ Absolute Golden Rules
+## 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.
 
-1. **Automation by default, approval by exception**: 
+## 2. 🔀 Decision Plane vs. Execution Plane
-   - Operations are autonomous unless they trigger a HITL (Human-in-the-loop) gate.
+- **Decision Plane**: Agents perform cognition, analysis loops, scenario building, and Memo Generation. All outputs here MUST be structured (JSON Schema) and attach provenance/freshness.
-2. **No strategic autonomy without evidence**: 
+- **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.
-   - Agents must write the `Decision Memo` output contract for every action. No silent changes.
-3. **AI assists decisions; business systems remain source of truth**: 
-   - Never mock a database state write unless executing a targeted test.
-4. **Every important action must be replayable, explainable, and reversible**:
-   - Provide a `rollback_plan` in every M&A or expansion document generated. 
-5. **Arabic-first is not a translation layer**: 
-   - Treat Arabic as a primary product architecture choice (RTL natively, `IBM Plex Sans Arabic`).
 
-## 2. 🚷 Prohibited Zones (Forbidden Paths)
+## 3. 🛡️ Absolute Boundaries (Forbidden Zones)
-Agents MUST NOT modify, read, or execute scripts related to the following without explicit `/canary-promote` or `-override` user commands:
+Agents MUST NOT:
-- `**/*.env` and `**/secrets/*`
+- Exfiltrate secrets or modify `**/*.env`/production API keys.
-- `production/db_migrations/*` (without Shannon preflight scans)
+- Bypass branch protection or execute silent destructive changes.
-- `salesflow-saas/backend/scripts/deploy_live.py` (Must invoke manually to enforce HITL)
+- Bypass the `Shannon` Security Gate for canary/production releases.
+- Make public claims without generating a verifiable Evidence Pack.
 
-## 3. 🧠 Memory & Verification Guidelines
+## 4. 🧠 Memory & Routing
-Agents MUST write their outputs contextually to the `/memory/` structure:
+- **Provider Routing**: Use `provider_router.py` to route logic. Highly sensitive data (M&A financials) routes to local/private inference.
-- `/memory/ma/` -> Deal valuation, target screening
+- **Project Memory**: Utilize the structured file-based `/memory` architecture (ADR, runbooks, growth, ma, etc.). No unstructured "dumps" allowed.
-- `/memory/partners/` -> Partner scouting, Alliance term sheets
-- `/memory/architecture/` -> System changes, ADRs
-- `/memory/policies/` -> Compliance engines rules
 
-**The Verification Toolproof Law:**
+## 5. 🤖 Agent Role Restrictions
-If you execute an event, you must log: Intent, Claimed Action, Side Effects, and Verification Status (verified, partially_verified, unverified).
+Any AI acting in this system must strictly adopt one of these roles:
-
+- `Observer`: Monitors and scores (No commit).
-## 4. 🔀 Preferred Toolchains & Adapters
+- `Recommender`: Proposes and generates memos (No direct commit).
-- **Orchestration**: `LangGraph` for M&A/Strategy long-running processes.
+- `Executor`: Triggers external execution workflows but MUST pass Policy Gates and attach Reversibility metadata.
-- **Local/Private Inference**: `Atomic Chat` where PDPL limits cloud transmission.
-- **Ops/Terminal Agent**: `goose` for system actions and multi-step OS workflows.
-- **Repo Context**: `Repomix` for packing complex code architectures for reviews.
-- **Security Check**: `Shannon` for white-box pre-release gates. 
-
-## 5. 🤖 Available Agent Families
-Agents must align with one of these namespaces:
-1. `growth.*` (Market Signal, Partnership Scout, Alliance Structuring, Expansion)
-2. `ma.*` (Screener, DD Analyst, Valuation, Negotiation, PMI)
-3. `revenue.*` (Lead Intel, Exec Outreach, Proposal Design, Expansion)
-4. `governance.*` (Strategic PMO, Compliance, Exec Sovereign Intelligence)
-
----
-*Note: Any agent caught hallucinating a success claim without `audit_metadata` verification will have its access revoked by the Sovereign Orchestrator.*

CLAUDE.md

@@ -1,29 +1,27 @@
-# Dealix AI Coding Guidelines
+# Claude Repo-Native Operating Rules (Dealix Sovereign OS)
 
-This document provides specialized guidelines for Anthropic Claude (via Claude Code, Cursor, or direct API) working in the Dealix Sovereign Growth OS repository.
+You are the Chief Hybrid AI Systems Architect editing this repository.
+Follow these absolute rules when writing or modifying code in this codebase.
 
-## 1. 🌍 Architecting for Arabic First
+## 1. 🏗️ Start with Discovery
-- All UI strings, generated proposals, and communications MUST be strictly Arabic unless otherwise specified.
+- NEVER write code blindly.
-- Use `IBM Plex Sans Arabic` for standard text and tables.
+- ALWAYS execute a Repository Discovery (architecture map, capability map, gap map) before altering system constraints.
-- Use `29LT Azal` for hero headlines and important numerical displays.
-- RTL layout assumptions are default. Ensure `dir="rtl"` is respected in web assets.
 
-## 2. 📝 Decision Memo Mandate
+## 2. 📝 Decision Memo & Output Formats
-Whenever you formulate a strategic script or Python orchestration logic, you MUST build the agent response formatting around the Universal Output Contract (`Decision Memo JSON`). Do not write monolithic text outputs for agents; use structured validation (e.g., Pydantic models).
+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. ⚙️ Slash Commands
+## 3. ⌨️ Development & Slash Commands
-Use the following slash commands within your chats to trigger specific pre-built workflows:
+* `/architecture-map`: Analyzes and outputs the current architecture footprint.
-- `/repo-map`: Maps the current structure and memory dependencies (via Repomix).
+* `/review-policy`: Scans current work against the Policy Governance matrices before commit.
-- `/arch-review`: Executes an architectural ADR compliance check against the `Policy Engine`.
+* `/generate-evidence`: Creates an evidence pack linking claimed code to the verification ledger.
-- `/safe-refactor`: Refactors while explicitly running tests and checking policy layers.
+* `/release-gate`: Runs the final white-box pre-flight (Shannon concepts + tests).
-- `/board-memo`: Compiles latest Sovereign inputs into an Arabic Executive Memo.
-- `/security-preflight`: Runs Shannon and formatting checks before generating a PR.
-- `/ma-brief`: Aggregates the contents of `/memory/ma/` to generate a DD summary.
 
-## 4. 🔗 Code Constraints & Quality
+## 4. 🎨 Design Quality & Arabic
-- Focus on robust typing (Python `typing`, Typescript `strict: true`).
+- Design quality must match engineering quality.
-- Prefer state machines (`LangGraph` patterns) over standard while-loops for long-running workflows.
+- **RTL-safe / Arabic First**: Use `IBM Plex Sans Arabic` for primary UI. Only use `29LT Azal` for hero/Display texts.
-- Always implement exhaustive try-except blocks for External API actions (CRM/ERP), appending `{status: 'unverified/failed'}` to the tool proof logger on failure.
+- Do NOT use generic placeholder text; generate structured Arabic operational outputs.
 
-## 5. 🚪 Approvals & Hooks
+## 5. 🔌 Integration & Connectors
-Do not write code that blindly patches `main`. Comply with `.claude/settings.json` hook definitions, ensuring you log pre/post execution evidence.
+- Do NOT integrate directly with vendor APIs from Agent scripts.
+- Use Internal Connector Facades with retries, timeouts, idempotency, and audit hook requirements.

docs/Architecture_Discovery_Phase1.md

@@ -0,0 +1,53 @@
+# Dealix Sovereign Growth OS: Discovery & Phase 1 Execution Plan
+
+بناءً على الفحص المعماري لبيئة العمل وتطبيق "Master Operating Prompt"، هذه هي الخريطة المعمارية الموثقة للكود (Code-backed Discovery):
+
+## 1. Code-backed Architecture Map
+* **Frontend/Routing Layer**: `Next.js` and `FastAPI` (serving at ports 8001/8002).
+* **Backend Agent Services**: `/salesflow-saas/backend/app/services/agents/` containing the execution routers (`router.py`, `executor.py`) routing standard sales tools.
+* **Core Operating System (New)**: `/salesflow-saas/backend/app/services/core_os/`
+  * `provider_router.py`: Handles abstract routing based on PDPL sensitivity (Local vs Cloud).
+  * `project_memory_store.py`: Abstraction backing the `/memory` infrastructure.
+  * `verification_ledger.py`: The `ToolProof` verification layer handling execution claims.
+  * `decision_memo.py`: Pydantic V2 engine validating the Universal Output Contract.
+* **Executive Strategic Core (New)**: `/salesflow-saas/backend/app/services/strategic_deals/`
+  * `partnership_scout.py`
+  * `strategic_pmo.py`
+* **Governance Scripts**: `.claude/settings.json`, `AGENTS.md`, and `/docs/governance/`.
+
+## 2. Verified Capability Map (What works today)
+* ✅ **Agent Command Routing**: The Execution framework robustly routes intents through LLMs loading `.md` prompts.
+* ✅ **Structured Prompting**: Health checks and 37 prompt definitions (including the new 16 executive agents).
+* ✅ **Central Output Standardization**: The Decision Memo schema now governs outputs, requiring risk and financial parameters.
+* ✅ **Infrastructure Foundations**: Local execution and cloud execution logics are physically defined in the router.
+* ✅ **Tool Claims Logging**: Verification ledger records Intents and Side-effects.
+
+## 3. Gap Map (Missing Critical Capabilities)
+* ❌ **Agent Long-Running Durability**: Current Python implementations (like PMO and Scout) emulate state but lack physical `LangGraph` Checkpoint integration to survive server restarts.
+* ❌ **IdP / RBAC Limits**: Approval rules (A, B, C) are defined in `.md` but not yet hard-coded physically into a middleware blocking FastAPI endpoints.
+* ❌ **Connector Facades**: The current system might contact external systems directly. True internal `Connector Facade` wrappers (with timeouts/idempotency keys) are not yet fully abstracted.
+* ❌ **White-box Security Logic**: `security_gate.py` must be upgraded to actually perform AST (Abstract Syntax Tree) exploit tests like Shannon.
+
+## 4. Safest Integration Points
+1. **Decision Output**: Integrate `DecisionMemo` into every final `return` statement of `executor.py`.
+2. **LangGraph Runtime**: Migrate the `execute_flow` method inside `partnership_scout.py` to inherit entirely from `StateGraph` (combining node functions).
+3. **Internal Tools Hooks**: Add decorators over tools in `salesflow-saas/backend/app/api/` that automatically log to `verification_ledger.py`.
+
+## 5. Target Operating Architecture
+* **Decision Plane (Stateless)**: Agents run fast iterations, generate Memos, and immediately stop. 
+* **Execution Plane (Stateful/LangGraph)**: The only entity allowed to commit APIs (e.g., Stripe, CRM, Jira). It reads the `DecisionMemo`, pauses for `CEO Approval` if `Class B/C`, then executes.
+* **Memory Fabric**: Everything feeds immediately back into the `.json` schemas inside `/memory/`.
+
+## 6. Policy & Approval Model Summary
+* **Class A (Auto)**: Repo code updates, test generation. Requires only Verification Ledger proof.
+* **Class B (Approval / R2 Reversibility)**: Public marketing, CRM adjustments. Triggers LangGraph HITL interrupt for VP Operations.
+* **Class C (Board / R3 Irreversible)**: M&A proposals, Partnership sign-offs. Requires C-level signatures via Execution Plane.
+
+## 7. Phased Implementation Plan (Phase 1 ONLY)
+
+**Phase 1: Wiring the Fabric (Strict execution of Repo Governance)**
+1. **Apply Hooks**: Ensure `.claude/hooks` actually trigger Python test harnesses locally for developers.
+2. **Execute LangGraph Checkpointing**: Physically wrap the existing `partnership_scout.py` inside a LangChain/LangGraph `MemorySaver` to provide resumption.
+3. **Connector Facade V1**: Build ONE facade (e.g. `CRM Connector`) proving idempotency and rollback logging, redirecting agents away from direct API endpoints.
+
+*Restriction: We will NOT move to Phase 2 (Advanced M&A, Deep PMO) until the Connector Facade and LangGraph durable worker integrations are proven operational and verified.*

docs/ai-operating-model.md

@@ -0,0 +1,30 @@
+# Dealix Sovereign Growth OS: AI Operating Model
+
+## 1. Core Operating Doctrine
+The operating fabric distinguishes between **Decision** and **Execution** planes:
+
+- **Decision Plane**: Agent cognition, analysis loops, scenario evaluation, structured output (`Decision Memo`). Handled by Agents like M&A Screener and Partnership Scout.
+- **Execution Plane**: Deterministic workflows, retries, worker durability. LangGraph states acting to commit external business processes.
+
+## 2. Infrastructure Routing (Provider Abstraction)
+We do not hardwire to one vendor. Use `ProviderRouter` to intelligently select:
+- **Cloud Models** (Claude 3.5, GPT-4o) for heavy reasoning and coding.
+- **Local/Private Inference** (Atomic Chat adapters / Llama-3) for PDPL compliance, Arabic parsing of sensitive contracts, and internal drafting.
+
+## 3. Tool Verification (ToolProof Pattern)
+Every meaningful script interaction requires Verification:
+1. `run_id` linked to the interaction.
+2. `intended_action` vs `claimed_action`.
+3. Evaluated status: `verified`, `partially_verified`, `unverified`, `contradicted`.
+If the system claims an action but evidence lacks, it is automatically marked `contradicted`.
+
+## 4. Connector Facade Rule
+Agents do NOT talk directly to external APIs (like Stripe, Salesforce). They must route through an internal Connector Facade which enforces:
+- Idempotency
+- Timeouts/Retries
+- Audit Logging
+- Reversibility plans
+
+## 5. Memory & Second Brain
+Filesystem-based JSON indexed memory in `/memory`.
+Includes: ADRs, Postmortems, Growth Experiments, Security Checks, and Escalation Memos.

docs/governance/approval-policy.md

@@ -0,0 +1,23 @@
+# Governance & Approval Policy Models
+
+Every action by any Agent must be assigned to an **Approval Class**, a **Reversibility Class**, and a **Sensitivity Class**.
+
+## 1. Approval Classes
+- **Class A (Auto Allowed)**: Repo inspection, summaries, drafts, testing, local DB reads.
+- **Class B (Approval Required)**: Changes to config, database migrations, marketing email blasts, pricing changes, public publishing. (Requires VP/Manager Gate).
+- **Class C (Board Level/Forbidden)**: Term sheets, M&A initiation, destructive changes. (Requires CEO/Board Gate).
+
+## 2. Reversibility Classes
+- **R0**: Fully auto-reversible (e.g. Git reset locally).
+- **R1**: Reversible with limited intervention (e.g. drafting an email).
+- **R2**: Costly/painful to reverse (e.g. generating an expensive comprehensive report).
+- **R3**: Irreversible / External Commitment (e.g. signing a digital contract, creating an external Dealroom).
+
+## 3. Sensitivity Classes
+- **S0**: Public data.
+- **S1**: Internal operational data.
+- **S2**: Confidential (Pricing margins, employee data). Must use local/private AI.
+- **S3**: Highly Sensitive (M&A targeting, legal disputes, board packets). Strictly guarded.
+
+## 4. Policy Engine Execution Constraint
+No Agent may commit an action of `R2/R3` or dealing with `S2/S3` without an `Evidence Pack` accompanying a `Decision Memo` that has explicitly secured authorization via the `Execution Plane`.