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 23:09:35 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat(tier1): master closure checklist AR, CI preflight, Class B bundle API, trust and execution docs

Browse Source 
Made-with: Cursor
This commit is contained in:
Sami Assiri 2026-04-16 16:28:33 +03:00
parent fb6b34bcc0
commit 33af10127d
26 changed files with 503 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.github/workflows/dealix-ci.yml vendored
View File

@ -22,6 +22,9 @@ jobs:
- uses: actions/setup-python@v5 - uses: actions/setup-python@v5
with: with:
python-version: "3.12" python-version: "3.12"
- name: Monorepo constitution preflight (repo root)
working-directory: .
run: python scripts/architecture_brief.py
- name: Install dependencies - name: Install dependencies
run: | run: |
pip install -r requirements.txt -r requirements-dev.txt pip install -r requirements.txt -r requirements-dev.txt

35
.github/workflows/repo-preflight.yml vendored Normal file
View File

@ -0,0 +1,35 @@
# Preflight when repo-level governance / scripts change (no salesflow-saas code required)
name: Repo preflight
on:
push:
branches: [main]
paths:
- "docs/**"
- "scripts/architecture_brief.py"
- "MASTER_OPERATING_PROMPT.md"
- "AGENTS.md"
- "CLAUDE.md"
- "Execution_Matrix.md"
- "Execution_Matrix_v2.md"
pull_request:
branches: [main]
paths:
- "docs/**"
- "scripts/architecture_brief.py"
- "MASTER_OPERATING_PROMPT.md"
- "AGENTS.md"
- "CLAUDE.md"
- "Execution_Matrix.md"
- "Execution_Matrix_v2.md"
jobs:
architecture_brief:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Architecture brief (constitution paths)
run: python scripts/architecture_brief.py

3
AGENTS.md
View File

@ -71,6 +71,9 @@ Use these for depth, onboarding, and review. Each expands themes from the master
| [docs/architecture-register.md](docs/architecture-register.md) | Subsystem status (Current / Partial / Pilot / Production) | | [docs/architecture-register.md](docs/architecture-register.md) | Subsystem status (Current / Partial / Pilot / Production) |
| [docs/adr/0002-execution-matrix-canonical-source.md](docs/adr/0002-execution-matrix-canonical-source.md) | Canonical `Execution_Matrix.md` vs draft v2 | | [docs/adr/0002-execution-matrix-canonical-source.md](docs/adr/0002-execution-matrix-canonical-source.md) | Canonical `Execution_Matrix.md` vs draft v2 |
| [docs/adr/0001-tier1-execution-policy-spikes.md](docs/adr/0001-tier1-execution-policy-spikes.md) | Gated spikes: Temporal, OPA, OpenFGA | | [docs/adr/0001-tier1-execution-policy-spikes.md](docs/adr/0001-tier1-execution-policy-spikes.md) | Gated spikes: Temporal, OPA, OpenFGA |
| [docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md](docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) | Tier-1 master closure (Arabic, 15 sections, repo links) |
| [docs/glossary-dealix-planes-tracks.md](docs/glossary-dealix-planes-tracks.md) | Planes / tracks / fabrics glossary |
| [salesflow-saas/docs/tier1-master-closure-checklist.md](salesflow-saas/docs/tier1-master-closure-checklist.md) | Tier-1 gates (English, 50 items) |
Operating overview with diagram: **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)**. Operating overview with diagram: **[`docs/ai-operating-model.md`](docs/ai-operating-model.md)**.

4
MASTER_OPERATING_PROMPT.md
View File

@ -31,6 +31,10 @@ Deep-dive topics live under [`docs/governance/`](docs/governance/) (keep this fi
| Architecture register (subsystem status) | [`docs/architecture-register.md`](docs/architecture-register.md) | | Architecture register (subsystem status) | [`docs/architecture-register.md`](docs/architecture-register.md) |
| ADR: Execution matrix canonical (v1 vs v2) | [`docs/adr/0002-execution-matrix-canonical-source.md`](docs/adr/0002-execution-matrix-canonical-source.md) | | ADR: Execution matrix canonical (v1 vs v2) | [`docs/adr/0002-execution-matrix-canonical-source.md`](docs/adr/0002-execution-matrix-canonical-source.md) |
| ADR: Temporal / OPA / OpenFGA spikes | [`docs/adr/0001-tier1-execution-policy-spikes.md`](docs/adr/0001-tier1-execution-policy-spikes.md) | | ADR: Temporal / OPA / OpenFGA spikes | [`docs/adr/0001-tier1-execution-policy-spikes.md`](docs/adr/0001-tier1-execution-policy-spikes.md) |
| Tier-1 Master Closure (AR checklist) | [`docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) |
| Tier-1 gates (EN, 50 items) | [`salesflow-saas/docs/tier1-master-closure-checklist.md`](salesflow-saas/docs/tier1-master-closure-checklist.md) |
| Glossary (planes / tracks / fabrics) | [`docs/glossary-dealix-planes-tracks.md`](docs/glossary-dealix-planes-tracks.md) |
| Track artifact paths (Revenue–PMI) | [`docs/tracks-tier1-artifact-paths.md`](docs/tracks-tier1-artifact-paths.md) |
--- ---

161
docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md Normal file
View File

@ -0,0 +1,161 @@
# قائمة إغلاق Tier-1 الرئيسية (مرجع عربي مربوط بالريبو)
**الغرض:** ترجمة منطق الإغلاق إلى **أقسام قابلة للتتبع** مع أعمدة **الحالة / الدليل / المالك / معيار الخروج**.
**قائمة إنجليزية تفصيلية (50 بندًا):** [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md)
**سجل الأنظمة الفرعية:** [`architecture-register.md`](architecture-register.md)
**برنامج الإكمال (WS1–WS8):** [`completion-program-workstreams.md`](completion-program-workstreams.md)
**حالات الحقل:** `NotStarted` | `DocOnly` | `Pilot` | `Production` — لا تُرفَع إلى Production بدون اختبار + PR/دليل.
---
## §0 قاعدة الحكم
| # | البند | الحالة | الدليل في الريبو | المالك (تعيين عند التشغيل) | معيار الخروج |
|---|--------|--------|-------------------|----------------------------|---------------|
| 0.1 | كل بند له مالك ومعيار خروج وقياس | DocOnly | هذا الملف + السجل | Program | صف مكتمل في السجل |
| 0.2 | مكان واحد لحالة كل subsystem | Pilot | [`architecture-register.md`](architecture-register.md) | Platform | لا تضارب مع `tier1-master-closure-checklist` |
---
## §1 الدستور التشغيلي و Truth Lock
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 1.1 | دستور تشغيلي واحد | Production | [`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md) | Architect | لا وثيقة متعارضة فوقه |
| 1.2 | سجل Current vs Target | Production | [`salesflow-saas/docs/current-vs-target-register.md`](../salesflow-saas/docs/current-vs-target-register.md) + السجل | Platform | جداول صريحة |
| 1.3 | تدقيق عدم المبالغة | DocOnly | [`salesflow-saas/docs/governance/document-consistency-audit.md`](../salesflow-saas/docs/governance/document-consistency-audit.md) | PMO | لا ادّعاء Prod بلا كود |
| 1.4 | قاموس مصطلحات | DocOnly | [`glossary-dealix-planes-tracks.md`](glossary-dealix-planes-tracks.md) | Product Ops | Planes/Tracks موحّدة |
---
## §2 سلامة الريبو والأوامر
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 2.1 | أوامر من جذر الريبو | Pilot | [`scripts/architecture_brief.py`](../scripts/architecture_brief.py) + CI | DevEx | `architecture_brief` في CI |
| 2.2 | توافق أوامر Cursor/Claude | DocOnly | [`.cursor/commands/`](../.cursor/commands/) + [`CLAUDE.md`](../CLAUDE.md) | AI Platform | جدول تطابق في [`governance/discovery-and-output-checklist.md`](governance/discovery-and-output-checklist.md) |
---
## §3 إغلاق التوثيق
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 3.1 | فهرس الحوكمة | Production | [`governance/README.md`](governance/README.md) | Tech Writer | كل مدخل له مسار |
| 3.2 | مخطط رئيسي | Production | [`blueprint-master-architecture.md`](blueprint-master-architecture.md) | Architect | يشير للقائمة هنا |
| 3.3 | مراجعة روابط | DocOnly | audit في `document-consistency-audit` | PMO | 100% روابط أساسية |
---
## §4 طائرة القرار
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 4.1 | مخططات منظمة (17 نوعًا) | Production | [`salesflow-saas/backend/app/schemas/structured_outputs.py`](../salesflow-saas/backend/app/schemas/structured_outputs.py) | AI Lead | Pydantic يمر |
| 4.2 | حزمة قرار موحّدة | Production | [`decision_plane_contracts.py`](../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) | Backend | مفاتيح bundle كاملة |
| 4.3 | فرض مسار Class B | Pilot | `GET /api/v1/approval-center/class-b-decision-bundle` | AI Lead | استجابة = bundle + اختبار |
---
## §5 طائرة التنفيذ
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 5.1 | جرد workflows | Pilot | [`workflows-inventory.md`](workflows-inventory.md) + [`salesflow-saas/docs/governance/workflow-inventory.md`](../salesflow-saas/docs/governance/workflow-inventory.md) | Workflow | أعمدة idempotency/compensation |
| 5.2 | pilot دائم | DocOnly | [`temporal-pilot-scope.md`](temporal-pilot-scope.md) + [`adr/0001-tier1-execution-policy-spikes.md`](adr/0001-tier1-execution-policy-spikes.md) | Platform | ADR بوابة |
---
## §6 طائرة الثقة
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 6.1 | سجل تحقق أدوات | Partial | [`verification_ledger.py`](../salesflow-saas/backend/app/services/core_os/verification_ledger.py) | Trust | اختبار contradiction |
| 6.2 | تلميحات تناقض أخرى | Partial | [`tool_verification.py`](../salesflow-saas/backend/app/services/tool_verification.py) | Trust | خريطة في [`trust/ledger-vs-tool-verification.md`](trust/ledger-vs-tool-verification.md) |
| 6.3 | مركز موافقات API | Pilot | [`approval_center.py`](../salesflow-saas/backend/app/api/v1/approval_center.py) | Governance | قائمة + bundle |
| 6.4 | سياسة خارج الـ prompt | Partial | [`policy_engine.py`](../salesflow-saas/backend/app/services/dealix_os/policy_engine.py) | Security | + [`trust-fabric.md`](governance/trust-fabric.md) |
---
## §7 البيانات والموصلات
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 7.1 | قاموس مقاييس | Pilot | [`semantic-metrics-dictionary.md`](semantic-metrics-dictionary.md) | Data | Owner لكل مفتاح |
| 7.2 | واجهة موصل | DocOnly | [`ws5-connector-events-metrics.md`](ws5-connector-events-metrics.md) | Integrations | عقد موحّد |
| 7.3 | حوكمة موصلات API | Pilot | [`connector_governance.py`](../salesflow-saas/backend/app/api/v1/connector_governance.py) | Integrations | `GET` يعمل |
---
## §8 طائرة التشغيل والتسليم
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 8.1 | قائمة تسليم GitHub/OIDC | DocOnly | [`github-enterprise-delivery-completion.md`](github-enterprise-delivery-completion.md) | DevOps | rulesets موثّقة |
| 8.2 | CI يغطي التطبيق | Production | [`.github/workflows/dealix-ci.yml`](../.github/workflows/dealix-ci.yml) | Platform | pytest + frontend |
| 8.3 | CI preflight للوثائق | Pilot | [`.github/workflows/repo-preflight.yml`](../.github/workflows/repo-preflight.yml) | DevEx | عند تغيير docs/scripts |
---
## §9 Revenue OS
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 9.1 | مخطط مخرجات تسويق/عروض | Production | `structured_outputs` (LeadScoreCard، ProposalPack، …) | Revenue | ربط API واحد حي |
| 9.2 | تدفق leads | Partial | [`agents/`](../salesflow-saas/backend/app/services/agents/) | Revenue | مسار في [`tracks-tier1-artifact-paths.md`](tracks-tier1-artifact-paths.md) |
---
## §10 Partnership OS
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 10.1 | دورة حياة شراكة | DocOnly | [`salesflow-saas/docs/governance/partnership-os.md`](../salesflow-saas/docs/governance/partnership-os.md) | Partnerships | + [`partnership_scout.py`](../salesflow-saas/backend/app/services/strategic_deals/partnership_scout.py) |
---
## §11 CorpDev / M&A
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 11.1 | مسار استراتيجي | Partial | [`strategic_deals/`](../salesflow-saas/backend/app/services/strategic_deals/) + [`ma-os.md`](../salesflow-saas/docs/governance/ma-os.md) | CorpDev | مسار artifact في tracks doc |
---
## §12 التوسّع و PMI
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 12.1 | PMI / توسّع | DocOnly | [`pmi-os.md`](../salesflow-saas/docs/governance/pmi-os.md) + [`expansion-os.md`](../salesflow-saas/docs/governance/expansion-os.md) | PMO | + [`strategic_pmo.py`](../salesflow-saas/backend/app/services/strategic_deals/strategic_pmo.py) |
---
## §13 التنفيذي والسوق
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 13.1 | غرفة تنفيذية | Pilot | [`executive_room.py`](../salesflow-saas/backend/app/api/v1/executive_room.py) + مكوّنات `dealix/*` | Product | لقطة API |
| 13.2 | مواصفات الإكمال | DocOnly | [`executive-room-completion-spec.md`](executive-room-completion-spec.md) | Product | مراحل واضحة |
---
## §14 السعودية / الخليج
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 14.1 | مصفوفات تحكم | Pilot | [`pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md) | Compliance | مربوطة بإصدار |
| 14.2 | جاهزية مؤسسية | DocOnly | [`saudi-enterprise-readiness.md`](../salesflow-saas/docs/governance/saudi-enterprise-readiness.md) | Legal/Eng | checklist إصدار |
---
## §15 بوابات الهيمنة (Dominance)
| # | البند | الحالة | الدليل في الريبو | المالك | معيار الخروج |
|---|--------|--------|-------------------|--------|---------------|
| 15.1 | التزام مخطط على مسار حرج | Pilot | اختبار `test_approval_center_class_b_bundle.py` | AI Lead | 200 + bundle keys |
| 15.2 | مقاييس تغليف / سوق | DocOnly | [`market-dominance-plan.md`](../salesflow-saas/docs/governance/market-dominance-plan.md) | GTM | مراجعة ربع سنوية |
---
*آخر تحديث: يُحدَّث مع كل إصدار يغيّر الحوكمة أو مسارات Class B.*

43
docs/architecture-register.md
View File

@ -3,26 +3,26 @@
**Purpose:** Single **code-backed** snapshot of **Current / Partial / Pilot / Production** for major subsystems. Refresh per milestone or release. **Purpose:** Single **code-backed** snapshot of **Current / Partial / Pilot / Production** for major subsystems. Refresh per milestone or release.
**Canonical agent matrix:** [`Execution_Matrix.md`](../Execution_Matrix.md) (see [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) for v2 draft status). **Canonical agent matrix:** [`Execution_Matrix.md`](../Execution_Matrix.md) (see [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) for v2 draft status).
| Subsystem | Path / anchor | Status | Evidence / notes | | Subsystem | Path / anchor | Status | Owner | Last verified | Evidence / notes |
|-----------|---------------|--------|-------------------| |-----------|---------------|--------|-------|----------------|-------------------|
| FastAPI API surface | `salesflow-saas/backend/app/main.py`, `app/api/` | **Production** (dev/staging/prod per deploy) | pytest API suites | | FastAPI API surface | `salesflow-saas/backend/app/main.py`, `app/api/` | **Production** (dev/staging/prod per deploy) | *assign* | *date on merge* | pytest API suites |
| Agent router / executor | `salesflow-saas/backend/app/services/agents/` | **Partial** | LangGraph + routing; extend structured bundle (WS2) | | Agent router / executor | `salesflow-saas/backend/app/services/agents/` | **Partial** | *assign* | *date* | LangGraph + routing; extend structured bundle (WS2) |
| Decision memo (Pydantic) | `salesflow-saas/backend/app/services/core_os/decision_memo.py` | **Production** | Schema used as universal memo contract | | Decision memo (Pydantic) | `salesflow-saas/backend/app/services/core_os/decision_memo.py` | **Production** | *assign* | *date* | Schema used as universal memo contract |
| Decision plane bundle (A/R/S + intent) | `salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py` | **Production** (initial) | WS2 — compose `memo` + `evidence_pack` + `approval_packet` + `execution_intent` | | Decision plane bundle (A/R/S + intent) | `salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py` | **Production** (initial) | *assign* | *date* | WS2 + `GET .../approval-center/class-b-decision-bundle` |
| Tool verification ledger | `salesflow-saas/backend/app/services/core_os/verification_ledger.py` | **Partial** | File-based proofs; wire to DB/API for multi-instance (WS4) | | Tool verification ledger | `salesflow-saas/backend/app/services/core_os/verification_ledger.py` | **Partial** | *assign* | *date* | `test_verification_ledger_contradiction.py` |
| Durable flows (LangGraph) | `salesflow-saas/backend/app/flows/` | **Partial** | `prospecting_durable_flow.py`, `self_improvement_flow.py` | | Durable flows (LangGraph) | `salesflow-saas/backend/app/flows/` | **Partial** | *assign* | *date* | `prospecting_durable_flow.py`, `self_improvement_flow.py` |
| Celery workers | `salesflow-saas/backend/app/workers/` | **Production** | Tasks for sequences, agents, notifications, affiliates | | Celery workers | `salesflow-saas/backend/app/workers/` | **Production** | *assign* | *date* | Tasks for sequences, agents, notifications, affiliates |
| Temporal durable engine | — | **Planned** | [`adr/0001-tier1-execution-policy-spikes.md`](adr/0001-tier1-execution-policy-spikes.md) | | Temporal durable engine | — | **Planned** | *assign* | — | [`adr/0001-tier1-execution-policy-spikes.md`](adr/0001-tier1-execution-policy-spikes.md) |
| Policy engine (in-app) | `salesflow-saas/backend/app/services/dealix_os/policy_engine.py` | **Partial** | OPA/FGA target in [`governance/trust-fabric.md`](governance/trust-fabric.md) | | Policy engine (in-app) | `salesflow-saas/backend/app/services/dealix_os/policy_engine.py` | **Partial** | *assign* | *date* | OPA/FGA target in [`governance/trust-fabric.md`](governance/trust-fabric.md) |
| Strategic deals / M&A helpers | `salesflow-saas/backend/app/services/strategic_deals/` | **Partial** | Multiple modules; HITL in matrix | | Strategic deals / M&A helpers | `salesflow-saas/backend/app/services/strategic_deals/` | **Partial** | *assign* | *date* | Multiple modules; HITL in matrix |
| Security gate | `salesflow-saas/backend/app/services/security_gate.py` | **Partial** | Expand release gates (WS6) | | Security gate | `salesflow-saas/backend/app/services/security_gate.py` | **Partial** | *assign* | *date* | Expand release gates (WS6) |
| Audit log model | `salesflow-saas/backend/app/models/audit_log.py` | **Partial** | Enterprise audit streaming TBD (WS6) | | Audit log model | `salesflow-saas/backend/app/models/audit_log.py` | **Partial** | *assign* | *date* | Enterprise audit streaming TBD (WS6) |
| OpenTelemetry | — | **Planned / partial** | Correlation IDs in some paths; full OTel per radar | | OpenTelemetry | — | **Planned / partial** | *assign* | — | Correlation IDs in some paths; full OTel per radar |
| OPA / OpenFGA / Vault / Keycloak | — | **Planned** | ADR-0001 spikes only | | OPA / OpenFGA / Vault / Keycloak | — | **Planned** | *assign* | — | ADR-0001 spikes only |
| Semantic metrics dictionary | `docs/semantic-metrics-dictionary.md` | **Pilot** (doc) | Code single source TBD (WS5) | | Semantic metrics dictionary | `docs/semantic-metrics-dictionary.md` | **Pilot** (doc) | Data lead | *date* | Code single source TBD (WS5) |
| Lineage catalog | `docs/lineage-catalog-choice.md` | **Pilot** (doc) | Default recommendation: OpenLineage until ADR | | Lineage catalog | `docs/lineage-catalog-choice.md` | **Pilot** (doc) | Data lead | *date* | Default recommendation: OpenLineage until ADR |
| PDPL / NCA / AI control matrices | `docs/governance/pdpl-nca-ai-control-matrices.md` | **Pilot** (doc) | Operationalize per release (WS7) | | PDPL / NCA / AI control matrices | `docs/governance/pdpl-nca-ai-control-matrices.md` | **Pilot** (doc) | Compliance | *date* | Operationalize per release (WS7) + enterprise readiness gate |
| Executive room UI/API | `salesflow-saas/frontend/`, APIs TBD | **Planned / partial** | [`executive-room-completion-spec.md`](executive-room-completion-spec.md) | | Executive room UI/API | `salesflow-saas/frontend/`, `executive_room` API | **Planned / partial** | Product | *date* | [`executive-room-completion-spec.md`](executive-room-completion-spec.md) |
## Rules ## Rules
@ -30,4 +30,5 @@
- **Pilot** requires feature flag, scope note, and rollback. - **Pilot** requires feature flag, scope note, and rollback.
- **Planned** rows must link to an ADR or workstream ID. - **Planned** rows must link to an ADR or workstream ID.
See [`completion-program-workstreams.md`](completion-program-workstreams.md) for the eight workstreams and exit criteria. See [`completion-program-workstreams.md`](completion-program-workstreams.md) for the eight workstreams and exit criteria.
**قائمة إغلاق Tier-1 (عربي):** [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) — **50 بندًا (إنجليزي):** [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md).

4
docs/blueprint-master-architecture.md
View File

@ -42,7 +42,9 @@ For the classic “8 layers” service map (signal, memory, reasoning, orchestra
- Master workstream index: [`completion-program-workstreams.md`](completion-program-workstreams.md) - Master workstream index: [`completion-program-workstreams.md`](completion-program-workstreams.md)
- Subsystem status register: [`architecture-register.md`](architecture-register.md) - Subsystem status register: [`architecture-register.md`](architecture-register.md)
- Execution matrix canonical decision: [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) - Execution matrix canonical decision: [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md)
- Tier-1 master closure (Arabic): [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) — English 50-gate checklist: [`../salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md)
- Glossary: [`glossary-dealix-planes-tracks.md`](glossary-dealix-planes-tracks.md)
## Enterprise readiness ## Enterprise readiness

3
docs/completion-program-workstreams.md
View File

@ -5,7 +5,8 @@
**Living registers:** [`architecture-register.md`](architecture-register.md) (subsystem status), [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) (matrix source of truth). **Living registers:** [`architecture-register.md`](architecture-register.md) (subsystem status), [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) (matrix source of truth).
**PR #16 closure bundle (merged):** [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md) (50-item master gates) + supporting tracks under [`salesflow-saas/docs/`](../salesflow-saas/docs/) and [`salesflow-saas/docs/governance/`](../salesflow-saas/docs/governance/) — use alongside this index; prefer **one** status column between the register and the master checklist to avoid drift. **PR #16 closure bundle (merged):** [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md) (50-item master gates) + supporting tracks under [`salesflow-saas/docs/`](../salesflow-saas/docs/) and [`salesflow-saas/docs/governance/`](../salesflow-saas/docs/governance/) — use alongside this index; prefer **one** status column between the register and the master checklist to avoid drift.
**Arabic master index (15 sections):** [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md).
| WS | Name | SLA (target) | Primary deliverable docs / code | | WS | Name | SLA (target) | Primary deliverable docs / code |
|----|------|--------------|-----------------------------------| |----|------|--------------|-----------------------------------|

4
docs/enterprise-readiness.md
View File

@ -12,7 +12,9 @@ This checklist helps **internal teams** prepare for **B2B / enterprise** convers
6. [`governance/github-and-release.md`](governance/github-and-release.md) — branch protection, environments, OIDC, audit retention. 6. [`governance/github-and-release.md`](governance/github-and-release.md) — branch protection, environments, OIDC, audit retention.
7. [`execution-matrix-90d-tier1.md`](execution-matrix-90d-tier1.md) — Phase 0–1 measurable outcomes. 7. [`execution-matrix-90d-tier1.md`](execution-matrix-90d-tier1.md) — Phase 0–1 measurable outcomes.
8. [`completion-program-workstreams.md`](completion-program-workstreams.md) — eight workstreams from constitution to production. 8. [`completion-program-workstreams.md`](completion-program-workstreams.md) — eight workstreams from constitution to production.
9. [`architecture-register.md`](architecture-register.md) — subsystem status snapshot. 9. [`architecture-register.md`](architecture-register.md) — subsystem status snapshot.
10. [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) — إغلاق Tier-1 (عربي) + [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md) (50 بندًا).
11. [`governance/pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md) — **بوابة إصدار enterprise:** اتبع قسم «Enterprise release gate» قبل وسم الإصدار.
## 2. Product and legal surface ## 2. Product and legal surface

1
docs/executive-room-completion-spec.md
View File

@ -4,6 +4,7 @@
## Milestones ## Milestones
0. **Class B bundle API (pilot)** — `GET /api/v1/approval-center/class-b-decision-bundle` returns a validated bundle (`validate_class_b_bundle`); frontend can bind read-only viewers to this shape before DB-backed queues exist.
1. **Read-only executive dashboard** — memos + evidence pack viewer fed from APIs returning [`decision_plane_contracts.assemble_decision_bundle`](../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) payloads. 1. **Read-only executive dashboard** — memos + evidence pack viewer fed from APIs returning [`decision_plane_contracts.assemble_decision_bundle`](../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) payloads.
2. **Approval center** — queue of Class B items with A/R/S and approver roles. 2. **Approval center** — queue of Class B items with A/R/S and approver roles.
3. **Policy violations board** — feed from audit log + tool ledger contradictions. 3. **Policy violations board** — feed from audit log + tool ledger contradictions.

15
docs/glossary-dealix-planes-tracks.md Normal file
View File

@ -0,0 +1,15 @@
# قاموس مصطلحات Dealix — Planes / Tracks / Fabrics
**الغرض:** توحيد الأسماء عبر الوثائق والكود. المصدر التفصيلي للطائرات: [`governance/planes-and-runtime.md`](governance/planes-and-runtime.md). المصدر للمسارات الستة: [`dealix-six-tracks.md`](dealix-six-tracks.md).
| المصطلح | المعنى المقصود | ملاحظة |
|---------|----------------|--------|
| **Decision plane** | إدراك، تحليل، مذكرات قرار، مخرجات منظمة — لا التزامات خارجية مباشرة | يقابل «استكشاف ذكاء» في الدستور |
| **Execution plane** | سير عمل حتمي، Celery/LangGraph، التزامات خارجية بعد بوابات | Temporal = هدف Tier-1 حسب ADR-0001 |
| **Trust / Control plane** | موافقات، سياسة، تدقيق، تحقق من أدوات، أدلة | لا سياسة حرجة داخل prompts فقط |
| **Data plane** | بيانات تشغيلية، موصلات، مقاييس دلالية، سلسلة بيانات | واجهات موصل versioned |
| **Operating plane** | تسليم: GitHub، CI/CD، بيئات، OIDC، احتفاظ سجلات | مذكور صراحة في `planes-and-runtime` |
| **Six tracks** | مسارات منتج Dealix (إيراد، شراكة، M&A، توسّع، PMI، ثقة/تنفيذي) | ليست نفس «الطائرات» — الطائرات عبرية |
| **Fabric** | طبقة تشغيل كاملة (مثلاً trust fabric = سياسة + IAM + audit + ledger) | يُستخدم في الرادار والـ ADR |
عند إضافة مصطلح جديد: حدّث هذا الملف ثم [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) §1.4.

4
docs/governance/README.md
View File

@ -18,7 +18,9 @@ This folder expands each major theme for navigation, review, and agent onboardin
| [technology-radar-tier1.md](technology-radar-tier1.md) | Tier-1 technology radar (official / optional / pilot) | | [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 | | [saudi-compliance-and-ai-governance.md](saudi-compliance-and-ai-governance.md) | PDPL/NCA readiness register, NIST/OWASP AI governance |
| [pdpl-nca-ai-control-matrices.md](pdpl-nca-ai-control-matrices.md) | WS7 operational control matrices (templates) | | [pdpl-nca-ai-control-matrices.md](pdpl-nca-ai-control-matrices.md) | WS7 operational control matrices (templates) |
| [../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md](../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) | Tier-1 master closure (Arabic index, repo-grounded) |
| [../glossary-dealix-planes-tracks.md](../glossary-dealix-planes-tracks.md) | Planes / tracks / fabrics glossary |
**Tier-1 index docs (repo `docs/`):** [dealix-six-tracks.md](../dealix-six-tracks.md), [blueprint-master-architecture.md](../blueprint-master-architecture.md), [completion-program-workstreams.md](../completion-program-workstreams.md), [architecture-register.md](../architecture-register.md), [execution-matrix-90d-tier1.md](../execution-matrix-90d-tier1.md), [enterprise-readiness.md](../enterprise-readiness.md), [adr/0001-tier1-execution-policy-spikes.md](../adr/0001-tier1-execution-policy-spikes.md), [adr/0002-execution-matrix-canonical-source.md](../adr/0002-execution-matrix-canonical-source.md). **Tier-1 index docs (repo `docs/`):** [dealix-six-tracks.md](../dealix-six-tracks.md), [blueprint-master-architecture.md](../blueprint-master-architecture.md), [completion-program-workstreams.md](../completion-program-workstreams.md), [architecture-register.md](../architecture-register.md), [TIER1_MASTER_CLOSURE_CHECKLIST_AR.md](../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md), [glossary-dealix-planes-tracks.md](../glossary-dealix-planes-tracks.md), [tracks-tier1-artifact-paths.md](../tracks-tier1-artifact-paths.md), [execution-matrix-90d-tier1.md](../execution-matrix-90d-tier1.md), [enterprise-readiness.md](../enterprise-readiness.md), [adr/0001-tier1-execution-policy-spikes.md](../adr/0001-tier1-execution-policy-spikes.md), [adr/0002-execution-matrix-canonical-source.md](../adr/0002-execution-matrix-canonical-source.md).
Repo entry points: [`../../AGENTS.md`](../../AGENTS.md), [`../../CLAUDE.md`](../../CLAUDE.md), [`../ai-operating-model.md`](../ai-operating-model.md). Repo entry points: [`../../AGENTS.md`](../../AGENTS.md), [`../../CLAUDE.md`](../../CLAUDE.md), [`../ai-operating-model.md`](../ai-operating-model.md).

4
docs/governance/discovery-and-output-checklist.md
View File

@ -2,7 +2,9 @@
**Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md). **Canonical:** [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md).
**Tier-1 bundle (tracks, radar, execution/trust specs, Saudi register, ADR gates):** [`../dealix-six-tracks.md`](../dealix-six-tracks.md), [`../blueprint-master-architecture.md`](../blueprint-master-architecture.md), [`technology-radar-tier1.md`](technology-radar-tier1.md), [`execution-fabric.md`](execution-fabric.md), [`saudi-compliance-and-ai-governance.md`](saudi-compliance-and-ai-governance.md), [`../enterprise-readiness.md`](../enterprise-readiness.md). **Tier-1 bundle (tracks, radar, execution/trust specs, Saudi register, ADR gates):** [`../dealix-six-tracks.md`](../dealix-six-tracks.md), [`../blueprint-master-architecture.md`](../blueprint-master-architecture.md), [`../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md), [`technology-radar-tier1.md`](technology-radar-tier1.md), [`execution-fabric.md`](execution-fabric.md), [`saudi-compliance-and-ai-governance.md`](saudi-compliance-and-ai-governance.md), [`../enterprise-readiness.md`](../enterprise-readiness.md).
**Cursor / Claude command parity:** أوامر الجذر في [`.cursor/commands/`](../../.cursor/commands/) يجب أن تعكس نفس التدفقات المذكورة في [`CLAUDE.md`](../../CLAUDE.md) (architecture-map، review-policy، generate-evidence، release-gate). عند إضافة أمر جديد، حدّث الملفين معًا.
## Before writing code ## Before writing code

10
docs/governance/pdpl-nca-ai-control-matrices.md
View File

@ -38,3 +38,13 @@
## Region / residency flags ## Region / residency flags
Define configuration keys for **data region** and **LLM routing** per tenant; document in ADR when enforced in `policy_engine` or external PDP. Define configuration keys for **data region** and **LLM routing** per tenant; document in ADR when enforced in `policy_engine` or external PDP.
---
## Enterprise release gate (operational)
Before tagging an **enterprise** release candidate:
1. Reconcile this matrix with [`../enterprise-readiness.md`](../enterprise-readiness.md) and [`saudi-compliance-and-ai-governance.md`](saudi-compliance-and-ai-governance.md).
2. Attach evidence: PDPL rows above filled (no `…` placeholders for production claims), NCA gap register owner + date, AI RMF row sign-off.
3. Cross-check [`../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](../TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) §14 and [`../../salesflow-saas/docs/tier1-master-closure-checklist.md`](../../salesflow-saas/docs/tier1-master-closure-checklist.md) Gate 8.

5
docs/semantic-metrics-dictionary.md
View File

@ -10,6 +10,11 @@
| `partner_sourced_pipeline_sar` | Pipeline attributed to partner channel | CRM attribution | Partnerships | | `partner_sourced_pipeline_sar` | Pipeline attributed to partner channel | CRM attribution | Partnerships |
| `synergy_realization_sar` | Post-close synergy captured vs plan | Finance + PMI tracker | CorpDev | | `synergy_realization_sar` | Post-close synergy captured vs plan | Finance + PMI tracker | CorpDev |
## Dominance / governance
- **Owner** column is mandatory for every business-critical key; assign in release planning.
- **CI / dashboard gate:** new executive widgets must only plot keys present in this table (see [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) §15).
## Rules ## Rules
- Do not redefine the same key in multiple services. - Do not redefine the same key in multiple services.

4
docs/temporal-pilot-scope.md
View File

@ -7,6 +7,10 @@
1. **Partner approval** — human waits, multi-day SLA, idempotent notifications. 1. **Partner approval** — human waits, multi-day SLA, idempotent notifications.
2. **DD room state machine** — long-running, audit-heavy, compensating actions on red-flag. 2. **DD room state machine** — long-running, audit-heavy, compensating actions on red-flag.
## Interim (pre-Temporal) hardening
Until ADR-0001 exit criteria are met, strengthen **LangGraph checkpoints + Celery idempotency** on the flows listed in [`workflows-inventory.md`](workflows-inventory.md) so long steps survive restarts without duplicate side effects.
## Non-goals for pilot v0 ## Non-goals for pilot v0
- Replacing all Celery workloads. - Replacing all Celery workloads.

13
docs/tracks-tier1-artifact-paths.md Normal file
View File

@ -0,0 +1,13 @@
# مسارات artifact حيّة — Revenue / Partnership / M&A / Expansion (Tier-1)
**قاعدة:** لكل track مسار **واحد** يُوسَّع تدريجيًا (schema → API/worker → اختبار). لا تفتح عشرات المسارات دون أدلة.
| Track | Artifact الأول | Schema / memo | كود أساسي | اختبار / دليل |
|-------|-----------------|---------------|-----------|-----------------|
| **Revenue OS** | Lead score / qualification | [`structured_outputs.py`](../salesflow-saas/backend/app/schemas/structured_outputs.py) (`LeadScoreCard`, `QualificationMemo`) | [`services/agents/`](../salesflow-saas/backend/app/services/agents/) | pytest واجهات ذات صلة |
| **Partnership OS** | Partner dossier | نفس الملف (`PartnerDossier`) | [`partnership_scout.py`](../salesflow-saas/backend/app/services/strategic_deals/partnership_scout.py) | تكامل عند توفر بيانات |
| **M&A / CorpDev** | Target profile / DD plan | `TargetProfile`, `DDPlan` | [`strategic_deals/`](../salesflow-saas/backend/app/services/strategic_deals/) | HITL من [`Execution_Matrix.md`](../Execution_Matrix.md) |
| **Expansion** | Expansion plan | `ExpansionPlan` | [`strategic_simulator.py`](../salesflow-saas/backend/app/services/strategic_deals/strategic_simulator.py) (إن وُجد) أو وثائق GTM | وثيقة + API لاحقًا |
| **PMI** | PMI program plan | `PMIProgramPlan` | [`strategic_pmo.py`](../salesflow-saas/backend/app/services/strategic_deals/strategic_pmo.py) | قالب ثم توليد |
**بوابات الهيمنة:** التزام schema على مسار Class B (`approval-center` bundle)؛ مقاييس الأعمال من [`semantic-metrics-dictionary.md`](semantic-metrics-dictionary.md) فقط في لوحات جديدة.

25
docs/trust/ledger-vs-tool-verification.md Normal file
View File

@ -0,0 +1,25 @@
# سجل التحقق (`VerificationLedger`) مقابل `tool_verification`
**الغرض:** توضيح متى تُستخدم كل طبقة لتفادي ازدواجية «تناقض» بدون تكامل.
## `VerificationLedger` ([`verification_ledger.py`](../../salesflow-saas/backend/app/services/core_os/verification_ledger.py))
- **نموذج:** إثبات لكل استدعاء أداة: intended / claimed / actual + `contradiction_flag` + `verification_status`.
- **تخزين:** ملفات JSON تحت مسار قابل للتكوين (مناسب لـ pilot أحادي العقدة).
- **استخدمه عندما:** تريد **سجل تدقيق** بسيط لمسار وكيل أو أداة قبل/بعد التنفيذ.
## `tool_verification` / `tool_receipts` ([`tool_verification.py`](../../salesflow-saas/backend/app/services/tool_verification.py))
- **نموذج:** تجميع مكالمات أدوات مع `contradiction_flags` على مستوى الدورة.
- **استخدمه عندما:** تقيس **جودة تشغيل الوكيل** أو معدل تناقض عبر مهام متعددة.
## مسار الدمج المستهدف (Tier-1)
1. كتابة إثبات في `VerificationLedger` عند بدء أداة حساسة.
2. تحديث الإثبات بعد التنفيذ مع `side_effects` و`evidence_paths`.
3. تغذية ملخص المخالفات في واجهة «Policy violations» من حالة `contradicted` + أعلام `tool_verification`.
4. نقل التخزين إلى DB/API عند تعدد العقد (انظر [`tool-verification-ledger-v1-completion.md`](tool-verification-ledger-v1-completion.md)).
## مركز الموافقات
حقول [`ApprovalPacket`](../../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) تُرفق باستجابات `/api/v1/approval-center/class-b-decision-bundle` كجزء من حزمة القرار الموحّدة.

22
docs/workflows-inventory.md
View File

@ -4,20 +4,20 @@
## LangGraph flows (`salesflow-saas/backend/app/flows/`) ## LangGraph flows (`salesflow-saas/backend/app/flows/`)
| Module | Role | Durability notes | | Module | Role | Durability notes | Idempotency (pilot) | Compensation (pilot) |
|--------|------|------------------| |--------|------|------------------|---------------------|-------------------------|
| `prospecting_durable_flow.py` | Prospecting pipeline | Checkpoint-friendly; validate persistence + idempotency keys on external steps | | `prospecting_durable_flow.py` | Prospecting pipeline | Checkpoint-friendly; validate persistence + idempotency keys on external steps | Idempotency key on CRM write steps (TBD in code) | Retry failed step; manual cancel path documented in flow |
| `self_improvement_flow.py` | Self-improvement loop | Async API integration; ensure no silent side effects without ledger | | `self_improvement_flow.py` | Self-improvement loop | Async API integration; ensure no silent side effects without ledger | Hash of last successful eval as key | Roll back prompt patch queue on fatal error (TBD) |
## Celery task families (`salesflow-saas/backend/app/workers/`) ## Celery task families (`salesflow-saas/backend/app/workers/`)
| Area | Files (examples) | Typical duration | | Area | Files (examples) | Typical duration | Idempotency | Compensation |
|------|------------------|------------------| |------|------------------|------------------|--------------|----------------|
| Sequences | `sequence_tasks.py` | Minutes | | Sequences | `sequence_tasks.py` | Minutes | Message dedupe by `(tenant, template, recipient, day)` | Disable sequence + alert |
| Agents | `agent_tasks.py` | Minutes | | Agents | `agent_tasks.py` | Minutes | Task id + tenant in broker | Dead-letter + replay from checkpoint |
| Notifications | `notification_tasks.py` | Minutes | | Notifications | `notification_tasks.py` | Minutes | External id from provider when available | Skip duplicate send on conflict |
| Affiliates | `affiliate_tasks.py` | Minutes–hours | | Affiliates | `affiliate_tasks.py` | Minutes–hours | Payout batch id | Reverse ledger entry (runbook) |
| Follow-up | `follow_up_tasks.py` | Variable | | Follow-up | `follow_up_tasks.py` | Variable | Step cursor in DB | Reset step + notify owner |
## Migration rule (draft) ## Migration rule (draft)

74
salesflow-saas/backend/app/api/v1/approval_center.py
View File

@ -1,8 +1,19 @@
"""Approval Center API — enhanced approval queue with SLA tracking.""" """Approval Center API — enhanced approval queue with SLA tracking."""
from typing import Any, Dict, Optional
from fastapi import APIRouter from fastapi import APIRouter
from pydantic import BaseModel as PydanticBase from pydantic import BaseModel as PydanticBase
from typing import Any, Dict, Optional
from app.services.core_os.decision_memo import DecisionMemo, FinancialImpact, RiskRegisterItem
from app.services.core_os.decision_plane_contracts import (
ApprovalPacket,
EvidencePack,
ExecutionIntent,
assemble_decision_bundle,
new_evidence_pack_id,
validate_class_b_bundle,
)
router = APIRouter(prefix="/approval-center", tags=["Approval Center"]) router = APIRouter(prefix="/approval-center", tags=["Approval Center"])
@ -11,6 +22,67 @@ class ApprovalAction(PydanticBase):
note: Optional[str] = None note: Optional[str] = None
@router.get("/class-b-decision-bundle")
async def class_b_decision_bundle_demo() -> Dict[str, Any]:
"""
Tier-1 Class B pilot: returns a fully validated decision bundle (demo data).
Used by executive surfaces and contract tests — replace payload with real DB rows later.
"""
memo = DecisionMemo.create_memo(
agent_id="approval_center_demo",
objective="عرض حزمة قرار Class B (Tier-1)",
recommendation="المتابعة وفق الحوكمة المعروضة في الوثائق",
confidence=90.0,
decision_context="Tier-1 master closure — demo bundle only",
inputs_used=["docs/architecture-register.md", "docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md"],
assumptions=["بيانات تجريبية؛ لا التزام تعاقدي"],
alternatives_considered=["تأجيل المسار"],
expected_financial_impact=FinancialImpact(),
risk_register=[
RiskRegisterItem(
risk="سطح تجريبي",
severity="low",
mitigation="عدم استخدامه لقرارات مالية حقيقية",
)
],
required_approvals=["governance_lead", "product_owner"],
next_best_action="ربط الواجهة التنفيذية بهذا المسار",
rollback_plan="تعطيل المسار أو إرجاع قائمة فارغة",
evidence_links=["docs/completion-program-workstreams.md"],
)
evidence = EvidencePack(
pack_id=new_evidence_pack_id(),
sources=["pytest:approval_center", "ci:dealix-ci"],
assumptions=["Evidence pack compiled for demo"],
artifact_refs=["architecture_brief.py"],
provenance_score=72.0,
tool_proof_ids=[],
)
approval_packet = ApprovalPacket(
approval_class="A2",
reversibility_class="R1",
sensitivity_class="S1",
actor_type="recommender_agent",
approvers_required=["human_approver"],
policy_notes="Class B — approval required before external side effects",
)
execution_intent = ExecutionIntent(
workflow_key="governance_class_b_review_v1",
idempotency_key="class-b-demo-approval-center-001",
requested_side_effect_class="internal_write",
correlation_id="corr_class_b_demo",
payload_summary="Record approval decision in internal audit trail",
)
bundle = assemble_decision_bundle(
evidence_pack=evidence,
approval_packet=approval_packet,
execution_intent=execution_intent,
memo_json=memo.model_dump(mode="json"),
)
validate_class_b_bundle(bundle)
return bundle
@router.get("/") @router.get("/")
async def list_approvals( async def list_approvals(
category: Optional[str] = None, category: Optional[str] = None,

6
salesflow-saas/backend/app/api/v1/contradiction.py
View File

@ -1,4 +1,8 @@
"""Contradiction Engine API — detect and manage system contradictions.""" """Contradiction Engine API — detect and manage system contradictions.
See repo root: `docs/trust/ledger-vs-tool-verification.md` for how this relates to
`VerificationLedger` / `tool_verification`.
"""
from fastapi import APIRouter, Depends, HTTPException from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel as PydanticBase from pydantic import BaseModel as PydanticBase

2
salesflow-saas/backend/app/services/core_os/__init__.py
View File

@ -8,6 +8,7 @@ from app.services.core_os.decision_plane_contracts import (
ExecutionIntent, ExecutionIntent,
assemble_decision_bundle, assemble_decision_bundle,
new_evidence_pack_id, new_evidence_pack_id,
validate_class_b_bundle,
) )
from app.services.core_os.verification_ledger import VerificationLedger from app.services.core_os.verification_ledger import VerificationLedger
@ -18,4 +19,5 @@ __all__ = [
"VerificationLedger", "VerificationLedger",
"assemble_decision_bundle", "assemble_decision_bundle",
"new_evidence_pack_id", "new_evidence_pack_id",
"validate_class_b_bundle",
] ]

32
salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py
View File

@ -60,6 +60,38 @@ def new_evidence_pack_id(prefix: str = "ep") -> str:
return f"{prefix}_{uuid4().hex[:12]}" return f"{prefix}_{uuid4().hex[:12]}"
CLASS_B_BUNDLE_KEYS = (
"memo_json",
"evidence_pack_json",
"risk_register_json",
"approval_packet_json",
"execution_intent_json",
)
def validate_class_b_bundle(bundle: Dict[str, Any]) -> None:
"""
Enforce Tier-1 Class B response shape: all bundle keys present and sub-objects valid.
Raises ValueError with a short message suitable for HTTP 400.
"""
missing = [k for k in CLASS_B_BUNDLE_KEYS if k not in bundle or bundle[k] is None]
if missing:
raise ValueError(f"Class B bundle missing keys: {', '.join(missing)}")
# Local import avoids import cycle at module load.
from app.services.core_os.decision_memo import DecisionMemo
memo = DecisionMemo.model_validate(bundle["memo_json"])
if not memo.required_approvals:
raise ValueError("memo_json.required_approvals must be non-empty for Class B paths")
EvidencePack.model_validate(bundle["evidence_pack_json"])
ApprovalPacket.model_validate(bundle["approval_packet_json"])
ExecutionIntent.model_validate(bundle["execution_intent_json"])
rr = bundle["risk_register_json"]
if not isinstance(rr, list):
raise ValueError("risk_register_json must be a list")
def assemble_decision_bundle( def assemble_decision_bundle(
*, *,
evidence_pack: EvidencePack, evidence_pack: EvidencePack,

18
salesflow-saas/backend/tests/test_approval_center_class_b_bundle.py Normal file
View File

@ -0,0 +1,18 @@
"""Class B decision bundle endpoint (Tier-1 Master Closure)."""
import pytest
from httpx import ASGITransport, AsyncClient
from app.main import app
from app.services.core_os.decision_plane_contracts import validate_class_b_bundle
@pytest.mark.asyncio
async def test_class_b_decision_bundle_endpoint():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
r = await client.get("/api/v1/approval-center/class-b-decision-bundle")
assert r.status_code == 200, r.text
data = r.json()
validate_class_b_bundle(data)
assert "memo_json" in data
assert data["approval_packet_json"]["approval_class"] == "A2"

45
salesflow-saas/backend/tests/test_decision_plane_contracts.py
View File

@ -1,13 +1,16 @@
"""Tests for decision plane bundle (Completion Program WS2).""" """Tests for decision plane bundle (Completion Program WS2)."""
from __future__ import annotations from __future__ import annotations
from app.services.core_os.decision_memo import DecisionMemo, AuditMetadata, FinancialImpact import pytest
from app.services.core_os.decision_memo import AuditMetadata, DecisionMemo, FinancialImpact
from app.services.core_os.decision_plane_contracts import ( from app.services.core_os.decision_plane_contracts import (
ApprovalPacket, ApprovalPacket,
EvidencePack, EvidencePack,
ExecutionIntent, ExecutionIntent,
assemble_decision_bundle, assemble_decision_bundle,
new_evidence_pack_id, new_evidence_pack_id,
validate_class_b_bundle,
) )
@ -61,3 +64,43 @@ def test_assemble_decision_bundle_keys():
} }
assert bundle["approval_packet_json"]["approval_class"] == "A2" assert bundle["approval_packet_json"]["approval_class"] == "A2"
assert bundle["execution_intent_json"]["idempotency_key"] == "idem-001" assert bundle["execution_intent_json"]["idempotency_key"] == "idem-001"
validate_class_b_bundle(bundle)
def test_validate_class_b_bundle_rejects_missing_memo_approvals():
memo = DecisionMemo(
objective="x",
decision_context="c",
inputs_used=["i"],
assumptions=["a"],
recommendation_ar="r",
alternatives_considered=["b"],
expected_financial_impact=FinancialImpact(),
risk_register=[],
confidence_score=50.0,
required_approvals=[], # invalid for Class B
next_best_action="n",
rollback_plan="rb",
evidence_links=[],
audit_metadata=AuditMetadata(agent_id="a", timestamp="2026-01-01T00:00:00Z"),
)
ep = EvidencePack(pack_id=new_evidence_pack_id(), provenance_score=1.0)
ap = ApprovalPacket(
approval_class="A1",
reversibility_class="R0",
sensitivity_class="S0",
actor_type="human",
)
ei = ExecutionIntent(
workflow_key="w",
idempotency_key="k",
requested_side_effect_class="none",
)
bundle = assemble_decision_bundle(
evidence_pack=ep,
approval_packet=ap,
execution_intent=ei,
memo_json=memo.to_json(),
)
with pytest.raises(ValueError, match="required_approvals"):
validate_class_b_bundle(bundle)

3
scripts/architecture_brief.py
View File

@ -20,6 +20,9 @@ CONSTITUTION_PATHS = [
"docs/enterprise-readiness.md", "docs/enterprise-readiness.md",
"docs/adr/0001-tier1-execution-policy-spikes.md", "docs/adr/0001-tier1-execution-policy-spikes.md",
"docs/adr/0002-execution-matrix-canonical-source.md", "docs/adr/0002-execution-matrix-canonical-source.md",
"docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md",
"docs/glossary-dealix-planes-tracks.md",
"docs/tracks-tier1-artifact-paths.md",
"docs/governance/README.md", "docs/governance/README.md",
"docs/governance/approval-policy.md", "docs/governance/approval-policy.md",
"docs/governance/planes-and-runtime.md", "docs/governance/planes-and-runtime.md",