diff --git a/AGENTS.md b/AGENTS.md index 24845e3a..9ff0fab1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,13 @@ Use these for depth, onboarding, and review. Each expands themes from the master | [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 | +| [docs/governance/execution-fabric.md](docs/governance/execution-fabric.md) | Celery/LangGraph today vs Temporal target | +| [docs/governance/technology-radar-tier1.md](docs/governance/technology-radar-tier1.md) | Official vs optional vs pilot stack | +| [docs/governance/saudi-compliance-and-ai-governance.md](docs/governance/saudi-compliance-and-ai-governance.md) | PDPL/NCA readiness, NIST/OWASP alignment | +| [docs/dealix-six-tracks.md](docs/dealix-six-tracks.md) | Six Dealix OS tracks + code pointers + status snapshot | +| [docs/blueprint-master-architecture.md](docs/blueprint-master-architecture.md) | Master blueprint index | +| [docs/execution-matrix-90d-tier1.md](docs/execution-matrix-90d-tier1.md) | Phase 0–1 outcomes vs matrix | +| [docs/adr/0001-tier1-execution-policy-spikes.md](docs/adr/0001-tier1-execution-policy-spikes.md) | Gated spikes: Temporal, OPA, OpenFGA | Operating overview with diagram: **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)**. diff --git a/Architecture_Pack.md b/Architecture_Pack.md index 2fc8ec84..040d2311 100644 --- a/Architecture_Pack.md +++ b/Architecture_Pack.md @@ -2,6 +2,8 @@ يمثل هذا المستند البنية الهندسية (Architecture Backbone) لتحويل Dealix من "نظام أتمتة مبيعات" إلى "نظام تشغيل نمو سيادي" (Level 5 Autonomy for Holding & Enterprise Scaling). +**فهرس Tier-1 (إنجليزي، يحدّث مع المستودع):** [`docs/blueprint-master-architecture.md`](docs/blueprint-master-architecture.md) — يربط المسارات الستة، الطائرات، مصفوفة التنفيذ، وحوكمة التسليم. **المسارات التشغيلية الستة:** [`docs/dealix-six-tracks.md`](docs/dealix-six-tracks.md). **طبقة التنفيذ الحتمية (حالي مقابل Temporal):** [`docs/governance/execution-fabric.md`](docs/governance/execution-fabric.md). + --- ## 1. 🗺️ خريطة الخدمات (Service Map) diff --git a/CLAUDE.md b/CLAUDE.md index a806ab8b..52b5dcf6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,5 +48,7 @@ For policy scanning, evidence packs, and release gates in Cursor, use `/review-p - **[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. +- **[docs/dealix-six-tracks.md](docs/dealix-six-tracks.md)** — six OS tracks + honest status vs Tier-1 target. +- **[docs/blueprint-master-architecture.md](docs/blueprint-master-architecture.md)** — blueprint index; **[docs/adr/0001-tier1-execution-policy-spikes.md](docs/adr/0001-tier1-execution-policy-spikes.md)** — gated spikes (Temporal, OPA, OpenFGA). Discovery before code; Phase 1 only until evidence; no policy logic in prompts where it belongs in policy systems. diff --git a/MASTER_OPERATING_PROMPT.md b/MASTER_OPERATING_PROMPT.md index 35be6268..8ac538c7 100644 --- a/MASTER_OPERATING_PROMPT.md +++ b/MASTER_OPERATING_PROMPT.md @@ -20,6 +20,13 @@ Deep-dive topics live under [`docs/governance/`](docs/governance/) (keep this fi | 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) | +| Six operational tracks (Dealix) | [`docs/dealix-six-tracks.md`](docs/dealix-six-tracks.md) | +| Execution fabric (current vs Tier-1 target) | [`docs/governance/execution-fabric.md`](docs/governance/execution-fabric.md) | +| Technology radar (official / optional / pilot) | [`docs/governance/technology-radar-tier1.md`](docs/governance/technology-radar-tier1.md) | +| Saudi compliance & AI governance register | [`docs/governance/saudi-compliance-and-ai-governance.md`](docs/governance/saudi-compliance-and-ai-governance.md) | +| Master architecture blueprint (index) | [`docs/blueprint-master-architecture.md`](docs/blueprint-master-architecture.md) | +| 90-day Tier-1 execution matrix | [`docs/execution-matrix-90d-tier1.md`](docs/execution-matrix-90d-tier1.md) | +| ADR: Temporal / OPA / OpenFGA spikes | [`docs/adr/0001-tier1-execution-policy-spikes.md`](docs/adr/0001-tier1-execution-policy-spikes.md) | --- diff --git a/docs/adr/0001-tier1-execution-policy-spikes.md b/docs/adr/0001-tier1-execution-policy-spikes.md new file mode 100644 index 00000000..14f01c1a --- /dev/null +++ b/docs/adr/0001-tier1-execution-policy-spikes.md @@ -0,0 +1,61 @@ +# ADR 0001 — Tier-1 spikes: Temporal, OPA, OpenFGA (gated) + +- **Status:** Proposed +- **Date:** 2026-04-16 +- **Context:** Dealix Tier-1 roadmap targets **Temporal** for crash-proof long workflows and **OPA / OpenFGA** (or Cedar) for separable policy and fine-grained authorization. The repo today uses **FastAPI, Celery, LangGraph**, and in-app policy patterns. + +## Decision (interim) + +**Do not** merge production dependencies on Temporal, OPA, or OpenFGA until **all** spike exit criteria below are met for each technology independently. + +Until then, document them only as **targets** in: + +- [`../governance/execution-fabric.md`](../governance/execution-fabric.md) +- [`../governance/trust-fabric.md`](../governance/trust-fabric.md) +- [`../governance/technology-radar-tier1.md`](../governance/technology-radar-tier1.md) + +## Spike — Temporal + +**Goal:** One non-customer-critical workflow (or shadow mode) proving resume after worker kill and **worker versioning** story. + +**Exit criteria:** + +1. Workflow code and tests in CI (docker-compose or Temporal test server). +2. Idempotency keys on external side effects; compensation path documented. +3. Security review for secrets and network boundaries. +4. Runbook: deploy, rollback, and “what happens on double start.” +5. Product owner sign-off to move additional flows. + +## Spike — OPA (or equivalent PDP) + +**Goal:** One policy (e.g. environment promotion or “may send message”) evaluated from **structured input** (JSON) with decision logged. + +**Exit criteria:** + +1. Policy bundle versioned in repo; CI runs `opa test` (or equivalent) on policies. +2. No duplication of the same rule in prompts and OPA without explicit ownership. +3. Latency and failure mode documented (fail closed vs open). + +## Spike — OpenFGA (or Cedar) + +**Goal:** One authorization model (e.g. “user U may read DD room R for tenant T”) with tuple writes on lifecycle events. + +**Exit criteria:** + +1. Model file + migration plan for existing RBAC. +2. Performance test for hot paths. +3. Audit: who changed tuples; backup/restore considered. + +## Evidence pack (per spike) + +Each spike produces: design note, threat assumptions, test commands and results, rollback plan, and explicit **Approved / Rejected / Extend pilot** outcome recorded in this ADR or a superseding ADR. + +## Consequences + +- Engineering avoids **split brain** between agent narration and system-of-record workflows. +- Compliance and security can review **one** policy and auth surface per decision type. + +## Related + +- [`../execution-matrix-90d-tier1.md`](../execution-matrix-90d-tier1.md) Phase 0–1 +- [`../blueprint-master-architecture.md`](../blueprint-master-architecture.md) diff --git a/docs/ai-operating-model.md b/docs/ai-operating-model.md index c679d2dd..df6c5af0 100644 --- a/docs/ai-operating-model.md +++ b/docs/ai-operating-model.md @@ -1,7 +1,9 @@ -# AI operating model — decision, execution, control, data, trust +# AI operating model — decision, execution, control, data, trust, operating This repository follows the **Master Operating Prompt** ([`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md)): a governed hybrid stack, not “agents only.” +**Dealix six tracks** (Revenue, Partnership, CorpDev/M&A, Expansion, PMI, Trust & exec): [`dealix-six-tracks.md`](dealix-six-tracks.md). + ## Governance library (full index) | Document | Purpose | @@ -16,6 +18,11 @@ This repository follows the **Master Operating Prompt** ([`MASTER_OPERATING_PROM | [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 | +| [governance/execution-fabric.md](governance/execution-fabric.md) | Celery/LangGraph today vs Temporal target (Tier-1) | +| [governance/technology-radar-tier1.md](governance/technology-radar-tier1.md) | Official vs optional vs pilot stack | +| [governance/saudi-compliance-and-ai-governance.md](governance/saudi-compliance-and-ai-governance.md) | PDPL posture, NCA readiness, NIST/OWASP alignment | +| [execution-matrix-90d-tier1.md](execution-matrix-90d-tier1.md) | Phase 0–1 outcomes vs agent matrix | +| [blueprint-master-architecture.md](blueprint-master-architecture.md) | Master blueprint index | ## Planes at a glance @@ -26,6 +33,9 @@ This repository follows the **Master Operating Prompt** ([`MASTER_OPERATING_PROM | **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 | +| **Operating** (Tier-1 naming) | Repo-native discipline, CI/CD, branch/env governance, SDLC, delivery evidence | “Control on paper” without pipeline and audit trail | + +**Operating** extends **Control** into how changes ship: see [planes-and-runtime.md — Operating plane](governance/planes-and-runtime.md#operating-plane-tier-1-naming). ## Flow (conceptual) @@ -51,16 +61,21 @@ flowchart LR Evidence[EvidenceAndVerification] Obs[ObservabilityAndSecurityGate] end + subgraph operatingPlane [OperatingPlane] + RepoCI[RepoCICDAndPromotion] + end decisionPlane --> controlPlane controlPlane --> executionPlane executionPlane --> dataPlane + operatingPlane --> controlPlane trustPlane -.-> decisionPlane trustPlane -.-> executionPlane trustPlane -.-> controlPlane trustPlane -.-> dataPlane + trustPlane -.-> operatingPlane ``` -Trust wraps every plane: verification, audit, telemetry, and gates apply to cognition outputs, policy decisions, workflow steps, and data mutations. +Trust wraps every plane: verification, audit, telemetry, and gates apply to cognition outputs, policy decisions, workflow steps, data mutations, and **operating** evidence (CI, merges, deployments). ## Starting path by product type diff --git a/docs/blueprint-master-architecture.md b/docs/blueprint-master-architecture.md new file mode 100644 index 00000000..1c33f2db --- /dev/null +++ b/docs/blueprint-master-architecture.md @@ -0,0 +1,47 @@ +# Master architecture blueprint — Dealix Sovereign OS (index) + +This document **indexes** the architecture backbone. It does not replace detailed Arabic/English packs already in the repo; it **routes** readers to the right source of truth. + +## North star + +**Dealix Sovereign Growth & Execution OS** — six operational tracks, one fabric: decision, execution, control, data, trust, and **operating** (delivery governance). See [`dealix-six-tracks.md`](dealix-six-tracks.md). + +**Rule:** AI explores; systems commit through workflows; humans approve critical moves (A/R/S). + +## Layered service view (narrative) + +For the classic “8 layers” service map (signal, memory, reasoning, orchestration, policy, actions, analytics, executive cockpit), see **[`Architecture_Pack.md`](../Architecture_Pack.md)** at repository root. + +## Planes and runtimes + +- Planes table + **Operating plane** definition: [`governance/planes-and-runtime.md`](governance/planes-and-runtime.md) +- Diagram + governance library index: [`ai-operating-model.md`](ai-operating-model.md) + +## Agents, events, and HITL + +- **16 agents × events × KPIs × gates:** [`Execution_Matrix.md`](../Execution_Matrix.md) (and `Execution_Matrix_v2.md` if maintained in parallel). + +## Execution and trust (Tier-1) + +- **Execution fabric (Celery/LangGraph → Temporal criteria):** [`governance/execution-fabric.md`](governance/execution-fabric.md) +- **Trust fabric (verification, security, evals):** [`governance/trust-fabric.md`](governance/trust-fabric.md) +- **Technology radar (official / optional / pilot):** [`governance/technology-radar-tier1.md`](governance/technology-radar-tier1.md) +- **Saudi compliance & AI governance register:** [`governance/saudi-compliance-and-ai-governance.md`](governance/saudi-compliance-and-ai-governance.md) + +## Constitution and repo operating pack + +- [`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md) +- [`AGENTS.md`](../AGENTS.md), [`CLAUDE.md`](../CLAUDE.md) +- `.cursor/commands/`, `.claude/settings.json`, `scripts/architecture_brief.py` + +## 90-day execution focus + +- [`execution-matrix-90d-tier1.md`](execution-matrix-90d-tier1.md) + +## Spikes and ADRs (gated) + +- [`adr/0001-tier1-execution-policy-spikes.md`](adr/0001-tier1-execution-policy-spikes.md) + +--- + +When updating architecture, change **one canonical place** for agent/event truth (`Execution_Matrix.md`) and link from here — avoid duplicating long tables in this file. diff --git a/docs/dealix-six-tracks.md b/docs/dealix-six-tracks.md new file mode 100644 index 00000000..334d5c95 --- /dev/null +++ b/docs/dealix-six-tracks.md @@ -0,0 +1,47 @@ +# Dealix — six operational tracks (Sovereign Growth & Execution OS) + +**Canonical constitution:** [`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md). +**Planes and runtimes:** [`docs/governance/planes-and-runtime.md`](governance/planes-and-runtime.md), [`docs/ai-operating-model.md`](ai-operating-model.md). + +Dealix is positioned as **Sovereign Growth & Execution OS**, not a single-purpose “AI sales bot.” The six tracks below are **product and governance lanes** that share the same decision / execution / trust / data / operating fabric. + +**Operating rule:** AI explores and recommends; **deterministic workflows** commit durable actions; **humans** approve critical moves (A/R/S classification). See [`docs/governance/approval-policy.md`](governance/approval-policy.md). + +--- + +## Track map + +| Track | Purpose (summary) | Primary code / docs (starting points) | +|-------|-------------------|----------------------------------------| +| **Revenue OS** | Pipeline, leads, proposals, commercial execution | [`salesflow-saas/backend/app/services/agents/`](../salesflow-saas/backend/app/services/agents/), CRM APIs, [`salesflow-saas/docs/ARCHITECTURE.md`](../salesflow-saas/docs/ARCHITECTURE.md), [`salesflow-saas/docs/API-MAP.md`](../salesflow-saas/docs/API-MAP.md) | +| **Partnership OS** | Scout, fit, structure, partner lifecycle | [`salesflow-saas/backend/app/services/strategic_deals/partnership_scout.py`](../salesflow-saas/backend/app/services/strategic_deals/partnership_scout.py), [`deal_negotiator.py`](../salesflow-saas/backend/app/services/strategic_deals/deal_negotiator.py), [`Execution_Matrix.md`](../Execution_Matrix.md) (Alliance / Scout rows) | +| **Corporate Development / M&A OS** | Screening, DD, valuation, deal room | [`salesflow-saas/backend/app/services/strategic_deals/`](../salesflow-saas/backend/app/services/strategic_deals/) (`acquisition_scouting.py`, `deal_room.py`, `company_profiler.py`, …), [`docs/governance/strategic-ops-pmi.md`](governance/strategic-ops-pmi.md) | +| **Expansion OS** | Markets, playbooks, launch readiness | [`salesflow-saas/backend/app/services/strategic_deals/strategic_simulator.py`](../salesflow-saas/backend/app/services/strategic_deals/strategic_simulator.py), GTM docs under [`salesflow-saas/docs/`](../salesflow-saas/docs/) | +| **PMI / Strategic PMO OS** | Post-close, synergies, milestones | [`strategic_pmo.py`](../salesflow-saas/backend/app/services/strategic_deals/strategic_pmo.py), [`Execution_Matrix.md`](../Execution_Matrix.md) (PMI / PMO rows), [`governance/strategic-ops-pmi.md`](governance/strategic-ops-pmi.md) | +| **Trust, Policy & Executive Governance OS** | Policy, audit, security gate, exec intelligence | [`salesflow-saas/backend/app/services/dealix_os/policy_engine.py`](../salesflow-saas/backend/app/services/dealix_os/policy_engine.py), [`docs/governance/trust-fabric.md`](governance/trust-fabric.md), [`docs/governance/approval-policy.md`](governance/approval-policy.md), legal pack [`salesflow-saas/docs/legal/`](../salesflow-saas/docs/legal/) | + +Agent families (16 agents) in [`Execution_Matrix.md`](../Execution_Matrix.md) roll up into these six tracks; when adding agents, tag the owning track and HITL gate in the matrix. + +--- + +## Implementation status vs Tier-1 target (honest snapshot) + +Use this to avoid claiming components that are not yet wired in production. Refresh when shipping milestones. + +| Area | Status | Notes | +|------|--------|--------| +| Decision plane (memos, structured outputs, routing) | **Partial** | LangGraph / agents / `AgentExecutor`; tighten schema + evidence on all governed paths | +| Execution plane (durable, crash-proof, versioned workers) | **Partial** | Celery + flows today; **Temporal** is a documented Tier-1 target only — see [`docs/governance/execution-fabric.md`](governance/execution-fabric.md) (when added) | +| Trust plane (tool verification, evals, red-team) | **Partial** | Audit, `security_gate`, policy engine; expand verification ledger consistently | +| Data plane (semantic metrics, single lineage catalog) | **Partial** | Postgres + patterns; semantic layer / lineage tool TBD per [`technology-radar-tier1.md`](governance/technology-radar-tier1.md) (when added) | +| Operating plane (GitHub rulesets, env promotion, OIDC) | **Partial** | Documented in [`github-and-release.md`](governance/github-and-release.md); enforce per org tier | +| OPA / OpenFGA / Vault / Keycloak as policy & IAM | **Planned** | Target architecture only until ADR + spike + evidence | + +--- + +## Related assets + +- Master execution matrix (agents × events × HITL): [`Execution_Matrix.md`](../Execution_Matrix.md) +- Architecture pack (layers): [`Architecture_Pack.md`](../Architecture_Pack.md) +- Tier-1 blueprint (index): [`docs/blueprint-master-architecture.md`](blueprint-master-architecture.md) (when present) +- 90-day Tier-1 matrix: [`docs/execution-matrix-90d-tier1.md`](execution-matrix-90d-tier1.md) (when present) diff --git a/docs/execution-matrix-90d-tier1.md b/docs/execution-matrix-90d-tier1.md new file mode 100644 index 00000000..136607e9 --- /dev/null +++ b/docs/execution-matrix-90d-tier1.md @@ -0,0 +1,53 @@ +# 90-day Tier-1 execution matrix (Phase 0–1) + +**Purpose:** Translate **Phase 0 (0–30d)** and **Phase 1 (30–90d)** outcomes from the Tier-1 roadmap into **measurable** deliverables tied to existing repo artifacts. +**Agent truth source:** [`Execution_Matrix.md`](../Execution_Matrix.md) — this file does not duplicate all agent rows; it maps **milestones** to **evidence** and **matrix coverage**. + +**Blueprint index:** [`blueprint-master-architecture.md`](blueprint-master-architecture.md). + +--- + +## Phase 0 (days 0–30): control + operating baseline + +**Goal:** Stabilize **control plane** and **operating plane** so later agent and workflow expansion is auditable. + +| # | Outcome | Evidence / artifact | Execution_Matrix touchpoints (examples) | +|---|---------|----------------------|----------------------------------------| +| P0.1 | **A / R / S** on governed events and APIs documented and used in reviews | [`governance/approval-policy.md`](governance/approval-policy.md); PR checklist | Policy & Compliance agent (row 15); any row with HITL | +| P0.2 | **Event envelope + schema discipline** agreed and referenced in new events | [`governance/events-and-schema.md`](governance/events-and-schema.md); schema folder or ADR | All rows with Events In/Out | +| P0.3 | **Trace/correlation** standard across API + workers + agent runs | OTel or structured logging ADR; sample trace | Executive Intelligence, Strategic PMO | +| P0.4 | **GitHub governance** (rulesets, required checks, no direct push to main) documented for org | [`governance/github-and-release.md`](governance/github-and-release.md) | Operating plane | +| P0.5 | **Executive room skeleton** — doc + minimal UI/API stub behind flag | `salesflow-saas/docs/` + backend route spec | Executive Intelligence (row 16) | +| P0.6 | **AI governance baseline** (NIST AI RMF / OWASP LLM alignment register) | [`governance/saudi-compliance-and-ai-governance.md`](governance/saudi-compliance-and-ai-governance.md) | Trust fabric | +| P0.7 | **PDPL / NCA readiness register** (non-legal checklist) | Same + [`salesflow-saas/docs/legal/`](../salesflow-saas/docs/legal/) | Policy & Compliance; DD Analyst | + +**Exit criteria for Phase 0:** checklist items P0.1–P0.4 **done** in repo/docs; P0.5–P0.7 **at least drafted** with owner and review date. + +--- + +## Phase 1 (days 30–90): Revenue + Partner OS MVP + +**Goal:** First **partner + revenue** loop with **evidence pack v1** and **tool verification v1** on critical paths. + +| # | Outcome | Evidence / artifact | Execution_Matrix touchpoints (examples) | +|---|---------|----------------------|----------------------------------------| +| P1.1 | **Partnership Scout** path: scouted → scored with audit fields | Tests + API or worker logs | Partnership Scout (row 2) | +| P1.2 | **Qualification / triage** for leads with structured memo output | JSON memo contract + tests | Lead Intelligence (row 10) | +| P1.3 | **Strategic PMO** milestone tracking integrated with real task source | Integration note + API | Strategic PMO (row 14) | +| P1.4 | **Connector / action facades** for first external channel (e.g. messaging) with retries + idempotency | Facade module + contract tests | Executive Outreach (row 11); Policy gates | +| P1.5 | **Partner scorecards** reproducible from data (not ad-hoc LLM text) | Query or report + snapshot tests | Partnership Scout; Alliance Structuring (row 3) | +| P1.6 | **Forecast vs actual** slice for one KPI (pipeline or revenue) | Semantic metric definition in one place | Customer Expansion (row 13); analytics docs | +| P1.7 | **Evidence pack v1** template used on Class B decisions | Template in docs + one exemplar PR | Alliance Structuring (term sheet HITL); Proposal (row 12) | +| P1.8 | **Tool verification v1** on at least one tool surface (intended vs actual logged) | Log schema or table + test | Trust fabric; any tool-using agent | + +**Exit criteria for Phase 1:** P1.1–P1.4 **shipped behind flags or staging** with tests; P1.5–P1.8 **documented + one end-to-end demo** with evidence references (no production claims without `verify-launch` / pytest where applicable). + +--- + +## Dependency order + +1. Phase 0 operating + policy + events **before** widening external connectors. +2. Evidence pack + tool verification **in parallel** with first Partner/Revenue MVP features. +3. **Temporal / OPA / OpenFGA** only after [`adr/0001-tier1-execution-policy-spikes.md`](adr/0001-tier1-execution-policy-spikes.md) approval and spike evidence — see execution fabric doc. + +See also: [`dealix-six-tracks.md`](dealix-six-tracks.md), [`governance/discovery-and-output-checklist.md`](governance/discovery-and-output-checklist.md). diff --git a/docs/governance/README.md b/docs/governance/README.md index d021b421..71ab9d9d 100644 --- a/docs/governance/README.md +++ b/docs/governance/README.md @@ -14,5 +14,10 @@ This folder expands each major theme for navigation, review, and agent onboardin | [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 | +| [execution-fabric.md](execution-fabric.md) | Durable execution: current stack vs Temporal target | +| [technology-radar-tier1.md](technology-radar-tier1.md) | Tier-1 technology radar (official / optional / pilot) | +| [saudi-compliance-and-ai-governance.md](saudi-compliance-and-ai-governance.md) | PDPL/NCA readiness register, NIST/OWASP AI governance | + +**Tier-1 index docs (repo `docs/`):** [dealix-six-tracks.md](../dealix-six-tracks.md), [blueprint-master-architecture.md](../blueprint-master-architecture.md), [execution-matrix-90d-tier1.md](../execution-matrix-90d-tier1.md), [adr/0001-tier1-execution-policy-spikes.md](../adr/0001-tier1-execution-policy-spikes.md). Repo entry points: [`../../AGENTS.md`](../../AGENTS.md), [`../../CLAUDE.md`](../../CLAUDE.md), [`../ai-operating-model.md`](../ai-operating-model.md). diff --git a/docs/governance/execution-fabric.md b/docs/governance/execution-fabric.md new file mode 100644 index 00000000..8497a249 --- /dev/null +++ b/docs/governance/execution-fabric.md @@ -0,0 +1,62 @@ +# Execution fabric — durable commitments (current vs Tier-1 target) + +**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md). +**Six tracks:** [`../dealix-six-tracks.md`](../dealix-six-tracks.md). + +## Principle + +Anything that: + +- lasts **hours to weeks**, +- crosses **multiple systems**, +- needs **retries, idempotency, or compensation**, +- and **must not be lost** on crash, restart, or deploy + +belongs in the **execution plane**, implemented as **deterministic workflows** — not as ephemeral agent narration alone. + +## Current state (this repository — evidence-based) + +| Mechanism | Role | Typical use in Dealix | +|-----------|------|------------------------| +| **FastAPI** | Synchronous / async request path | APIs, webhooks entrypoints | +| **Celery** | Async tasks, beat schedules | Notifications, SLA ticks, background jobs | +| **LangGraph** (where used) | Stateful agent graphs, HITL interrupts | Cognition + bounded flows with checkpoints | +| **`salesflow-saas/backend/app/flows/`** | Named durable-style flows | Prospecting, self-improvement, etc. (verify each flow’s persistence model in code) | + +This stack is **valid** for many SaaS patterns. Tier-1 **does not** require ripping it out overnight; it requires **clear ownership** and **criteria** for when a flow must graduate to a stronger runtime. + +## Tier-1 target: Temporal (or equivalent durable workflow engine) + +**Temporal** (or another workflow engine with the same properties) is the **documented target** for: + +- cross-system **business commitments** (signatures, partner activation, DD room state, PMI milestones), +- **worker versioning** and safe rollout of workflow code, +- **crash-proof** resume after process/network failure. + +**Status:** *Planned* until an ADR-approved spike ships with tests. See [`../adr/0001-tier1-execution-policy-spikes.md`](../adr/0001-tier1-execution-policy-spikes.md). + +## When to keep Celery vs graduate to Temporal + +| Signal | Prefer Celery / short task | Prefer Temporal / workflow engine | +|--------|-----------------------------|-----------------------------------| +| Duration | Minutes, single service | Hours–days, multi-step state machine | +| State | Task idempotency sufficient | Long-lived state + human waits + versioning | +| Compensation | Rare, manual acceptable | Required, audited, replayable | +| Failure domain | Retry and DLQ enough | Must resume exact step after deploy | + +## LangGraph vs Temporal (division of labor) + +- **LangGraph:** decision-centric cognition, structured outputs, interrupts, **bounded** execution loops tied to agent sessions. +- **Temporal:** **system-of-record** for long-lived business processes, external side effects, and compensation — especially when multiple teams or services participate. + +Do not duplicate the same external commitment path in both without an explicit boundary (one source of truth for “what step are we on?”). + +## Evidence before production promotion + +Any new execution path that sends customer messages, moves money, signs contracts, or opens external systems must: + +1. Carry **approval_class**, **reversibility_class**, **sensitivity_class** (see [approval-policy.md](approval-policy.md)). +2. Emit **correlation/trace** IDs and persist audit-friendly records. +3. Pass **security gate** and release checklist for the environment. + +See also: [events-and-schema.md](events-and-schema.md), [trust-fabric.md](trust-fabric.md), [github-and-release.md](github-and-release.md). diff --git a/docs/governance/planes-and-runtime.md b/docs/governance/planes-and-runtime.md index 000c6d5c..4ffff8df 100644 --- a/docs/governance/planes-and-runtime.md +++ b/docs/governance/planes-and-runtime.md @@ -22,6 +22,18 @@ **Rule:** cognition loops belong in the decision layer; commitments belong in the execution layer. +## Operating plane (Tier-1 naming) + +For **enterprise / Tier-1** discussions, it helps to name a sixth surface explicitly — the **Operating plane** — so repo and delivery governance are not folded only into “Control” in conversation. + +| Surface | Owns (examples) | Relationship to existing table | +|---------|-----------------|--------------------------------| +| **Operating** | Git-native engineering, `AGENTS.md` / `CLAUDE.md`, Cursor/Claude commands, CI/CD, branch rulesets, environments (dev → prod), artifact provenance, merge queue, runbooks | **Control** policies (approvals, RBAC, secrets, promotion) **execute through** operating practices; treat **Control ⊂ Operating** for delivery: you cannot run a governed control plane without repo and pipeline discipline. | + +**Trust** remains a **cross-cutting** concern (wraps decision, execution, control, data, and operating evidence), as in [`../ai-operating-model.md`](../ai-operating-model.md). + +**Dealix product lanes** (Revenue, Partnership, CorpDev, Expansion, PMI, Trust exec) are mapped in [`../dealix-six-tracks.md`](../dealix-six-tracks.md). + ## Technology mapping (when to use what) - **Repo-native coding agents** — repository inspection, edits, refactors, tests, release prep, architecture discovery. diff --git a/docs/governance/saudi-compliance-and-ai-governance.md b/docs/governance/saudi-compliance-and-ai-governance.md new file mode 100644 index 00000000..482de0d4 --- /dev/null +++ b/docs/governance/saudi-compliance-and-ai-governance.md @@ -0,0 +1,68 @@ +# Saudi compliance & AI governance register (design-time) + +**Not legal advice.** This is an engineering **readiness register** for building Dealix as a **Tier-1** operating system in KSA/GCC. Legal review remains required for production claims and customer contracts. + +**Canonical trust model:** [trust-fabric.md](trust-fabric.md). **Product legal texts:** [`salesflow-saas/docs/legal/`](../../salesflow-saas/docs/legal/). + +--- + +## 1. PDPL / personal data (design checklist) + +When processing data that may identify individuals in the Kingdom: + +- **Inventory** data categories, purposes, lawful basis, retention, subprocessors, and cross-border transfers (if any). +- **Minimize** collection; default deny for exports and bulk analytics on personal fields. +- **Consent and notices** aligned with product copy ([`salesflow-saas/docs/legal/consent-policy-ar.md`](../../salesflow-saas/docs/legal/consent-policy-ar.md), privacy / data protection docs). +- **AI-specific:** training, enrichment, search, scoring, messaging, and **logs** can all be processing — classify sensitivity (S0–S3) per [approval-policy.md](approval-policy.md) and route S2/S3 away from unreviewed third-party models/tools. +- **Subject rights / export:** define operational runbooks before offering enterprise SLAs. + +**References (external):** Saudi PDPL / SDAIA knowledge center and official guidance — verify current text with counsel. + +--- + +## 2. NCA cybersecurity posture (readiness, not certification) + +Design so the platform **can** align with **ECC** and related cloud/data controls (**DCC**, **CCC**) as the customer tier demands: + +- Asset inventory, patch cadence, access control, logging, incident response hooks. +- **Segregation** of prod/staging; break-glass for admin; audit streaming for long retention (pair with [github-and-release.md](github-and-release.md) audit notes). + +**References (external):** NCA published controls and updates (e.g. ECC 2-2024 track) — map controls to features in an ADR when pursuing attestation. + +--- + +## 3. AI governance (NIST + OWASP) + +Use as a **risk and testing** frame for agentic features: + +| Frame | Use in Dealix | +|-------|----------------| +| **NIST AI RMF** | Govern, map, measure, manage — tie to release gates and evidence packs | +| **NIST Generative AI profile** | Supplement for LLM-specific risks | +| **OWASP Top 10 for LLM Apps** | Prompt injection, insecure output handling, excessive agency, sensitive disclosure — explicit test cases in CI where feasible | + +Pair with [trust-fabric.md](trust-fabric.md): red-team workflows, structured output validation, tool allowlists, and rollback plans for Class B / R2+. + +**References (external):** NIST publications portal; OWASP LLM Top 10 and GenAI security project pages. + +--- + +## 4. Arabic-first execution (product, not theme) + +Beyond RTL UI: + +- Arabic **classification** and **summaries** for internal notes where policy allows. +- **Partner memos** and **notification templates** with terminology normalization (sector-specific). +- **Retrieval quality** for Arabic queries (embedding model + chunking + evaluation). +- **Trust cues** in UX (support, compliance, local expectations). + +See [design-and-arabic.md](design-and-arabic.md). + +--- + +## 5. Review cadence + +- **Quarterly:** re-read this register against shipped features and incident postmortems. +- **Per major release:** update PDPL/NCA mapping appendix when product surface area changes. + +See also: [technology-radar-tier1.md](technology-radar-tier1.md), [`../execution-matrix-90d-tier1.md`](../execution-matrix-90d-tier1.md). diff --git a/docs/governance/technology-radar-tier1.md b/docs/governance/technology-radar-tier1.md new file mode 100644 index 00000000..ff6f0ff8 --- /dev/null +++ b/docs/governance/technology-radar-tier1.md @@ -0,0 +1,72 @@ +# Technology radar — Tier-1 Dealix (official vs optional vs pilot) + +**Purpose:** Separate **what we ship today**, **what we commit to architecturally**, and **what stays a pilot/pattern** until benchmarked. Do not treat pilot items as production dependencies without an ADR and evidence. + +**Execution criteria:** [execution-fabric.md](execution-fabric.md). **Spike policy:** [`../adr/0001-tier1-execution-policy-spikes.md`](../adr/0001-tier1-execution-policy-spikes.md). + +--- + +## Tier definitions + +| Tier | Meaning | +|------|---------| +| **Official (now)** | In repo, used in dev/staging/prod paths as implemented today | +| **Official (target)** | ADR-approved direction; may not be wired yet — document status honestly | +| **Strong optional** | Adopt when scale/integration needs justify ops cost | +| **Pilot / pattern** | Try behind flags; benchmark; no core coupling | + +--- + +## Radar table + +| Technology | Tier | Role | Notes | +|------------|------|------|--------| +| **FastAPI + PostgreSQL** | Official (now) | API + operational store | Tenant isolation remains mandatory | +| **Celery + Redis** | Official (now) | Async tasks, schedules | See execution fabric for graduation criteria | +| **LangGraph** (where used) | Official (now) / partial | Stateful agents, HITL | Not a substitute for all long-running business workflows | +| **Temporal** | Official (target) | Crash-proof workflows, worker versioning | **Planned** — spike only until ADR passes | +| **CloudEvents + JSON Schema + AsyncAPI** | Official (target) | Event contracts | Discipline in [events-and-schema.md](events-and-schema.md) | +| **OpenTelemetry** | Official (target) | Unified traces/metrics/logs | Incremental adoption | +| **OPA / Rego** | Strong optional / target | Policy PDP over JSON | See [trust-fabric.md](trust-fabric.md) target table | +| **OpenFGA or Cedar** | Strong optional / target | Fine-grained authorization | Same | +| **Vault** (or cloud secret manager) | Strong optional / target | Secrets, dynamic creds | Rotation + audit | +| **Keycloak** (or enterprise IdP) | Strong optional / target | SSO / B2B identity | Map to customer IAM | +| **Airbyte** | Strong optional | Connector / ingestion plane | Reduces agent→vendor sprawl | +| **Unstructured** | Strong optional | Document extraction (PDFs, CIMs) | Pair with retention + S-class | +| **dbt-style semantic layer** | Strong optional | Single KPI source of truth | Avoid five definitions of “revenue” | +| **Great Expectations** | Strong optional | Data quality checkpoints | | +| **OpenLineage** *or* **OpenMetadata** | Strong optional (pick **one** first) | Lineage / catalog | Do not run two overlapping catalogs without cause | +| **Neo4j** | Pilot | Graph intelligence | Only when relationship reasoning is proven required | +| **LangSmith** | Strong optional | LangGraph/LangChain observability + evals | Commercial; evaluate vs OSS | +| **Phoenix (Arize)** | Strong optional | OTel-native tracing/evals | | +| **Promptfoo** | Strong optional | CI red-team / eval harness | | +| **Guardrails AI** | Strong optional | I/O validators | | +| **ToolProof (concept)** | Pilot / pattern | Verification ledger pattern | Not a hard dependency by default | +| **MemPalace / similar** | Pilot | Memory product | Benchmark before core | +| **Flowise** | Pilot | Internal sandbox only | Not core runtime | +| **Local inference** (generic) | Official (pattern) | Via **adapter** + health checks | No hardcoded vendor lock-in in agents | + +--- + +## External references (documentation) + +Use upstream docs for detailed semantics (versions change). Prefer pinning versions in ADRs when adopting. + +- OpenAI: Responses API, Agents SDK, structured outputs, MCP — [OpenAI Platform documentation](https://platform.openai.com/docs) +- LangGraph: [LangChain / LangGraph documentation](https://docs.langchain.com/) +- Temporal: [Temporal documentation](https://docs.temporal.io/) +- CloudEvents: [CloudEvents spec (CNCF)](https://github.com/cloudevents/spec) +- JSON Schema: [json-schema.org](https://json-schema.org/) +- AsyncAPI: [asyncapi.com](https://www.asyncapi.com/) +- OpenTelemetry: [opentelemetry.io/docs](https://opentelemetry.io/docs/) +- OPA: [Open Policy Agent](https://www.openpolicyagent.org/) +- OpenFGA: [openfga.dev](https://openfga.dev/) +- Cedar (AWS): [Cedar policy language](https://www.cedar-policy.com/) +- GitHub: rulesets, environments, OIDC — [GitHub Docs](https://docs.github.com/) +- NIST AI RMF, OWASP LLM Top 10 — see [saudi-compliance-and-ai-governance.md](saudi-compliance-and-ai-governance.md) + +--- + +## Review + +Revisit this radar **quarterly** or when adding a new external system. Update [`../dealix-six-tracks.md`](../dealix-six-tracks.md) status table when a pilot graduates to official. diff --git a/docs/governance/trust-fabric.md b/docs/governance/trust-fabric.md index 0ed32be9..7f78edc6 100644 --- a/docs/governance/trust-fabric.md +++ b/docs/governance/trust-fabric.md @@ -54,3 +54,20 @@ Expect: severity classification, stored findings, and **release-blocking** rules - 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). + +--- + +## Target Tier-1 components (policy, IAM, secrets) — vs current + +The following are **architecture targets** for enterprise-grade trust. They are **not** all implemented as named products in this repo today. Track status in [`../dealix-six-tracks.md`](../dealix-six-tracks.md) and [`technology-radar-tier1.md`](technology-radar-tier1.md). + +| Component | Role | Target use in Dealix | Current (typical) | +|-----------|------|----------------------|-------------------| +| **OPA / Rego** | Policy decision point over JSON inputs (deploy, tenancy, risk) | Central PDP for “may this workflow step run?” | Application policy in Python (`dealix_os/policy_engine.py`, services) — evolve toward policy-as-data | +| **OpenFGA** or **Cedar** | Fine-grained **authorization** (ReBAC / analyzable policies) | DD room, term sheet, board memo, agent-on-behalf-of-user | RBAC in app + tenant checks — evolve toward explicit relationship model | +| **HashiCorp Vault** (or cloud equivalent) | **Secrets**, dynamic credentials, audit | Short-lived DB/API credentials, connector secrets | Env + platform secrets — tighten rotation and audit story | +| **Keycloak** (or enterprise IdP) | **Identity**, SSO, brokering | B2B tenants, executive users | JWT / tenant auth in app — map to IdP roadmap | + +**Integration pattern:** policy engines and PDPs should consume the same **A/R/S** and **actor_type** fields as events (see [events-and-schema.md](events-and-schema.md)) — avoid duplicating conflicting rules in prompts. + +**Spike gate:** no production dependency on OPA/OpenFGA/Vault/Keycloak until ADR + security review + tests; see [`../adr/0001-tier1-execution-policy-spikes.md`](../adr/0001-tier1-execution-policy-spikes.md). diff --git a/salesflow-saas/AGENTS.md b/salesflow-saas/AGENTS.md index c7023de4..564f0902 100644 --- a/salesflow-saas/AGENTS.md +++ b/salesflow-saas/AGENTS.md @@ -133,19 +133,29 @@ The **institutional** operating prompt and governance library live at the **repo **Operating overview** -- [`../docs/ai-operating-model.md`](../docs/ai-operating-model.md) — five planes, mermaid flow, product-type routing, Dealix code pointers. +- [`../docs/ai-operating-model.md`](../docs/ai-operating-model.md) — planes (incl. operating), mermaid flow, product-type routing, Dealix code pointers. +- [`../docs/dealix-six-tracks.md`](../docs/dealix-six-tracks.md) — six OS tracks, code pointers, implementation status snapshot. +- [`../docs/blueprint-master-architecture.md`](../docs/blueprint-master-architecture.md) — master blueprint index. +- [`../docs/execution-matrix-90d-tier1.md`](../docs/execution-matrix-90d-tier1.md) — Phase 0–1 Tier-1 execution matrix. **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/planes-and-runtime.md`](../docs/governance/planes-and-runtime.md) — planes, layers, runtimes, operating plane. - [`../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/trust-fabric.md`](../docs/governance/trust-fabric.md) — trust substrate, tool verification, security gate, Tier-1 targets (OPA, FGA, Vault, IdP). +- [`../docs/governance/execution-fabric.md`](../docs/governance/execution-fabric.md) — Celery/LangGraph vs Temporal criteria. - [`../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. +- [`../docs/governance/technology-radar-tier1.md`](../docs/governance/technology-radar-tier1.md) — official / optional / pilot stack. +- [`../docs/governance/saudi-compliance-and-ai-governance.md`](../docs/governance/saudi-compliance-and-ai-governance.md) — PDPL/NCA readiness, NIST/OWASP. + +**ADR (gated spikes)** + +- [`../docs/adr/0001-tier1-execution-policy-spikes.md`](../docs/adr/0001-tier1-execution-policy-spikes.md) — Temporal / OPA / OpenFGA spike policy. 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. diff --git a/scripts/architecture_brief.py b/scripts/architecture_brief.py index 1c782f47..ab76a7bf 100644 --- a/scripts/architecture_brief.py +++ b/scripts/architecture_brief.py @@ -12,16 +12,23 @@ CONSTITUTION_PATHS = [ "AGENTS.md", "CLAUDE.md", "docs/ai-operating-model.md", + "docs/dealix-six-tracks.md", + "docs/blueprint-master-architecture.md", + "docs/execution-matrix-90d-tier1.md", + "docs/adr/0001-tier1-execution-policy-spikes.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/execution-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", + "docs/governance/technology-radar-tier1.md", + "docs/governance/saudi-compliance-and-ai-governance.md", ".cursor/commands/architecture-map.md", ".cursor/commands/review-policy.md", ".cursor/commands/generate-evidence.md",