mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-17 14:59:35 +00:00
feat(tier1): finalize production activation and revenue execution pack
Complete Tier-1 closure follow-through by wiring docs governance gates, RC release readiness checks, source-of-truth enforcement, executive weekly contract surface, and go-live severity notes. Add full go-live revenue execution documentation set (production activation, real production playbook, trust expansion, first 3 clients, live deployment, and automated revenue engine) and register all canonical paths. Made-with: Cursor
This commit is contained in:
parent
b4531f0a4c
commit
1ceeea9004
19
.github/workflows/dealix-ci.yml
vendored
19
.github/workflows/dealix-ci.yml
vendored
@ -39,11 +39,28 @@ jobs:
|
||||
DATABASE_URL: sqlite+aiosqlite:///./openapi_verify.db
|
||||
DEALIX_INTERNAL_API_TOKEN: ""
|
||||
run: python scripts/verify_frontend_openapi_paths.py
|
||||
- name: Go-live gate (in-process CLI)
|
||||
- name: No-overclaim (repo governance)
|
||||
working-directory: .
|
||||
run: python scripts/check_no_overclaim.py
|
||||
|
||||
- name: Glossary consistency (contract names)
|
||||
working-directory: .
|
||||
run: python scripts/check_glossary_consistency.py
|
||||
|
||||
- name: Source of truth index (minimal)
|
||||
working-directory: .
|
||||
run: python scripts/check_source_of_truth_index.py
|
||||
|
||||
- name: Release readiness matrix structure
|
||||
working-directory: .
|
||||
run: python scripts/check_release_readiness_matrix.py
|
||||
|
||||
- name: Go-live gate (in-process CLI, fail-closed)
|
||||
working-directory: salesflow-saas
|
||||
env:
|
||||
DATABASE_URL: sqlite+aiosqlite:///./go_live_gate_ci.db
|
||||
DEALIX_INTERNAL_API_TOKEN: ""
|
||||
DEALIX_CI_FAIL_ON_GO_LIVE: "1"
|
||||
run: python scripts/check_go_live_gate.py
|
||||
|
||||
frontend:
|
||||
|
||||
52
.github/workflows/docs-governance.yml
vendored
52
.github/workflows/docs-governance.yml
vendored
@ -6,9 +6,15 @@ on:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "docs/**"
|
||||
- "salesflow-saas/docs/**"
|
||||
- "scripts/architecture_brief.py"
|
||||
- "scripts/check_docs_links.py"
|
||||
- "scripts/check_no_overclaim.py"
|
||||
- "scripts/check_release_readiness_matrix.py"
|
||||
- "scripts/check_source_of_truth_index.py"
|
||||
- "scripts/check_glossary_consistency.py"
|
||||
- ".github/workflows/docs-governance.yml"
|
||||
- ".github/workflows/release-readiness-rc-gate.yml"
|
||||
- "MASTER_OPERATING_PROMPT.md"
|
||||
- "AGENTS.md"
|
||||
- "CLAUDE.md"
|
||||
@ -19,9 +25,15 @@ on:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "docs/**"
|
||||
- "salesflow-saas/docs/**"
|
||||
- "scripts/architecture_brief.py"
|
||||
- "scripts/check_docs_links.py"
|
||||
- "scripts/check_no_overclaim.py"
|
||||
- "scripts/check_release_readiness_matrix.py"
|
||||
- "scripts/check_source_of_truth_index.py"
|
||||
- "scripts/check_glossary_consistency.py"
|
||||
- ".github/workflows/docs-governance.yml"
|
||||
- ".github/workflows/release-readiness-rc-gate.yml"
|
||||
- "MASTER_OPERATING_PROMPT.md"
|
||||
- "AGENTS.md"
|
||||
- "CLAUDE.md"
|
||||
@ -49,3 +61,43 @@ jobs:
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- run: python scripts/check_docs_links.py
|
||||
|
||||
no_overclaim:
|
||||
name: Docs no-overclaim scan
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- run: python scripts/check_no_overclaim.py
|
||||
|
||||
release_readiness_matrix:
|
||||
name: Release readiness matrix structure
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- run: python scripts/check_release_readiness_matrix.py
|
||||
|
||||
glossary_consistency:
|
||||
name: Glossary contract names (minimal)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- run: python scripts/check_glossary_consistency.py
|
||||
|
||||
source_of_truth_index:
|
||||
name: Source of truth index (minimal)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- run: python scripts/check_source_of_truth_index.py
|
||||
|
||||
39
.github/workflows/release-readiness-rc-gate.yml
vendored
Normal file
39
.github/workflows/release-readiness-rc-gate.yml
vendored
Normal file
@ -0,0 +1,39 @@
|
||||
# Optional strict RC row check when PR is tagged release-candidate or touches the matrix file.
|
||||
name: Release readiness RC row gate
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
types: [opened, synchronize, reopened, labeled, unlabeled]
|
||||
|
||||
jobs:
|
||||
strict_rc_row:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- name: Decide strict matrix check
|
||||
id: gate
|
||||
env:
|
||||
LABEL_NAMES: ${{ join(github.event.pull_request.labels.*.name, ',') }}
|
||||
run: |
|
||||
set -e
|
||||
if echo "$LABEL_NAMES" | grep -q 'release-candidate'; then
|
||||
echo "run=1" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
if git diff --name-only "${{ github.event.pull_request.base.sha }}...HEAD" | grep -q '^docs/RELEASE_READINESS_MATRIX_AR\.md$'; then
|
||||
echo "run=1" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
echo "run=0" >> "$GITHUB_OUTPUT"
|
||||
- name: Strict RC row (RELEASE_MATRIX_RC_ROW_REQUIRED)
|
||||
if: steps.gate.outputs.run == '1'
|
||||
run: RELEASE_MATRIX_RC_ROW_REQUIRED=1 python scripts/check_release_readiness_matrix.py
|
||||
- name: Skip strict RC row gate
|
||||
if: steps.gate.outputs.run != '1'
|
||||
run: echo "Skipping strict RC row gate (no release-candidate label; matrix file unchanged in this PR)."
|
||||
@ -34,6 +34,7 @@ Deep-dive topics live under [`docs/governance/`](docs/governance/) (keep this fi
|
||||
| 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) |
|
||||
| Tier-1 Master Closure (AR checklist) | [`docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) |
|
||||
| Final Tier-1 closure program (AR — operating law) | [`docs/FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](docs/FINAL_TIER1_CLOSURE_PROGRAM_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) |
|
||||
|
||||
124
docs/AUTOMATED_REVENUE_ENGINE_AR.md
Normal file
124
docs/AUTOMATED_REVENUE_ENGINE_AR.md
Normal file
@ -0,0 +1,124 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Growth + Platform"
|
||||
status: "canonical"
|
||||
review_cadence: "عند إضافة قناة inbound جديدة أو تغيير سياسة الـ outreach"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md"
|
||||
- "FIRST_THREE_CLIENTS_PLAN_AR.md"
|
||||
- "outreach_engine API (backend)"
|
||||
---
|
||||
|
||||
# محرك إيراد آلي (حدود واقعية + تنفيذ كامل)
|
||||
|
||||
«محرك إيراد آلي» هنا يعني: **تسلسلًا مُهيكلًا** من التقاط الاهتمام → التأهيل → جدولة → متابعة، مع **بوابات بشرية** حيث القانون أو المخاطرة يقتضيان ذلك — وليس إرسالًا جماعيًا بلا رقابة في السعودية أو أي سوق خاضع لـ PDPL/اشتراك.
|
||||
|
||||
---
|
||||
|
||||
## 1) المبادئ (غير قابلة للتفاوض)
|
||||
|
||||
1. **الموافقة والاشتراك:** لا رسائل بلا opt-in حيث يلزم القانون.
|
||||
2. **PDPL:** أي مسار يعرّض بيانات شركة/أشخاص يمرّ بتصنيف وحقول حوكمة — انظر [`proposals.py`](../salesflow-saas/backend/app/api/v1/proposals.py) و[`pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md).
|
||||
3. **الحد من الإزعاج:** حدود يومية/أسبوعية + قائمة عدم الاتصال.
|
||||
4. **أثر قابل للقياس:** كل خطوة تُسجَّل (CRM أو جدول) لربط الإنفاق بالإيراد لاحقًا.
|
||||
|
||||
---
|
||||
|
||||
## 2) مخطط التدفق (منطقي)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
inbound[Inbound_capture] --> qualify[Qualify_score]
|
||||
qualify --> route[Route_owner]
|
||||
route --> humanGate{Human_approval_for_send}
|
||||
humanGate -->|yes| outreach[Outreach_API]
|
||||
humanGate -->|no| nurture[Nurture_queue]
|
||||
outreach --> log[Audit_log]
|
||||
nurture --> log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) مصادر الإدخال (Capture)
|
||||
|
||||
| المصدر | تنفيذ |
|
||||
|--------|--------|
|
||||
| نماذج ويب / landing | توجيه إلى CRM أو جدول leads مع timestamp ومصدر |
|
||||
| استيراد قائمة | تنظيف + إزالة تكرار + **عدم** إرسال لمن لم يوافق |
|
||||
| حدث يدوي (معرض، مكالمة) | تسجيل في نفس النموذج |
|
||||
|
||||
---
|
||||
|
||||
## 4) التأهيل (Qualify)
|
||||
|
||||
* استخدام حقول Lead (حجم، قطاع، نضج شراكة) إن وُجدت في النموذج.
|
||||
* عتبة: فقط من يمرّ بعتبة الدخول إلى **قائمة اتصال بشري** أو إلى **قالب رسالة معتمد**.
|
||||
|
||||
---
|
||||
|
||||
## 5) التنفيذ الآلي المسموح (Outreach API)
|
||||
|
||||
الكود المرجعي: [`outreach_engine.py`](../salesflow-saas/backend/app/api/v1/outreach_engine.py) — مسارات مثل:
|
||||
|
||||
* `POST .../outreach-engine/send`
|
||||
* `POST .../outreach-engine/campaign/launch`
|
||||
* `GET .../outreach-engine/log`
|
||||
|
||||
**قاعدة:** أي إرسال جماعي يمرّ بـ:
|
||||
|
||||
1. مراجعة نص القالب (إصدار ثابت).
|
||||
2. حد أعلى لعدد المستلمين لكل دفعة.
|
||||
3. تسجيل النتيجة في `log` / مراقبة.
|
||||
|
||||
---
|
||||
|
||||
## 6) البوابة البشرية (Human-in-the-loop)
|
||||
|
||||
قبل أول إرسال لقائمة جديدة:
|
||||
|
||||
* موافقة داخلية (Slack/email مسجّل) **أو** موافقة Class B حيث السياسة تفرض ذلك على «التزام خارجي».
|
||||
|
||||
---
|
||||
|
||||
## 7) المتابعة (Cadence)
|
||||
|
||||
| بعد الإرسال | فعل |
|
||||
|-------------|-----|
|
||||
| يوم 2 | متابعة قصيرة |
|
||||
| يوم 5 | قيمة إضافية (رابط case أو مقياس) |
|
||||
| يوم 10 | إغلاق المحاولة أو تحويل لـ nurture |
|
||||
|
||||
استخدم نفس النصوص المرجعية في [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md).
|
||||
|
||||
---
|
||||
|
||||
## 8) القياس (Funnel)
|
||||
|
||||
1. Lead captured
|
||||
2. Qualified
|
||||
3. Meeting booked
|
||||
4. Pilot offered
|
||||
5. Pilot signed
|
||||
6. Paid
|
||||
|
||||
اربط كل مرحلة بمصدر حقيقة (CRM field أو log id).
|
||||
|
||||
---
|
||||
|
||||
## 9) ما لا يُسمى «أتمتة» هنا
|
||||
|
||||
* شراء قوائم بريدية غير موافَق عليها.
|
||||
* إرسال مخفي عبر قنوات تخرق سياسة المنصة.
|
||||
* «AI يغلق الصفقة» بدون إنسان — خارج النطاق التشغيلي الآمن.
|
||||
|
||||
---
|
||||
|
||||
## 10) التوسع التقني (لاحقًا)
|
||||
|
||||
* Webhooks من نماذج إلى طابور (queue) ثم عامل workers — عند الحاجة للحجم.
|
||||
* مزامنة ثنائية مع CRM — بعد أول عميل مدفوع.
|
||||
|
||||
---
|
||||
|
||||
*هذا المستند يحدّ السلوك الآمن والقابل للقياس؛ يلتزم فريق المنتج والقانون بتعديله عند تغيير السياسات.*
|
||||
337
docs/FINAL_TIER1_CLOSURE_PROGRAM_AR.md
Normal file
337
docs/FINAL_TIER1_CLOSURE_PROGRAM_AR.md
Normal file
@ -0,0 +1,337 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Program + Architect"
|
||||
status: "canonical"
|
||||
review_cadence: "عند تغيير معايير Tier-1 أو أدوات الموردين أو بوابات الإصدار"
|
||||
last_updated: "2026-04-16"
|
||||
---
|
||||
|
||||
# FINAL_TIER1_CLOSURE_PROGRAM_AR
|
||||
|
||||
---
|
||||
|
||||
## مقدمة
|
||||
|
||||
هذا المستند هو **برنامج الإغلاق النهائي لـ Tier-1** في Dealix.
|
||||
الغرض منه ليس إضافة أفكار جديدة، بل تثبيت ما بُني، وفرضه تشغيليًا، وإغلاق الفجوة بين:
|
||||
|
||||
* المرجعية
|
||||
* التنفيذ
|
||||
* التشغيل
|
||||
* الجاهزية المؤسسية
|
||||
|
||||
### القاعدة الحاكمة
|
||||
|
||||
**AI يستكشف ويحلل ويقترح. الأنظمة تنفذ. البشر يعتمدون القرارات الحرجة. الأدلة تثبت كل شيء.**
|
||||
|
||||
### الاعتماديات المرجعية المعتمدة
|
||||
|
||||
1. **OpenAI Responses API + remote MCP/tools** لطبقة القرار والاستدعاءات المهيكلة. ([platform.openai.com][1])
|
||||
2. **Structured Outputs** بدل JSON mode للمخرجات الحرجة. ([OpenAI][2])
|
||||
3. **LangGraph durable execution** للمسارات stateful وHITL. ([docs.langchain.com][3])
|
||||
4. **GitHub OIDC** لتبادل short-lived credentials بدل الأسرار الثابتة. ([GitHub Docs][4])
|
||||
5. **GitHub artifact attestations** لإثبات provenance وسلامة البناء. ([GitHub Docs][5])
|
||||
6. **OpenFGA immutable model pinning** لتثبيت authorization model في الإنتاج. ([openfga.dev][6])
|
||||
7. **NIST AI RMF + GenAI Profile** كمرجعية حوكمة ومخاطر للذكاء الاصطناعي. ([NIST][7])
|
||||
|
||||
**مرافق:** [`TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md`](TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md) (ستة اختبارات إغلاق) · [`TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md`](TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md) (تفعيل إنتاج) · [`TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md`](TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md) (Playbook مراحل الإطلاق) · [`TIER1_TRUST_EXPANSION_PLAN_AR.md`](TIER1_TRUST_EXPANSION_PLAN_AR.md) (توسع الثقة) · [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) (تفعيل إيراد Go-Live).
|
||||
|
||||
---
|
||||
|
||||
## 1) Must enforce now
|
||||
|
||||
هذا القسم ليس roadmap؛ هذا **قانون تشغيل**. أي بند هنا يجب أن يتحول إلى منع فعلي داخل runtime وCI.
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| ---------------------------------------------- | --------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| Structured Outputs إلزامية لكل المخرجات الحرجة | لأن `json_schema` يعطي التزامًا أقوى بالبنية من JSON mode | AI Platform Lead | schemas + runtime validation + fixture tests | لا يوجد output حرج free-text أو schema-less | كل `memo_json` و`approval_packet_json` و`execution_intent_json` تمر validation تلقائيًا |
|
||||
| Evidence Gate إلزامي لكل `external_*` | لأن أي external commitment بدون approval/evidence/correlation يضرب الثقة والتدقيق | Trust Systems Lead | tests تفشل عند غياب `correlation_id` أو `trace_id` أو `approval_packet` أو `evidence_pack` | أي external flow يفشل hard إذا نقص شرط | لا يمر term sheet أو signature request بلا bundle كامل |
|
||||
| Root-safe execution | لأن path assumptions تكسر hooks/CI وتخلق drift | DevEx Lead | preflight من جذر الريبو + hook/CI enforcement | كل أمر يبدأ من repo root | لا يوجد `cd` hardcoded لمسار قديم |
|
||||
| Severity V0–V3 policy | لتحويل severity من توصيف إلى سياسة قرار | Governance Lead | severity mapping في approvals / contradictions / incidents | V2/V3 توقف promotion أو external commitment تلقائيًا | severity تؤثر فعليًا على السلوك |
|
||||
| Source-of-Truth enforcement | لمنع تضارب docs والـ PRs والنسخ | Program Manager | `SOURCE_OF_TRUTH_INDEX.md` مكتمل ومربوط | كل topic له canonical file واحد | لا يوجد ملفان يعرّفان الشيء نفسه بلا أولوية |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
يجب أن تصبح **Docs/Governance CI** جزءًا من P0، لأن الحقيقة المرجعية إذا بقيت خارج CI فستتباعد عن التنفيذ مهما كانت قوة attestations. كما يجب فصل **OIDC** عن **artifact attestations** داخل الضوابط: الأول خاص بالوصول الآمن إلى مزودات السحابة ([GitHub Docs][4])، والثاني خاص بإثبات provenance للـ artifacts ([GitHub Docs][5]).
|
||||
|
||||
---
|
||||
|
||||
## 2) One live path to close
|
||||
|
||||
لا تغلقوا Tier-1 عبر عشرات المسارات.
|
||||
أغلقوه عبر **مسار حي واحد** يمثل المنصة كلها.
|
||||
|
||||
### المسار الذهبي المعتمد
|
||||
|
||||
**Partner intake → Partner dossier → Economics model → Approval packet → Approval Center → Workflow commitment → Evidence pack → Executive weekly summary**
|
||||
|
||||
### لماذا هذا هو المسار الأفضل؟
|
||||
|
||||
لأنه يختبر:
|
||||
|
||||
* Decision Plane
|
||||
* Trust Plane
|
||||
* Execution Plane
|
||||
* Data Plane
|
||||
* Executive Surface
|
||||
|
||||
دفعة واحدة، وهو أسرع مسار لإظهار قيمة تشغيلية وتجارية مبكرة.
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| --------------------------- | ---------------------------- | --------------------- | -------------------------------------- | --------------------------------------- | ------------------------------------------ |
|
||||
| Partner dossier حي | يثبت أن القرار ليس نصًا حرًا | Partnerships Lead | dossier artifact + schema pass | dossier يُولد من بيانات حقيقية | dossier قابل للعرض والمراجعة |
|
||||
| Economics model حي | يربط الشراكة بالمال | Strategy/Finance Lead | economics output + assumptions | contribution margin visible | لا توجد شراكة بلا economics |
|
||||
| Approval path حي | يثبت Trust Fabric عمليًا | Governance Lead | approval logs + SLA | approve/edit/reject working | المسار لا يتجاوز approval |
|
||||
| Workflow commitment حي | يثبت execution beyond chat | Platform Lead | commitment record + status transitions | state moves correctly with pause/resume | المسار يستكمل بعد interruption |
|
||||
| Evidence pack حي | يثبت reproducibility | Trust Lead | evidence pack + source links | reproducible from same inputs | القرار يأتي معه دليله |
|
||||
| Executive weekly summary حي | يثبت board-usable surface | Product Lead | weekly contract rendered in UI | exec can review one live case weekly | التنفيذي يرى "ماذا تغير؟ ماذا يحتاج قرار؟" |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
لا يبدأ مسار حي ثانٍ قبل نجاح هذا المسار في:
|
||||
|
||||
* schema validation
|
||||
* SLA approval
|
||||
* contradiction handling
|
||||
* executive usage
|
||||
* reproducible evidence
|
||||
|
||||
---
|
||||
|
||||
## 3) CI changes
|
||||
|
||||
افصلوا CI إلى ثلاث حارات واضحة.
|
||||
|
||||
### A. Docs & Governance CI
|
||||
|
||||
يشغّل:
|
||||
|
||||
* `python scripts/architecture_brief.py`
|
||||
* `python scripts/check_docs_links.py`
|
||||
* source-of-truth checks
|
||||
* no-overclaim checks
|
||||
* glossary consistency checks
|
||||
|
||||
### B. Schemas & Contracts CI
|
||||
|
||||
يشغّل:
|
||||
|
||||
* JSON schema validation
|
||||
* structured output fixtures
|
||||
* approval/evidence contract tests
|
||||
* correlation propagation tests
|
||||
|
||||
### C. Runtime Trust & Release CI
|
||||
|
||||
يشغّل:
|
||||
|
||||
* approval flow tests
|
||||
* contradiction flow tests
|
||||
* workflow commitment tests
|
||||
* release readiness completeness checks
|
||||
* executive contract generation tests
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| ------------------------ | ----------------------------------------------------- | ---------------- | ----------------------------------- | -------------------------------------- | ------------------------------ |
|
||||
| Docs/Governance CI مستقل | لأن docs/scripts جزء من source of truth | DevEx Lead | workflow file + passing runs | أي تغيير في docs/scripts يطلق checks | لا drift بين المرجعية والتنفيذ |
|
||||
| Contracts CI | لأن Structured Outputs تحتاج fixture validation أيضًا | AI Platform Lead | fixture suite + CI pass | كل contract حرج covered | أي كسر في schema يظهر فورًا |
|
||||
| Release Readiness CI | لربط الحوكمة بالإطلاق | Release Manager | release matrix generated on RC | لا RC صالح بلا matrix مكتملة | الإطلاق قرار موثق لا شفهي |
|
||||
| Provenance check | لرفع supply-chain trust | Platform Lead | attestation step أو documented gate | one artifact path at least provenanced | تعرف كيف بُني كل artifact |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
يجب أن تصبح `RELEASE_READINESS_MATRIX_AR.md` **gate فعلية** في PR/RC، لا مجرد وثيقة مرجعية. كما يجب أن تبقى حوكمة `docs/` و`scripts/` تحت CI دائمًا، لأنها جزء من الدستور التشغيلي لا من الشرح فقط. ([GitHub Docs][5])
|
||||
|
||||
---
|
||||
|
||||
## 4) Executive surface rollout
|
||||
|
||||
أفضل rollout الآن ليس كل الأسطح، بل أربع واجهات حية فقط.
|
||||
|
||||
### Executive Room
|
||||
|
||||
يعرض:
|
||||
|
||||
* what changed this week
|
||||
* what needs decision now
|
||||
* what is blocked
|
||||
* what is at risk if delayed
|
||||
* actual vs forecast
|
||||
|
||||
### Approval Center
|
||||
|
||||
يدعم:
|
||||
|
||||
* approve
|
||||
* edit
|
||||
* reject
|
||||
|
||||
### Evidence Pack Viewer
|
||||
|
||||
يعرض:
|
||||
|
||||
* sources
|
||||
* assumptions
|
||||
* freshness
|
||||
* confidence
|
||||
* approvals
|
||||
* tool receipts
|
||||
* contradictions
|
||||
|
||||
### Actual vs Forecast
|
||||
|
||||
موحد بين:
|
||||
|
||||
* revenue
|
||||
* partnerships
|
||||
* execution velocity
|
||||
* trust incidents
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| ---------------------------- | ------------------------------- | --------------- | -------------------------- | -------------------------------------- | ---------------------------------------------- |
|
||||
| Executive Room حي | هذا هو surface الذي "يبيع نفسه" | Product Lead | live screen + weekly usage | stakeholder تنفيذي يستخدمه أسبوعيًا | الإدارة ترى control tower لا dashboards مبعثرة |
|
||||
| Approval Center ثلاثي القرار | يرفع نضج الحوكمة | Governance Lead | approve/edit/reject logs | كل قرار حساس يمر عبره | لا approvals خارج النظام |
|
||||
| Evidence Pack Viewer حي | يثبت الثقة | Trust Lead | one live viewer path | evidence inspectable for one live flow | كل قرار له ملف أدلة واضح |
|
||||
| Actual vs Forecast موحد | يربط القرار بالأثر | Finance/Product | live dashboard | weekly review حي | التنفيذي يرى deviation مبكرًا |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
يجب أن يكون **`ExecWeeklyGovernanceContract` هو المصدر الوحيد** الذي يغذي:
|
||||
|
||||
* Executive Room
|
||||
* Weekly pack
|
||||
* Board draft
|
||||
* What changed
|
||||
* Pending decisions
|
||||
* Blockers
|
||||
* At-risk items
|
||||
|
||||
ولا يسمح بأي منطق موازٍ لهذه الواجهات.
|
||||
|
||||
---
|
||||
|
||||
## 5) Saudi control activation
|
||||
|
||||
أفضل Tier-1 هنا هو **workflow-level control activation**.
|
||||
|
||||
ابدأوا بمسار سعودي حساس واحد فقط، مثل:
|
||||
|
||||
* partner data sharing
|
||||
* external proposal containing personal/company data
|
||||
* DD document ingestion
|
||||
|
||||
ثم اربطوه بـ:
|
||||
|
||||
* PDPL data classification
|
||||
* NCA/ECC owner
|
||||
* NIST GenAI overlay
|
||||
* OWASP LLM threat mapping
|
||||
* retention/export rules
|
||||
* approval and audit path
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| -------------------------------- | -------------------------------- | -------------------- | --------------------------- | --------------------------- | -------------------------------------------- |
|
||||
| Saudi Workflow Control Matrix حي | يحول الامتثال من doc إلى control | Compliance Lead | matrix by workflow | one workflow fully mapped | لا غموض في data class / approval / retention |
|
||||
| NIST GenAI overlay | يرفع نضج AI governance | AI Safety Lead | control mapping on one flow | AI risk reviewed in release | المخاطر التوليدية مرئية لا ضمنية |
|
||||
| OWASP mapping by plane | يحسن threat modeling | Security Lead | mapped surfaces | one active checklist used | لكل plane تهديداته وضوابطه |
|
||||
| Retention/export policy حي | مهم قانونيًا وتشغيليًا | Compliance/Data Lead | retention rules + owner | one sensitive path governed | تعرف ماذا يُحفظ وأين ولمدة كم |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
لا تعتبروا Saudi readiness "مكتملة" حتى يوجد **workflow واحد حي** مرتبط بـ:
|
||||
|
||||
* PDPL
|
||||
* NCA/ECC
|
||||
* NIST GenAI
|
||||
* OWASP
|
||||
|
||||
بشكل عملي، لا وثائقي فقط. ([NIST][7])
|
||||
|
||||
---
|
||||
|
||||
## 6) Release gate
|
||||
|
||||
لا يوجد Release Candidate صالح إلا إذا تحققت الشروط التالية معًا:
|
||||
|
||||
* `architecture_brief.py` passes
|
||||
* Docs/Governance CI passes
|
||||
* Structured output contracts pass
|
||||
* Approval flow حي لمسار واحد على الأقل
|
||||
* Evidence pack reproducibility مثبتة
|
||||
* No unresolved V3 contradiction
|
||||
* One executive view محدث من بيانات حية
|
||||
* One Saudi-sensitive workflow mapped and gated
|
||||
* Provenance path موجود حيث تسمح الخطة والبنية
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| -------------------------------- | -------------------------------- | --------------- | ------------------------------- | -------------------------- | -------------------------------- |
|
||||
| Release Readiness Matrix إلزامية | تمنع إطلاقًا مبنيًا على الانطباع | Release Manager | completed matrix per RC | no release without matrix | الإطلاق قرار موثق لا شفهي |
|
||||
| Contradiction gate | يمنع تجاهل تعارضات خطرة | Trust Lead | contradiction severity queue | no open V3 on RC | الخطر الواضح يوقف الإطلاق |
|
||||
| Provenance gate | يرفع ثقة supply chain | Platform Lead | attestation/provenance evidence | one verified artifact path | تعرف ماذا بُني وكيف |
|
||||
| Executive signoff path | يربط المنتج بالإدارة | Product/Founder | review log | one exec review per RC | الإدارة جزء من gate وليس ما بعده |
|
||||
|
||||
### قرار Tier-1
|
||||
|
||||
يجب أن يكون **صف RC في `RELEASE_READINESS_MATRIX_AR.md` موجودًا ومفحوصًا آليًا**، وأي RC بلا matrix مكتملة أو بلا صف RC صالح يعتبر غير مؤهل للإطلاق.
|
||||
|
||||
---
|
||||
|
||||
## 7) Definition of Tier-1 complete
|
||||
|
||||
اعتبروا Dealix **Tier-1 complete** فقط إذا تحققت هذه الشروط معًا:
|
||||
|
||||
1. كل output حرج schema-bound ويجتاز validation.
|
||||
2. يوجد live path واحد end-to-end عبر Decision + Trust + Execution + Executive.
|
||||
3. يوجد approval flow حي مع SLA measurable.
|
||||
4. يوجد contradiction-aware tool flow حي.
|
||||
5. توجد Evidence Pack قابلة لإعادة البناء من نفس المصادر بنفس الهيكل.
|
||||
6. CI يحرس docs/scripts/contracts، لا الكود فقط.
|
||||
7. توجد Executive Room تُستخدم فعليًا في مراجعة أسبوعية.
|
||||
8. يوجد Saudi control activation لمسار حي واحد على الأقل.
|
||||
9. يوجد provenance/release control واضح where applicable.
|
||||
10. لا يوجد overclaim بين docs والكود والحالة التشغيلية.
|
||||
|
||||
| البند التنفيذي | لماذا مهم | Owner | Evidence required | Exit criteria | What good looks like |
|
||||
| ---------------------------------- | ---------------------------- | ---------------- | ---------------------------- | ---------------------------------------- | ------------------------------------ |
|
||||
| Structured critical outputs | أساس trustable decisioning | AI Platform Lead | pass rate reports | all critical outputs validated | outputs قابلة للتشغيل لا للقراءة فقط |
|
||||
| One live end-to-end path | يثبت أن النظام ليس docs-only | Program Lead | demo + logs + artifacts | one path closed fully | المنصة تعمل كنسيج واحد |
|
||||
| Executive weekly usage | يثبت product reality | Product Lead | usage analytics / review log | one executive role weekly active | النظام جزء من cadence الإدارة |
|
||||
| Saudi-sensitive control activation | يثبت الجاهزية المحلية | Compliance Lead | mapped workflow evidence | one live governed workflow | الامتثال حاضر في التشغيل |
|
||||
| No-overclaim state | يحمي الثقة | Program Manager | truth audit | zero misleading claims in canonical docs | الواقع والوثيقة متطابقان |
|
||||
|
||||
---
|
||||
|
||||
## الحكم النهائي
|
||||
|
||||
**نعم، بهذه الصيغة هي Tier-1 فعلًا وبأفضل شكل منطقي الآن**، لكن بشرط واحد حاسم:
|
||||
|
||||
لا تعتبروا "اكتمال الوثائق" = "اكتمال Tier-1".
|
||||
Tier-1 الحقيقي يبدأ عندما يصبح هذا البرنامج:
|
||||
|
||||
* enforced in runtime
|
||||
* guarded by CI
|
||||
* proven by one live path
|
||||
* visible in executive surfaces
|
||||
* reflected in release decisions
|
||||
|
||||
إذا طبقتم الأقسام السبعة أعلاه كما هي، فأنتم لا تعودون "قريبين من Tier-1"، بل **دخلتم Tier-1 تشغيلًا**.
|
||||
|
||||
---
|
||||
|
||||
## المراجع الرسمية
|
||||
|
||||
1. OpenAI Responses API + remote MCP / tools. ([platform.openai.com][1])
|
||||
2. OpenAI Structured Outputs. ([OpenAI][2])
|
||||
3. LangGraph durable execution. ([docs.langchain.com][3])
|
||||
4. GitHub Actions OIDC. ([GitHub Docs][4])
|
||||
5. GitHub artifact attestations. ([GitHub Docs][5])
|
||||
6. OpenFGA immutable authorization models. ([openfga.dev][6])
|
||||
7. NIST AI RMF + NIST GenAI Profile. ([NIST][7]) — ملحق GenAI: [NIST GenAI Profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence)
|
||||
|
||||
[1]: https://platform.openai.com/docs/api-reference/responses/remote-mcp "API Overview | OpenAI API Reference"
|
||||
[2]: https://openai.com/index/introducing-structured-outputs-in-the-api/ "Introducing Structured Outputs in the API | OpenAI"
|
||||
[3]: https://docs.langchain.com/oss/javascript/langgraph/durable-execution "Durable execution - Docs by LangChain"
|
||||
[4]: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect "OpenID Connect in GitHub Actions | GitHub Docs"
|
||||
[5]: https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/security/artifact-attestations "Artifact attestations | GitHub Docs"
|
||||
[6]: https://openfga.dev/docs/getting-started/immutable-models "Immutable Authorization Models | OpenFGA"
|
||||
[7]: https://www.nist.gov/itl/ai-risk-management-framework "AI Risk Management Framework | NIST"
|
||||
127
docs/FIRST_THREE_CLIENTS_PLAN_AR.md
Normal file
127
docs/FIRST_THREE_CLIENTS_PLAN_AR.md
Normal file
@ -0,0 +1,127 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Founder + Sales"
|
||||
status: "canonical"
|
||||
review_cadence: "أسبوعيًا حتى توقيع ثلاثة pilots على الأقل"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md"
|
||||
- "TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md"
|
||||
---
|
||||
|
||||
# خطة أول 3 عملاء (B2B — تنفيذ كامل)
|
||||
|
||||
هدف الملف: تحويل [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) إلى **خطة أسبوعية قابلة للتنفيذ**: من يستهدف، بماذا تتواصل، كيف تُغلق pilot، وما الذي تُثبته كأثر.
|
||||
|
||||
---
|
||||
|
||||
## 1) تعريف العميل المثالي (ICP) — صف واحد لا يتجزأ
|
||||
|
||||
| بعد | قرار |
|
||||
|-----|------|
|
||||
| جغرافيا | السعودية (أو GCC إن كان المنتج مهيأ) |
|
||||
| حجم | 50–500 موظفًا أو إيرادًا يتطلب **قرارات شراكات متكررة** |
|
||||
| ألم واضح | تأخير موافقات، غموض صفقة شراكة، فقدان رؤية تنفيذية أسبوعية |
|
||||
| سلطة شرائية | CRO / VP Sales / CEO يملك تجربة pilot بميزانية محدودة |
|
||||
| استبعاد صريح | شركات بلا مسار قرار خلال 21 يومًا؛ جهات تتطلب RFP طويلة قبل أي محادثة |
|
||||
|
||||
**مخرج:** قائمة **40–60 شركة** في جدول (اسم، قطاع، جهة اتصال، قناة أولى، تاريخ آخر لمس).
|
||||
|
||||
---
|
||||
|
||||
## 2) العرض الموحّد (One Offer)
|
||||
|
||||
نفس العبارة في كل القناة (تعديل طفيف حسب القناة):
|
||||
|
||||
> Pilot **14 يومًا**: ربط **موافقات أسرع + وضوح صفقات شراكة + ملخص تنفيذي أسبوعي** على مسار واحد حي — بدون تفعيل M&A كامل أو كل الموصلات.
|
||||
|
||||
**سعر مرساة للمناقشة:** 15K–50K SAR (نطاق يُحدَّد حسب عدد المستخدمين والموصلات المفعّلة في الـ pilot).
|
||||
|
||||
---
|
||||
|
||||
## 3) حزم الرسائل (جاهزة للنسخ)
|
||||
|
||||
### أ) LinkedIn / رسالة قصيرة
|
||||
|
||||
```
|
||||
[الاسم] — تحية سريعة.
|
||||
|
||||
نركّب لفرق مبيعات/شراكات في [القطاع] طبقة تشغيل تسرّع الموافقات وتُظهر حالة الصفقة للإدارة أسبوعيًا.
|
||||
Pilot لمدة أسبوعين بحدود واضحة. هل يناسبك اتصال 15 دقيقة [يوم/ساعة مقترحة]؟
|
||||
```
|
||||
|
||||
### ب) WhatsApp (مع الالتزام بالموافقة والاشتراك)
|
||||
|
||||
```
|
||||
السلام عليكم [الاسم]، أنا [اسمك] من [Dealix].
|
||||
نشتغل pilot 14 يومًا لتحسين موافقات الشراكات ورؤية الإدارة للصفقة. هل أرسل لك فقرة نطاق صغيرة (3 أسطر)؟
|
||||
```
|
||||
|
||||
### ج) بريد إلكتروني
|
||||
|
||||
* موضوع: `Pilot 14 يوم — موافقات + رؤية تنفيذية (شراكات)`
|
||||
* جسم: 5 أسطر: المشكلة → ما تفعله المنصة في الـ pilot → مدة → طلب اجتماع 20 دقيقة → توقيع.
|
||||
|
||||
---
|
||||
|
||||
## 4) إيقاع الأسبوع (حتى 3 عملاء)
|
||||
|
||||
| اليوم | نشاط | كمية هدف |
|
||||
|-------|------|-----------|
|
||||
| 1 | بناء القائمة 40–60 + رسائل LinkedIn | 25 اتصالًا أوليًا |
|
||||
| 2 | متابعة + WhatsApp للمهتمين + بريد | 20 متابعة |
|
||||
| 3–4 | حجز demos (Executive Simulation كما في [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md)) | 6–10 اجتماعات |
|
||||
| 5 | عروض أسعار / نطاق pilot موقّت | 4 عروض |
|
||||
| 6–7 | إغلاق: توقيع أو دفعة مقدمة أو جدولة قاطعة | **هدف: 1 عميل على الأقل**؛ تكرار الأسبوع الثاني والثالث لبلوغ 3 |
|
||||
|
||||
---
|
||||
|
||||
## 5) سكربت الاجتماع (20 دقيقة)
|
||||
|
||||
1. دقيقتان: سياقهم (قرار شراكة أخير تأخر؟).
|
||||
2. ثماني دقائق: عرض **Executive Room + Approval + Evidence** على بياناتهم التجريبية أو نموذج قريب منهم.
|
||||
3. خمس دقائق: سؤال الأثر: «كم يكلفكم تأخير أسبوع في هذه المرحلة؟»
|
||||
4. خمس دقائق: نطاق pilot + السعر + تاريخ البدء.
|
||||
|
||||
---
|
||||
|
||||
## 6) معالجة الاعتراضات (مختصرة)
|
||||
|
||||
| الاعتراض | رد |
|
||||
|----------|-----|
|
||||
| «نحتاج أمان أكثر» | نعرض Class B + evidence + مسار السعودية في العروض — انظر [`governance/pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md). |
|
||||
| «نحتاج تكامل كامل» | الـ pilot يحدّ الموصلات؛ التوسع بعد إثبات الأثر — [`TIER1_TRUST_EXPANSION_PLAN_AR.md`](TIER1_TRUST_EXPANSION_PLAN_AR.md). |
|
||||
| «غالي» | نربط بالأثر: أسبوع تأخير = X؛ الـ pilot يحدّ المخاطر. |
|
||||
|
||||
---
|
||||
|
||||
## 7) قائمة تحقق قبل التوقيع (Pilot)
|
||||
|
||||
- [ ] نطاق: مستخدمون، موصلات، بيانات حساسة أم لا.
|
||||
- [ ] PDPL: تصنيف بيانات عند `external_company_contacts` — [`proposals` send rules](../salesflow-saas/backend/app/api/v1/proposals.py).
|
||||
- [ ] SLA: زمن استجابة، قناة دعم، ساعات عمل.
|
||||
- [ ] خروج: تعريف «نجاح pilot» بأرقام (موافقة، دورة، وضوح).
|
||||
- [ ] **دفعة:** مبلغ + تاريخ فوترة + طريقة دفع.
|
||||
|
||||
---
|
||||
|
||||
## 8) ما بعد العميل الأول
|
||||
|
||||
* **Case study** صفحة واحدة: المشكلة → ما رُكّب → رقم قبل/بعد (حتى تقريبي مع توثيق).
|
||||
* **Referral ask:** في نهاية الـ pilot — «من تعرف في [قطاعين] قد يستفيد؟»
|
||||
|
||||
---
|
||||
|
||||
## 9) مؤشرات قياس (CRM بسيط)
|
||||
|
||||
| المؤشر | تعريف |
|
||||
|--------|--------|
|
||||
| اتصالات أولى | رسالة مرسلة |
|
||||
| رد | أي رد إيجابي أو حجز |
|
||||
| demo | اجتماع أُجري |
|
||||
| عرض | عرض سعر مرسل |
|
||||
| won | عقد موقّع أو دفعة |
|
||||
|
||||
---
|
||||
|
||||
*هذا الملف تجاري تشغيلي؛ يلتزم بالقوانين المحلية للتسويق والخصوصية عند التنفيذ.*
|
||||
180
docs/GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md
Normal file
180
docs/GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md
Normal file
@ -0,0 +1,180 @@
|
||||
---
|
||||
version: "1.1"
|
||||
owner: "Founder + Program"
|
||||
status: "canonical"
|
||||
review_cadence: "أسبوعيًا حتى أول عميل مدفوع؛ ثم مع كل pilot"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md"
|
||||
- "TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md"
|
||||
- "golden-path-partner-intake-runbook.md"
|
||||
- "enterprise-readiness.md"
|
||||
- "FIRST_THREE_CLIENTS_PLAN_AR.md"
|
||||
- "LIVE_DEPLOYMENT_GUIDE_AR.md"
|
||||
- "AUTOMATED_REVENUE_ENGINE_AR.md"
|
||||
---
|
||||
|
||||
# GO-LIVE Revenue Activation System
|
||||
|
||||
بعد إكمال **البنية + الحوكمة + العقود + CI**، الخطورة التالية ليست «ميزة إضافية» بل **تشغيل إيراد**: السوق يقيس بعميل، بصفقة، بـROI واضح — لا بعدد ملفات الحوكمة.
|
||||
|
||||
هذا المستند يحدد **تشغيلًا واقعيًا** (outreach → demo → pilot → دفع) مع **تثبيت إنتاجي** خفيف بعد الإطلاق، دون انتظار «كمال» يقتل الزمن.
|
||||
|
||||
**مرافق تقني:** [`TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md`](TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md) · [`TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md`](TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md) · [`enterprise-readiness.md`](enterprise-readiness.md) · [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md) · [`LIVE_DEPLOYMENT_GUIDE_AR.md`](LIVE_DEPLOYMENT_GUIDE_AR.md) · [`AUTOMATED_REVENUE_ENGINE_AR.md`](AUTOMATED_REVENUE_ENGINE_AR.md)
|
||||
|
||||
---
|
||||
|
||||
## الحقيقة التشغيلية
|
||||
|
||||
| لديك الآن | ما يزال مطلوبًا لإيراد |
|
||||
|-----------|-------------------------|
|
||||
| Tier-1 architecture، governance، CI، trust، contracts | **صفقات مدفوعة**، قرار تنفيذي يُستخدم، دليل أثر (وقت/وضوح/دورة) |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Revenue Engine LIVE (أول 48 ساعة عمل)
|
||||
|
||||
### 1) هدف عميل واضح
|
||||
|
||||
مثال اتجاه (قابل للتعديل): B2B في السعودية، مبيعات معقّدة، شراكات، pipeline ثقيل — **شرط واحد**: تستطيع الوصول إليهم خلال أسبوع.
|
||||
|
||||
### 2) عرض واحد (بدون تعقيد)
|
||||
|
||||
صياغة مقترحة للعرض:
|
||||
|
||||
> نركّب لكم طبقة تشغيل تحسّن سرعة الإغلاق، الموافقات، وصفقات الشراكة خلال **14 يومًا** (pilot محدود النطاق).
|
||||
|
||||
### 3) استخدام ما هو موجود في المنصة
|
||||
|
||||
| قدرة | مرجع في المشروع |
|
||||
|------|------------------|
|
||||
| Outreach / حملات | [`outreach_engine.py`](../salesflow-saas/backend/app/api/v1/outreach_engine.py) — API تحت `/api/v1/outreach-engine/` |
|
||||
| WhatsApp / قنوات | إعدادات البيئة + مسارات القنوات في [`INTEGRATION_MASTER_AR.md`](../salesflow-saas/docs/INTEGRATION_MASTER_AR.md) حيث ينطبق |
|
||||
| عروض / PDF | [`proposals.py`](../salesflow-saas/backend/app/api/v1/proposals.py) + مولّد العروض في `app/services/cpq/` |
|
||||
|
||||
### 4) حجم أولي للاتصال (مثال يوم 1)
|
||||
|
||||
* 30 رسالة LinkedIn (أو ما يعادلها قانونيًا)
|
||||
* 20 WhatsApp (ضمن سياسة الاشتراك والـ PDPL)
|
||||
* 10 بريد إلكتروني
|
||||
|
||||
### سكربت رسالة قصيرة (مثال)
|
||||
|
||||
```
|
||||
نشتغل مع شركات شبيهة بـ[قطاعكم].
|
||||
نركّب طبقة تشغيل تسرّع الموافقات، توضّح صفقات الشراكة، وتعطي الإدارة رؤية مباشرة للقرار.
|
||||
إن رغبتم pilot لمدة أسبوعين، نرتّب لكم جلسة قصيرة مع demo تنفيذي.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Demo Engine (تنفيذي لا تقني فقط)
|
||||
|
||||
### مبدأ
|
||||
|
||||
لا تعرض «شاشات تقنية» فقط؛ عرض **Executive Simulation**:
|
||||
|
||||
* Executive Room / الملخص الأسبوعي — [`executive-room-completion-spec.md`](executive-room-completion-spec.md) و`GET /api/v1/executive-room/snapshot`
|
||||
* Approval Center — مسار Class B في [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md)
|
||||
* Evidence Pack — `GET /api/v1/evidence-packs/tier1-demo` (أو مسار حي عند الجاهزية)
|
||||
* Pipeline / صفقة نموذجية — حسب ما هو مفعّل لدى العميل
|
||||
|
||||
### سؤال قرار للعميل
|
||||
|
||||
> لو كان هذا لديكم اليوم — كم يوفر من **وقت** أو **تكلفة فرصة** أو **مخاطر تأخير موافقة**؟
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — إغلاق أول صفقة (Critical)
|
||||
|
||||
* الهدف: **أول دفعة pilot** — لا عقد «مثالي» ولا scale كامل.
|
||||
* تسعير مقترح للنقاش: **15K–50K SAR** لمدة **2–4 أسابيع** (حسب النطاق والالتزامات القانونية).
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — نشر Pilot حقيقي
|
||||
|
||||
### يركّب فقط
|
||||
|
||||
* مسار الإيراد + الموافقات + لوحة تنفيذية — كما في اتفاق الـ pilot.
|
||||
|
||||
### لا يركّب في الـ pilot الأول
|
||||
|
||||
* M&A كامل، توسع موصلات بلا حد، «كل النظام» — يبقى خارج النطاق حتى إثبات القيمة.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Evidence Generation (إثبات الأثر)
|
||||
|
||||
يثبت الـ pilot (أرقام أو مؤشرات اتجاهية):
|
||||
|
||||
* انخفاض زمن الموافقة (approval time)
|
||||
* زيادة وضوح الصفقة (deal clarity)
|
||||
* انخفاض دورة القرار (cycle time)
|
||||
|
||||
اربط الأرقام بسجلات النظام (سجلات موافقة، طوابع زمنية، evidence packs) حيث متاح.
|
||||
|
||||
---
|
||||
|
||||
## تثبيت ما بعد الإطلاق (Production Hardening للإيراد)
|
||||
|
||||
بعد بدء دفع العميل، ثبّت **ثلاثة** فقط مع الأولوية:
|
||||
|
||||
1. **Observability:** `trace_id` / `correlation_id` على الطلبات الحرجة؛ أخطاء مسجّلة؛ لوحة مراقبة حية.
|
||||
2. **Failure recovery:** إعادة محاولة، idempotency، خطة rollback (انظر [`governance/github-and-release.md`](governance/github-and-release.md)).
|
||||
3. **سجلات حقيقية:** ليست سجلات اختبار فقط — احتفظ بمسار تدقيق للـ pilot.
|
||||
|
||||
---
|
||||
|
||||
## Revenue Loop (قمع لا يُهمل)
|
||||
|
||||
1. Lead
|
||||
2. Demo
|
||||
3. Pilot
|
||||
4. Case study (موثّق)
|
||||
5. Referral
|
||||
|
||||
بدون حلقة إحالة وقصة نجاج، يبقى النظام **قويًا تقنيًا** وضعيفًا تجاريًا.
|
||||
|
||||
---
|
||||
|
||||
## خطة أسبوع واقعية (مثال)
|
||||
|
||||
| الأيام | التركيز |
|
||||
|--------|---------|
|
||||
| 1–2 | Outreach + تجهيز demo |
|
||||
| 3–5 | Demos |
|
||||
| 6–7 | إغلاق أول التزام مدفوع (أو جدولة واضحة بتاريخ + مبلغ) |
|
||||
|
||||
---
|
||||
|
||||
## مؤشرات نجاح (غير تقنية بحتة)
|
||||
|
||||
* عميل دفع pilot (أو عقد موقّع بمبلغ محدد).
|
||||
* تنفيذي يستخدم لوحة/ملخص أسبوعي **مرة على الأقل** خلال الـ pilot.
|
||||
* قرار مهم مرّ عبر النظام (موافقة + أدلة) وليس خارجها.
|
||||
* تحسّن ملحوظ في زمن موافقة **قابل للإثبات** من السجلات.
|
||||
|
||||
---
|
||||
|
||||
## تحذير تشغيلي
|
||||
|
||||
غالبية المشاريع القوية تقف عند «اكتمال التقنية» بسبب:
|
||||
|
||||
* over-engineering،
|
||||
* تأخير البيع،
|
||||
* انتظار كمال غير ضروري للـ pilot.
|
||||
|
||||
الفوز: **system → decision → deal → money** بأصغر نطاق ممكن أولًا.
|
||||
|
||||
---
|
||||
|
||||
## الملحقات (مفعّلة — وثائق كاملة)
|
||||
|
||||
1. [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md) — استهداف، رسائل، إيقاع أسبوع، إغلاق pilot.
|
||||
2. [`LIVE_DEPLOYMENT_GUIDE_AR.md`](LIVE_DEPLOYMENT_GUIDE_AR.md) — تركيب عند عميل، بيئة، بوابات، مراقبة.
|
||||
3. [`AUTOMATED_REVENUE_ENGINE_AR.md`](AUTOMATED_REVENUE_ENGINE_AR.md) — تدفق capture→qualify→outreach مع حدود قانونية وبوابة بشرية.
|
||||
|
||||
---
|
||||
|
||||
*هذا المستند عملي وتجاري؛ لا يستبدل الاستشارة القانونية أو عقود المبيعات.*
|
||||
117
docs/LIVE_DEPLOYMENT_GUIDE_AR.md
Normal file
117
docs/LIVE_DEPLOYMENT_GUIDE_AR.md
Normal file
@ -0,0 +1,117 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Platform + Release"
|
||||
status: "canonical"
|
||||
review_cadence: "مع كل pilot أو تغيير بيئة عميل"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md"
|
||||
- "TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md"
|
||||
- "LAUNCH_CHECKLIST (salesflow-saas/docs)"
|
||||
---
|
||||
|
||||
# دليل النشر الحي عند عميل (Pilot / Prod)
|
||||
|
||||
دليل **خطوة بخطوة** لتركيب Dealix في بيئة عميل (staging أو إنتاج محدود) مع الإشارة إلى الملفات القائمة في المستودع. لا يغني عن runbooks الداخلة لدى العميل.
|
||||
|
||||
---
|
||||
|
||||
## 0) نطاق الـ pilot (قبل أي أمر)
|
||||
|
||||
| بند | قرار |
|
||||
|-----|------|
|
||||
| Tenant / حسابات | من يملك المستخدم الإداري؟ |
|
||||
| موصلات مفعّلة | بريد، WhatsApp، CRM، توقيع — **قائمة صريحة** |
|
||||
| بيانات حساسة | نعم/لا → تفعيل حقول PDPL على المسارات الخارجية |
|
||||
| نافذة الصيانة | تاريخ + تراجع إن لزم |
|
||||
|
||||
---
|
||||
|
||||
## 1) المتطلبات والتحقق المحلي (Repo)
|
||||
|
||||
من **جذر المستودع**:
|
||||
|
||||
```bash
|
||||
python scripts/architecture_brief.py
|
||||
python scripts/check_docs_links.py
|
||||
```
|
||||
|
||||
من **`salesflow-saas/backend`**:
|
||||
|
||||
```bash
|
||||
py -3 -m pytest tests -q
|
||||
```
|
||||
|
||||
من **`salesflow-saas`** (موصى به):
|
||||
|
||||
```powershell
|
||||
.\verify-launch.ps1
|
||||
```
|
||||
|
||||
المرجع الكامل: [`salesflow-saas/docs/LAUNCH_CHECKLIST.md`](../salesflow-saas/docs/LAUNCH_CHECKLIST.md).
|
||||
|
||||
---
|
||||
|
||||
## 2) الخادم (API)
|
||||
|
||||
* نسخ البيئة: [`salesflow-saas/backend/.env.phase2.example`](../salesflow-saas/backend/.env.phase2.example) → `backend/.env` وملء الحقول حسب [`INTEGRATION_MASTER_AR.md`](../salesflow-saas/docs/INTEGRATION_MASTER_AR.md).
|
||||
* **PostgreSQL** للإنتاج (ليس SQLite الاعتماد الدائم) — انظر قسم قاعدة البيانات في قائمة الإطلاق.
|
||||
* التشغيل:
|
||||
|
||||
```bash
|
||||
cd salesflow-saas/backend
|
||||
py -3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
* فحص جاهزية التكامل التجاري:
|
||||
|
||||
```bash
|
||||
cd salesflow-saas
|
||||
py -3 scripts/check_go_live_gate.py
|
||||
```
|
||||
|
||||
توقع **403** مع `blocked_reasons` حتى اكتمال المتغيرات — هذا سلوك **بوابة** لا خللًا بالضرورة.
|
||||
|
||||
---
|
||||
|
||||
## 3) الواجهة (Next.js)
|
||||
|
||||
* [`salesflow-saas/frontend/.env.example`](../salesflow-saas/frontend/.env.example): `NEXT_PUBLIC_API_URL` يطابق أصل الـ API الفعلي (HTTPS).
|
||||
* الباكند: `FRONTEND_URL` و`CORS_EXTRA_ORIGINS` في الإعدادات — انظر [`LAUNCH_CHECKLIST.md`](../salesflow-saas/docs/LAUNCH_CHECKLIST.md) §3.
|
||||
|
||||
---
|
||||
|
||||
## 4) الأمن والوصول
|
||||
|
||||
* رموز داخلية / JWT حسب نموذجكم؛ لا تُخزَّن أسرار في الوثائق.
|
||||
* حدود معدل الطلبات (إن وُجدت) على مسارات الـ outreach عند التفعيل.
|
||||
|
||||
---
|
||||
|
||||
## 5) المراقبة والاسترجاع
|
||||
|
||||
* صحة: `GET /api/v1/health` و`GET /api/v1/ready`.
|
||||
* بعد أي تغيير على أسرار الطرف الثالث: إعادة `go-live-gate`.
|
||||
* سياسة التراجع: راجع [`salesflow-saas/memory/runbooks/production-deployment-guide.md`](../salesflow-saas/memory/runbooks/production-deployment-guide.md)؛ وإلا وثّقوا خطوة rollback (صورة سابقة + تعطيل flags).
|
||||
|
||||
---
|
||||
|
||||
## 6) تسليم للعميل (Handoff)
|
||||
|
||||
| المخرج | الوصف |
|
||||
|--------|--------|
|
||||
| قائمة متغيرات مملوءة | بدون قيم سرية في البريد — استخدم قنوات آمنة |
|
||||
| مستخدم إداري | بيانات الدخول عبر قناة آمنة |
|
||||
| مسار demo مسجّل | روابط + خطوات من [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) |
|
||||
| جهة اتصال دعم | SLA من الاتفاق |
|
||||
|
||||
---
|
||||
|
||||
## 7) بعد Go-Live
|
||||
|
||||
* [`salesflow-saas/docs/DEALIX_POST_LAUNCH_OPS_AR.md`](../salesflow-saas/docs/DEALIX_POST_LAUNCH_OPS_AR.md) إن وُجد.
|
||||
* إعادة فحص [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) لصف RC التالي.
|
||||
|
||||
---
|
||||
|
||||
*الدليل تقني؛ الالتزامات القانونية والتعاقدية مع العميل خارج نطاق هذا الملف.*
|
||||
21
docs/PR16_MERGE_RECONCILE_CHECKLIST.md
Normal file
21
docs/PR16_MERGE_RECONCILE_CHECKLIST.md
Normal file
@ -0,0 +1,21 @@
|
||||
# PR #16 merge reconcile checklist (Tier-1)
|
||||
|
||||
Use after merging [PR #16](https://github.com/VoXc2/system-prompts-and-models-of-ai-tools/pull/16) (`claude/dealix-tier1-completion-*`) into `main`.
|
||||
|
||||
## Goals
|
||||
|
||||
- **One** canonical copy for: operating constitution, Tier-1 closure lists, governance deep-dives.
|
||||
- No conflicting `MASTER_OPERATING_PROMPT.md` (root vs `salesflow-saas/`).
|
||||
- `scripts/architecture_brief.py` `CONSTITUTION_PATHS` lists only existing canonical files.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Compare `MASTER_OPERATING_PROMPT.md` (root) vs `salesflow-saas/MASTER_OPERATING_PROMPT.md` — pick one winner; delete or symlink the loser; update [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md).
|
||||
2. Compare `salesflow-saas/docs/tier1-master-closure-checklist.md` vs root [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) — keep EN + AR pair with a single status column owner.
|
||||
3. Re-run `python scripts/architecture_brief.py` and `python scripts/check_docs_links.py` from repo root.
|
||||
4. Re-run `Dealix CI` (pytest + OpenAPI verify + governance scripts).
|
||||
5. Update [`architecture-register.md`](architecture-register.md) if subsystem ownership moved.
|
||||
|
||||
## If you cannot merge yet
|
||||
|
||||
Keep PR #16 branch open; treat duplicate paths as **Shadow** per [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) until the merge completes.
|
||||
@ -18,6 +18,12 @@
|
||||
|
||||
**حالات مقترحة للعمود «الحالة»:** `OK` | `Risk` | `Blocked` — مع أعلى [`operational-severity-model.md`](governance/operational-severity-model.md) مفتوحة في الملاحظات.
|
||||
|
||||
## صف مرشح إصدار (نموذج — للتحقق الآلي `RELEASE_MATRIX_RC_ROW_REQUIRED`)
|
||||
|
||||
| البُعد | الحالة | الدليل | المالك |
|
||||
|--------|--------|--------|--------|
|
||||
| **RC-2026-W16-demo** | OK | تجميعي: الصفوف أعلاه + CI `docs-governance` / `Dealix CI` | Release |
|
||||
|
||||
## بوابة جودة البيانات (Great Expectations)
|
||||
|
||||
عند تفعيل GE: اربط **checkpoint** ناجحًا بصف «schema adherence» أو صف فرعي «data quality»؛ لا تعتبر GE مجرد ملحق Data plane — انظر [`ws5-connector-events-metrics.md`](ws5-connector-events-metrics.md).
|
||||
|
||||
@ -6,12 +6,23 @@
|
||||
|---------|---------------------------|-----------------|--------|----------------|
|
||||
| دستور التشغيل للوكلاء | [`MASTER_OPERATING_PROMPT.md`](../MASTER_OPERATING_PROMPT.md) | [`AGENTS.md`](../AGENTS.md)، [`CLAUDE.md`](../CLAUDE.md) (ملخصات) | Architect | عند تغيير حوكمة رئيسية |
|
||||
| إغلاق Tier-1 (عربي) | [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) | — | Program | كل أسبوعين مع السجل |
|
||||
| برنامج الإغلاق التشغيلي النهائي (AR) | [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md) | — | Program + Architect | عند تغيير معايير Tier-1 أو أدوات الموردين |
|
||||
| التحقق من إغلاق Tier-1 وما بعد الإغلاق (AR) | [`TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md`](TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md) | — | Program + Architect | مع تحديث بوابات الإصدار أو اختبارات الإغلاق الستة |
|
||||
| تفعيل الإنتاج Tier-1 (AR) | [`TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md`](TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md) | — | Program + Architect | بعد كل canary أو توسع Trust على endpoints حساسة |
|
||||
| Playbook إنتاج حقيقي (AR) | [`TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md`](TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md) | — | Program + Release | قبل كل RC / canary |
|
||||
| توسع الثقة على المسارات (AR) | [`TIER1_TRUST_EXPANSION_PLAN_AR.md`](TIER1_TRUST_EXPANSION_PLAN_AR.md) | — | Platform + Governance | مع كل مسار external جديد أو مراجعة A/R/S |
|
||||
| تفعيل إيراد Go-Live (AR) | [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) | — | Founder + Program | أسبوعيًا حتى أول عميل مدفوع ثم مع كل pilot |
|
||||
| أول 3 عملاء B2B (AR) | [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md) | — | Founder + Sales | أسبوعيًا حتى 3 pilots موقّعة |
|
||||
| دليل النشر الحي عند عميل (AR) | [`LIVE_DEPLOYMENT_GUIDE_AR.md`](LIVE_DEPLOYMENT_GUIDE_AR.md) | — | Platform + Release | مع كل pilot أو تغيير بيئة |
|
||||
| محرك إيراد آلي — حدود وتشغيل (AR) | [`AUTOMATED_REVENUE_ENGINE_AR.md`](AUTOMATED_REVENUE_ENGINE_AR.md) | — | Growth + Platform | عند تغيير سياسة outreach أو قناة inbound |
|
||||
| إغلاق Tier-1 (50 بندًا EN) | [`salesflow-saas/docs/tier1-master-closure-checklist.md`](../salesflow-saas/docs/tier1-master-closure-checklist.md) | — | Program | مع PR إغلاق |
|
||||
| سجل الأنظمة الفرعية | [`architecture-register.md`](architecture-register.md) | تكرار حالة في checklists طالما عمود واحد للحالة | Platform | أسبوعيًا |
|
||||
| مصفوفة التنفيذ | [`adr/0002-execution-matrix-canonical-source.md`](adr/0002-execution-matrix-canonical-source.md) + الملف الذي يحدده الـ ADR | نسخ قديمة بأسماء متعددة إن وُجدت | PMO | عند إعادة تسمية المصفوفة |
|
||||
| حوكمة الموصلات / Data plane | [`governance/connectors-and-data-plane.md`](governance/connectors-and-data-plane.md) | [`ws5-connector-events-metrics.md`](ws5-connector-events-metrics.md) (تفاصيل WS5) | Integrations | مع كل موصل جديد |
|
||||
| أحداث وعقود | [`governance/events-and-schema.md`](governance/events-and-schema.md) | حقول **CloudEvents** الخارجية — انظر الملحق أدناه | Platform | عند تغيير الحدث |
|
||||
| جاهزية الإصدار (RC) | [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) | — | Release | كل RC |
|
||||
| مسار ذهبي Tier-1 (Partner → Exec) | [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) | تفاصيل إضافية في `salesflow-saas/docs/governance/*` عند الحاجة | Program | مع كل تغيير في مسار Class B |
|
||||
| دمج [PR #16](https://github.com/VoXc2/system-prompts-and-models-of-ai-tools/pull/16) (فرع `claude/dealix-tier1-completion-*`) | [`PR16_MERGE_RECONCILE_CHECKLIST.md`](PR16_MERGE_RECONCILE_CHECKLIST.md) + بعد الدمج: **`MASTER_OPERATING_PROMPT` مصدر واحد** | الملفات المكررة داخل `salesflow-saas/` قبل الدمج = **Shadow** مؤقت | Release Captain | لمرة واحدة عند merge |
|
||||
|
||||
## ملحق: مراجع خارجية (تجمع هنا لتقليل rot)
|
||||
|
||||
|
||||
200
docs/TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md
Normal file
200
docs/TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md
Normal file
@ -0,0 +1,200 @@
|
||||
---
|
||||
version: "1.1"
|
||||
owner: "Program + Architect"
|
||||
status: "canonical"
|
||||
review_cadence: "مع تحديث بوابات الإصدار أو اختبارات الإغلاق الستة أو مرحلة ما بعد الإغلاق"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "FINAL_TIER1_CLOSURE_PROGRAM_AR.md"
|
||||
- "SOURCE_OF_TRUTH_INDEX.md"
|
||||
- "RELEASE_READINESS_MATRIX_AR.md"
|
||||
---
|
||||
|
||||
# التحقق من إغلاق Tier-1 وما بعد الإغلاق
|
||||
|
||||
أفضل طريقة تتأكد فيها أن **الإغلاق صار صحيح فعلًا** ليست بكثرة الملفات ولا بعدد الاختبارات فقط، بل بأن تجعل الإغلاق يمر عبر **بوابات إلزامية** واضحة: مخرجات مهيكلة، تنفيذ durable، موافقات قابلة للتدقيق، وrelease gate حقيقي. هذا هو الاتجاه الصحيح اليوم لأن OpenAI توصي باستخدام **Structured Outputs** بدل JSON mode عندما تحتاج التزامًا فعليًا بالـ schema، ولأن LangGraph يوفّر durable execution مع pause/resume وcheckpointer للمسارات الطويلة وHITL، ولأن GitHub يوفّر OIDC وartifact attestations لرفع ثقة التسليم وسلامة الـ provenance. ([OpenAI][1])
|
||||
|
||||
**مرافق إلزامي:** [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md) · [`TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md`](TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md) · [`TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md`](TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md) · [`TIER1_TRUST_EXPANSION_PLAN_AR.md`](TIER1_TRUST_EXPANSION_PLAN_AR.md) · [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) · [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) · [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) · [`references/tier1-external-index.md`](references/tier1-external-index.md)
|
||||
|
||||
---
|
||||
|
||||
## كيف تتأكد أن الإغلاق صحيح؟
|
||||
|
||||
ابدأ من قاعدة واحدة: **أي شيء غير مثبت بالأدلة ما يعتبر مقفلًا**.
|
||||
|
||||
هذا يعني أن كل بند Tier-1 يجب أن يملك 5 أشياء معًا: owner واضح، evidence واضح، gate واضح، exit criteria واضح، وحالة واحدة فقط من: current أو partial أو pilot أو production.
|
||||
|
||||
التأكد الحقيقي يكون عبر **6 اختبارات إغلاق**:
|
||||
|
||||
### 1) Truth test
|
||||
|
||||
هل عندك ملف واحد فقط يحدد الحقيقة الحالية لكل subsystem؟
|
||||
|
||||
إذا ما عندك ملف موحد مثل current-vs-target register أو source-of-truth index، فالإغلاق ناقص حتى لو كل شيء "موجود".
|
||||
|
||||
**في الريبو:** [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) و[`architecture-register.md`](architecture-register.md)؛ CI: `architecture_brief.py`، `check_docs_links.py`، `check_source_of_truth_index.py`.
|
||||
|
||||
### 2) Schema test
|
||||
|
||||
هل كل المخرجات الحرجة تمر بـ schema validation فعلية؟
|
||||
|
||||
إذا كان جوابك لا، فالإغلاق ناقص. Structured Outputs اليوم ليست تحسينًا تجميليًا؛ هي الطريقة الصحيحة لجعل `memo_json` و`approval_packet_json` و`execution_intent_json` قابلة للتشغيل آليًا بدل أن تبقى نصوصًا جميلة. ([OpenAI][1])
|
||||
|
||||
**في الريبو:** عقود [`structured_outputs.py`](../salesflow-saas/backend/app/schemas/structured_outputs.py) و`POST /api/v1/approval-center/validate-class-b-bundle` و`pytest` على المسارات الحرجة.
|
||||
|
||||
### 3) Workflow test
|
||||
|
||||
هل عندك مسار حي واحد على الأقل end-to-end يمر عبر القرار والموافقة والتنفيذ والأدلة والواجهة التنفيذية؟
|
||||
|
||||
إذا لا، فالمشروع ما زال في مرحلة "مرجعية قوية" وليس "Tier-1 تشغيلًا". LangGraph يوضح أن durable execution الحقيقي يحتاج checkpointer وthread identifiers وأن تكون الـ side effects داخل tasks لضمان الاستئناف الصحيح وعدم التكرار. ([docs.langchain.com][2])
|
||||
|
||||
**في الريبو:** [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) و`tests/test_tier1_golden_path_partner.py`.
|
||||
|
||||
### 4) Trust test
|
||||
|
||||
هل كل external commitment يرفض تلقائيًا إذا غاب `approval_packet` أو `evidence_pack` أو `correlation_id`؟
|
||||
|
||||
إذا لا، فطبقة الثقة لم تُغلق بعد.
|
||||
|
||||
**في الريبو:** [`decision_plane_contracts.py`](../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) ومسارات `approval_center`؛ سياسة التعارضات: `POST /api/v1/contradictions/` مع evidence عند V3/critical.
|
||||
|
||||
### 5) Release test
|
||||
|
||||
هل يوجد Release Readiness Matrix فعلي يوقف الإصدار إذا فشل docs truth أو schema pass أو contradiction gate أو provenance؟
|
||||
|
||||
إذا لا، فالإغلاق ناقص. GitHub OIDC مناسب للوصول الآمن المؤقت إلى السحابة بدل الأسرار الثابتة، وartifact attestations مناسبة لإثبات provenance، لكن يجب أن يكونا جزءًا من gate الفعلي لا مجرد توصية. ([GitHub Docs][3]) — تفاصيل الروابط في [`references/tier1-external-index.md`](references/tier1-external-index.md).
|
||||
|
||||
**في الريبو:** [`scripts/check_release_readiness_matrix.py`](../scripts/check_release_readiness_matrix.py) و[`.github/workflows/release-readiness-rc-gate.yml`](../.github/workflows/release-readiness-rc-gate.yml) و[`docs/governance/github-and-release.md`](governance/github-and-release.md).
|
||||
|
||||
### 6) Executive test
|
||||
|
||||
هل يوجد Executive Room حي يُستخدم فعلًا في مراجعة أسبوعية؟
|
||||
|
||||
إذا لا، فالإغلاق ما زال داخليًا تقنيًا، لا مؤسسيًا.
|
||||
|
||||
**في الريبو:** [`executive_room.py`](../salesflow-saas/backend/app/api/v1/executive_room.py) يغذّي `tier1_exec_surface` من `ExecWeeklyGovernanceContract.model_dump` المبني من مسار الـ demo إلى حين خدمة أسبوعية كاملة.
|
||||
|
||||
---
|
||||
|
||||
## كيف تبدأ "من جد" وبأفضل طريقة؟
|
||||
|
||||
ابدأ بهذا الترتيب فقط، ولا تكسره.
|
||||
|
||||
### المرحلة 1: ثبّت الحقيقة
|
||||
|
||||
أول أسبوع يجب أن يكون كله لإغلاق الحقيقة التشغيلية:
|
||||
|
||||
* ثبّت [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md) كمرجع نهائي.
|
||||
* ثبّت [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md).
|
||||
* ثبّت current/target register (مثل [`architecture-register.md`](architecture-register.md) حيث ينطبق).
|
||||
* اجعل `architecture_brief.py` و`check_docs_links.py` وفحوص glossary/source-of-truth ضمن CI الإلزامي (انظر [`.github/workflows/docs-governance.yml`](../.github/workflows/docs-governance.yml)).
|
||||
|
||||
هذه الخطوة هي الأساس، لأن أي توسع قبلها سيعيد الفوضى.
|
||||
|
||||
### المرحلة 2: أغلق مسارًا حيًا واحدًا
|
||||
|
||||
أفضل مسار الآن هو:
|
||||
|
||||
**Partner intake → Partner dossier → Economics model → Approval packet → Approval Center → Workflow commitment → Evidence pack → Executive weekly summary**
|
||||
|
||||
هذا المسار هو أفضل مسار Tier-1 لأنه يثبت:
|
||||
|
||||
* Structured Outputs
|
||||
* HITL
|
||||
* durable state
|
||||
* evidence pack
|
||||
* executive visibility
|
||||
|
||||
ويظهر قيمة سريعة بدون تعقيد M&A الكامل. ([OpenAI][1])
|
||||
|
||||
### المرحلة 3: اربط الحوكمة بالإطلاق
|
||||
|
||||
بعد المسار الحي، فعّل Release Gate:
|
||||
|
||||
* لا RC صالح بلا Release Readiness Matrix
|
||||
* لا RC صالح مع contradiction V3 مفتوح
|
||||
* لا RC صالح بلا executive signoff لمسار حي
|
||||
* لا RC صالح بلا provenance path حيث تسمح الخطة والمنصة
|
||||
|
||||
هذا هو الفارق بين "النظام يعمل" و"النظام صالح للإطلاق المؤسسي". ([GitHub Docs][3])
|
||||
|
||||
### المرحلة 4: فعّل مسار سعودي حساس واحد
|
||||
|
||||
اختر workflow واحد فقط:
|
||||
|
||||
* مشاركة بيانات شريك
|
||||
* عرض خارجي يحوي بيانات شركة/أشخاص
|
||||
* ingestion لوثائق DD
|
||||
|
||||
ثم اربطه بـ:
|
||||
|
||||
* PDPL classification
|
||||
* NCA/ECC owner
|
||||
* NIST GenAI overlay
|
||||
* OWASP mapping
|
||||
* retention/export rules
|
||||
|
||||
هنا تتحول الجاهزية السعودية من وثيقة قوية إلى control حي.
|
||||
|
||||
**مرجع مصفوفة:** [`governance/pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md).
|
||||
|
||||
---
|
||||
|
||||
## كيف ترسم ما بعد الإغلاق؟
|
||||
|
||||
بعد ما تتأكد أن الإغلاق تم، لا تبني roadmap على شكل features.
|
||||
ابنه على شكل **4 طبقات**:
|
||||
|
||||
**1) Assurance**
|
||||
truth، CI، evidence، release gates
|
||||
|
||||
**2) Live operating surfaces**
|
||||
Executive Room، Approval Center، Evidence Viewer، Actual vs Forecast
|
||||
|
||||
**3) Durable commitments**
|
||||
partner approvals، signatures، DD orchestration، launches، PMI
|
||||
|
||||
**4) Market dominance**
|
||||
packaging، pricing، Saudi/GCC compliance narrative، enterprise rollout
|
||||
|
||||
هذا أفضل رسم لأن السوق اليوم يكافئ المنصات التي تدمج الذكاء داخل العمل الحقيقي وتضبط المخاطر والحوكمة، لا المنصات التي "تبدو ذكية" فقط. ([OpenAI][1])
|
||||
|
||||
---
|
||||
|
||||
## تعريف "كل شيء مقفل"
|
||||
|
||||
لا تعتبر النظام مقفلًا بالكامل إلا إذا تحقق هذا معًا:
|
||||
|
||||
* كل output حرج schema-bound
|
||||
* كل external commitment يمر عبر approval + evidence + correlation
|
||||
* عندك live path واحد كامل end-to-end
|
||||
* CI يحرس docs/scripts/contracts
|
||||
* Executive Room حي ويُستخدم أسبوعيًا
|
||||
* Release Matrix توقف الإطلاق فعلًا
|
||||
* مسار سعودي حساس واحد mapped ومفعل
|
||||
* لا يوجد overclaim بين docs والكود والحالة التشغيلية
|
||||
|
||||
إذا تحققت هذه الثمانية، فأنت لم تعد "قريبًا من Tier-1" — أنت **دخلت Tier-1 تشغيلًا**.
|
||||
|
||||
---
|
||||
|
||||
## القرار العملي الآن
|
||||
|
||||
إذا تبي **أفضل بداية حقيقية** من هذه اللحظة، فابدأ بهذا الترتيب اليوم:
|
||||
|
||||
1. شغّل truth pass على كل docs/gates.
|
||||
2. فعّل CI على docs/scripts/contracts.
|
||||
3. أغلق المسار الذهبي للشراكات end-to-end.
|
||||
4. فعّل Executive Room من `ExecWeeklyGovernanceContract` كمصدر وحيد.
|
||||
5. اربط Release Readiness Matrix بالـ PR/RC فعليًا.
|
||||
6. فعّل workflow سعودي حساس واحد بالكامل.
|
||||
|
||||
هذا هو أقصر طريق واقعي للإغلاق الصحيح، وليس مجرد "إكمال ملفات".
|
||||
|
||||
---
|
||||
|
||||
## المراجع
|
||||
|
||||
[1]: https://openai.com/index/introducing-structured-outputs-in-the-api/ "Introducing Structured Outputs in the API | OpenAI"
|
||||
[2]: https://docs.langchain.com/oss/javascript/langgraph/durable-execution "Durable execution - Docs by LangChain"
|
||||
[3]: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect "OpenID Connect in GitHub Actions | GitHub Docs"
|
||||
@ -160,4 +160,22 @@
|
||||
|
||||
---
|
||||
|
||||
## §16 تعريف إغلاق Tier-1 الكامل (DoD — قابل للقياس)
|
||||
|
||||
يُعتبر **Tier-1 مغلقًا تشغيليًا** عند اكتمال الدليل لكل بند أدناه (PR، اختبار، أو صف في المصفوفة):
|
||||
|
||||
| # | البند | الدليل في الريبو | CI / اختبار |
|
||||
|---|--------|------------------|--------------|
|
||||
| 16.1 | مصدر الحقيقة محدّث | [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) | مراجعة يدوية + عدم وجود Shadow حرج بلا مالك |
|
||||
| 16.2 | صف مرشح إصدار (RC) | [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) | اختياري: `RELEASE_MATRIX_RC_ROW_REQUIRED=1` + [`scripts/check_release_readiness_matrix.py`](../scripts/check_release_readiness_matrix.py) |
|
||||
| 16.3 | لا ادّعاء prod زائد | [`salesflow-saas/docs/governance/document-consistency-audit.md`](../salesflow-saas/docs/governance/document-consistency-audit.md) | Job **`no_overclaim`** في [`.github/workflows/docs-governance.yml`](../.github/workflows/docs-governance.yml) و[`dealix-ci.yml`](../.github/workflows/dealix-ci.yml) عبر [`scripts/check_no_overclaim.py`](../scripts/check_no_overclaim.py) |
|
||||
| 16.4 | روابط وجود ملفات دستور | [`scripts/architecture_brief.py`](../scripts/architecture_brief.py) | Job **`architecture_brief`** في `docs-governance` |
|
||||
| 16.5 | روابط Markdown نسبية | [`scripts/check_docs_links.py`](../scripts/check_docs_links.py) | Job **`docs_links`** في `docs-governance` |
|
||||
| 16.6 | Go-live gate | [`salesflow-saas/scripts/check_go_live_gate.py`](../salesflow-saas/scripts/check_go_live_gate.py) | **`DEALIX_CI_FAIL_ON_GO_LIVE=1`** في `dealix-ci` (فشل عند `launch_allowed≠true`) |
|
||||
| 16.7 | لا إصدار مع V3 مفتوحة | [`governance/operational-severity-model.md`](governance/operational-severity-model.md) | مراجعة يدوية + تدقيق تناقضات |
|
||||
| 16.8 | مسار ذهبي حي | [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) | `pytest` **`test_tier1_golden_path_partner`** |
|
||||
| 16.9 | برنامج الإغلاق التشغيلي النهائي (AR) | [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md) | مضمّن في [`scripts/architecture_brief.py`](../scripts/architecture_brief.py) `CONSTITUTION_PATHS` + مراجعة Program/Architect عند تغيير المعايير |
|
||||
|
||||
---
|
||||
|
||||
*آخر تحديث: يُحدَّث مع كل إصدار يغيّر الحوكمة أو مسارات Class B.*
|
||||
|
||||
218
docs/TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md
Normal file
218
docs/TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md
Normal file
@ -0,0 +1,218 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Program + Architect"
|
||||
status: "canonical"
|
||||
review_cadence: "بعد كل محاولة إطلاق canary أو توسع Trust على endpoints حساسة"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "FINAL_TIER1_CLOSURE_PROGRAM_AR.md"
|
||||
- "TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md"
|
||||
- "RELEASE_READINESS_MATRIX_AR.md"
|
||||
---
|
||||
|
||||
# TIER-1 Production Activation Program
|
||||
|
||||
بعد بناء **Verified System** (وثائق + عقود + CI + مسار ذهبي)، تبقى الفجوة إلى **Production-Proven Sovereign System**: ليس قياس الإغلاق بعدد الملفات أو الاختبارات فقط، بل **هل النظام يعمل في الواقع دون انهيار؟** وهل جاهزية الإصدار **confidence قائم على أدلة** لا «إكمال مهام»؟ ([tqsystems.io][1])
|
||||
|
||||
**مرافق إلزامي:** [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md) · [`TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md`](TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md) · [`TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md`](TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md) · [`TIER1_TRUST_EXPANSION_PLAN_AR.md`](TIER1_TRUST_EXPANSION_PLAN_AR.md) · [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) · [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) · [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md)
|
||||
|
||||
---
|
||||
|
||||
## موقعك الآن
|
||||
|
||||
* **Verified System:** مرجعية، بوابات، CI، ومسار مهيكل مثبت في الكود.
|
||||
* **Production-Proven:** نفس المسارات تعمل **تحت ضغط**، مع مراقبة واسترجاع، واعتماد تنفيذي حقيقي.
|
||||
|
||||
الفرق غالبًا في **آخر نسبة صغيرة من العمل** لكنها تحمل أغلب مخاطر الفشل في الإنتاج.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 1: Real System Validation (الأهم)
|
||||
|
||||
### الهدف
|
||||
|
||||
إثبات أن النظام يعمل end-to-end **بدون تدخل ترقيعي** (بدون bypass يدوي، بدون patch مؤقت يُنسى).
|
||||
|
||||
### ماذا تفعل
|
||||
|
||||
شغّل **Golden Path حقيقي** (ليس demo فقط عندما ينضج المنتج):
|
||||
|
||||
`Partner intake → scoring → dossier → approval → execution → evidence → executive`
|
||||
|
||||
### معايير النجاح
|
||||
|
||||
* استجابات API حقيقية ومتسقة مع العقود.
|
||||
* Evidence pack كامل مع مصادر قابلة للتدقيق.
|
||||
* سجل موافقة (approve/edit/reject) واضح.
|
||||
* **Trace / correlation** عبر الطبقات (انظر [`governance/trust-fabric.md`](governance/trust-fabric.md)).
|
||||
|
||||
**في الريبو اليوم:** [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) و`tests/test_tier1_golden_path_partner.py` — توسيع التشغيل «الحقيقي» يعني بيئة بيانات ومزودين مضبوطين وليس اختبار ASGI فقط.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 2: Chaos Testing (اختبار الكسر)
|
||||
|
||||
### الفكرة
|
||||
|
||||
أي نظام يُفترض Tier-1 ينبغي أن **يُختبر على الفشل** قبل الثقة به في الإنتاج.
|
||||
|
||||
### سيناريوهات مقترحة
|
||||
|
||||
* موافقة مفقودة أو bundle غير صالح.
|
||||
* Evidence ناقص أو `correlation_id` فارغ.
|
||||
* فشل موصل / timeout في مسار workflow.
|
||||
* تنفيذ مكرر (idempotency).
|
||||
* تناقض بيانات أو حالة وسيطة غير متوقعة.
|
||||
|
||||
### ما الذي تتوقعه
|
||||
|
||||
* **إيقاف آمن** أو تعويض مسموح به سياسيًا، أو **خطأ تشغيلي واضح** قابل للرصد — لا سلوك صامت.
|
||||
|
||||
الأنظمة تفشل غالبًا من **تفاصيل صغيرة مهملة** لا من أخطاء كبيرة ظاهرة. ([DECODE][2])
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 3: Production Simulation
|
||||
|
||||
### ماذا تفعل
|
||||
|
||||
* بيئة staging قريبة من prod قدر الإمكان.
|
||||
* حركة مرور محدودة (حقيقية أو mock واقعي) عبر المسارات الحرجة.
|
||||
|
||||
### ماذا تتحقق
|
||||
|
||||
* SLA واضحة (موافقات، زمن استجابة، حدود إعادة المحاولة).
|
||||
* سجلات واضحة وربط مع OpenTelemetry حيث ينطبق.
|
||||
* تنبيهات على الفشل الحرج.
|
||||
* **Rollback** واضح ومجرّب (انظر [`governance/github-and-release.md`](governance/github-and-release.md)).
|
||||
|
||||
جاهزية الإنتاج تعتمد على المراقبة، الاسترجاع، وفرض SLA — وليس على «نجاح الاختبار الوحيد». ([TechTarget][3])
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 4: Executive Reality Check
|
||||
|
||||
### الهدف
|
||||
|
||||
التأكد أن سطح التنفيذ **قابل للاعتماد القراري** وليس تقنيًا فقط.
|
||||
|
||||
### ماذا تفعل
|
||||
|
||||
عرض مباشر (حتى لو جلسة مصغّرة) لـ:
|
||||
|
||||
* Executive Room / الملخص الأسبوعي.
|
||||
* القرار المعلق والأدلة والموافقات.
|
||||
|
||||
### أسئلة حاسمة
|
||||
|
||||
* هل يمكن الاعتماد على هذا القرار في اجتماع حقيقي؟
|
||||
|
||||
إذا «لا أفهم» → مشكلة عرض/تجربة.
|
||||
إذا «لا أثق» → مشكلة ثقة/أدلة.
|
||||
إذا «ناقص بيانات» → مشكلة بيانات/مسار.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 5: Trust Hardening النهائي
|
||||
|
||||
### الهدف
|
||||
|
||||
توسيع **enforcement وقت التشغيل** على كل ما هو `external_*` أو تكامل حساس.
|
||||
|
||||
### ماذا تتحقق
|
||||
|
||||
* موافقة إلزامية حيث السياسة تقتضي ذلك.
|
||||
* Evidence إلزامي حيث السياسة تقتضي ذلك.
|
||||
* Correlation / trace إلزامي للالتزامات الخارجية.
|
||||
|
||||
الحوكمة الحقيقية هي **تنفيذ وقت التشغيل** لا وصف في وثيقة. ([logiciel.io][4])
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 6: Saudi Reality Activation
|
||||
|
||||
### الهدف
|
||||
|
||||
تحويل الامتثال إلى **ضوابط تشغيلية** على مسار حي واحد.
|
||||
|
||||
### مثال مسار
|
||||
|
||||
مشاركة بيانات شريك → ربط بـ:
|
||||
|
||||
* تصنيف PDPL.
|
||||
* سياسة احتفاظ وتدقيق وصول.
|
||||
* سجل تدقيق.
|
||||
|
||||
الامتثال المؤسسي: **ضوابط تشغيلية** لا مجرد policy docs. ([seisan.com][5])
|
||||
|
||||
**مرجع:** [`governance/pdpl-nca-ai-control-matrices.md`](governance/pdpl-nca-ai-control-matrices.md).
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 7: Real Release
|
||||
|
||||
### ماذا تفعل
|
||||
|
||||
* PR مصنّف `release-candidate` حيث تطبق السياسة.
|
||||
* Release Readiness Matrix بحالة **PASS** للأبعاد المطلوبة.
|
||||
* CI أخضر بما في ذلك بوابات الحوكمة ذات الصلة.
|
||||
* موافقة تنفيذية على مسار حي.
|
||||
|
||||
ثم: **canary** → مراقبة → **rollback جاهز**.
|
||||
|
||||
الإطلاق الصحيح يعتمد على إشارات الجاهزية، أمان التدرج، وجاهزية الاسترجاع. ([tqsystems.io][1])
|
||||
|
||||
---
|
||||
|
||||
## اختبار الحقيقة (قبل ادعاء Production)
|
||||
|
||||
1. هل تستطيع تشغيل صفقة شراكة كاملة **بدون تعديل يدوي**؟
|
||||
2. هل يُوقف أي قرار **بدون** موافقة حيث يلزم؟
|
||||
3. هل يمكن إعادة بناء evidence pack **من الصفر** من نفس المصادر؟
|
||||
4. هل القرار **قابل للتتبع** (trace/correlation)؟
|
||||
5. هل يمكن **الرجوع** إذا فشل الإطلاق؟
|
||||
6. هل الإدارة **تعتمد** القرار المعروض؟
|
||||
|
||||
إذا كانت الإجابة «نعم» على الستة مع تعريف واضح لكل «نعم» — عندها يمكن اعتبار النظام **Tier-1 Production** بحسب هذا البرنامج.
|
||||
|
||||
---
|
||||
|
||||
## ملاحظة على ادعاء «الجاهزية»
|
||||
|
||||
خطأ شائع: «نظامنا جاهز لأنه اجتاز الاختبارات».
|
||||
|
||||
الواقع: أنظمة enterprise تفشل غالبًا بسبب:
|
||||
|
||||
* تنفيذ غير durable،
|
||||
* حوكمة غير enforced،
|
||||
* بيانات غير موثوقة،
|
||||
* أو واجهة غير usable للقرار.
|
||||
|
||||
الأساس التنظيمي والتشغيلي أهم من «قوة النموذج» وحدها. ([sapinsider.org][6])
|
||||
|
||||
---
|
||||
|
||||
## الخلاصة
|
||||
|
||||
ما سبق يكمّل ما بنيتَه: foundation قوي، ربط docs + code + CI، ومسار ذهبي.
|
||||
|
||||
الإغلاق الإنتاجي يحتاج بالترتيب العملي:
|
||||
|
||||
1. تشغيل مسار حي حقيقي.
|
||||
2. كسره (chaos) ومعالجة الثغرات.
|
||||
3. إعادة تشغيله بعد الإصلاح.
|
||||
4. عرضه على الإدارة.
|
||||
5. إطلاق canary مع مراقبة واسترجاع.
|
||||
|
||||
**توسيع لاحق (اختياري):** تحويل هذا الملف إلى **Real Production Playbook** (خطوات زمنية + أوامر + مخرجات متوقعة)، أو **Trust Expansion Plan** لتغطية endpoints حساسة بدون انفجار التعقيد — يُفضّل فتح مهمة منفصلة لتحديد النطاق (بيئة، tenants، قائمة endpoints).
|
||||
|
||||
---
|
||||
|
||||
## المراجع
|
||||
|
||||
[1]: https://www.tqsystems.io/blog/release-readiness-checklist "Release Readiness Checklist (A Practical Go/No-Go Framework) | TQ Systems"
|
||||
[2]: https://decode.agency/article/software-release-checklists/ "Software release checklists | DECODE agency"
|
||||
[3]: https://www.techtarget.com/searchsoftwarequality/tip/A-production-readiness-checklist-for-software-development "A production readiness checklist for software development | TechTarget"
|
||||
[4]: https://logiciel.io/blog/ai-accountability-cto-readiness-checklist "Designing AI Systems for Accountability | logiciel.io"
|
||||
[5]: https://seisan.com/enterprise-app-readiness/ "Enterprise App Readiness | Seisan"
|
||||
[6]: https://sapinsider.org/articles/2026-sap-ai-readiness-checklist/ "SAP AI Readiness Checklist | SAPinsider"
|
||||
187
docs/TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md
Normal file
187
docs/TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md
Normal file
@ -0,0 +1,187 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Program + Release"
|
||||
status: "canonical"
|
||||
review_cadence: "قبل كل RC أو بعد كل canary"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "golden-path-partner-intake-runbook.md"
|
||||
- "TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md"
|
||||
- "RELEASE_READINESS_MATRIX_AR.md"
|
||||
---
|
||||
|
||||
# Real Production Playbook (من التحقق إلى إطلاق)
|
||||
|
||||
Playbook تنفيذي **ساعة بساعة (كمقاطع عمل)** من حالة «Verified» إلى **إطلاق مدعوم بأدلة**، مع الاعتماد على ممارسات جاهزية الإنتاج (اختبار، أداء، أمن، تدرج، استرجاع). ([TechTarget][1])
|
||||
|
||||
**مرجع المسار الفعلي في الكود:** [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) — أي خطوة هنا تتبع نفس التسلسل حيث ينطبق.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Preflight (30–60 دقيقة)
|
||||
|
||||
### الهدف
|
||||
|
||||
التأكد أن البيئة **قابلة للتشغيل** قبل أي «تشغيل حي» طويل.
|
||||
|
||||
### أوامر (من جذر الريبو)
|
||||
|
||||
```bash
|
||||
python scripts/architecture_brief.py
|
||||
python scripts/check_docs_links.py
|
||||
```
|
||||
|
||||
### أوامر الاختبار (من `salesflow-saas/backend`)
|
||||
|
||||
```bash
|
||||
cd salesflow-saas/backend
|
||||
python -m pytest tests -q
|
||||
```
|
||||
|
||||
### Exit
|
||||
|
||||
* كل ما سبق **PASS**؛ أي فشل → **أوقف** ولا تكمل المراحل التالية حتى الإصلاح.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Golden Path Run (أول تشغيل حي)
|
||||
|
||||
### الهدف
|
||||
|
||||
تشغيل **المسار الذهبي** كما هو موثّق في الـ API الحالي (v1 demo-backed حيث ينطبق).
|
||||
|
||||
### تسلسل HTTP (انظر الـ runbook للتفاصيل والأجسام)
|
||||
|
||||
| الخطوة | الطلب |
|
||||
|--------|--------|
|
||||
| 1 | `GET /api/v1/approval-center/class-b-decision-bundle` |
|
||||
| 2 | `POST /api/v1/approval-center/validate-class-b-bundle` (body = ناتج 1) |
|
||||
| 3 | `POST /api/v1/approval-center/{approval_id}/approve` مع `hitl` + `decision_bundle` |
|
||||
| 4 | `GET /api/v1/executive-room/snapshot` |
|
||||
| 5 | `GET /api/v1/evidence-packs/tier1-demo` |
|
||||
| 6 | `GET /api/v1/connectors/governance` |
|
||||
| 7 | `POST /api/v1/proposals/{id}/send` (مسار سعودي حساس عند `external_company_contacts`) |
|
||||
|
||||
### مخرجات متوقعة (مستوى العقود)
|
||||
|
||||
* حزمة Class B تمر `validate` مع `correlation_id` سليم.
|
||||
* `tier1_exec_surface` يطابق `ExecWeeklyGovernanceContract` (حقول `changes_summary`, `pending_decisions`, `provenance.trace_id`, …).
|
||||
* Evidence وconnector governance يعيدان حقولًا مهيكلة وليس نصًا حرًا فقط.
|
||||
|
||||
### Exit
|
||||
|
||||
* **لا** تعديل يدوي على JSON لتجاوز الفشل.
|
||||
* **لا** حقول ناقطة حرجة في المسار المختبر.
|
||||
* **لا** bypass للموافقة حيث السياسة تفرض الحزمة.
|
||||
|
||||
> ملاحظة: مسارات مثل `POST /api/v1/partners/intake` **ليست** جزءًا من المسار الذهبي الموثّق اليوم؛ أي توسيع لاحق يحدّث الـ runbook أولًا ثم هذا الـ Playbook.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Trace + Evidence Validation
|
||||
|
||||
### الهدف
|
||||
|
||||
التأكد أن **التتبع والأدلة** متصلان بالقرار.
|
||||
|
||||
### تحقق يدوي / عبر اختبار
|
||||
|
||||
* `execution_intent_json.correlation_id` موجود وغير فارغ للمسارات الخارجية.
|
||||
* `provenance.trace_id` في `ExecWeeklyGovernanceContract` يطابق مسار الـ bundle عند الـ demo.
|
||||
* فشل متعمد (مثلاً `correlation_id` فارغ مع `external_*`) → **422** كما في الـ runbook.
|
||||
|
||||
### أتمتة
|
||||
|
||||
```bash
|
||||
cd salesflow-saas/backend
|
||||
python -m pytest tests/test_tier1_golden_path_partner.py -q
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Chaos Test (كسر النظام)
|
||||
|
||||
### الهدف
|
||||
|
||||
إثبات السلوك عند **غير المسار السعيد**.
|
||||
|
||||
| الحالة | المتوقع (مبدأيًا) |
|
||||
|--------|---------------------|
|
||||
| بدون موافقة / bundle غير صالح | رفض (`422` / 4xx حسب المسار) |
|
||||
| Evidence ناقص حيث يلزم | فشل صريح |
|
||||
| فشل موصل | إعادة محاولة / تنبيه (حسب تنفيذ الموصل) |
|
||||
| تكرار طلب بنفس المفتاح | سلوك idempotent حيث عُرّف |
|
||||
| timeout في workflow طويل | استئناف / checkpoint (LangGraph حيث ينطبق) |
|
||||
|
||||
> فشل الإنتاج غالبًا من **حالات الحافة** لا من المسار السعيد وحده. ([TechTarget][1])
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Production Simulation
|
||||
|
||||
### الهدف
|
||||
|
||||
ضغط خفيف على بيئة **شبيهة بالإنتاج**.
|
||||
|
||||
### أنشطة
|
||||
|
||||
* محاذاة إعدادات staging مع prod (متغيرات، حدود، flags).
|
||||
* اختبار حمل **محدود** (10–50 مستخدمًا متزامنًا أو ما يعادله) على المسارات الحرجة فقط.
|
||||
|
||||
### تحقق
|
||||
|
||||
* زمن استجابة ضمن هدف الفريق.
|
||||
* لا انهيار عملية؛ سجلات واضحة؛ تتبع (traces) عند التفعيل.
|
||||
* قنوات تنبيه للأخطاء الحرجة.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Executive Test
|
||||
|
||||
### الطلب
|
||||
|
||||
`GET /api/v1/executive-room/snapshot`
|
||||
|
||||
### تحقق
|
||||
|
||||
* حقول العقد الأسبوعي ظاهرة للقارئ التنفيذي: `changes_summary`, `pending_decisions`, `blockers_summary`, `at_risk_items`, `next_best_actions`.
|
||||
|
||||
### سؤال قرار
|
||||
|
||||
هل يمكن لصاحب قرار أن **يعتمد** ما يُعرض بدون شرح تقني طويل؟
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Release Candidate
|
||||
|
||||
### فروع ووسوم
|
||||
|
||||
* فرع إصدار (مثال): `release/tier1-…` حسب اتفاق الفريق.
|
||||
* على PR: تسمية **`release-candidate`** حيث تُفعّل السياسة.
|
||||
|
||||
### CI صارم للمصفوفة
|
||||
|
||||
```bash
|
||||
RELEASE_MATRIX_RC_ROW_REQUIRED=1 python scripts/check_release_readiness_matrix.py
|
||||
```
|
||||
|
||||
(يُشغّل تلقائيًا عبر [`.github/workflows/release-readiness-rc-gate.yml`](../.github/workflows/release-readiness-rc-gate.yml) عند الشروط الموثّقة في [`governance/github-and-release.md`](governance/github-and-release.md).)
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Canary Release
|
||||
|
||||
* توجيه **5–10%** من الحركة (أو tenants canary) نحو الإصدار الجديد.
|
||||
* مراقبة: أخطاء، زمن، SLA موافقات، طابور تعارضات إن وُجد.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Full Production
|
||||
|
||||
* عند استقرار المؤشرات: توسيع التدرج إلى **100%** مع بقاء خطة **rollback** جاهزة.
|
||||
|
||||
---
|
||||
|
||||
## المراجع
|
||||
|
||||
[1]: https://www.techtarget.com/searchsoftwarequality/tip/A-production-readiness-checklist-for-software-development "A production readiness checklist for software development | TechTarget"
|
||||
153
docs/TIER1_TRUST_EXPANSION_PLAN_AR.md
Normal file
153
docs/TIER1_TRUST_EXPANSION_PLAN_AR.md
Normal file
@ -0,0 +1,153 @@
|
||||
---
|
||||
version: "1.0"
|
||||
owner: "Platform + Governance"
|
||||
status: "canonical"
|
||||
review_cadence: "مع كل توسع لمسارات external أو موصلات جديدة"
|
||||
last_updated: "2026-04-16"
|
||||
related:
|
||||
- "governance/approval-policy.md"
|
||||
- "trust/ledger-vs-tool-verification.md"
|
||||
- "TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md"
|
||||
---
|
||||
|
||||
# Trust Expansion Plan (تغطية شاملة للثقة)
|
||||
|
||||
هدف البرنامج: أن تصبح المسارات الحساسة **policy-enforced** و**evidence-backed** بشكل يمكن تدقيقه، دون «تضخيم تعقيدي» يعطل التسليم.
|
||||
|
||||
> الأنظمة لا تفشل لغياب الذكاء فقط؛ تفشل بغياب **enforcement**، وتنفيذ ضعيف، أو ملاحظة ضعيفة. ([Seisan][2])
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 1 — Endpoint Inventory
|
||||
|
||||
### الهدف
|
||||
|
||||
قائمة **شاملة** لمسارات HTTP المعروضة من التطبيق.
|
||||
|
||||
### أداة مقترحة (من جذر الريبو)
|
||||
|
||||
```bash
|
||||
rg "@router\\.(get|post|put|delete|patch)" salesflow-saas/backend/app/api -n
|
||||
```
|
||||
|
||||
(على Windows يمكن استخدام `rg` من [ripgrep](https://github.com/BurntSushi/ripgrep) أو بحث المحرّر بنفس النمط.)
|
||||
|
||||
### تصنيف أولي (مثال)
|
||||
|
||||
| النوع | معنى تشغيلي | مثال نمطي |
|
||||
|--------|-------------|-----------|
|
||||
| internal | قراءة/داخلية، أثر محدود | صحة، لوحات داخلية |
|
||||
| external | أثر خارجي أو بيانات عميل | إرسال، توقيع، دفع |
|
||||
| critical | أثر مالي/تنظيمي عالٍ | عروض حساسة، M&A عند التفعيل |
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 2 — Classification (A / R / S)
|
||||
|
||||
لكل مسار **حساس**، عيّن وفق [`governance/approval-policy.md`](governance/approval-policy.md):
|
||||
|
||||
* `approval_class` (A0–A4 أو ما يعادلها في عقودكم)
|
||||
* `reversibility` (R0–R3)
|
||||
* `sensitivity` (S0–S3)
|
||||
|
||||
سجّل النتيجة في جدول (داخل الريبو أو أداة إدارة) مع **مالك** وتاريخ المراجعة.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 3 — Enforcement Layer
|
||||
|
||||
### مبدأ
|
||||
|
||||
على الحدود `external_*` (أو ما يعادلها في الكود):
|
||||
|
||||
* طلب موافقة / حزمة قرار حيث السياسة تقتضي.
|
||||
* evidence pack حيث السياسة تقتضي.
|
||||
* `correlation_id` / `trace_id` حيث السياسة تقتضي.
|
||||
|
||||
### في الكود اليوم
|
||||
|
||||
مرجع التنفيذ: [`decision_plane_contracts.py`](../salesflow-saas/backend/app/services/core_os/decision_plane_contracts.py) ومسارات [`approval_center.py`](../salesflow-saas/backend/app/api/v1/approval_center.py).
|
||||
|
||||
التوسيع = **تطبيق نفس الأنماط** على كل مسار صُنّف external/critical بعد المراجعة.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 4 — Tool Verification
|
||||
|
||||
### هدف
|
||||
|
||||
ربط نتيجة الأداة بما يُخزَّن في السجل/الدليل (حيث ينطبق [`trust/ledger-vs-tool-verification.md`](trust/ledger-vs-tool-verification.md)).
|
||||
|
||||
### حقول مفاهيمية (هدف تصميمي)
|
||||
|
||||
* `intended_action` / `actual_action` / `result` / `side_effects` / معرّف تكاملي (hash أو proof id) حيث تدعم المنصة.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 5 — Contradiction Engine (تغطية منطقية)
|
||||
|
||||
### مقارنات يجب أن تبقى قابلة للمراجعة
|
||||
|
||||
| المصدر | مقابل |
|
||||
|--------|--------|
|
||||
| memo / قرار | ما نُفِّذ فعليًا |
|
||||
| نتيجة أداة | حالة DB أو سجل |
|
||||
| موافقة | إجراء تم على المسار |
|
||||
|
||||
**API مرجعي:** `POST /api/v1/contradictions/` (مع evidence عند severity حرجة — انظر الاختبارات الحالية).
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 6 — Coverage Test (هدف أتمتة)
|
||||
|
||||
### حالة الريبو
|
||||
|
||||
* اختبار شامّل باسم `test_trust_enforcement_all_routes.py` **غير موجود بعد** كـ«100% endpoints» — يُستهدف تدريجيًا (ابدأ بالمسارات `external_*` والمسار الذهبي).
|
||||
|
||||
### حتى ذلك الحين
|
||||
|
||||
* وسّع `pytest` على المسارات التي تلمس `external_*` والـ Class B (مثل [`test_proposals_saudi_send_validation.py`](../salesflow-saas/backend/tests/test_proposals_saudi_send_validation.py) و[`test_tier1_golden_path_partner.py`](../salesflow-saas/backend/tests/test_tier1_golden_path_partner.py)).
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 7 — Policy Stress Test
|
||||
|
||||
سيناريوهات:
|
||||
|
||||
* محاولة override لسياسة.
|
||||
* سياسة مفقودة أو role خاطئ.
|
||||
* رمز منتهٍ / غير مصرّح.
|
||||
|
||||
المتوقع: **رفض واضح** + سجل تدقيق، لا سلوك صامت.
|
||||
|
||||
---
|
||||
|
||||
## المرحلة 8 — Audit Proof
|
||||
|
||||
لكل إجراء حرج يجب أن يبقى أثر يمكن تسليمه للتدقيق:
|
||||
|
||||
* سجل موافقة.
|
||||
* evidence pack (أو مرجع pack id).
|
||||
* trace / correlation.
|
||||
* إيصال أداة حيث ينطبق.
|
||||
|
||||
---
|
||||
|
||||
## الخلاصة التنفيذية
|
||||
|
||||
هذا التوسع يكمّل قوائم جاهزية الإنتاج القياسية (اختبار، أمن، تدرج، استرجاع) عندما تُطبَّق على **حدود الثقة** لا على الواجهات فقط. ([TechTarget][1])
|
||||
|
||||
1. Golden path run (حسب الـ runbook).
|
||||
2. Chaos على الحالات الحرجة.
|
||||
3. Executive validation.
|
||||
4. توسع Trust مسارًا مسارًا (جدول + A/R/S + enforcement).
|
||||
5. Canary ثم full rollout مع rollback جاهز.
|
||||
|
||||
**توسيع لاحق (اختياري):** أتمتة PR (رفض تلقائي عند مخالفة governance)، أو **Full Backend Hardening** (DB، تخزين مؤقت، طوابير، توسع أفقي) — يُفضّل مشروع منفصل بحدود زمنية ونطاق واضحين.
|
||||
|
||||
---
|
||||
|
||||
## المراجع
|
||||
|
||||
[1]: https://www.techtarget.com/searchsoftwarequality/tip/A-production-readiness-checklist-for-software-development "A production readiness checklist for software development | TechTarget"
|
||||
[2]: https://seisan.com/enterprise-app-readiness/ "Enterprise App Readiness | Seisan"
|
||||
@ -7,7 +7,9 @@
|
||||
|
||||
**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).
|
||||
**فهرس مصدر الحقيقة:** [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) (canonical vs shadow).
|
||||
**فهرس مصدر الحقيقة:** [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) (canonical vs shadow).
|
||||
**مسار ذهبي Tier-1 (تنفيذ):** [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) + `pytest tests/test_tier1_golden_path_partner.py`.
|
||||
**البرنامج التشغيلي النهائي (AR):** [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md).
|
||||
|
||||
| WS | Name | SLA (target) | Primary deliverable docs / code |
|
||||
|----|------|--------------|-----------------------------------|
|
||||
|
||||
@ -52,4 +52,22 @@ Revisit this file after each major release or enterprise pilot; update [`dealix-
|
||||
|
||||
## 7. Maintainer sync
|
||||
|
||||
`scripts/architecture_brief.py` includes this path in `CONSTITUTION_PATHS`; `.claude/settings.json` references it in `projectInstructions` for Claude Code. Update both when adding new enterprise-facing governance files.
|
||||
`scripts/architecture_brief.py` includes this path in `CONSTITUTION_PATHS` (بما فيها [`FINAL_TIER1_CLOSURE_PROGRAM_AR.md`](FINAL_TIER1_CLOSURE_PROGRAM_AR.md))؛ `.claude/settings.json` references it in `projectInstructions` for Claude Code. Update both when adding new enterprise-facing governance files.
|
||||
|
||||
## 8. Tier-1 complete (Definition of Done — operational)
|
||||
|
||||
Use this as the **release bar** alongside [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) and [`TIER1_MASTER_CLOSURE_CHECKLIST_AR.md`](TIER1_MASTER_CLOSURE_CHECKLIST_AR.md) §16.
|
||||
|
||||
| Gate | Evidence |
|
||||
|------|----------|
|
||||
| Source of truth | [`SOURCE_OF_TRUTH_INDEX.md`](SOURCE_OF_TRUTH_INDEX.md) — owners and review cadence filled for critical topics |
|
||||
| RC row | [`RELEASE_READINESS_MATRIX_AR.md`](RELEASE_READINESS_MATRIX_AR.md) — one completed row per enterprise candidate |
|
||||
| Docs CI | GitHub Actions workflow **`Docs governance`**: `architecture_brief`, `check_docs_links`, `check_no_overclaim`, `check_release_readiness_matrix`, `check_source_of_truth_index` |
|
||||
| RC strict row (optional) | Workflow **`Release readiness RC row gate`**: runs `RELEASE_MATRIX_RC_ROW_REQUIRED=1` when the PR label is `release-candidate` or the PR changes `docs/RELEASE_READINESS_MATRIX_AR.md` — see [`governance/github-and-release.md`](governance/github-and-release.md) |
|
||||
| Backend CI | **`Dealix CI`**: pytest, OpenAPI path verify, `check_no_overclaim`, `check_release_readiness_matrix`, **`check_go_live_gate` with `DEALIX_CI_FAIL_ON_GO_LIVE=1`** |
|
||||
| Runtime Class B | `POST /api/v1/approval-center/validate-class-b-bundle` + bundle validation on approve/reject when `decision_bundle` is supplied |
|
||||
| Golden path | [`golden-path-partner-intake-runbook.md`](golden-path-partner-intake-runbook.md) + `test_tier1_golden_path_partner` |
|
||||
| Saudi sensitive path | Proposal `send` with `external_company_contacts` requires `pdpl_processing_class` + `owasp_surface_ref` (422 otherwise) |
|
||||
| Severity V3 / critical contradictions | `POST /api/v1/contradictions` requires `evidence` when severity is `critical` or `V3` |
|
||||
| No open V3 | Operational rule: no enterprise RC with unresolved **V3** per [`governance/operational-severity-model.md`](governance/operational-severity-model.md) |
|
||||
| Revenue go-live (commercial) | [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) + [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md) + [`LIVE_DEPLOYMENT_GUIDE_AR.md`](LIVE_DEPLOYMENT_GUIDE_AR.md) — pilot scope, deploy, and handoff evidence |
|
||||
|
||||
53
docs/golden-path-partner-intake-runbook.md
Normal file
53
docs/golden-path-partner-intake-runbook.md
Normal file
@ -0,0 +1,53 @@
|
||||
# Golden path — Partner intake → Executive surface (Tier-1)
|
||||
|
||||
**Canonical runbook** for the first **end-to-end** governed path. APIs are under `/api/v1/` in `salesflow-saas/backend`.
|
||||
|
||||
## Preconditions
|
||||
|
||||
- `cwd` = repo root for scripts; backend tests from `salesflow-saas/backend`.
|
||||
- CI: `Dealix CI` + `Docs governance` green (see [`enterprise-readiness.md`](enterprise-readiness.md) §8).
|
||||
|
||||
## Sequence (v1 — demo-backed where DB is empty)
|
||||
|
||||
1. **Class B bundle (Decision plane)**
|
||||
`GET /api/v1/approval-center/class-b-decision-bundle`
|
||||
→ Full bundle (`memo_json`, `evidence_pack_json`, `approval_packet_json`, `execution_intent_json`, `risk_register_json`).
|
||||
|
||||
2. **Runtime validation gate**
|
||||
`POST /api/v1/approval-center/validate-class-b-bundle` with JSON body = response from step 1.
|
||||
→ `200` + `{"status":"valid","correlation_id":"..."}`.
|
||||
Mutate `execution_intent_json.correlation_id` to empty while `requested_side_effect_class` stays `external_*` → expect **`422`**.
|
||||
|
||||
3. **HITL (approve with bundle)**
|
||||
`POST /api/v1/approval-center/{approval_id}/approve` with body:
|
||||
```json
|
||||
{ "hitl": "approve", "decision_bundle": { ... same bundle ... } }
|
||||
```
|
||||
Invalid bundle → **`422`**.
|
||||
|
||||
4. **Executive snapshot (Operating / Executive plane)**
|
||||
`GET /api/v1/executive-room/snapshot`
|
||||
→ Includes `tier1_exec_surface` keyed off the same demo bundle (`correlation_id`, `pending_decisions`, etc.).
|
||||
|
||||
5. **Evidence viewer (Trust)**
|
||||
`GET /api/v1/evidence-packs/tier1-demo`
|
||||
→ Structured fields: `verification_status`, sources, assumptions.
|
||||
|
||||
6. **Connector governance**
|
||||
`GET /api/v1/connectors/governance`
|
||||
→ Includes `tier1_connector_surface` policy hooks.
|
||||
|
||||
7. **Saudi-sensitive proposal send (Data / compliance)**
|
||||
`POST /api/v1/proposals/{id}/send` with `external_company_contacts: true` **requires** `pdpl_processing_class` and `owasp_surface_ref` or **`422`** (FastAPI validation).
|
||||
|
||||
## Automated proof
|
||||
|
||||
- Pytest: `tests/test_tier1_golden_path_partner.py` (name may vary) exercises steps 1–4 (and optionally 5–7 where auth/DB fixtures exist).
|
||||
|
||||
## Ownership
|
||||
|
||||
| Step | Owner |
|
||||
|------|--------|
|
||||
| Bundle + validation | Backend / Governance |
|
||||
| Executive + evidence UI | Product + Frontend |
|
||||
| Saudi fields on send | Compliance + Backend |
|
||||
@ -34,6 +34,19 @@ Use explicit promotion: **dev → staging → canary → prod** (names may vary;
|
||||
|
||||
Do not rely on GitHub (or any single SaaS) **retention alone** for audit-critical evidence. Plan streaming or export for long-lived audit trails where legal or enterprise customers require it.
|
||||
|
||||
## Go-live gate (fail-closed in CI)
|
||||
|
||||
`Dealix CI` runs [`salesflow-saas/scripts/check_go_live_gate.py`](../../salesflow-saas/scripts/check_go_live_gate.py) with **`DEALIX_CI_FAIL_ON_GO_LIVE=1`**: the job fails if the in-process `GET .../go-live-gate` response is not HTTP 200 or `launch_allowed` is not `true`. Local runs default to informational unless you pass `--strict` or set the same env var.
|
||||
|
||||
## Release readiness matrix — strict RC row (optional PR gate)
|
||||
|
||||
Workflow [`.github/workflows/release-readiness-rc-gate.yml`](../../.github/workflows/release-readiness-rc-gate.yml) runs on pull requests to `main` and executes `RELEASE_MATRIX_RC_ROW_REQUIRED=1 python scripts/check_release_readiness_matrix.py` when **either**:
|
||||
|
||||
- the PR has the label **`release-candidate`**, or
|
||||
- the PR diff touches **`docs/RELEASE_READINESS_MATRIX_AR.md`**.
|
||||
|
||||
Keep a documented **RC-…** summary row in that matrix (see the sample block in the file) so the strict check passes when you enable the gate.
|
||||
|
||||
## Dealix pointers
|
||||
|
||||
- CI workflows: `salesflow-saas/.github/` (if present) or repo-root `.github/`.
|
||||
|
||||
@ -16,3 +16,12 @@ Use this scale for **policy violations**, **ledger contradictions**, **connector
|
||||
|
||||
- اربط كل حدث حوكمة بـ `severity` (V0–V3) في السجلات واللوحات.
|
||||
- صفوف [`RELEASE_READINESS_MATRIX_AR.md`](../RELEASE_READINESS_MATRIX_AR.md) تلخص أعلى خطورة مفتوحة لكل مرشح إصدار.
|
||||
|
||||
## V2 / V3 وعلاقتها ببوابة الإطلاق (`go-live-gate`)
|
||||
|
||||
- **V2 (Customer-impacting):** يجب أن يوقف ترقية **canary → prod** (أو يفرض استثناءً مسجّلًا) حتى يُخفّف الخطر؛ لا يكفي تسجيل الحدث في لوحة فقط.
|
||||
- **V3 (Regulatory / release-blocking):** **Stop ship** لمرشحي الإصدار؛ لا يُعتبر RC enterprise جاهزًا مع تعارضات V3 مفتوحة — انظر [`enterprise-readiness.md`](../enterprise-readiness.md) §8 و[`trust-fabric.md`](trust-fabric.md).
|
||||
|
||||
**تنفيذ API اليوم:** استجابة `GET /api/v1/autonomous-foundation/integrations/go-live-gate` تعكس أساسًا **جاهزية التكامل/البيئة** (`build_go_live_readiness_report` + [`go_live_matrix.py`](../../salesflow-saas/backend/app/services/go_live_matrix.py)). سياسة **V3 على مسار التعارضات** تبقى بوابة ثقة منفصلة في الوثائق وفي اختبارات `POST /api/v1/contradictions/` حتى تُربَط قائمة التعارضات المفتوحة بذات التقرير؛ عندها يمكن دمج `launch_allowed=false` أو إثراء `blocked_reasons` دون تغيير معنى فحوص البيئة الحالية.
|
||||
|
||||
**عقد الاستجابة:** يُنصح بإرجاع حقل توضيحي (مثل `trust_severity_note`) يربط المستهلك بـ operational-severity وenterprise-readiness حتى لا يُخلط بين «تكامل الإنتاج جاهز» و«لم يبقَ خطر V3 في سجل الثقة».
|
||||
|
||||
@ -6,6 +6,9 @@
|
||||
|---------|--------|
|
||||
| OpenAI Structured Outputs | https://openai.com/index/introducing-structured-outputs-in-the-api/ |
|
||||
| OpenAI Responses API | https://platform.openai.com/docs/api-reference/responses |
|
||||
| OpenAI Responses API (remote MCP) | https://platform.openai.com/docs/api-reference/responses/remote-mcp |
|
||||
| GitHub Actions OIDC (hardening deployments) | https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect |
|
||||
| GitHub Artifact attestations (Enterprise Cloud) | https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/security/artifact-attestations |
|
||||
| LangGraph durable execution | https://docs.langchain.com/oss/javascript/langgraph/durable-execution |
|
||||
| LangGraph / LangChain HITL | https://docs.langchain.com/oss/javascript/langchain/frontend/human-in-the-loop |
|
||||
| Temporal worker versioning | https://temporal.io/change-log/worker-versioning-public-preview |
|
||||
@ -16,6 +19,7 @@
|
||||
| Keycloak Server Admin | https://www.keycloak.org/docs/latest/server_admin/index.html |
|
||||
| OpenTelemetry Logging | https://opentelemetry.io/docs/specification/logs/ |
|
||||
| CloudEvents spec | https://github.com/cloudevents/spec |
|
||||
| NIST AI Risk Management Framework (AI RMF 1.0) | https://www.nist.gov/itl/ai-risk-management-framework |
|
||||
| NIST AI RMF GenAI profile | https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence |
|
||||
| OWASP LLM Top 10 | https://owasp.org/www-project-top-10-for-large-language-model-applications/ |
|
||||
| Great Expectations checkpoints | https://docs.greatexpectations.io/docs/0.18/reference/learn/terms/checkpoint |
|
||||
|
||||
@ -11,3 +11,5 @@
|
||||
| **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) فقط في لوحات جديدة.
|
||||
|
||||
**إيراد وتشغيل (بعد Tier-1):** [`GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md`](GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md) + [`FIRST_THREE_CLIENTS_PLAN_AR.md`](FIRST_THREE_CLIENTS_PLAN_AR.md) + [`LIVE_DEPLOYMENT_GUIDE_AR.md`](LIVE_DEPLOYMENT_GUIDE_AR.md) + [`AUTOMATED_REVENUE_ENGINE_AR.md`](AUTOMATED_REVENUE_ENGINE_AR.md).
|
||||
|
||||
17
salesflow-saas/backend/app/api/governance_http.py
Normal file
17
salesflow-saas/backend/app/api/governance_http.py
Normal file
@ -0,0 +1,17 @@
|
||||
"""HTTP helpers for Class B decision bundle enforcement (Tier-1 runtime)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict
|
||||
|
||||
from fastapi import HTTPException
|
||||
|
||||
from app.services.core_os.decision_plane_contracts import validate_class_b_bundle
|
||||
|
||||
|
||||
def http_validate_class_b_bundle(bundle: Dict[str, Any]) -> None:
|
||||
"""Raise 422 if bundle fails Tier-1 Class B gate (including correlation for external_*)."""
|
||||
try:
|
||||
validate_class_b_bundle(bundle)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=422, detail=str(exc)) from exc
|
||||
@ -1,25 +1,22 @@
|
||||
"""Approval Center API — enhanced approval queue with SLA tracking."""
|
||||
|
||||
from typing import Any, Dict, Optional
|
||||
from typing import Any, Dict, Literal, Optional
|
||||
|
||||
from fastapi import APIRouter
|
||||
from fastapi import APIRouter, Body
|
||||
from pydantic import BaseModel as PydanticBase
|
||||
|
||||
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,
|
||||
)
|
||||
from app.api.governance_http import http_validate_class_b_bundle
|
||||
from app.services.core_os.tier1_demo_bundle import build_class_b_demo_bundle
|
||||
|
||||
router = APIRouter(prefix="/approval-center", tags=["Approval Center"])
|
||||
|
||||
|
||||
class ApprovalAction(PydanticBase):
|
||||
"""HITL action per execution-fabric taxonomy (approve / edit / reject)."""
|
||||
|
||||
note: Optional[str] = None
|
||||
hitl: Optional[Literal["approve", "edit", "reject"]] = None
|
||||
decision_bundle: Optional[Dict[str, Any]] = None
|
||||
|
||||
|
||||
@router.get("/class-b-decision-bundle")
|
||||
@ -28,59 +25,17 @@ 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="external_message",
|
||||
correlation_id="corr_class_b_demo",
|
||||
payload_summary="Demo external-class path; correlation_id mandatory per validate_class_b_bundle",
|
||||
)
|
||||
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
|
||||
return build_class_b_demo_bundle()
|
||||
|
||||
|
||||
@router.post("/validate-class-b-bundle")
|
||||
async def validate_class_b_bundle_endpoint(
|
||||
body: Dict[str, Any] = Body(..., description="Full Class B bundle JSON"),
|
||||
) -> Dict[str, Any]:
|
||||
"""Runtime gate: 422 if bundle violates Class B + correlation rules."""
|
||||
http_validate_class_b_bundle(body)
|
||||
ei = body.get("execution_intent_json") or {}
|
||||
return {"status": "valid", "correlation_id": ei.get("correlation_id")}
|
||||
|
||||
|
||||
@router.get("/")
|
||||
@ -113,14 +68,28 @@ async def my_pending_approvals() -> Dict[str, Any]:
|
||||
|
||||
@router.post("/{approval_id}/approve")
|
||||
async def approve(approval_id: str, body: ApprovalAction) -> Dict[str, Any]:
|
||||
"""Approve a request."""
|
||||
return {"id": approval_id, "status": "approved", "note": body.note}
|
||||
"""Approve a request. If decision_bundle is supplied, it must pass Class B validation."""
|
||||
if body.decision_bundle is not None:
|
||||
http_validate_class_b_bundle(body.decision_bundle)
|
||||
return {
|
||||
"id": approval_id,
|
||||
"status": "approved",
|
||||
"note": body.note,
|
||||
"hitl": body.hitl or "approve",
|
||||
}
|
||||
|
||||
|
||||
@router.post("/{approval_id}/reject")
|
||||
async def reject(approval_id: str, body: ApprovalAction) -> Dict[str, Any]:
|
||||
"""Reject a request."""
|
||||
return {"id": approval_id, "status": "rejected", "note": body.note}
|
||||
"""Reject a request. Optional decision_bundle validated when present."""
|
||||
if body.decision_bundle is not None:
|
||||
http_validate_class_b_bundle(body.decision_bundle)
|
||||
return {
|
||||
"id": approval_id,
|
||||
"status": "rejected",
|
||||
"note": body.note,
|
||||
"hitl": body.hitl or "reject",
|
||||
}
|
||||
|
||||
|
||||
@router.post("/{approval_id}/escalate")
|
||||
|
||||
@ -168,6 +168,20 @@ def build_go_live_readiness_report() -> Dict[str, Any]:
|
||||
)
|
||||
if getattr(settings, "ENVIRONMENT", "") == "development" and launch_allowed:
|
||||
warnings.append("ENVIRONMENT=development — use production settings before real go-live.")
|
||||
trust_severity_note = {
|
||||
"policy_docs": [
|
||||
"docs/governance/operational-severity-model.md",
|
||||
"docs/enterprise-readiness.md",
|
||||
],
|
||||
"summary_ar": (
|
||||
"بوابة الإطلاق الحالية تقيس التكامل والبيئة؛ امتثال V2/V3 للتعارضات والثقة "
|
||||
"يُدار عبر مصفوفة الجاهزية وسجل الثقة وليس فقط عبر launch_allowed."
|
||||
),
|
||||
"summary_en": (
|
||||
"This gate primarily reflects env/integration readiness; V2/V3 trust backlog is "
|
||||
"governed via release matrix and contradiction policy in addition to launch_allowed."
|
||||
),
|
||||
}
|
||||
return {
|
||||
"gate": "go_live",
|
||||
"launch_mode": "full_commercial",
|
||||
@ -197,6 +211,7 @@ def build_go_live_readiness_report() -> Dict[str, Any]:
|
||||
"frontend_env_example": "salesflow-saas/frontend/.env.example",
|
||||
},
|
||||
"cli_examples": cli_examples,
|
||||
"trust_severity_note": trust_severity_note,
|
||||
"warnings": warnings,
|
||||
"notes": [
|
||||
"الفحوص الإلزامية تشمل: أمان، قاعدة بيانات، ذكاء، بريد، Salesforce، واتساب (ومنع الوضع التجريبي)، Stripe + webhook، Twilio، توقيع إلكتروني.",
|
||||
@ -444,6 +459,7 @@ async def live_readiness_report() -> Dict[str, Any]:
|
||||
"missing_optional": report["missing_optional"],
|
||||
"integration_docs": report["integration_docs"],
|
||||
"cli_examples": report["cli_examples"],
|
||||
"trust_severity_note": report["trust_severity_note"],
|
||||
"notes": report["notes"],
|
||||
}
|
||||
|
||||
|
||||
@ -9,7 +9,16 @@ router = APIRouter(prefix="/connectors", tags=["Connector Governance"])
|
||||
@router.get("/governance")
|
||||
async def governance_board() -> Dict[str, Any]:
|
||||
"""Get connector governance board."""
|
||||
return {"connectors": [], "total": 0}
|
||||
return {
|
||||
"connectors": [],
|
||||
"total": 0,
|
||||
"tier1_connector_surface": {
|
||||
"policy_ref": "docs/ws5-connector-events-metrics.md",
|
||||
"approval_hook": "Class B before external_commitment",
|
||||
"audit_coverage": "trace_id/correlation_id required on facade calls",
|
||||
"health_model": "healthy|degraded|error",
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
@router.post("/{connector_key}/health-check")
|
||||
|
||||
@ -30,6 +30,12 @@ class ContradictionResolve(PydanticBase):
|
||||
@router.post("/")
|
||||
async def register_contradiction(body: ContradictionCreate) -> Dict[str, Any]:
|
||||
"""Register a new contradiction."""
|
||||
sev = (body.severity or "").strip().lower()
|
||||
if sev in ("v3", "critical") and not (body.evidence or {}):
|
||||
raise HTTPException(
|
||||
status_code=422,
|
||||
detail="severity V3/critical requires non-empty evidence (trust plane receipt)",
|
||||
)
|
||||
return {
|
||||
"status": "registered",
|
||||
"source_a": body.source_a,
|
||||
|
||||
@ -36,6 +36,18 @@ async def list_evidence_packs(pack_type: Optional[str] = None) -> Dict[str, Any]
|
||||
@router.get("/{pack_id}")
|
||||
async def get_evidence_pack(pack_id: str) -> Dict[str, Any]:
|
||||
"""Get a specific evidence pack."""
|
||||
if pack_id == "tier1-demo":
|
||||
return {
|
||||
"id": pack_id,
|
||||
"status": "ready",
|
||||
"sources": ["ci:dealix-ci", "pytest:evidence_packs"],
|
||||
"assumptions": ["Demo pack for Executive / Trust surfaces"],
|
||||
"confidence": 0.85,
|
||||
"approvals": ["governance_lead"],
|
||||
"verification_status": "partially_verified",
|
||||
"actual_tool_call": None,
|
||||
"contradictions": [],
|
||||
}
|
||||
return {"id": pack_id, "status": "not_found"}
|
||||
|
||||
|
||||
|
||||
@ -3,12 +3,15 @@
|
||||
from fastapi import APIRouter
|
||||
from typing import Any, Dict
|
||||
|
||||
from app.services.core_os.tier1_demo_bundle import build_exec_weekly_governance_contract_from_demo_bundle
|
||||
|
||||
router = APIRouter(prefix="/executive-room", tags=["Executive Room"])
|
||||
|
||||
|
||||
@router.get("/snapshot")
|
||||
async def executive_snapshot() -> Dict[str, Any]:
|
||||
"""Full executive room snapshot."""
|
||||
exec_weekly = build_exec_weekly_governance_contract_from_demo_bundle()
|
||||
return {
|
||||
"revenue": {
|
||||
"actual": 0,
|
||||
@ -45,6 +48,7 @@ async def executive_snapshot() -> Dict[str, Any]:
|
||||
"ready": 0,
|
||||
"pending_review": 0,
|
||||
},
|
||||
"tier1_exec_surface": exec_weekly.model_dump(mode="json"),
|
||||
}
|
||||
|
||||
|
||||
|
||||
@ -4,11 +4,11 @@ Dealix Proposals & Quotes API
|
||||
"""
|
||||
|
||||
from datetime import datetime, timezone
|
||||
from typing import Optional
|
||||
from typing import Literal, Optional
|
||||
from uuid import UUID
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, Query
|
||||
from pydantic import BaseModel, Field
|
||||
from pydantic import BaseModel, Field, model_validator
|
||||
from sqlalchemy import select, func, and_
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
@ -51,6 +51,25 @@ class ProposalUpdateRequest(BaseModel):
|
||||
class SendRequest(BaseModel):
|
||||
channel: str = Field(pattern=r"^(whatsapp|email)$", default="whatsapp")
|
||||
recipient: str
|
||||
# Tier-1 / WS7: external proposal with company contacts → PDPL + OWASP mapping required
|
||||
external_company_contacts: bool = False
|
||||
pdpl_processing_class: Optional[Literal["public", "internal", "personal", "sensitive"]] = None
|
||||
ecc_control_owner: Optional[str] = None
|
||||
owasp_surface_ref: Optional[str] = None
|
||||
|
||||
@model_validator(mode="after")
|
||||
def saudi_sensitive_path(self) -> "SendRequest":
|
||||
if self.external_company_contacts:
|
||||
if not self.pdpl_processing_class:
|
||||
raise ValueError(
|
||||
"pdpl_processing_class required when external_company_contacts is true"
|
||||
)
|
||||
if not self.owasp_surface_ref:
|
||||
raise ValueError(
|
||||
"owasp_surface_ref required when external_company_contacts is true "
|
||||
"(map to OWASP LLM / control matrix)"
|
||||
)
|
||||
return self
|
||||
|
||||
|
||||
class AcceptRequest(BaseModel):
|
||||
|
||||
119
salesflow-saas/backend/app/services/core_os/tier1_demo_bundle.py
Normal file
119
salesflow-saas/backend/app/services/core_os/tier1_demo_bundle.py
Normal file
@ -0,0 +1,119 @@
|
||||
"""Shared Tier-1 Class B demo bundle for approval center, executive snapshot, and tests."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any, Dict, List
|
||||
|
||||
from app.schemas.structured_outputs import ExecWeeklyGovernanceContract, Provenance
|
||||
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,
|
||||
)
|
||||
|
||||
|
||||
def build_class_b_demo_bundle() -> Dict[str, Any]:
|
||||
"""Validated demo bundle; same shape as GET /approval-center/class-b-decision-bundle."""
|
||||
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="external_message",
|
||||
correlation_id="corr_class_b_demo",
|
||||
payload_summary="Demo external-class path; correlation_id mandatory per validate_class_b_bundle",
|
||||
)
|
||||
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
|
||||
|
||||
|
||||
def build_exec_weekly_governance_contract_from_demo_bundle() -> ExecWeeklyGovernanceContract:
|
||||
"""Single source for executive weekly fields: same demo bundle as Class B / golden path."""
|
||||
bundle = build_class_b_demo_bundle()
|
||||
memo = bundle.get("memo_json") or {}
|
||||
ei = bundle.get("execution_intent_json") or {}
|
||||
correlation_id = ei.get("correlation_id") or "unknown"
|
||||
iso = datetime.now(timezone.utc).isocalendar()
|
||||
week_of = f"{iso.year}-W{iso.week:02d}"
|
||||
pending = list(memo.get("required_approvals") or [])
|
||||
nba_raw = memo.get("next_best_action")
|
||||
next_best: List[str] = [nba_raw] if isinstance(nba_raw, str) and nba_raw.strip() else []
|
||||
risks = memo.get("risk_register") or []
|
||||
at_risk: List[str] = []
|
||||
if isinstance(risks, list):
|
||||
for item in risks:
|
||||
if isinstance(item, dict) and item.get("risk"):
|
||||
at_risk.append(str(item["risk"]))
|
||||
changes_summary = (
|
||||
f"Weekly rollup (demo): {memo.get('objective', '')} — {memo.get('recommendation', '')}".strip()
|
||||
)
|
||||
raw_conf = memo.get("confidence")
|
||||
if raw_conf is not None:
|
||||
c = float(raw_conf)
|
||||
conf_norm = c / 100.0 if c > 1.0 else c
|
||||
else:
|
||||
conf_norm = 0.72
|
||||
provenance = Provenance(
|
||||
generated_by="tier1_demo_bundle",
|
||||
model_provider=None,
|
||||
model_id=None,
|
||||
confidence=min(1.0, max(0.0, conf_norm)),
|
||||
freshness_hours=0.0,
|
||||
trace_id=str(correlation_id),
|
||||
)
|
||||
return ExecWeeklyGovernanceContract(
|
||||
week_of=week_of,
|
||||
changes_summary=changes_summary or "No changes summary in demo memo.",
|
||||
pending_decisions=pending,
|
||||
blockers_summary="No live blockers in demo mode.",
|
||||
at_risk_items=at_risk,
|
||||
next_best_actions=next_best or ["none"],
|
||||
provenance=provenance,
|
||||
)
|
||||
@ -16,3 +16,30 @@ async def test_class_b_decision_bundle_endpoint():
|
||||
validate_class_b_bundle(data)
|
||||
assert "memo_json" in data
|
||||
assert data["approval_packet_json"]["approval_class"] == "A2"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_validate_class_b_bundle_endpoint_rejects_bad_correlation():
|
||||
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")
|
||||
bundle = r.json()
|
||||
bad = dict(bundle)
|
||||
bad["execution_intent_json"] = dict(bundle["execution_intent_json"])
|
||||
bad["execution_intent_json"]["correlation_id"] = ""
|
||||
v = await client.post("/api/v1/approval-center/validate-class-b-bundle", json=bad)
|
||||
assert v.status_code == 422
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_approve_with_invalid_bundle_returns_422():
|
||||
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")
|
||||
bundle = r.json()
|
||||
bad = dict(bundle)
|
||||
bad["execution_intent_json"] = dict(bundle["execution_intent_json"])
|
||||
bad["execution_intent_json"]["correlation_id"] = ""
|
||||
a = await client.post(
|
||||
"/api/v1/approval-center/x/approve",
|
||||
json={"decision_bundle": bad},
|
||||
)
|
||||
assert a.status_code == 422
|
||||
|
||||
@ -53,6 +53,7 @@ async def test_live_readiness_endpoint(client):
|
||||
assert "categories" in payload
|
||||
assert "blocking" in payload
|
||||
assert "integration_docs" in payload
|
||||
assert "trust_severity_note" in payload
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@ -68,6 +69,8 @@ async def test_go_live_gate_returns_403_with_report_when_not_fully_ready(client)
|
||||
assert "summary" in payload
|
||||
assert "cli_examples" in payload
|
||||
assert "warnings" in payload
|
||||
assert "trust_severity_note" in payload
|
||||
assert payload["trust_severity_note"]["policy_docs"]
|
||||
if not payload["launch_allowed"]:
|
||||
assert response.status_code == 403
|
||||
assert payload["readiness_percent"] < 100.0
|
||||
|
||||
@ -0,0 +1,36 @@
|
||||
"""Trust CI: critical / V3 contradictions require evidence."""
|
||||
|
||||
import pytest
|
||||
from httpx import ASGITransport, AsyncClient
|
||||
|
||||
from app.main import app
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_contradiction_critical_requires_evidence():
|
||||
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
|
||||
r = await client.post(
|
||||
"/api/v1/contradictions/",
|
||||
json={
|
||||
"source_a": "a",
|
||||
"source_b": "b",
|
||||
"claim_a": "x",
|
||||
"claim_b": "y",
|
||||
"severity": "critical",
|
||||
"evidence": None,
|
||||
},
|
||||
)
|
||||
assert r.status_code == 422
|
||||
|
||||
r2 = await client.post(
|
||||
"/api/v1/contradictions/",
|
||||
json={
|
||||
"source_a": "a",
|
||||
"source_b": "b",
|
||||
"claim_a": "x",
|
||||
"claim_b": "y",
|
||||
"severity": "critical",
|
||||
"evidence": {"receipt": "r1"},
|
||||
},
|
||||
)
|
||||
assert r2.status_code == 200
|
||||
@ -0,0 +1,45 @@
|
||||
"""WS7: Saudi-sensitive proposal send — PDPL + OWASP fields when external contacts."""
|
||||
|
||||
import pytest
|
||||
from pydantic import ValidationError
|
||||
|
||||
from app.api.v1.proposals import SendRequest
|
||||
|
||||
|
||||
def test_send_request_allows_without_external_contacts():
|
||||
s = SendRequest(channel="email", recipient="x@example.com")
|
||||
assert s.external_company_contacts is False
|
||||
|
||||
|
||||
def test_send_request_rejects_external_contacts_without_pdpl():
|
||||
with pytest.raises(ValidationError, match="pdpl_processing_class"):
|
||||
SendRequest(
|
||||
channel="email",
|
||||
recipient="x@example.com",
|
||||
external_company_contacts=True,
|
||||
pdpl_processing_class=None,
|
||||
owasp_surface_ref="LLM01",
|
||||
)
|
||||
|
||||
|
||||
def test_send_request_rejects_external_contacts_without_owasp():
|
||||
with pytest.raises(ValidationError, match="owasp_surface_ref"):
|
||||
SendRequest(
|
||||
channel="email",
|
||||
recipient="x@example.com",
|
||||
external_company_contacts=True,
|
||||
pdpl_processing_class="personal",
|
||||
owasp_surface_ref=None,
|
||||
)
|
||||
|
||||
|
||||
def test_send_request_accepts_gated_fields():
|
||||
s = SendRequest(
|
||||
channel="email",
|
||||
recipient="x@example.com",
|
||||
external_company_contacts=True,
|
||||
pdpl_processing_class="sensitive",
|
||||
owasp_surface_ref="LLM01_prompt_injection",
|
||||
ecc_control_owner="security@example.com",
|
||||
)
|
||||
assert s.pdpl_processing_class == "sensitive"
|
||||
@ -0,0 +1,19 @@
|
||||
"""Schema / contract CI: ExecWeeklyGovernanceContract round-trip."""
|
||||
|
||||
from app.schemas.structured_outputs import ExecWeeklyGovernanceContract, Provenance
|
||||
|
||||
|
||||
def test_exec_weekly_governance_contract_roundtrip():
|
||||
p = Provenance(generated_by="pytest", confidence=0.9)
|
||||
m = ExecWeeklyGovernanceContract(
|
||||
week_of="2026-W16",
|
||||
changes_summary="Closed Tier-1 gates",
|
||||
pending_decisions=["CFO sign-off"],
|
||||
blockers_summary="None",
|
||||
at_risk_items=["connector X"],
|
||||
next_best_actions=["Run RC checklist"],
|
||||
provenance=p,
|
||||
)
|
||||
d = m.model_dump(mode="json")
|
||||
m2 = ExecWeeklyGovernanceContract.model_validate(d)
|
||||
assert m2.pending_decisions == ["CFO sign-off"]
|
||||
@ -0,0 +1,50 @@
|
||||
"""Tier-1 golden path: Partner intake → Class B → Executive snapshot (contract test)."""
|
||||
|
||||
import pytest
|
||||
from httpx import ASGITransport, AsyncClient
|
||||
|
||||
from app.main import app
|
||||
from app.schemas.structured_outputs import ExecWeeklyGovernanceContract
|
||||
from app.services.core_os.decision_plane_contracts import validate_class_b_bundle
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_tier1_golden_path_partner_demo_chain():
|
||||
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
|
||||
r1 = await client.get("/api/v1/approval-center/class-b-decision-bundle")
|
||||
assert r1.status_code == 200
|
||||
bundle = r1.json()
|
||||
validate_class_b_bundle(bundle)
|
||||
|
||||
r2 = await client.post("/api/v1/approval-center/validate-class-b-bundle", json=bundle)
|
||||
assert r2.status_code == 200
|
||||
assert r2.json().get("status") == "valid"
|
||||
assert r2.json().get("correlation_id") == bundle["execution_intent_json"]["correlation_id"]
|
||||
|
||||
bad = dict(bundle)
|
||||
bad["execution_intent_json"] = dict(bundle["execution_intent_json"])
|
||||
bad["execution_intent_json"]["correlation_id"] = " "
|
||||
r3 = await client.post("/api/v1/approval-center/validate-class-b-bundle", json=bad)
|
||||
assert r3.status_code == 422
|
||||
|
||||
r4 = await client.post(
|
||||
"/api/v1/approval-center/demo-1/approve",
|
||||
json={"hitl": "approve", "decision_bundle": bundle},
|
||||
)
|
||||
assert r4.status_code == 200
|
||||
|
||||
r5 = await client.get("/api/v1/executive-room/snapshot")
|
||||
assert r5.status_code == 200
|
||||
snap = r5.json()
|
||||
tier1 = snap.get("tier1_exec_surface") or {}
|
||||
parsed = ExecWeeklyGovernanceContract.model_validate(tier1)
|
||||
assert parsed.provenance.trace_id == bundle["execution_intent_json"]["correlation_id"]
|
||||
assert list(parsed.pending_decisions) == list(bundle["memo_json"]["required_approvals"])
|
||||
|
||||
r6 = await client.get("/api/v1/evidence-packs/tier1-demo")
|
||||
assert r6.status_code == 200
|
||||
assert r6.json().get("verification_status")
|
||||
|
||||
r7 = await client.get("/api/v1/connectors/governance")
|
||||
assert r7.status_code == 200
|
||||
assert "tier1_connector_surface" in r7.json()
|
||||
@ -7,10 +7,14 @@ Uses the in-process FastAPI app (same deps as pytest). Does not start uvicorn.
|
||||
Run from repo:
|
||||
cd salesflow-saas && py -3 scripts/check_go_live_gate.py
|
||||
|
||||
Strict CI mode (fail closed):
|
||||
DEALIX_CI_FAIL_ON_GO_LIVE=1 py -3 scripts/check_go_live_gate.py
|
||||
py -3 scripts/check_go_live_gate.py --strict
|
||||
|
||||
Against a running API instead:
|
||||
curl -sS http://127.0.0.1:8000/api/v1/autonomous-foundation/integrations/go-live-gate | py -3 -m json.tool
|
||||
|
||||
Exit code: 0 always (informational). Use HTTP status / launch_allowed in the JSON when calling from CI.
|
||||
Exit code: 0 when informational; strict mode returns 1 if HTTP != 200 or launch_allowed is false.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@ -27,6 +31,8 @@ def main() -> int:
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
strict = os.environ.get("DEALIX_CI_FAIL_ON_GO_LIVE", "").strip() in ("1", "true", "yes") or "--strict" in sys.argv
|
||||
|
||||
saas = Path(__file__).resolve().parent.parent
|
||||
backend = saas / "backend"
|
||||
os.environ.setdefault("DATABASE_URL", "sqlite+aiosqlite:///./go_live_gate_cli.db")
|
||||
@ -43,7 +49,7 @@ def main() -> int:
|
||||
body = r.json()
|
||||
except Exception:
|
||||
print("HTTP", r.status_code, "non-JSON body", r.text[:500])
|
||||
return 0
|
||||
return 1 if strict else 0
|
||||
|
||||
la = body.get("launch_allowed")
|
||||
print(f"HTTP {r.status_code} launch_allowed={la}")
|
||||
@ -57,6 +63,14 @@ def main() -> int:
|
||||
print(f"blocking_checks={len(blocking)}")
|
||||
if "--json" in sys.argv:
|
||||
print(json.dumps(body, indent=2, ensure_ascii=False))
|
||||
|
||||
if strict:
|
||||
if r.status_code != 200:
|
||||
print("STRICT_FAIL: non-200 from go-live-gate", file=sys.stderr)
|
||||
return 1
|
||||
if la is not True:
|
||||
print("STRICT_FAIL: launch_allowed is not true", file=sys.stderr)
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
|
||||
@ -21,6 +21,12 @@ CONSTITUTION_PATHS = [
|
||||
"docs/RELEASE_READINESS_MATRIX_AR.md",
|
||||
"docs/SOURCE_OF_TRUTH_INDEX.md",
|
||||
"docs/references/tier1-external-index.md",
|
||||
"docs/golden-path-partner-intake-runbook.md",
|
||||
"docs/PR16_MERGE_RECONCILE_CHECKLIST.md",
|
||||
"scripts/check_no_overclaim.py",
|
||||
"scripts/check_release_readiness_matrix.py",
|
||||
"scripts/check_source_of_truth_index.py",
|
||||
"scripts/check_glossary_consistency.py",
|
||||
"docs/ws5-connector-events-metrics.md",
|
||||
"docs/executive-room-completion-spec.md",
|
||||
"docs/governance/pdpl-nca-ai-control-matrices.md",
|
||||
@ -28,6 +34,15 @@ CONSTITUTION_PATHS = [
|
||||
"docs/adr/0001-tier1-execution-policy-spikes.md",
|
||||
"docs/adr/0002-execution-matrix-canonical-source.md",
|
||||
"docs/TIER1_MASTER_CLOSURE_CHECKLIST_AR.md",
|
||||
"docs/FINAL_TIER1_CLOSURE_PROGRAM_AR.md",
|
||||
"docs/TIER1_CLOSURE_VERIFICATION_POSTCLOSURE_AR.md",
|
||||
"docs/TIER1_PRODUCTION_ACTIVATION_PROGRAM_AR.md",
|
||||
"docs/TIER1_REAL_PRODUCTION_PLAYBOOK_AR.md",
|
||||
"docs/TIER1_TRUST_EXPANSION_PLAN_AR.md",
|
||||
"docs/GO_LIVE_REVENUE_ACTIVATION_SYSTEM_AR.md",
|
||||
"docs/FIRST_THREE_CLIENTS_PLAN_AR.md",
|
||||
"docs/LIVE_DEPLOYMENT_GUIDE_AR.md",
|
||||
"docs/AUTOMATED_REVENUE_ENGINE_AR.md",
|
||||
"docs/glossary-dealix-planes-tracks.md",
|
||||
"docs/tracks-tier1-artifact-paths.md",
|
||||
"docs/governance/README.md",
|
||||
|
||||
35
scripts/check_glossary_consistency.py
Normal file
35
scripts/check_glossary_consistency.py
Normal file
@ -0,0 +1,35 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Lightweight glossary presence check for Tier-1 Docs/Governance CI."""
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
GLOSSARY = ROOT / "docs" / "glossary-dealix-planes-tracks.md"
|
||||
|
||||
# Stable anchors that must remain if the glossary is the naming contract.
|
||||
REQUIRED_SUBSTRINGS = (
|
||||
"Decision",
|
||||
"Execution",
|
||||
"Trust",
|
||||
"Operating",
|
||||
"Plane",
|
||||
)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if not GLOSSARY.is_file():
|
||||
print("MISSING", GLOSSARY, file=sys.stderr)
|
||||
return 1
|
||||
text = GLOSSARY.read_text(encoding="utf-8")
|
||||
missing = [s for s in REQUIRED_SUBSTRINGS if s not in text]
|
||||
if missing:
|
||||
print("GLOSSARY_FAIL missing:", missing, file=sys.stderr)
|
||||
return 1
|
||||
print("glossary consistency OK")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
80
scripts/check_no_overclaim.py
Normal file
80
scripts/check_no_overclaim.py
Normal file
@ -0,0 +1,80 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Fail-closed scan for obvious documentation overclaim (Tier-1 governance CI).
|
||||
|
||||
Rules (conservative): flag lines that assert production deployment of gated tech
|
||||
(Temporal, OPA, OpenFGA, Vault, Keycloak) without a negation on the same line.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
|
||||
# Scan governance-facing markdown under repo root + salesflow-saas/docs subset.
|
||||
GLOBS = [
|
||||
"docs/**/*.md",
|
||||
"MASTER_OPERATING_PROMPT.md",
|
||||
"AGENTS.md",
|
||||
"CLAUDE.md",
|
||||
"salesflow-saas/docs/**/*.md",
|
||||
]
|
||||
|
||||
NEGATION = re.compile(
|
||||
r"\b(planned|pilot|doconly|watch|target|not\s+implemented|spike|proposed|optional)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
TECH = re.compile(
|
||||
r"\b(temporal|open\s*fga|openfga|\bopa\b|vault|keycloak)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
CLAIM = re.compile(
|
||||
r"\b(in\s+production|production\s+deploy|fully\s+shipped|deployed\s+to\s+prod)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def collect_files() -> list[Path]:
|
||||
out: list[Path] = []
|
||||
for g in GLOBS:
|
||||
if "**" in g:
|
||||
out.extend(p for p in ROOT.glob(g) if p.is_file())
|
||||
else:
|
||||
p = ROOT / g
|
||||
if p.is_file():
|
||||
out.append(p)
|
||||
return sorted(set(out))
|
||||
|
||||
|
||||
def main() -> int:
|
||||
errors: list[str] = []
|
||||
for path in collect_files():
|
||||
if "node_modules" in path.parts or ".cursor" in path.parts:
|
||||
continue
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
except OSError:
|
||||
continue
|
||||
rel = path.relative_to(ROOT)
|
||||
for i, line in enumerate(text.splitlines(), 1):
|
||||
if not CLAIM.search(line) or not TECH.search(line):
|
||||
continue
|
||||
if NEGATION.search(line):
|
||||
continue
|
||||
errors.append(f"{rel}:{i}: possible overclaim: {line.strip()[:200]}")
|
||||
|
||||
if errors:
|
||||
print("NO_OVERCLAIM_FAIL", file=sys.stderr)
|
||||
for e in errors[:50]:
|
||||
print(e, file=sys.stderr)
|
||||
if len(errors) > 50:
|
||||
print(f"... and {len(errors) - 50} more", file=sys.stderr)
|
||||
return 1
|
||||
print(f"no-overclaim OK ({len(collect_files())} files scanned)")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
52
scripts/check_release_readiness_matrix.py
Normal file
52
scripts/check_release_readiness_matrix.py
Normal file
@ -0,0 +1,52 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Structural lint for docs/RELEASE_READINESS_MATRIX_AR.md (Tier-1 Runtime Trust CI, optional strict)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
DOC = ROOT / "docs" / "RELEASE_READINESS_MATRIX_AR.md"
|
||||
|
||||
REQUIRED = (
|
||||
"مصفوفة جاهزية الإصدار",
|
||||
"docs truth",
|
||||
"schema adherence",
|
||||
"Saudi controls",
|
||||
"provenance",
|
||||
)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if not DOC.is_file():
|
||||
print("MISSING", DOC, file=sys.stderr)
|
||||
return 1 if os.environ.get("RELEASE_MATRIX_STRICT") == "1" else 0
|
||||
text = DOC.read_text(encoding="utf-8")
|
||||
missing = [s for s in REQUIRED if s not in text]
|
||||
if missing and os.environ.get("RELEASE_MATRIX_STRICT") == "1":
|
||||
print("RELEASE_MATRIX_STRICT missing:", missing, file=sys.stderr)
|
||||
return 1
|
||||
# Light mode: require template table row markers exist
|
||||
if "**docs truth**" not in text and "| docs truth |" not in text:
|
||||
if os.environ.get("RELEASE_MATRIX_STRICT") == "1":
|
||||
print("RELEASE_READINESS_MATRIX_AR.md: expected docs truth row", file=sys.stderr)
|
||||
return 1
|
||||
# Optional: RC row filled — look for non-empty status cell pattern (Arabic/English OK)
|
||||
if os.environ.get("RELEASE_MATRIX_RC_ROW_REQUIRED") == "1":
|
||||
# RC row: bold marker **RC-...** or plain | RC-... | with status in next cell
|
||||
if not re.search(r"\|\s*\*\*RC[\w.-]+\*\*\s*\|", text) and not re.search(
|
||||
r"\|\s*RC[\w.-]+\s*\|\s*(OK|Risk|Blocked|مكتمل)", text, re.I
|
||||
):
|
||||
print(
|
||||
"Set RELEASE_MATRIX_RC_ROW_REQUIRED=1 only when an RC row is documented.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
print("release readiness matrix structure OK")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
76
scripts/check_source_of_truth_index.py
Normal file
76
scripts/check_source_of_truth_index.py
Normal file
@ -0,0 +1,76 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Minimal structural checks for docs/SOURCE_OF_TRUTH_INDEX.md (Tier-1 SOT hygiene)."""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
DOC = ROOT / "docs" / "SOURCE_OF_TRUTH_INDEX.md"
|
||||
|
||||
|
||||
def _split_table_row(line: str) -> list[str]:
|
||||
line = line.strip()
|
||||
if not line.startswith("|") or line.startswith("|---"):
|
||||
return []
|
||||
parts = [p.strip() for p in line.strip("|").split("|")]
|
||||
return parts
|
||||
|
||||
|
||||
def main() -> int:
|
||||
strict = os.environ.get("SOURCE_OF_TRUTH_INDEX_STRICT") == "1"
|
||||
if not DOC.is_file():
|
||||
print("MISSING", DOC, file=sys.stderr)
|
||||
return 1 if strict else 0
|
||||
text = DOC.read_text(encoding="utf-8")
|
||||
if "| الموضوع |" not in text and "|الموضوع|" not in text.replace(" ", ""):
|
||||
if strict:
|
||||
print("SOURCE_OF_TRUTH_INDEX: expected topic column header", file=sys.stderr)
|
||||
return 1
|
||||
if "المالك" not in text or "دورة المراجعة" not in text:
|
||||
print("SOURCE_OF_TRUTH_INDEX: missing owner or review cadence column labels", file=sys.stderr)
|
||||
return 1
|
||||
pipe_rows = sum(1 for ln in text.splitlines() if ln.strip().startswith("|"))
|
||||
if pipe_rows < 3:
|
||||
print("SOURCE_OF_TRUTH_INDEX: expected markdown table rows", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
for line in text.splitlines():
|
||||
cells = _split_table_row(line)
|
||||
if len(cells) < 5:
|
||||
continue
|
||||
# topic | canonical | shadow | owner | cadence
|
||||
shadow = cells[2].strip()
|
||||
owner = cells[3].strip()
|
||||
if not shadow or shadow in ("—", "-", "—"):
|
||||
continue
|
||||
if not owner:
|
||||
print(
|
||||
f"SOURCE_OF_TRUTH_INDEX: shadow row without owner: {line[:120]}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
# Reject obvious placeholder owners in strict mode
|
||||
if strict:
|
||||
for line in text.splitlines():
|
||||
cells = _split_table_row(line)
|
||||
if len(cells) < 5:
|
||||
continue
|
||||
owner = cells[3].strip().lower()
|
||||
if owner in ("tbd", "todo", "n/a", ""):
|
||||
shadow = cells[2].strip()
|
||||
if shadow and shadow not in ("—", "-"):
|
||||
print(
|
||||
f"SOURCE_OF_TRUTH_INDEX: strict mode rejects placeholder owner: {line[:120]}",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
print("source of truth index structure OK")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Loading…
Reference in New Issue
Block a user