mancitrus/system-prompts-and-models-of-ai-tools
1
0
Fork 0
mirror of https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git synced 2026-06-17 14:59:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(tier1): six tracks, operating plane, execution fabric, radar, Saudi register, ADR spikes

Browse Source 
Made-with: Cursor
This commit is contained in:
Sami Assiri 2026-04-16 08:07:07 +03:00
parent c6efca32b5
commit c3b4ca0cf3
17 changed files with 499 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
AGENTS.md
View File

@ -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)**.

2
Architecture_Pack.md
View File

@ -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)

2
CLAUDE.md
View File

@ -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.

7
MASTER_OPERATING_PROMPT.md
View File

@ -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) |
---

61
docs/adr/0001-tier1-execution-policy-spikes.md Normal file
View File

@ -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)

19
docs/ai-operating-model.md
View File

@ -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

47
docs/blueprint-master-architecture.md Normal file
View File

@ -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.

47
docs/dealix-six-tracks.md Normal file
View File

@ -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)

53
docs/execution-matrix-90d-tier1.md Normal file
View File

@ -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).

5
docs/governance/README.md
View File

@ -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).

62
docs/governance/execution-fabric.md Normal file
View File

@ -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).

12
docs/governance/planes-and-runtime.md
View File

@ -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.

68
docs/governance/saudi-compliance-and-ai-governance.md Normal file
View File

@ -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).

72
docs/governance/technology-radar-tier1.md Normal file
View File

@ -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.

17
docs/governance/trust-fabric.md
View File

@ -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).

16
salesflow-saas/AGENTS.md
View File

@ -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.

7
scripts/architecture_brief.py
View File

@ -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",