diff --git a/.claude/settings.json b/.claude/settings.json index 9d3c5e73..11480761 100644 --- a/.claude/settings.json +++ b/.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", - "description": "Generates a comprehensive layout of the core OS structure including agents and memory.", + "name": "architecture-map", + "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", - "description": "Ensure newly written markdown or python files follow architectural constraints." + "command": "python scripts/validate_universal_contract.py", + "description": "Check if agent scripts adhere to Decision Memo structured outputs." } ] } diff --git a/AGENTS.md b/AGENTS.md index 8c521e0b..a3c8a687 100644 --- a/AGENTS.md +++ b/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**: - - Operations are autonomous unless they trigger a HITL (Human-in-the-loop) gate. -2. **No strategic autonomy without evidence**: - - 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. 🔀 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. 🚷 Prohibited Zones (Forbidden Paths) -Agents MUST NOT modify, read, or execute scripts related to the following without explicit `/canary-promote` or `-override` user commands: -- `**/*.env` and `**/secrets/*` -- `production/db_migrations/*` (without Shannon preflight scans) -- `salesflow-saas/backend/scripts/deploy_live.py` (Must invoke manually to enforce HITL) +## 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. -## 3. 🧠 Memory & Verification Guidelines -Agents MUST write their outputs contextually to the `/memory/` structure: -- `/memory/ma/` -> Deal valuation, target screening -- `/memory/partners/` -> Partner scouting, Alliance term sheets -- `/memory/architecture/` -> System changes, ADRs -- `/memory/policies/` -> Compliance engines rules +## 4. 🧠 Memory & Routing +- **Provider Routing**: Use `provider_router.py` to route logic. Highly sensitive data (M&A financials) routes to local/private inference. +- **Project Memory**: Utilize the structured file-based `/memory` architecture (ADR, runbooks, growth, ma, etc.). No unstructured "dumps" allowed. -**The Verification Toolproof Law:** -If you execute an event, you must log: Intent, Claimed Action, Side Effects, and Verification Status (verified, partially_verified, unverified). - -## 4. 🔀 Preferred Toolchains & Adapters -- **Orchestration**: `LangGraph` for M&A/Strategy long-running processes. -- **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.* +## 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. diff --git a/CLAUDE.md b/CLAUDE.md index 32665aee..48600aa8 100644 --- a/CLAUDE.md +++ b/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 -- All UI strings, generated proposals, and communications MUST be strictly Arabic unless otherwise specified. -- Use `IBM Plex Sans Arabic` for standard text and tables. -- Use `29LT Azal` for hero headlines and important numerical displays. -- RTL layout assumptions are default. Ensure `dir="rtl"` is respected in web assets. +## 1. 🏗️ Start with Discovery +- NEVER write code blindly. +- ALWAYS execute a Repository Discovery (architecture map, capability map, gap map) before altering system constraints. -## 2. 📝 Decision Memo Mandate -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). +## 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. ⚙️ Slash Commands -Use the following slash commands within your chats to trigger specific pre-built workflows: -- `/repo-map`: Maps the current structure and memory dependencies (via Repomix). -- `/arch-review`: Executes an architectural ADR compliance check against the `Policy Engine`. -- `/safe-refactor`: Refactors while explicitly running tests and checking policy layers. -- `/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. +## 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). -## 4. 🔗 Code Constraints & Quality -- Focus on robust typing (Python `typing`, Typescript `strict: true`). -- Prefer state machines (`LangGraph` patterns) over standard while-loops for long-running workflows. -- Always implement exhaustive try-except blocks for External API actions (CRM/ERP), appending `{status: 'unverified/failed'}` to the tool proof logger on failure. +## 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. -## 5. 🚪 Approvals & Hooks -Do not write code that blindly patches `main`. Comply with `.claude/settings.json` hook definitions, ensuring you log pre/post execution evidence. +## 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. diff --git a/docs/Architecture_Discovery_Phase1.md b/docs/Architecture_Discovery_Phase1.md new file mode 100644 index 00000000..e47a3084 --- /dev/null +++ b/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.* diff --git a/docs/ai-operating-model.md b/docs/ai-operating-model.md new file mode 100644 index 00000000..0ea9813d --- /dev/null +++ b/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. diff --git a/docs/governance/approval-policy.md b/docs/governance/approval-policy.md new file mode 100644 index 00000000..1ceadb6b --- /dev/null +++ b/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`.