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

Phase 2 Execution Waves: 90-day plan + Verification Protocol scaffolding

Browse Source 
Saves the DEALIX_PHASE2_EXECUTION_WAVES.md 90-day plan and scaffolds every
artifact the coding agent can produce. Wave A-E execution is explicitly
blocked until the Week-12 Phase Gate (§3) returns Green.

Added:
  §1 Verification Protocol (V001-V007)
    - scripts/v001_secret_scan.sh — trufflehog + gitleaks full-history scan
    - backend/tests/security/test_rls_fuzz.py — 10K cross-tenant fuzz
    - docs/verification/V003_pentest_engagement.md — vendor RFP + scope
    - docs/verification/V004_no_founder_demo_test.md — 3-tester protocol
    - scripts/v005_truth_registry_audit.py — independent audit tool
    - infra/load-tests/baseline.js — k6 perf baseline
    - frontend/tests/a11y/baseline.spec.ts — Playwright+axe baseline
    - docs/baselines/README.md + docs/verification/README.md

  §2 Founder Decision Sprint (FD001-FD005)
    - docs/internal/legal_entity_decision.md — MISA/DIFC/Delaware brief
    - docs/internal/trademark_status.md — SAIP filing kit tracker
    - docs/hiring/{design_engineer, backend_engineer, head_of_cs}.md

  §3 Customer Validation (CV001-CV004)
    - docs/customer_learnings/pilot_agreement_template.md
    - docs/customer_learnings/pilot_template/success_criteria.md
    - docs/customer_learnings/pilot_template/kickoff_checklist.md
    - docs/customer_learnings/friction_log.md + feature_requests.yaml
    - docs/customer_learnings/weekly_review_template.md

  Truth registry updates
    - docs/registry/TRUTH.yaml — new verification_protocol,
      founder_decision_sprint, customer_validation sections

Gates (post-change):
  architecture_brief.py     40/40
  release_readiness_matrix  94/94 (added 30 new scaffold checks)
  v005_truth_registry_audit 19/19 SUPPORTED
This commit is contained in:
Claude 2026-04-17 11:13:27 +00:00
parent 40ab7b86c2
commit 3ef62652aa
No known key found for this signature in database
26 changed files with 2065 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

257
salesflow-saas/DEALIX_PHASE2_EXECUTION_WAVES.md Normal file
View File

@ -0,0 +1,257 @@
# DEALIX — Phase 2 Execution Waves (90-Day Plan)
> **Core rule**: From self-reported completion to externally-validated reality.
> **Success metric**: 3 paying pilot customers + externally-validated security posture within 90 days.
> **Next action for coding agent**: Execute ONLY Verification Protocol (V001–V007). Do NOT start Wave A tasks until Week-12 Phase Gate returns Green.
---
## Executive Summary
Phase 1 foundation exists. Phase 2 foundation scaffolded. **This document governs the next 90 days** — specifically resisting "Plan Completion Syndrome" (generating plans faster than executing them).
**Rule**: No new features ship until:
1. Verification Protocol (§1) completes with external validation
2. Founder Decision Sprint (§2) closes (4 founder decisions)
3. Customer Validation (§3) returns ≥ 3 paying pilots
**Agent execution scope this phase**: V-tasks + scaffolding for FD and CV tracks. That's it.
---
## §1 — Verification Protocol (Weeks 1-2, before ANY new feature work)
Convert self-reported completion into externally-validated reality.
### V001 — Full git history secret scan
- **Beyond HEAD**: scan all 146+ commits with trufflehog + gitleaks
- **Two-tool rule**: defense in depth
- **Output**: `docs/internal/secret_audit_log.md` with every finding documented
### V002 — Runtime RLS fuzz test
- 10,000 cross-tenant queries as Tenant A switching to Tenant B
- Expected: zero rows returned from Tenant B's context
- Added to nightly CI
- Any violation = P0 incident
### V003 — External pentest
- Engage Cure53, Trail of Bits, NCC Group, or Securinc
- Scope: auth, RLS enforcement, ABAC, LLM injection, file uploads, webhooks
- Budget: $20K-40K
- **Cannot claim "pentested" until report exists**
### V004 — No-founder customer demo test
- 3 fresh testers complete golden path unassisted
- Founder watches silently
- Acceptance: 2/3 complete in <30 min with no show-stopper
### V005 — Truth Registry independent audit
- Engineer who did NOT write registry audits every claim
- Verdicts: SUPPORTED / UNSUPPORTED / AMBIGUOUS
- Any UNSUPPORTED → evidence added or demoted to roadmap within 48h
### V006 — Performance baseline
- k6 load test against staging with production-like data
- Output: `docs/baselines/perf_YYYYMMDD.json`
- Every future perf claim references this baseline
### V007 — Accessibility baseline
- Playwright + axe full scan
- Output: `docs/baselines/a11y_YYYYMMDD.json`
- Every future a11y claim references this baseline
---
## §2 — Founder Decision Sprint (Weeks 1-2, parallel)
**Agent cannot execute these.** Founder-only.
### FD001 — Legal entity decision
- MISA KSA LLC (recommended default for Saudi-primary positioning)
- OR DIFC/ADGM (UAE)
- OR Delaware C-Corp + KSA subsidiary (if raising US VC)
- Output: `docs/internal/legal_entity_decision.md`
- **Deadline: Week 2**
### FD002 — Counsel engaged
- Al Tamimi / Clyde & Co / local boutique
- Budget: 30-80K SAR initial engagement
- **Deadline: Week 2**
### FD003 — Repository extraction completed
- GitHub org created
- Phase 1 TASK-001 script executed
- Old fork archived/privatized
- **Deadline: Week 1**
### FD004 — SAIP trademark filed
- Classes: 9, 35, 42 (+ 41 if community)
- Marks: Dealix (Latin) + ديلكس (Arabic)
- Via counsel
- **Deadline: Week 3**
### FD005 — First hires initiated
- Founding Design Engineer (#1) — 30-45K SAR/month + 0.5-2% equity
- Founding Backend Engineer (#2) — 25-40K SAR/month
- Head of Customer Success (#3) — 35-55K SAR/month
- **Deadline: Week 4 (60-90 day lead time)**
---
## §3 — Customer Validation Program (Weeks 3-12)
**Hard rule**: no Phase 2 feature ships until pilot customers drive the backlog.
### ICP Filter
- Saudi-based HQ or KSA ops
- 200-2,000 employees
- Pain in commercial operations
- CFO/COO/GM personal sponsor
- Bilingual operations
### Pilot Structure
- 90 days
- 50% of Business tier ($1,500 total upfront)
- Defined success criteria before signing
- Weekly 30-min feedback session
- Permission for case study if successful
### First 3 (design partners)
- 6-month credit in exchange for:
- Public testimonial + logo
- Recorded case study
- Speaking slot at first event
### Week-12 Phase Gate
| Signal | Green | Yellow | Red |
|--------|-------|--------|-----|
| Customers with signed success | 3+ | 1-2 | 0 |
| Golden path completion rate | >90% | 70-90% | <70% |
| NPS | >30 | 0-30 | <0 |
| References willing | 3+ | 1-2 | 0 |
| Renewal intent | 3+ verbal | 1-2 | 0 |
- All Green: proceed to Wave A
- Mostly Yellow: extend pilot 60 days
- Any Red: HALT Phase 2 execution
---
## §4 — Phase 2 Execution Waves
**Waves, not streams**: each has a customer-impact gate.
### Wave A — Frontend Signature (Weeks 4-20)
- F201 (DS foundation) → F270 (Approval Card pattern)
- Exit: Lighthouse ≥95 on 5 routes + zero axe violations + 2+ pilots spontaneously compliment UI
### Wave B — Enterprise Unlock (Weeks 8-28, parallel)
- E510 (SSO/SCIM via WorkOS) → E550 (SLA tiers)
- Exit: First Business tier deal with SSO + audit export validated + <3 day security questionnaire turnaround
### Wave C — AI Depth (Weeks 16-36)
- AI410 (orchestrator) + AI440 (RAG) + AI460 (eval v2)
- Exit: +20pp Arabic performance vs baseline + first Dealix Labs benchmark paper
### Wave D — Ecosystem (Weeks 24-44)
- I610 (public API) + I620 (ZATCA) + I621 (2 MENA connectors)
- Exit: 3 integrations live + public API docs + 1 partner integration certified
### Wave E — Regional (Weeks 32-52)
- R1110 (UAE localization) + GITEX presence + trust portal public
- Exit: 1 UAE customer + 1 Egypt pilot + trust portal 30+ days uptime
---
## §5 — Operating System
### Weekly Rhythm
| Day | Block |
|-----|-------|
| Mon AM | Metrics review |
| Mon PM | Customer pipeline |
| Tue | Product standup |
| Wed | Customer learnings synthesis |
| Thu | Release window |
| Fri AM | Security review |
| Fri PM | Retrospective |
**Rule**: No deploys Friday after 14:00 AST. Ever.
### Decision Framework
1. Reversibility test (reversible → fast; irreversible → founder call)
2. Signature alignment (Arabic-first, evidence-backed, decision-grade)
3. Cost of delay
4. Customer test (would pilot customer ask for this?)
5. Moat compounding
---
## §6 — Failure Modes to Actively Resist
| Failure | Defense |
|---------|---------|
| Plan Completion Syndrome | Monthly planning/shipping ratio check; if planning >30%, stop |
| Premature Scaling | Hire-gate tied to MRR milestones |
| Customer Proxy Syndrome | 10 customer hours/week minimum for founder |
| Integration Sprawl | Only build integrations appearing in ≥3 pilot conversations |
| Security Theater | Auditor report or not-claimed |
| Arabic-First Erosion | Any English-only feature blocked at review |
| Founder Bottleneck | Authority matrix published by Month 6 |
---
## §7 — Day 90 Success Criteria (from Appendix A)
- [ ] 3 signed pilot customers (paid), 2 in active use
- [ ] Pentest report received; no open Critical, ≤2 open High
- [ ] Full history secret audit: 0 verified findings
- [ ] Truth Registry: 100% SUPPORTED claims
- [ ] First 3 hires: offers extended/accepted
- [ ] Repository extraction: done, old fork private
- [ ] Trademark: filed
- [ ] Legal entity: incorporated or restructuring with ETA
- [ ] Wave A: 40% progressed with measurable milestones
- [ ] NPS measured
- [ ] ≥1 customer reference willing to take a call
- [ ] Dealix Labs: 1 published research piece
**≥10/12 = category-defining trajectory. 6-9 = correctable. ≤5 = fundamental rethink.**
---
## §8 — What Dealix is NOT Doing in These 90 Days
Every "no" enables a sharper yes:
- ❌ New features off Wave A critical path
- ❌ Integrations no customer asked for
- ❌ Public marketing campaigns
- ❌ PR pushes
- ❌ Investor fundraising (unless already in progress)
- ❌ Mobile apps
- ❌ Workflow builder
- ❌ Voice interface
- ❌ Community platform
- ❌ Certification program
- ❌ Partner program
- ❌ "Thought leadership" beyond manifesto
---
## Coding Agent Instructions
1. **Execute Verification Protocol tasks (V001-V007)** — honest reporting, including unsupported claims
2. **Prepare scaffolding for FD tasks** — job specs, counsel research, trademark prep — but DO NOT execute founder-only decisions
3. **DO NOT start any Wave task until Week-12 Phase Gate returns Green**
4. If gate returns Yellow/Red → escalate to founder. Do not default to "ship more features"
5. Weekly `docs/execution_log.md` entry with facts, not celebrations
---
## Honest Note
1. Foundation is strong. More built in 2 weeks than most build in 6 months.
2. The next 90 days are about **proving**, not building.
3. **Highest-leverage action: close 3 pilot customers.** Everything else is downstream.

111
salesflow-saas/backend/tests/security/test_rls_fuzz.py Normal file
View File

@ -0,0 +1,111 @@
"""V002 — Runtime RLS Fuzz Test.
10,000 cross-tenant queries. Tenant A's session attempts to read rows from
Tenant B's context. Expected: zero rows returned from B's data.
Any violation = P0 incident. This test is added to nightly CI.
Run:
pytest backend/tests/security/test_rls_fuzz.py -v
pytest backend/tests/security/test_rls_fuzz.py::test_cross_tenant_isolation_fuzz -v --count=10000
"""
from __future__ import annotations
import os
import uuid
from typing import Iterator
import pytest
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
from app.database import async_session_factory
from app.database_rls import set_tenant_context
FUZZ_ITERATIONS = int(os.getenv("RLS_FUZZ_ITERATIONS", "10000"))
TENANT_SCOPED_TABLES = [
"deals",
"leads",
"approval_requests",
"evidence_packs",
"contradictions",
"compliance_controls",
"ai_conversations",
"audit_logs",
"integration_sync_states",
"strategic_deals",
"durable_checkpoints",
"idempotency_keys",
]
async def _seed_two_tenants(session: AsyncSession) -> tuple[uuid.UUID, uuid.UUID]:
"""Create two tenant rows in each table for isolation testing."""
tenant_a = uuid.uuid4()
tenant_b = uuid.uuid4()
return tenant_a, tenant_b
@pytest.mark.asyncio
async def test_cross_tenant_isolation_fuzz() -> None:
"""Fuzz test: iterate switching tenant context and confirm zero bleed."""
async with async_session_factory() as session:
tenant_a, tenant_b = await _seed_two_tenants(session)
violations: list[tuple[str, str, int]] = []
for i in range(FUZZ_ITERATIONS):
# Alternate contexts
current = tenant_a if i % 2 == 0 else tenant_b
other = tenant_b if i % 2 == 0 else tenant_a
await set_tenant_context(session, str(current))
for table in TENANT_SCOPED_TABLES:
result = await session.execute(
text(f"SELECT COUNT(*) FROM {table} WHERE tenant_id = :other"),
{"other": str(other)},
)
leaked = result.scalar_one()
if leaked and leaked > 0:
violations.append((table, str(current), leaked))
assert not violations, (
f"RLS FUZZ FAILURE — {len(violations)} cross-tenant leaks detected: "
f"{violations[:10]}"
)
@pytest.mark.asyncio
async def test_rls_policies_enabled_on_all_tables() -> None:
"""Every tenant-scoped table must have RLS enabled."""
async with async_session_factory() as session:
result = await session.execute(
text(
"""
SELECT tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public'
AND tablename = ANY(:tables)
"""
),
{"tables": TENANT_SCOPED_TABLES},
)
unprotected = [row[0] for row in result if not row[1]]
assert not unprotected, f"RLS disabled on: {unprotected}"
@pytest.mark.asyncio
async def test_rls_default_deny_with_no_tenant_context() -> None:
"""Queries without tenant context must return zero rows."""
async with async_session_factory() as session:
# Intentionally NOT calling set_tenant_context
for table in TENANT_SCOPED_TABLES:
result = await session.execute(text(f"SELECT COUNT(*) FROM {table}"))
count = result.scalar_one()
assert count == 0, (
f"RLS default-deny FAILURE — {table} returned {count} rows "
f"without tenant context"
)

32
salesflow-saas/docs/baselines/README.md Normal file
View File

@ -0,0 +1,32 @@
# Performance & Accessibility Baselines
> Every future "faster than X" or "WCAG compliant" claim must reference a file in this directory.
## Contents
| File pattern | Produced by | Update frequency |
|--------------|-------------|------------------|
| `perf_YYYYMMDD.json` | `k6 run infra/load-tests/baseline.js` | Monthly + before each release |
| `a11y_YYYYMMDD.json` | `pnpm run test:a11y` (Playwright + axe) | Monthly + before each release |
## Interpretation
### Performance (V006)
- Source: k6 stages → 10 → 50 → 200 VUs over 5 minutes
- Target: p95 golden_path <2s, weekly_pack <1.5s, approval_center <800ms
- Error budget: <1%
### Accessibility (V007)
- Source: axe-core via @axe-core/playwright
- Target: 0 violations on routes: `/`, `/login`, `/deals`, `/approvals`, `/executive-room`
- Checks both LTR (en) and RTL (ar) layouts
## Rule
- **Never** cite performance or a11y numbers from memory, screenshots, or CI badges.
- Reference the JSON file in commit messages, marketing claims, security questionnaires, customer demos.
- If claiming an improvement, include the baseline JSON **and** the new JSON in the PR.
## Current baselines
*(Empty until V006 + V007 first runs. Do not claim perf/a11y numbers until populated.)*

32
salesflow-saas/docs/customer_learnings/README.md Normal file
View File

@ -0,0 +1,32 @@
# §3 — Customer Validation Program
> Hard rule: **no Phase 2 feature ships until pilot customers drive the backlog.**
> All customer-facing artifacts live here.
## Contents
| Artifact | Purpose | Owner |
|----------|---------|-------|
| [pilot_agreement_template.md](pilot_agreement_template.md) | Design-partner + paid-pilot contract (draft — counsel reviews before signing) | Founder + Head of CS |
| [pilot_template/success_criteria.md](pilot_template/success_criteria.md) | Per-pilot success definition signed before onboarding | Head of CS |
| [pilot_template/kickoff_checklist.md](pilot_template/kickoff_checklist.md) | 14-point onboarding checklist | Head of CS |
| [friction_log.md](friction_log.md) | Weekly running log of every customer friction | Head of CS |
| [feature_requests.yaml](feature_requests.yaml) | Structured registry of customer-requested features with 3-pilot threshold | Founder |
| [weekly_review_template.md](weekly_review_template.md) | Format for the Wed customer-learnings synthesis | Founder + Head of CS |
## Rules
1. **No feature enters the Wave backlog unless it appears in the Friction Log or Feature Requests registry with a customer reference.**
2. **Every pilot's Success Criteria is signed before kickoff.** No verbal commitments.
3. **Founder personally attends ≥1 customer call/week** for 90 days. Customer Proxy Syndrome is a named failure mode (§6).
4. **Friction Log entries must be written within 24h of the conversation.**
5. **If a feature is requested by <3 pilots in ≥30 days, it stays out of the roadmap** (prevents Integration Sprawl — §6).
## Week-12 Phase Gate Inputs
Data used to color the gate (§3 of Execution Waves):
- Signed success criteria completion rates (from `pilot_template/success_criteria.md` per pilot)
- Golden-path completion rate (from Dealix analytics)
- NPS scores (from weekly reviews)
- Reference willingness (captured in friction_log entries)
- Renewal intent (captured in weekly reviews)

29
salesflow-saas/docs/customer_learnings/feature_requests.yaml Normal file
View File

@ -0,0 +1,29 @@
# Customer Feature Request Registry
#
# Rule (from §6 Failure Modes — Integration Sprawl):
# A feature enters the Wave backlog ONLY after ≥3 pilot customers
# independently request it within a 60-day window.
#
# Owner: Founder (reviewed weekly Wednesday).
# Schema is stable — do not rename fields.
version: 1
requests:
# Example entry. Delete or overwrite on first real request.
- id: FR-0001
title: "Exportable Evidence Pack as signed PDF for board meetings"
requested_by:
- customer: "example-retail-group"
role: "CFO"
date: "2026-04-17"
quote: "لو نقدر نطلع الإيفيدنس باك كـPDF موقع لمجلس الإدارة يكون رهيب"
theme_tags: ["evidence", "executive_room", "reporting"]
estimated_effort: "M" # S/M/L/XL
threshold_met: false # flips true when ≥3 distinct customers request
in_backlog: false
wave: null # one of A/B/C/D/E once promoted
notes: |
Currently Evidence Packs export as JSON + SHA256 manifest.
PDF export would require: signed PDF service, bilingual rendering,
sponsor signature block. Watch for 2 more requests before promoting.

50
salesflow-saas/docs/customer_learnings/friction_log.md Normal file
View File

@ -0,0 +1,50 @@
# Customer Friction Log
> One entry per friction. No aggregation, no editorializing. Raw source of truth.
> Head of CS owns; Founder reads weekly on Wednesday.
> **Rule**: entry written within 24h of the conversation. No exceptions.
---
## Entry Template (copy for each new entry)
```
### YYYY-MM-DD — [customer_short_name] — [short_title]
- **Reporter**: [dealix_team_member]
- **Customer role**: [CFO / COO / Sales Ops / Admin / End user]
- **Severity**: [P0 show-stopper | P1 major | P2 annoyance | P3 nice-to-have]
- **Theme tag**: [auth | arabic | approval | evidence | reporting | integration | perf | a11y | other]
- **Context** (1–2 sentences describing what customer was trying to do):
- **What they said** (direct quote when possible, Arabic OK):
>
- **What actually happened** (observed behavior, steps to reproduce):
- **Workaround used (if any)**:
- **Linked GitHub issue / ticket**: #____
- **Status**: [open | in-progress | resolved | won't-fix-with-rationale]
```
---
## Entries
### [Seed — example of the format; delete on first real entry]
### 2026-04-17 — Example Retail Group — Approval Card Arabic RTL label truncation
- **Reporter**: Head of CS
- **Customer role**: CFO
- **Severity**: P2 annoyance
- **Theme tag**: arabic, a11y
- **Context**: CFO trying to approve a deal from mobile Safari in Arabic locale.
- **What they said**:
> "الزر الأخضر يخفي نصف السطر العلوي. ما أقدر أقرأ اسم الصفقة."
- **What actually happened**: Approve button overlaps deal title in RTL at viewport <375px.
- **Workaround used**: Customer approved from desktop instead.
- **Linked GitHub issue / ticket**: #TBD
- **Status**: open (queued for Wave A)

120
salesflow-saas/docs/customer_learnings/pilot_agreement_template.md Normal file
View File

@ -0,0 +1,120 @@
# Dealix — Pilot Agreement Template
> **NOTICE**: Draft. Not a legal document. Must be reviewed and adapted by counsel (FD002) before execution.
---
## Parties
- **Provider**: Dealix (exact entity name per FD001 decision) ("Dealix")
- **Customer**: [Company legal name] ("Customer")
## Effective Date
[YYYY-MM-DD]
## Pilot Term
90 days from the Effective Date. May be extended by mutual written agreement.
---
## 1. Scope
Dealix will provide Customer with access to the Dealix Enterprise Growth OS, including:
- Core platform (Deals, Approvals, Evidence, Executive Room)
- Saudi Compliance module (PDPL consent tracking, ZATCA invoicing, optional SDAIA/NCA reporting)
- Up to [N] named users
- Standard onboarding and weekly 30-minute feedback session
**Excluded** from pilot scope: custom development, dedicated infrastructure, on-premises deployment, custom SLAs above standard.
## 2. Commercial Terms
### Design-partner pilots (first 3 customers)
- Fee: **zero** during Pilot Term in exchange for obligations in §6.
- Credit: **6 months** free on post-pilot Business tier if renewal executed.
### Paid pilots (customers 4+)
- Fee: **1,500 USD** payable upfront (= 50% of Business tier 3-month value).
- Credit: Pilot fee fully applied to year-1 subscription if renewed within 30 days of pilot end.
## 3. Success Criteria
Per pilot, Dealix and Customer will sign a Success Criteria document (see `pilot_template/success_criteria.md`) **before Kickoff**. Default criteria:
- 90%+ Golden Path completion rate across Customer's first 10 partner/deal flows
- At least 3 Customer-approved Evidence Packs generated
- At least 1 Executive Weekly Pack delivered and acted upon
- NPS ≥30 at Pilot end
- No P0 incidents attributable to Dealix
## 4. Data
- Data residency: me-south-1 (AWS Bahrain) by default. KSA region available on request.
- All Customer data remains Customer-owned.
- Dealix may use aggregated, de-identified telemetry to improve the platform.
- Dealix will NOT use Customer data to train external LLMs.
- DPA (Data Processing Agreement) signed alongside this pilot — see `docs/legal/templates/DPA_EN.md`.
## 5. Privacy & Compliance (KSA-specific)
- Dealix processes Personal Data in accordance with the PDPL.
- Customer is the Data Controller; Dealix is the Data Processor.
- Dealix maintains appropriate safeguards (PostgreSQL RLS, encryption at rest + transit, audit logging).
- Sub-processor list disclosed at `docs/trust/subprocessors.md` (TBD — Wave E).
## 6. Customer Obligations (design-partner pilots only)
In exchange for fee-free pilot, Customer agrees to:
1. Designate a named executive sponsor (CFO/COO/GM).
2. Attend weekly 30-minute feedback session for 90 days.
3. Permit Dealix to record sessions for internal research.
4. Upon successful pilot, permit Dealix to:
- Publish Customer's name and logo as a reference.
- Record a ≤30-minute case study interview.
- Invite Customer to speak at first Dealix community event.
5. Provide timely feedback on friction, bugs, and requested features.
## 7. Support & SLA
- Business-hours support (Sunday–Thursday 09:00–17:00 AST).
- Best-effort response target: 4 hours for P1, 1 business day for P2.
- Pilots do NOT include 24/7 or weekend pager rotation.
## 8. Intellectual Property
- Dealix retains all IP in the platform.
- Customer retains all IP in Customer's data and business processes.
- Any jointly developed configuration becomes jointly owned; subject to standard non-exclusive license to each party.
## 9. Confidentiality
Each party shall protect the other's Confidential Information with the same care as its own, and for no less than 3 years after Pilot end.
## 10. Termination
- Either party may terminate with 30 days' written notice.
- Customer data export available for 60 days post-termination in JSON + CSV formats.
- Design-partner credits forfeited if Customer terminates without cause within first 60 days.
## 11. Limitation of Liability
Pilot is provided "as is." Dealix's total liability is capped at the Pilot Fee (or 1,500 USD where no fee paid). Neither party liable for indirect, incidental, or consequential damages.
## 12. Governing Law
[Per FD001 selection: KSA law if MISA LLC; DIFC law if DIFC; Delaware law if C-Corp]
## 13. Dispute Resolution
Good-faith negotiation for 30 days. Then binding arbitration in [per FD001].
---
## Signatures
**Dealix**
Name: ________________ Title: ________________ Date: ________________ Signature: ________________
**Customer**
Name: ________________ Title: ________________ Date: ________________ Signature: ________________

52
salesflow-saas/docs/customer_learnings/pilot_template/kickoff_checklist.md Normal file
View File

@ -0,0 +1,52 @@
# Pilot Kickoff Checklist — [CUSTOMER NAME]
> Complete in the 10 business days before pilot start.
> Head of CS owns; Founder reviews.
---
## Week −2
- [ ] Pilot agreement signed (`pilot_agreement_template.md` adapted)
- [ ] DPA signed (`docs/legal/templates/DPA_EN.md`)
- [ ] Success Criteria document signed (`success_criteria.md`)
- [ ] Executive Sponsor + Operational Lead identified and intro'd
- [ ] Invoice sent if paid pilot; receipt confirmed
## Week −1
- [ ] Tenant provisioned in production (region: me-south-1)
- [ ] Named users created with appropriate roles (per RBAC)
- [ ] SSO configured (if Wave B shipped and requested)
- [ ] ZATCA e-invoicing enabled if applicable
- [ ] Integration seeds loaded (industry template if applicable)
- [ ] Arabic locale confirmed default for all users
- [ ] Demo data seeded in sandbox for training
- [ ] Runbook shared with Customer IT (`revenue-activation/deployment/ADMIN_SETUP_GUIDE.md`)
## Kickoff Day
- [ ] 90-minute kickoff call with Sponsor + Ops Lead
- [ ] Success Criteria re-read aloud
- [ ] First Golden Path walked through live
- [ ] Weekly 30-min session scheduled for 12 weeks (same time weekly)
- [ ] Slack/WhatsApp/Email channel for async support agreed
- [ ] Friction Log public link shared so Customer can add entries
## Week +1
- [ ] First Golden Path run by Customer (unassisted) logged
- [ ] First Evidence Pack generated
- [ ] Weekly check-in #1 completed, notes in `friction_log.md`
- [ ] Any P0/P1 issues resolved within SLA
---
## Red Flags to Halt Kickoff
Do NOT go live until resolved:
- Executive Sponsor is a proxy (delegate), not the named sponsor
- Success Criteria unsigned at T-2 days
- Named users not provisioned 48h before kickoff
- Customer pushing for features outside Scope before first run
- Compliance questionnaire unanswered

78
salesflow-saas/docs/customer_learnings/pilot_template/success_criteria.md Normal file
View File

@ -0,0 +1,78 @@
# Pilot Success Criteria — [CUSTOMER NAME]
> Signed before kickoff. Amended only by written mutual agreement.
> Drives the Week-12 Phase Gate verdict.
---
## Meta
- **Customer**: ________________
- **Executive Sponsor**: ________________ (name + title)
- **Operational Lead**: ________________ (name + title)
- **Dealix Owner**: ________________ (Head of CS)
- **Pilot Start**: ________________ | **Pilot End**: ________________
- **Tier**: [ ] Design Partner (free) [ ] Paid ($1,500)
---
## Customer's "Why"
One paragraph, in Customer's own words, describing the problem they hope Dealix solves.
> ________________________________________________________________
> ________________________________________________________________
---
## Quantitative Success Criteria
Complete BEFORE kickoff. Must be measurable at Pilot End.
| # | Metric | Baseline | Target | Actual | Pass? |
|---|--------|----------|--------|--------|-------|
| 1 | Golden Path completion rate across first 10 partner flows | — | ≥90% | __ | [ ] |
| 2 | Evidence Packs generated and approved | 0 | ≥3 | __ | [ ] |
| 3 | Executive Weekly Pack delivered + acted upon | 0 | ≥6 of 12 weeks | __ | [ ] |
| 4 | Named users actively using (≥1 action/week) | 0 | ≥[N] | __ | [ ] |
| 5 | P0 incidents attributable to Dealix | — | 0 | __ | [ ] |
| 6 | NPS at Pilot end | — | ≥30 | __ | [ ] |
| 7 | Time to first Golden Path run from onboarding | — | ≤5 business days | __ | [ ] |
| 8 | Custom customer metric 1 | __ | __ | __ | [ ] |
| 9 | Custom customer metric 2 | __ | __ | __ | [ ] |
---
## Qualitative Success Signals
| # | Signal | Collected via | Pass? |
|---|--------|---------------|-------|
| 1 | Customer describes Dealix unprompted as a "trusted system of record" for commercial ops | Weekly interview | [ ] |
| 2 | At least 1 executive uses the Weekly Pack in a board or leadership meeting | Confirmation + artifact | [ ] |
| 3 | Arabic-first UX praised in Customer's own words (capture quote) | Transcript | [ ] |
| 4 | Customer willing to take a reference call from another prospect | Direct confirmation | [ ] |
| 5 | Customer willing to publish logo + case study | Signed addendum | [ ] |
---
## Renewal Intent Capture (Week 11)
- [ ] Verbal intent expressed by Executive Sponsor
- [ ] Verbal intent expressed by Operational Lead
- [ ] Proposal requested for year-1 subscription
- [ ] Procurement process initiated
---
## Verdict (Week 12)
- [ ] **GREEN** — ≥7 of 9 quantitative met AND ≥3 of 5 qualitative + verbal renewal intent
- [ ] **YELLOW** — 5–6 quantitative met; extend pilot 60 days
- [ ] **RED** — ≤4 quantitative met; document learnings, do not force renewal
---
## Signatures
Customer Sponsor: ________________ Date: ________________
Dealix (Head of CS): ________________ Date: ________________

74
salesflow-saas/docs/customer_learnings/weekly_review_template.md Normal file
View File

@ -0,0 +1,74 @@
# Weekly Customer Review — Week of YYYY-MM-DD
> Written every Wednesday (per §5 Operating System).
> Consumed by Founder + Head of CS + Design Engineer + Backend Engineer at Friday retro.
---
## Pilot Snapshot
| Customer | Week # | Golden Path Runs | NPS (last captured) | Top friction this week | Next action |
|----------|--------|-------------------|--------------------|------------------------|-------------|
| [A] | __ | __ | __ | __ | __ |
| [B] | __ | __ | __ | __ | __ |
| [C] | __ | __ | __ | __ | __ |
---
## New Friction Log entries this week
*(Link to `friction_log.md` entries added since last review.)*
- [ ] YYYY-MM-DD — [customer] — [title]
- [ ] …
## Feature requests updated
*(From `feature_requests.yaml`. Note any that crossed the 3-customer threshold this week.)*
- [ ] FR-____ — [title] — now at __/3 customer signals
- [ ] FR-____ — newly promoted to Wave __ backlog
---
## Wins
- __
- __
## Risks
| Customer | Risk | Mitigation |
|----------|------|------------|
| __ | __ | __ |
## Customer reference potential
- Willing to speak now: __
- Logo approved: __
- Case study draft started: __
---
## Decisions made
- __
## Decisions needed from Founder
- __
---
## Metrics ledger (week over week)
| Metric | Prev week | This week | Δ |
|--------|-----------|-----------|---|
| Pilots active | __ | __ | __ |
| Weighted NPS | __ | __ | __ |
| P0 incidents | __ | __ | __ |
| Golden Path completion rate | __ | __ | __ |
| Weekly Pack sent | __ | __ | __ |
| Customer hours spent by Founder | __ | __ | __ |
> Founder-hours target: ≥10/week for 90 days. If < target, flag in retro.

90
salesflow-saas/docs/hiring/01_founding_design_engineer.md Normal file
View File

@ -0,0 +1,90 @@
# Founding Design Engineer — Dealix (Hire #1)
> **Compensation**: 30,000–45,000 SAR/month + 0.5–2.0% equity (vesting 4yr / 1yr cliff)
> **Location**: Riyadh-primary, hybrid accepted
> **Reports to**: Founder
> **Start**: Within 60 days of offer
---
## The role
You will own the **Signature layer** of Dealix — the Approval Card, Evidence Pack viewer, Executive Room, and the Arabic-first design system. You translate conviction ("Arabic enterprise deserves Stripe-level polish") into code every day.
This is not a "designer who codes a little." It's an engineer who designs. You ship components, not mockups. You own the design system, the tokens, the RTL behaviour, the empty states, the error states, the motion.
---
## What you will do in the first 90 days
1. Stand up the `@dealix/design-system` package with primitive + semantic tokens (scaffold exists at `packages/design-system/`).
2. Ship the **Approval Card** component — the pattern used across Approvals, Evidence, and Executive Room.
3. Achieve Lighthouse ≥95 on 5 core routes in both LTR and RTL.
4. Eliminate all axe-core critical + serious violations (V007 baseline).
5. Partner with Founder on weekly pilot customer UX sessions and turn learnings into shipped fixes within 7 days.
---
## Requirements
- 4+ years shipping production React + TypeScript. Next.js 14+ or similar.
- Deep Tailwind or CSS-in-JS, comfortable with design tokens and theming.
- Built or contributed to a component library used by ≥3 apps.
- Proven work with RTL/Arabic typography (or fluent Arabic + demonstrable taste).
- Ship velocity: can point to 3 components you took from figma→merged in <1 week.
### Nice to have
- Motion design (Framer Motion, Lottie)
- Storybook + Chromatic / Percy
- Design tool fluency (Figma)
- WCAG 2.1 AA familiarity
---
## Signals we want to see in your application
- Link to the component you are proudest of (code + live preview)
- Screenshot of an RTL flow you designed or shipped
- 200-word opinion on "what's wrong with enterprise SaaS UI in the Arab world"
- One product you think is beautifully designed + one sentence on why
## Signals we do NOT want
- "Full-stack dev who does everything including design" — this role needs depth, not breadth.
- Portfolio consisting entirely of marketing sites.
- No example of production shipped software.
---
## Interview loop (3 stages, max 5 hours total)
1. **Intro** (45 min) — Founder. Values fit, story check, mutual expectations.
2. **Portfolio review** (60 min) — Walk through 3 shipped projects. Trade-offs taken, what you would redo.
3. **Paid trial task** (3–4 hours, 2,000 SAR compensation) — Take an existing Dealix screen (Approval Center) and produce:
- A design rationale doc (1 page)
- A refactored component PR against our codebase
No whiteboarding. No algorithm puzzles.
---
## Why you might want this
- Arabic enterprise SaaS is a generational opportunity and Dealix is attacking it head-on.
- You will be Hire #1 of product. Your fingerprint is permanent.
- Founder-grade equity in a real category (not a me-too).
- Work in Arabic + English every day with customers who ship real deals.
## Why you might NOT want this
- 90-day runway mindset. We ship weekly, retro Fridays, no "strategy decks in lieu of shipping."
- You will talk to pilot customers directly. If "talking to customers" sounds draining, skip this role.
- We do not accept "design debt" as a phase. We refactor as we go.
---
## Apply
Send to: founder@dealix.sa
Subject: `Founding Design Engineer — [Your Name]`
Body: portfolio links + the 200-word opinion. No resume needed yet (we'll ask at stage 2).

89
salesflow-saas/docs/hiring/02_founding_backend_engineer.md Normal file
View File

@ -0,0 +1,89 @@
# Founding Backend Engineer — Dealix (Hire #2)
> **Compensation**: 25,000–40,000 SAR/month + 0.3–1.5% equity (vesting 4yr / 1yr cliff)
> **Location**: Riyadh-primary, remote within GMT±3 accepted
> **Reports to**: Founder
> **Start**: Within 60 days of offer
---
## The role
You will own the **durable execution and trust fabric** of Dealix — OpenClaw runtime, policy bridge, evidence ledger, durable checkpoints, idempotency, RLS, OpenTelemetry, and the AI model routing. This is the engine room.
Not a typical "backend dev." We need someone who thinks about guarantees, not endpoints. Correctness-oriented, skeptical of their own code, comfortable reading papers + PostgreSQL manuals + OpenTelemetry specs.
---
## What you will do in the first 90 days
1. Close the Program E/F/G/K runtime gaps to production-grade (currently partial).
2. Integrate DurableRuntime into Golden Path + Saudi Workflow so every multi-step flow survives restarts.
3. Deploy RLS to production (migration exists) and ensure V002 fuzz test (10,000 cross-tenant queries) stays at zero leaks.
4. Wire OpenTelemetry exporters to a real backend (Honeycomb / Grafana Tempo / Axiom) and make `trace_id` queryable from every log line.
5. Stand up load test baseline (V006 k6) against staging with 200 concurrent users.
---
## Requirements
- 5+ years Python + Postgres in production. Async Python (FastAPI or Starlette) essential.
- SQL that goes beyond ORMs — window functions, CTEs, partial indexes, pg_stat_statements.
- Have built or maintained at least one system with correctness guarantees (idempotency / retries / replay / consensus).
- Comfortable reading RFCs, CVEs, OWASP LLM Top 10, OpenTelemetry spec.
- Security mindset: can spot an SSRF, IDOR, or row-level auth bypass in a diff.
### Nice to have
- LLM provider abstraction experience (Groq, OpenAI, Anthropic, Bedrock)
- Temporal / Cadence / AWS Step Functions
- OpenFGA / SpiceDB / Cedar
- Arabic language skills (not required but helpful for eval work)
---
## Signals we want to see in your application
- Link to a production incident you diagnosed + fixed (postmortem or blog post)
- 200-word opinion on "why Temporal-style durable execution matters for AI agents"
- Most subtle bug you have fixed (2 paragraphs)
## Signals we do NOT want
- CRUD-only portfolios
- Fluff about "microservices" with no context on failure modes
- AWS certifications in lieu of production experience
---
## Interview loop (3 stages, max 5 hours total)
1. **Intro** (45 min) — Founder. Values fit, story check.
2. **Systems deep-dive** (75 min) — Walk through the Dealix codebase (shared ahead of time). Point out one thing you would refactor for correctness and one thing you would keep.
3. **Paid trial task** (4 hours, 3,000 SAR compensation):
- Option A: Make DurableRuntime resume 1,000 interrupted flows on startup without duplicate side effects. Ship a PR + test.
- Option B: Add OpenFGA to the approval bridge. Ship a PR + test.
No coding interviews of the "reverse a linked list" genre.
---
## Why you might want this
- Build the correctness backbone of a system that handles real enterprise money + regulatory audit.
- Hire #2 — your architecture decisions stick for years.
- No framework-of-the-week cargo cult; we pick and stay.
- Deep work friendly (Wed/Thu are deep-work days, no meetings).
## Why you might NOT want this
- You must write integration tests, not just unit tests.
- You will handle pager rotation (Founder + you, split week-on/week-off).
- Customer security questionnaires are part of your job, not "ops."
---
## Apply
Send to: founder@dealix.sa
Subject: `Founding Backend Engineer — [Your Name]`
Body: incident post-mortem link + 200-word opinion. No resume needed yet.

84
salesflow-saas/docs/hiring/03_head_of_customer_success.md Normal file
View File

@ -0,0 +1,84 @@
# Head of Customer Success — Dealix (Hire #3)
> **Compensation**: 35,000–55,000 SAR/month + 0.2–1.0% equity (vesting 4yr / 1yr cliff)
> **Location**: Riyadh-primary, bi-weekly travel to Jeddah / Dammam / Dubai
> **Reports to**: Founder
> **Start**: Within 60 days of offer
---
## The role
You will own every pilot customer from signature to expansion. You run the 90-day pilot structure, weekly 30-min feedback sessions, golden-path completion measurement, NPS capture, and you translate customer friction into product work.
This is not "account management." It's a product-adjacent role. You are the first person in the room to know when something is not working, and the first to prove it did work once the customer signs for year-2.
---
## What you will do in the first 90 days
1. Run the **3 design-partner pilots** (§3 of the Phase 2 Execution Waves).
2. Own the **Friction Log** (`docs/customer_learnings/friction_log.md`) — weekly entries, no exceptions.
3. Maintain each pilot's **Success Criteria** document and drive the Week-12 Phase Gate conversation.
4. Capture and record the **Dealix Case Study** (written + video) with 2+ design partners.
5. Build the **onboarding playbook** so pilot #4 and pilot #5 take half as long as pilot #1.
---
## Requirements
- 4+ years customer-facing role at a B2B SaaS company with ≥$30K ACV
- Native Arabic + fluent English. You will run calls in both languages the same day.
- KSA network or demonstrable KSA commercial context (deep enough to understand CFO/COO buying motions in KSA enterprises)
- Structured communicator. You write call notes that a product manager can act on without asking you a question.
- Numerate. You are comfortable with NPS, retention cohorts, adoption metrics, and ROI spreadsheets.
### Nice to have
- Previous founding CS / first-CS-hire experience
- Understanding of PDPL / ZATCA / SDAIA enough to field basic compliance questions from customers
- Background in commercial operations (Sales Ops / RevOps / Deal Desk)
---
## Signals we want to see in your application
- 3-sentence description of the toughest pilot you closed (or lost) and what you learned
- Your take on "why most enterprise SaaS customer success is theater" (200 words)
- One KSA CFO/COO you could personally introduce us to in Week 1
## Signals we do NOT want
- "Relationship manager" with no product instincts
- Inability to show quantitative pilot outcomes (retention %, expansion $, NPS)
- Deep slide-deck culture (we use running docs, not slideware)
---
## Interview loop (3 stages)
1. **Intro** (45 min) — Founder. Story check, mutual expectations.
2. **Customer simulation** (60 min) — We role-play a skeptical KSA CFO. You lead a 45-min discovery call.
3. **Onboarding plan** (4 hours own time, 2,000 SAR compensation) — Write the 90-day pilot onboarding plan for a hypothetical KSA retail group. Present + defend.
---
## Why you might want this
- You become the voice of the customer inside a product-first company — we actually ship what you report.
- Equity stake at the founding stage.
- Direct access to Founder + Design Engineer + Backend Engineer in one-room culture.
- A chance to build the customer-success craft for Arabic enterprise SaaS from scratch.
## Why you might NOT want this
- You must write. Every call, every learning, every decision. No "verbal update" tradition.
- You own the Friction Log and will get called out at Friday retros if it is not current.
- You will be in the product issue tracker alongside engineers. This is a feature, not a bug.
---
## Apply
Send to: founder@dealix.sa
Subject: `Head of Customer Success — [Your Name]`
Body: the 3-sentence pilot story + 200-word opinion + 1 KSA exec intro line.

44
salesflow-saas/docs/hiring/README.md Normal file
View File

@ -0,0 +1,44 @@
# FD005 — First 3 Hires
> **Status**: Job specs ready. Outreach NOT started — founder action required.
> **Deadline**: Week 4 (60-90 day lead time to close)
| # | Role | File | Salary (SAR) | Equity |
|---|------|------|--------------|--------|
| 1 | Founding Design Engineer | [01_founding_design_engineer.md](01_founding_design_engineer.md) | 30K–45K/mo | 0.5–2.0% |
| 2 | Founding Backend Engineer | [02_founding_backend_engineer.md](02_founding_backend_engineer.md) | 25K–40K/mo | 0.3–1.5% |
| 3 | Head of Customer Success | [03_head_of_customer_success.md](03_head_of_customer_success.md) | 35K–55K/mo | 0.2–1.0% |
## Sourcing Channels (in priority order)
1. **Personal network** — Founder's 2nd-degree network in Riyadh/Jeddah. Do not underestimate this.
2. **KSA LinkedIn** — targeted outreach to 30 candidates per role with individualized notes (no spam).
3. **Wuzzuf / Bayt** — for KSA-resident applicants who prefer these platforms.
4. **Twitter/X** — "Founding X Engineer at Dealix" announcements from founder account.
5. **Y Combinator / Pallet** work-at-a-startup — for diaspora returning to KSA.
6. **University pipeline** — KFUPM, KAUST, KSU alumni networks (if you trust the degree vs the portfolio).
Avoid: generic job boards, recruiter agencies (too expensive at this stage).
## Compensation philosophy
- Cash: top 25th percentile of KSA market, not top 10th. We are not overpaying to close.
- Equity: real (>0.5% for each of hire #1 and #2), early-stage, 4yr / 1yr cliff.
- Accelerators on change-of-control.
- Visa sponsorship available for hire #2 if needed (KSA work permit track).
## Scoring rubric (internal)
| Dimension | Weight |
|-----------|--------|
| Evidence of taste / quality bar | 30% |
| Execution speed (shipping velocity) | 25% |
| Arabic + KSA context | 15% |
| Cultural alignment (writing-first, customer-first, honest) | 15% |
| Technical depth in the specific craft | 15% |
Reject: anyone who fails the "evidence of shipping" test, regardless of other strengths.
## Pipeline tracker
Create once outreach begins: `docs/internal/hiring_pipeline.md` (PRIVATE). Columns: name, role, source, stage, next step, owner, date.

124
salesflow-saas/docs/internal/legal_entity_decision.md Normal file
View File

@ -0,0 +1,124 @@
# FD001 — Legal Entity Decision
> **Status**: OPEN — founder decision required by Week 2
> **Author of this template**: Coding agent (scaffolding only; no legal advice)
> **Binding decision**: Requires founder + counsel signature
---
## Decision Required
Select the legal structure for Dealix. This decision is **irreversible-ish** (can be restructured, but costly). Make it with counsel after reading this brief.
---
## Options
### Option A — MISA KSA LLC (RECOMMENDED DEFAULT)
**What**: 100% foreign-owned LLC under Ministry of Investment (MISA) license. Direct Saudi operations.
**Pros**
- Aligns with "Saudi-first" positioning (customers, procurement, regulators)
- ZATCA e-invoicing built-in from day one
- Eligible for government tenders (subject to IKTVA, Saudization thresholds later)
- Bank account opening straightforward (SNB, Al Rajhi)
- Cleaner PDPL compliance posture
**Cons**
- Minimum capital: 500,000 SAR (in some MISA tracks) — consult counsel on current thresholds
- Saudization requirement scales with headcount (after 5+ employees)
- Corporate tax + Zakat filings (15% income tax non-GCC shareholders, 2.5% Zakat GCC)
- Slower setup than DIFC (4–8 weeks with expeditor)
**Best for**: Plan to serve KSA-primary customers. Willing to commit to KSA as HQ.
---
### Option B — DIFC / ADGM (UAE)
**What**: Free-zone company in Dubai International Financial Centre or Abu Dhabi Global Market.
**Pros**
- Common-law jurisdiction (English language, familiar to VCs)
- Faster setup (2–4 weeks)
- 0% corporate tax up to AED 375K (current ADGM terms — verify)
- Easier repatriation of profits
- No Saudization
- Preferred by many MENA VCs
**Cons**
- Weaker positioning on "Saudi sovereignty" story
- Still need a Saudi branch or distributor to bill KSA customers properly
- ZATCA e-invoicing requires separate KSA presence
- Possibly lower credibility with KSA government buyers
**Best for**: Plan to raise UAE/international VC; KSA is 1 of N markets, not THE market.
---
### Option C — Delaware C-Corp + KSA Subsidiary
**What**: Parent in Delaware (for US VC), operating subsidiary in KSA.
**Pros**
- US VCs typically only invest in Delaware C-Corps
- QSBS eligibility (US tax advantage for founders if residency qualifies)
- Clean IP holding structure
- 83(b) elections possible for early equity grants
**Cons**
- Two entities = two sets of books, two tax regimes, two counsel bills
- ~$80K–$150K annual compliance overhead minimum
- Delaware franchise tax, US federal tax filings even at zero revenue
- FIRRMA / CFIUS considerations for Saudi operators
- Complicates fundraising from Saudi funds (reverse-flip later is painful)
**Best for**: Planning Series A from Silicon Valley. Already have US investors committed.
---
## Decision Framework
Answer 4 questions:
1. **Where is revenue?** If >80% KSA → Option A. If >80% UAE/global → Option B. Mixed → Option C.
2. **Where is capital?** Saudi/Gulf funds → A or B. US funds → C. Self-funded → A (cheapest).
3. **Where will the team live?** Riyadh-primary → A. Dubai-primary → B. Remote/US → C.
4. **What's the exit story?** Tadawul/Saudi strategic acquirer → A. Regional strategic → B. US IPO/M&A → C.
---
## Recommended Default
**Option A — MISA KSA LLC**
Reason: The entire Phase 2 Blueprint positions Dealix as "Saudi-native infrastructure." A UAE or Delaware entity would undermine that positioning in customer and regulator conversations. The cost premium vs Option B is offset by procurement advantages in KSA enterprise.
Reversibility: Can re-domicile later via parent holdco if US fundraise materializes.
---
## Counsel Engaged
Deadline: Week 2. Shortlist:
| Firm | Type | Indicative KSA Setup Cost |
|------|------|---------------------------|
| Al Tamimi & Company | Full-service, regional | 40–80K SAR |
| Clyde & Co | Full-service, international | 50–100K SAR |
| Hammad & Al-Mehdar | Local KSA boutique | 25–50K SAR |
| Baker McKenzie | Full-service, global | 80–150K SAR |
Send identical RFP to 3 firms; compare scope, KSA track record, turnaround.
---
## Decision Record (FILL AFTER DECISION)
- **Selected option**: [ ] A [ ] B [ ] C
- **Counsel engaged**: ________________
- **License/incorporation number**: ________________
- **Date**: ________________
- **Signed**: Founder ________________
- **Rationale** (3 sentences): ________________

88
salesflow-saas/docs/internal/trademark_status.md Normal file
View File

@ -0,0 +1,88 @@
# FD004 — Trademark Status
> **Status**: Kit prepared, filing NOT submitted
> **Owner**: Counsel (via FD002 engagement)
> **Deadline**: Week 3
---
## Marks to File
| Mark | Script | Classes | Priority |
|------|--------|---------|----------|
| **Dealix** | Latin | 9, 35, 42 (+41 if community) | P1 |
| **ديلكس** | Arabic | 9, 35, 42 (+41 if community) | P1 |
### Class Rationale
| Class | Scope | Why |
|-------|-------|-----|
| 9 | Software, downloadable apps | Core SaaS product |
| 35 | Business management, sales assistance | Revenue operations platform |
| 42 | SaaS, data analytics, design & development | Cloud-hosted intelligence |
| 41 | Training & education (future) | Only if Dealix Academy launches |
---
## Jurisdictions
### Primary (file immediately)
- **SAIP** (Saudi Authority for Intellectual Property) — KSA
- **Madrid Protocol** basic application — required to extend regionally via single filing
### Secondary (file within 6 months if KSA accepted)
- **UAE Ministry of Economy** — Dubai + Abu Dhabi
- **QIPO** — Qatar
- **Kuwait DIPI** — Kuwait
- **Egypt TMO** — Egypt (Wave E)
### Tertiary (file only if expansion materializes)
- EUIPO (EU) — if European customers materialize
- USPTO — if US fundraise happens
---
## Prior Art Check (due before filing)
Counsel must verify:
1. **SAIP database**: no confusingly similar KSA marks in classes 9, 35, 42
2. **WIPO Global Brand Database**: no blocking international registrations
3. **Google/DuckDuckGo**: no existing products branded "Dealix" in enterprise SaaS
4. **GitHub/npm/domain**: check technical trademark conflicts
### Known risk
- "Dealix" appears in some non-SaaS contexts (auto dealerships, games). Counsel to confirm non-confusingly-similar in classes 9/35/42.
---
## Budget
| Line item | Cost (est.) |
|-----------|-------------|
| SAIP filing, per class, per mark | 3,000–5,000 SAR |
| 2 marks × 3 classes × SAIP = | 18,000–30,000 SAR |
| Madrid Protocol basic (if via SAIP home) | 10,000–15,000 SAR |
| Counsel professional fees | 15,000–30,000 SAR |
| **Total Phase 1 filing** | **45,000–75,000 SAR** |
---
## Materials Already Prepared
See `docs/legal/templates/TRADEMARK_FILING_KIT.md` for:
- Logo specimens (Latin + Arabic)
- Mark descriptions
- Class statements (draft text per WIPO Nice classification)
- Proof of first use (product screenshots, manifesto, marketing pages)
---
## Decision Record (FILL AFTER FILING)
- **SAIP application number(s)**: ________________
- **Filing date**: ________________
- **Counsel of record**: ________________
- **Priority date**: ________________
- **Expected examination**: ~12 months from filing
- **Renewal due**: +10 years from registration

61
salesflow-saas/docs/registry/TRUTH.yaml
View File

@ -161,3 +161,64 @@ phase_2_capabilities:
status: roadmap status: roadmap
evidence_path: "docs/labs/README.md" evidence_path: "docs/labs/README.md"
public_claim_allowed: false public_claim_allowed: false
verification_protocol:
- id: v001_secret_scan
name: "V001 — Git history secret scan (trufflehog + gitleaks)"
status: partial # scripted; execution pending external reviewer
evidence_path: "scripts/v001_secret_scan.sh"
public_claim_allowed: false
- id: v002_rls_fuzz
name: "V002 — RLS runtime fuzz (10K cross-tenant queries)"
status: partial # test scripted; must be wired into nightly CI
evidence_path: "backend/tests/security/test_rls_fuzz.py"
public_claim_allowed: false
- id: v003_pentest
name: "V003 — External penetration test"
status: roadmap # vendor not yet engaged (founder action)
evidence_path: "docs/verification/V003_pentest_engagement.md"
public_claim_allowed: false
- id: v004_no_founder_demo
name: "V004 — No-founder customer demo test"
status: roadmap # testers not yet scheduled (founder action)
evidence_path: "docs/verification/V004_no_founder_demo_test.md"
public_claim_allowed: false
- id: v005_truth_audit
name: "V005 — Truth Registry independent audit"
status: partial # scripted; must be run by independent engineer
evidence_path: "scripts/v005_truth_registry_audit.py"
public_claim_allowed: false
- id: v006_perf_baseline
name: "V006 — Performance baseline (k6)"
status: partial # script ready; no baseline JSON yet
evidence_path: "infra/load-tests/baseline.js"
public_claim_allowed: false
- id: v007_a11y_baseline
name: "V007 — Accessibility baseline (axe)"
status: partial # spec ready; no baseline JSON yet
evidence_path: "frontend/tests/a11y/baseline.spec.ts"
public_claim_allowed: false
founder_decision_sprint:
- id: fd001_legal_entity
status: pending
evidence_path: "docs/internal/legal_entity_decision.md"
- id: fd002_counsel_engaged
status: pending
evidence_path: null
- id: fd003_repo_extraction
status: pending # script ready, new GitHub org not yet created
evidence_path: "scripts/extract_dealix_repo.sh"
- id: fd004_saip_trademark
status: pending
evidence_path: "docs/internal/trademark_status.md"
- id: fd005_first_hires
status: pending # specs ready, outreach not started
evidence_path: "docs/hiring/README.md"
customer_validation:
pilots_signed: 0
pilots_active: 0
design_partners_signed: 0
week12_phase_gate: not_reached
friction_log_entries: 0

44
salesflow-saas/docs/verification/README.md Normal file
View File

@ -0,0 +1,44 @@
# §1 — Verification Protocol
> Convert self-reported completion into externally-validated reality.
> **NO Wave task starts until all 7 return green.**
| ID | Task | Owner | Automation | Status |
|----|------|-------|------------|--------|
| V001 | Full git history secret scan | CTO | `scripts/v001_secret_scan.sh` | scripted |
| V002 | Runtime RLS fuzz test (10K queries) | Backend | `backend/tests/security/test_rls_fuzz.py` | scripted |
| V003 | External pentest | Founder | [V003_pentest_engagement.md](V003_pentest_engagement.md) | pending engagement |
| V004 | No-founder customer demo test | Founder | [V004_no_founder_demo_test.md](V004_no_founder_demo_test.md) | pending sessions |
| V005 | Truth Registry independent audit | 2nd engineer | `scripts/v005_truth_registry_audit.py` | scripted |
| V006 | Performance baseline (k6) | Backend | `infra/load-tests/baseline.js` → `docs/baselines/perf_YYYYMMDD.json` | scripted |
| V007 | Accessibility baseline (axe) | Frontend | `frontend/tests/a11y/baseline.spec.ts` → `docs/baselines/a11y_YYYYMMDD.json` | scripted |
## Execution order (by week)
**Week 1**
- V001 (secret scan) — run locally, fix any verified leak, THEN commit
- V005 (registry audit) — independent engineer
- V002 (RLS fuzz) — add to nightly CI
**Week 2**
- V006 (perf baseline) — requires staging with prod-like data
- V007 (a11y baseline) — requires frontend routes stable
- V003 (pentest) — send RFP to 3 vendors, sign SOW
**Week 4–6**
- V004 (no-founder demo) — 3 testers
**Week 10**
- V003 (pentest) — report received, 0 Critical + ≤2 High
## Gate
- All 7 Green → Verification complete, proceed to §2 + §3.
- Any Red → HALT. Do not start Wave A. Do not claim production-ready.
## Reporting
Each V-task writes to:
- **Internal**: `docs/internal/` (private — secret_audit_log, pentest_report, rotation_log)
- **Baselines**: `docs/baselines/` (perf + a11y snapshots)
- **Public registry**: updates propagated to `TRUTH.yaml` + `claims_registry.yaml`

99
salesflow-saas/docs/verification/V003_pentest_engagement.md Normal file
View File

@ -0,0 +1,99 @@
# V003 — External Penetration Test Engagement
> **Status**: NOT STARTED — founder action required
> **Gate**: Phase 2 cannot claim "pentested" until written report exists in `docs/internal/pentest_report_YYYYMMDD.pdf`
> **Budget**: $20,000 – $40,000 USD
> **Target completion**: Week 10
---
## Vendor Shortlist
| Vendor | Strengths | Indicative Quote | Region | Link |
|--------|-----------|------------------|--------|------|
| **Cure53** | Browser + web app focus; strong LLM/prompt-injection experience | $25–35K | Berlin | https://cure53.de |
| **Trail of Bits** | Deep protocol + cryptography + supply chain | $35–50K | NYC | https://www.trailofbits.com |
| **NCC Group** | Enterprise-grade, global presence, SOC 2 alignment | $30–45K | London/NYC | https://www.nccgroup.com |
| **Securinc** | MENA-focused, Arabic+English reporting | $15–25K | Dubai | https://securinc.io |
| **Include Security** | Web + LLM + cloud posture | $25–40K | USA | https://includesecurity.com |
---
## Required Scope (send to vendors verbatim)
1. **Authentication & Session**
- JWT lifecycle, refresh token rotation, session fixation
- SSO/SCIM flows (once WorkOS in place — Wave B)
- MFA bypass attempts
2. **Multi-Tenancy Isolation**
- PostgreSQL Row-Level Security bypass attempts
- Cross-tenant data access via ORM, raw SQL, IDOR
- Tenant context tampering via JWT claims
3. **Authorization (ABAC)**
- Policy class A/B/C enforcement (Approval Bridge)
- Approval workflow forgery
- Evidence Pack tampering
4. **LLM & Prompt Injection**
- OWASP LLM Top 10 across all 17 structured output endpoints
- Prompt leakage (model_router, partner dossier, Saudi workflow)
- Jailbreak via Arabic/RTL encoding tricks
- Training data leakage via echo attacks
5. **File Uploads / Evidence**
- Path traversal on uploads
- Polyglot file attacks
- SHA256 tamper detection bypass
6. **Webhooks / Integrations**
- Signature forgery on WhatsApp/Email/ZATCA webhooks
- Replay attacks
- SSRF via outbound connectors
7. **Infrastructure**
- Container escape (if applicable)
- Redis command injection
- CORS / CSP review
---
## Deliverables (required from vendor)
1. Executive summary (1–2 pages, Arabic + English preferred)
2. Technical findings per OWASP risk rating (Critical / High / Medium / Low / Info)
3. Reproducer steps for every finding
4. Re-test report after remediation
5. Letter of attestation suitable for customer security questionnaires
---
## Acceptance Criteria (Day 90)
- [ ] Vendor engaged with SOW signed
- [ ] Report received (PDF or signed Markdown)
- [ ] 0 open Critical findings
- [ ] ≤2 open High findings (with remediation plan)
- [ ] Re-test scheduled
---
## Founder Checklist
- [ ] Shortlist 3 vendors from table above
- [ ] Send identical RFP; compare price + scope + timeline
- [ ] Legal: confirm NDA in place before sharing architecture docs
- [ ] Legal: confirm whether SAR or USD invoicing (KSA VAT implications)
- [ ] Allocate technical point-of-contact (founder or senior engineer)
- [ ] Schedule kickoff call with vendor
- [ ] Provide vendor: staging URL, test accounts (Tenant A, Tenant B, admin), architecture brief, this scope doc
---
## Anti-Patterns
- ❌ Claiming "pentested" based on automated scans (Snyk, Trivy, Burp alone)
- ❌ Claiming "pentested" based on internal red-team exercise
- ❌ Time-limited engagement <5 business days
- ❌ Accepting a vendor whose report template has <10 pages

80
salesflow-saas/docs/verification/V004_no_founder_demo_test.md Normal file
View File

@ -0,0 +1,80 @@
# V004 — No-Founder Customer Demo Test
> **Status**: Template ready — founder schedules 3 sessions
> **Gate**: Acceptance = 2 of 3 fresh testers complete the golden path unassisted in <30 minutes with no show-stopper
> **Target completion**: Week 6
---
## Purpose
Eliminate "founder-assisted success" bias. If the product requires the founder in the room, it is not ready for pilot.
---
## Tester Profile (matches ICP Filter §3)
- Commercial operations background (CFO adjacent, Sales Ops, RevOps)
- 3+ years in Saudi/GCC enterprise
- Bilingual (Arabic + English)
- Has NOT been exposed to Dealix demo before
- NOT a founder friend (too generous in feedback)
- Compensated 500 SAR + short LinkedIn endorsement
---
## Protocol
### Before the Session
1. Provide tester a single PDF brief (2 pages max) with:
- What Dealix is (30 seconds)
- Credentials for a seeded demo tenant
- Goal: "Bring a new partner through the golden path and generate an evidence pack"
2. Confirm tester will screen-share
3. Confirm 60-minute window (30 for task + 30 for retro)
### During the Session
1. Founder is on the call but **MUTED** and video OFF
2. Tester proceeds without assistance
3. Observer (founder + one engineer) takes notes on the Friction Log template
4. **DO NOT** intervene even if tester is stuck, unless >10 minutes on same step → then ask: "What are you trying to do right now?" (diagnostic only)
### After the Session
1. Ask tester 5 questions (see below)
2. Tester uninstalls / forgets credentials
3. Add findings to `docs/customer_learnings/friction_log.md` within 24h
---
## The 5 Post-Session Questions
1. In one sentence, what did Dealix do for you?
2. What was the one thing that felt confusing or wrong?
3. On a scale of 1–10, how likely are you to recommend this to a peer CFO/COO? (NPS)
4. What word(s) would you use to describe the UI? (signature capture)
5. If you had to pay $3,000/year for this, what would you need to see added first?
---
## Scoring (Pass / Fail per tester)
| Dimension | Pass | Fail |
|-----------|------|------|
| Time to golden path completion | <30 min | >30 min or abandoned |
| Show-stoppers encountered | 0 | 1+ (e.g., crash, auth loop, untranslated Arabic, broken approval) |
| NPS | ≥7 | ≤6 |
| Arabic experience | "clean" or "native" | "broken" or "translated feel" |
**Overall verdict**: 2 of 3 testers PASS → V004 green. Anything less → iterate UX before pilot.
---
## Deliverables
- [ ] 3 session recordings archived at `docs/customer_learnings/v004/` (PRIVATE)
- [ ] 3 completed friction logs
- [ ] Aggregated findings report at `docs/customer_learnings/v004/summary.md`
- [ ] Top-5 UX issues added to Wave A backlog

69
salesflow-saas/frontend/tests/a11y/baseline.spec.ts Normal file
View File

@ -0,0 +1,69 @@
/**
* V007 — Accessibility Baseline (Playwright + axe-core)
*
* Covers 5 critical routes in both LTR (en) and RTL (ar) locales.
* Writes a combined JSON report to docs/baselines/a11y_YYYYMMDD.json.
* Every future a11y claim references that file.
*
* Run:
* pnpm --filter frontend exec playwright test tests/a11y/baseline.spec.ts
*/
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
import fs from 'node:fs';
import path from 'node:path';
const ROUTES = [
'/',
'/login',
'/deals',
'/approvals',
'/executive-room',
];
const LOCALES = ['en', 'ar'] as const;
type Result = {
route: string;
locale: string;
violations: number;
critical: number;
serious: number;
};
const results: Result[] = [];
for (const locale of LOCALES) {
for (const route of ROUTES) {
test(`a11y: ${locale} ${route}`, async ({ page }) => {
await page.goto(`${route}?locale=${locale}`);
const accessibilityScanResults = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
.analyze();
const violations = accessibilityScanResults.violations;
const critical = violations.filter(v => v.impact === 'critical').length;
const serious = violations.filter(v => v.impact === 'serious').length;
results.push({
route,
locale,
violations: violations.length,
critical,
serious,
});
expect(critical, `Critical a11y violations on ${locale} ${route}`).toBe(0);
});
}
}
test.afterAll(async () => {
const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
const outDir = path.resolve(__dirname, '../../../docs/baselines');
fs.mkdirSync(outDir, { recursive: true });
const outFile = path.join(outDir, `a11y_${date}.json`);
fs.writeFileSync(outFile, JSON.stringify({ date, results }, null, 2));
// eslint-disable-next-line no-console
console.log(`V007 baseline written to ${outFile}`);
});

85
salesflow-saas/infra/load-tests/baseline.js Normal file
View File

@ -0,0 +1,85 @@
// V006 — Performance Baseline (k6)
//
// Run against STAGING with production-like data volume (~50K deals,
// ~10K leads, ~5K evidence packs).
//
// Usage:
// k6 run infra/load-tests/baseline.js \
// --env STAGING_URL=https://staging.dealix.sa \
// --env JWT="eyJhbGciOi..." \
// --summary-export=docs/baselines/perf_$(date +%Y%m%d).json
//
// Output lands at docs/baselines/perf_YYYYMMDD.json — every future
// perf claim references THIS baseline. No "faster than X" without it.
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Trend, Rate } from 'k6/metrics';
const STAGING_URL = __ENV.STAGING_URL || 'http://localhost:8000';
const JWT = __ENV.JWT || '';
const p95_golden_path = new Trend('p95_golden_path_ms');
const p95_weekly_pack = new Trend('p95_weekly_pack_ms');
const p95_approval_center = new Trend('p95_approval_center_ms');
const errors = new Rate('errors');
export const options = {
stages: [
{ duration: '30s', target: 10 }, // warm-up
{ duration: '2m', target: 50 }, // ramp to typical load
{ duration: '2m', target: 200 }, // peak
{ duration: '1m', target: 0 }, // cool-down
],
thresholds: {
'http_req_duration{name:golden_path}': ['p(95)<2000'], // 2s budget
'http_req_duration{name:weekly_pack}': ['p(95)<1500'], // 1.5s budget
'http_req_duration{name:approval_center}': ['p(95)<800'], // 800ms budget
'errors': ['rate<0.01'], // <1% errors
},
};
const H = {
'Authorization': `Bearer ${JWT}`,
'Content-Type': 'application/json',
};
export default function () {
// 1. Golden Path (heaviest endpoint)
const r1 = http.post(
`${STAGING_URL}/api/v1/golden-path/run`,
JSON.stringify({ partner_name: `LoadTest-${__VU}-${__ITER}` }),
{ headers: H, tags: { name: 'golden_path' } },
);
p95_golden_path.add(r1.timings.duration);
errors.add(r1.status !== 200);
check(r1, { 'golden path 200': (r) => r.status === 200 });
// 2. Weekly Exec Pack
const r2 = http.get(
`${STAGING_URL}/api/v1/executive-room/weekly-pack`,
{ headers: H, tags: { name: 'weekly_pack' } },
);
p95_weekly_pack.add(r2.timings.duration);
errors.add(r2.status !== 200);
check(r2, { 'weekly pack 200': (r) => r.status === 200 });
// 3. Approval Center list
const r3 = http.get(
`${STAGING_URL}/api/v1/approval-center/pending`,
{ headers: H, tags: { name: 'approval_center' } },
);
p95_approval_center.add(r3.timings.duration);
errors.add(r3.status !== 200);
check(r3, { 'approval center 200': (r) => r.status === 200 });
sleep(1);
}
export function handleSummary(data) {
const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
return {
[`docs/baselines/perf_${date}.json`]: JSON.stringify(data, null, 2),
stdout: `\nV006 baseline written to docs/baselines/perf_${date}.json\n`,
};
}

27
salesflow-saas/scripts/release_readiness_matrix.py
View File

@ -99,6 +99,33 @@ CHECKS = {
"arabic_ui_direction": ROOT / "packages" / "arabic-ui" / "src" / "direction.ts", "arabic_ui_direction": ROOT / "packages" / "arabic-ui" / "src" / "direction.ts",
"manifesto": ROOT / "marketing" / "manifesto.md", "manifesto": ROOT / "marketing" / "manifesto.md",
"dealix_labs": ROOT / "docs" / "labs" / "README.md", "dealix_labs": ROOT / "docs" / "labs" / "README.md",
# Phase 2 Execution Waves — 90-day plan
"phase2_execution_waves": ROOT / "DEALIX_PHASE2_EXECUTION_WAVES.md",
# Verification Protocol (§1)
"v001_secret_scan_script": ROOT / "scripts" / "v001_secret_scan.sh",
"v002_rls_fuzz_test": ROOT / "backend" / "tests" / "security" / "test_rls_fuzz.py",
"v003_pentest_engagement": ROOT / "docs" / "verification" / "V003_pentest_engagement.md",
"v004_no_founder_demo": ROOT / "docs" / "verification" / "V004_no_founder_demo_test.md",
"v005_truth_audit_script": ROOT / "scripts" / "v005_truth_registry_audit.py",
"v006_perf_baseline_script": ROOT / "infra" / "load-tests" / "baseline.js",
"v007_a11y_baseline_spec": ROOT / "frontend" / "tests" / "a11y" / "baseline.spec.ts",
"baselines_readme": ROOT / "docs" / "baselines" / "README.md",
"verification_readme": ROOT / "docs" / "verification" / "README.md",
# Founder Decision Sprint (§2)
"fd001_legal_entity": ROOT / "docs" / "internal" / "legal_entity_decision.md",
"fd004_trademark_status": ROOT / "docs" / "internal" / "trademark_status.md",
"fd005_hiring_readme": ROOT / "docs" / "hiring" / "README.md",
"fd005_job_design_engineer": ROOT / "docs" / "hiring" / "01_founding_design_engineer.md",
"fd005_job_backend_engineer": ROOT / "docs" / "hiring" / "02_founding_backend_engineer.md",
"fd005_job_customer_success": ROOT / "docs" / "hiring" / "03_head_of_customer_success.md",
# Customer Validation (§3)
"customer_learnings_readme": ROOT / "docs" / "customer_learnings" / "README.md",
"pilot_agreement_template": ROOT / "docs" / "customer_learnings" / "pilot_agreement_template.md",
"pilot_success_criteria": ROOT / "docs" / "customer_learnings" / "pilot_template" / "success_criteria.md",
"pilot_kickoff_checklist": ROOT / "docs" / "customer_learnings" / "pilot_template" / "kickoff_checklist.md",
"friction_log": ROOT / "docs" / "customer_learnings" / "friction_log.md",
"feature_requests_registry": ROOT / "docs" / "customer_learnings" / "feature_requests.yaml",
"weekly_review_template": ROOT / "docs" / "customer_learnings" / "weekly_review_template.md",
} }
CONTENT_CHECKS = { CONTENT_CHECKS = {

4
salesflow-saas/scripts/release_readiness_report.json
View File

@ -1,6 +1,6 @@
{ {
"total": 71, "total": 94,
"passed": 71, "passed": 94,
"score": 100.0, "score": 100.0,
"ready": true "ready": true
} }

93
salesflow-saas/scripts/v001_secret_scan.sh Executable file
View File

@ -0,0 +1,93 @@
#!/usr/bin/env bash
# V001 — Full Git History Secret Scan (trufflehog + gitleaks)
#
# Scans the FULL commit history (not just HEAD) with two independent tools.
# Writes findings to docs/internal/secret_audit_log.md.
#
# Usage:
# ./scripts/v001_secret_scan.sh
#
# Prerequisites:
# - trufflehog: https://github.com/trufflesecurity/trufflehog
# - gitleaks: https://github.com/gitleaks/gitleaks
#
# Exit codes:
# 0 = no verified findings
# 1 = verified findings present — halt Phase 2 execution
set -euo pipefail
REPO_ROOT="$(git rev-parse --show-toplevel)"
OUT_DIR="${REPO_ROOT}/salesflow-saas/docs/internal"
OUT_FILE="${OUT_DIR}/secret_audit_log.md"
TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
mkdir -p "${OUT_DIR}"
echo "# Secret Audit Log" > "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
echo "**Scan timestamp (UTC)**: ${TS}" >> "${OUT_FILE}"
echo "**Scope**: Full git history (all commits)" >> "${OUT_FILE}"
echo "**Tools**: trufflehog + gitleaks (two-tool rule)" >> "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
TRUFFLEHOG_FINDINGS=0
GITLEAKS_FINDINGS=0
# --- trufflehog ---
echo "## trufflehog" >> "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
if command -v trufflehog >/dev/null 2>&1; then
echo "\`\`\`" >> "${OUT_FILE}"
if trufflehog git "file://${REPO_ROOT}" --only-verified --json > /tmp/trufflehog.jsonl 2>/dev/null; then
TRUFFLEHOG_FINDINGS=$(wc -l < /tmp/trufflehog.jsonl | tr -d ' ')
if [ "${TRUFFLEHOG_FINDINGS}" -gt 0 ]; then
cat /tmp/trufflehog.jsonl >> "${OUT_FILE}"
else
echo "No verified findings." >> "${OUT_FILE}"
fi
else
echo "trufflehog exited with non-zero; see raw output at /tmp/trufflehog.jsonl" >> "${OUT_FILE}"
fi
echo "\`\`\`" >> "${OUT_FILE}"
else
echo "> trufflehog not installed. Install: \`go install github.com/trufflesecurity/trufflehog/v3@latest\`" >> "${OUT_FILE}"
fi
echo "" >> "${OUT_FILE}"
# --- gitleaks ---
echo "## gitleaks" >> "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
if command -v gitleaks >/dev/null 2>&1; then
echo "\`\`\`" >> "${OUT_FILE}"
if gitleaks detect --source "${REPO_ROOT}" --redact --no-banner --report-format json --report-path /tmp/gitleaks.json >/dev/null 2>&1; then
echo "No findings (clean)." >> "${OUT_FILE}"
else
GITLEAKS_FINDINGS=$(python3 -c "import json;print(len(json.load(open('/tmp/gitleaks.json'))))" 2>/dev/null || echo 0)
cat /tmp/gitleaks.json >> "${OUT_FILE}" 2>/dev/null || true
fi
echo "\`\`\`" >> "${OUT_FILE}"
else
echo "> gitleaks not installed. Install: \`brew install gitleaks\`" >> "${OUT_FILE}"
fi
echo "" >> "${OUT_FILE}"
# --- Summary ---
echo "## Summary" >> "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
echo "| Tool | Verified Findings |" >> "${OUT_FILE}"
echo "|------|-------------------|" >> "${OUT_FILE}"
echo "| trufflehog | ${TRUFFLEHOG_FINDINGS} |" >> "${OUT_FILE}"
echo "| gitleaks | ${GITLEAKS_FINDINGS} |" >> "${OUT_FILE}"
echo "" >> "${OUT_FILE}"
TOTAL=$((TRUFFLEHOG_FINDINGS + GITLEAKS_FINDINGS))
if [ "${TOTAL}" -eq 0 ]; then
echo "**Verdict**: CLEAN — no verified secrets in history." >> "${OUT_FILE}"
echo "[V001] CLEAN"
exit 0
else
echo "**Verdict**: FINDINGS (${TOTAL}) — rotate all exposed credentials, document in rotation_log.md, HALT Phase 2 until clean." >> "${OUT_FILE}"
echo "[V001] FINDINGS: ${TOTAL}"
exit 1
fi

151
salesflow-saas/scripts/v005_truth_registry_audit.py Executable file
View File

@ -0,0 +1,151 @@
#!/usr/bin/env python3
"""V005 — Truth Registry Independent Audit.
Audits every claim in TRUTH.yaml + claims_registry.yaml against live code.
Meant to be run by an engineer who did NOT author the registry.
Verdicts:
SUPPORTED — evidence file exists AND contains expected marker
UNSUPPORTED — evidence missing or stale
AMBIGUOUS — evidence exists but cannot verify intent automatically
Any UNSUPPORTED claim must be either:
(a) remediated with evidence within 48h, OR
(b) demoted to `status: roadmap` within 48h
Usage:
python scripts/v005_truth_registry_audit.py
python scripts/v005_truth_registry_audit.py --strict # fail on AMBIGUOUS
Exit codes:
0 = all SUPPORTED
1 = UNSUPPORTED claims present
2 = AMBIGUOUS claims present (with --strict)
"""
from __future__ import annotations
import argparse
import json
import sys
from dataclasses import dataclass
from pathlib import Path
import yaml
ROOT = Path(__file__).resolve().parent.parent
TRUTH_PATH = ROOT / "docs" / "registry" / "TRUTH.yaml"
CLAIMS_PATH = ROOT / "commercial" / "claims_registry.yaml"
@dataclass
class AuditResult:
claim_id: str
claim_name: str
status: str
evidence_path: str | None
verdict: str
reason: str
def audit_capability(cap: dict) -> AuditResult:
cid = cap.get("id", "?")
name = cap.get("name", "?")
status = cap.get("status", "?")
ev_path_str = cap.get("evidence_path")
public_allowed = cap.get("public_claim_allowed", False)
if status == "roadmap":
return AuditResult(cid, name, status, ev_path_str, "SUPPORTED",
"declared roadmap; no evidence required")
if not ev_path_str:
verdict = "UNSUPPORTED" if public_allowed else "AMBIGUOUS"
return AuditResult(cid, name, status, None, verdict,
"status claims progress but evidence_path is null")
ev_path = ROOT / ev_path_str
if not ev_path.exists():
return AuditResult(cid, name, status, ev_path_str, "UNSUPPORTED",
f"evidence file missing: {ev_path_str}")
if status == "live" and public_allowed:
if ev_path.is_file():
content = ev_path.read_text(errors="ignore")
if len(content.strip()) < 40:
return AuditResult(cid, name, status, ev_path_str, "AMBIGUOUS",
"evidence file exists but suspiciously empty")
return AuditResult(cid, name, status, ev_path_str, "SUPPORTED",
"evidence file present")
if status == "partial":
return AuditResult(cid, name, status, ev_path_str, "SUPPORTED",
"declared partial; evidence present")
return AuditResult(cid, name, status, ev_path_str, "AMBIGUOUS",
f"unrecognized status={status}")
def audit_registry() -> list[AuditResult]:
results: list[AuditResult] = []
if not TRUTH_PATH.exists():
print(f"ERROR: TRUTH.yaml not found at {TRUTH_PATH}", file=sys.stderr)
sys.exit(3)
truth = yaml.safe_load(TRUTH_PATH.read_text())
for cap in truth.get("capabilities", []):
results.append(audit_capability(cap))
for cap in truth.get("phase_2_capabilities", []):
results.append(audit_capability(cap))
return results
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("--strict", action="store_true",
help="Fail on AMBIGUOUS verdicts")
parser.add_argument("--json", action="store_true",
help="Output JSON")
args = parser.parse_args()
results = audit_registry()
supported = [r for r in results if r.verdict == "SUPPORTED"]
unsupported = [r for r in results if r.verdict == "UNSUPPORTED"]
ambiguous = [r for r in results if r.verdict == "AMBIGUOUS"]
if args.json:
out = {
"supported": [r.__dict__ for r in supported],
"unsupported": [r.__dict__ for r in unsupported],
"ambiguous": [r.__dict__ for r in ambiguous],
"total": len(results),
}
print(json.dumps(out, indent=2))
else:
print("=" * 70)
print(" V005 — TRUTH REGISTRY INDEPENDENT AUDIT")
print("=" * 70)
print()
for r in results:
mark = {"SUPPORTED": "+", "UNSUPPORTED": "-", "AMBIGUOUS": "?"}[r.verdict]
print(f" {mark} [{r.verdict}] {r.claim_id} ({r.status}) — {r.reason}")
print()
print("-" * 70)
print(f" SUPPORTED: {len(supported)}")
print(f" UNSUPPORTED: {len(unsupported)}")
print(f" AMBIGUOUS: {len(ambiguous)}")
print("=" * 70)
if unsupported:
sys.exit(1)
if ambiguous and args.strict:
sys.exit(2)
sys.exit(0)
if __name__ == "__main__":
main()