# CASAN — Workflow & Full Pipeline (biểu đồ trực quan)

> Biểu đồ vẽ bằng **Mermaid** (VS Code + Markdown Preview Mermaid hoặc GitHub render trực tiếp).
> Gồm: **1 biểu đồ FULL** + các biểu đồ nhỏ zoom vào từng harness trọng tâm (H4·H5·H6) và luồng tự chấm điểm.

---

## 1. BIỂU ĐỒ FULL — AI-SDLC Pipeline bọc trong CASAN Harness

> Mỗi bước (STEP) là **một AI agent**. Mọi lời gọi agent **đi xuyên qua 7 harness** rồi mới sinh ra artifact. Có 2 vòng lặp tự sửa: review-spec và BACK-TO-PLAN.

```mermaid
flowchart TB
    IN["📥 INPUT
okr-requirement.md · technical_architecture.md"]

    subgraph BOSS["🧠 Orchestrator: okr.bossbuiltin"]
      direction TB
      S1["STEP 1 · okr.srs → SRS"]
      S2["STEP 2 · okr.bd → BD (外部設計)"]
      S3["STEP 3 · speckit.specify → spec.md"]
      S4["STEP 4 · speckit.clarify"]
      S5{"STEP 5 · okr.reviewspec
🔄 auto-retry"}
      S6["STEP 6 · speckit.plan → plan.md"]
      S7{"STEP 7 · okr.reviewplan
🔄 BACK-TO-PLAN"}
      S8["STEP 8 · okr.dd → DD (内部設計)"]
      S8b["STEP 8b · okr.testkit → gen-testcases"]
      S9["STEP 9 · speckit.tasks → tasks.md"]
      S10["STEP 10 · speckit.implement 🔄"]
      S11{"STEP 11 · okr.reviewcode 🔄"}
      S12{"STEP 12 · okr.testkit run-tests"}
      S13["STEP 13 · Deploy: build BE+FE, launch UI"]

      S1 --> S2 --> S3 --> S4 --> S5
      S5 -- REJECTED --> S3
      S5 -- APPROVED --> S6 --> S7
      S7 -- REJECTED --> S6
      S7 -- APPROVED --> S8 --> S8b --> S9 --> S10 --> S11
      S11 -- REJECTED --> S10
      S11 -- APPROVED --> S12
      S12 -- FAIL --> S6
      S12 -- PASS --> S13
    end

    subgraph HARNESS["🛡️ CASAN HARNESS — mọi agent call đi qua"]
      direction LR
      H1["H1 Context"]:::ctx
      H2["H2 Tool"]:::tool
      H3["H3 Eval"]:::eval
      H4["H4 Security"]:::sec
      H5["H5 Governance"]:::gov
      H6["H6 AgentOps"]:::ops
      H7["H7 Orchestration"]:::orch
    end

    OUT["📤 OUTPUT
backend/ + frontend/ (source code)
+ EVIDENCE: audit chain · cost metrics · test reports"]

    IN --> BOSS
    BOSS -. "mỗi step gọi agent
đi xuyên harness" .-> HARNESS
    HARNESS -. "gate: APPROVE / REJECT / BLOCK" .-> BOSS
    BOSS --> OUT

    classDef sec fill:#ffe0e0,stroke:#c0392b,stroke-width:2px;
    classDef gov fill:#e0e8ff,stroke:#2c3e91,stroke-width:2px;
    classDef ops fill:#e0ffe8,stroke:#1e8449,stroke-width:2px;
    classDef ctx fill:#fff6e0,stroke:#b9770e;
    classDef tool fill:#fff6e0,stroke:#b9770e;
    classDef eval fill:#fff6e0,stroke:#b9770e;
    classDef orch fill:#f0e0ff,stroke:#6c3483;
```

**Đọc biểu đồ:** Input → Boss chạy 13 bước; mỗi bước gọi agent **đi qua 7 harness** (kiểm soát); harness trả verdict APPROVE/REJECT/BLOCK → Boss quyết đi tiếp hay lặp lại (STEP5, STEP7 BACK-TO-PLAN, STEP11, STEP12). Kết quả: source code + **evidence chứng minh được**.

---

## 2. Zoom: MỘT LỜI GỌI AGENT đi qua harness thế nào (sequence)

> 3 harness trọng tâm **H4 · H5 · H6** nằm ngay trên đường thực thi (không đứng bên lề).

```mermaid
sequenceDiagram
    autonumber
    participant Boss as 🧠 Boss (casan-step.mjs)
    participant HS as casan-harness.sh
    participant H4 as 🔴 H4 security-check
    participant MR as model-router → model-call.py
    participant OL as 🤖 Ollama ornith:9b
    participant H6 as 🟢 H6 telemetry
    participant H5 as 🔵 H5 audit chain
    participant H7 as 🟣 H7 checkpoint

    Boss->>HS: chạy step (input, output)
    HS->>H4: scan input (injection/secret/PII)
    alt phát hiện tấn công
        H4-->>Boss: BLOCKED rc=2 (fail-closed)
    else an toàn
        H4->>MR: prompt đã làm sạch
        MR->>OL: classify / judge / generate
        OL-->>MR: verdict + token thật
        MR->>H6: ghi provider-usage.jsonl (tokens)
        MR->>H5: ghi audit.jsonl (hash-chain + ký RSA)
        H7->>H7: checkpoint TRƯỚC khi ghi đè
        H5-->>Boss: verdict APPROVED/REJECTED
        alt REJECTED
            H7-->>Boss: rollback → restore file gốc
        end
    end
```

---

## 3. Zoom H4 — Security (regex + semantic)

```mermaid
flowchart LR
    A["Input / Artifact"] --> B{"Regex + normalization
(fold leetspeak, gộp space)"}
    B -- "khớp mẫu đã biết" --> BLK["🚫 BLOCKED rc=2"]
    B -- "không khớp" --> C{"Semantic classify
ornith:9b"}
    C -- "INJECTION" --> BLK
    C -- "SAFE" --> OK["✅ Cho qua"]
    B -. "artifact-scan (indirect injection)" .-> BLK
    A2["Secret / PII trong input"] --> BLK

    style BLK fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
    style OK fill:#d0ffd0,stroke:#1e8449,stroke-width:2px
```

**Điểm chốt:** regex bắt câu *đã biết* (recall 0.00 với paraphrase mới) → **model bù phần semantic**. Có secret/PII → chặn cứng luôn.

---

## 4. Zoom H5 — Governance (audit chain + chống giả mạo)

```mermaid
flowchart TB
    R1["record 1"] --> R2["record 2"] --> R3["record 3"]
    R3 --> HEAD["HEAD hash"]
    HEAD --> SIG["🔏 Ký RSA head
(mỏ neo ngoài)"]
    SIG --> V{"verify-audit-chain"}
    V -- "chain khớp + chữ ký hợp lệ" --> OK["✅ AUDIT_CHAIN_VALID"]
    ATK["👺 Kẻ tấn công sửa 1 ký tự"] -.-> R1
    R1 -. "hash lệch" .-> V
    V -- "phát hiện" --> BAD["🚨 AUDIT_HASH_MISMATCH line=1"]

    style OK fill:#d0ffd0,stroke:#1e8449
    style BAD fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
```

**Vì sao cần ký RSA:** hash-chain tự chứa → sửa xong tính lại cả chain thì hash vẫn khớp. Ký head bằng private key (kẻ tấn công không có) → sửa xong **không ký lại được** → verify gãy.

---

## 5. Zoom H6 — AgentOps (cost-spike + drift)

```mermaid
flowchart LR
    subgraph SRC["Nguồn dữ liệu (AI local cấp)"]
      T["provider-usage.jsonl
token THẬT mỗi step"]
    end
    T --> M["Tính median total_tokens"]
    M --> TH["threshold = 3 × median"]
    TH --> D{"step > threshold?"}
    D -- "có (710 > 660)" --> SPIKE["🚨 COST_SPIKE_DETECTED exit=2"]
    D -- "không" --> NONE["✅ COST_SPIKE_NONE exit=0"]
    G["golden vs candidate"] --> DR{"drift-detect
similarity under 1.0?"}
    DR -- "0.66 under 1.0" --> WARN["⚠️ DRIFT_WARN"]

    style SPIKE fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
    style NONE fill:#d0ffd0,stroke:#1e8449
    style WARN fill:#fff0c0,stroke:#b9770e
```

**Câu hỏi chốt H6:** *"step tốn 3× token có ai biết không?"* → CÓ, gate đỏ (`exit=2`). Logic deterministic; **AI local chỉ cấp token thật**.

---

## 6. Luồng TỰ CHẤM ĐIỂM → suy ra CASAN Level

```mermaid
flowchart TB
    START["Chạy self-scoring
security-gate.sh + per-harness"] --> SCORE["Chấm H1..H7 (0-100)"]
    SCORE --> GAP{"Có harness duoi 30?
GAP"}
    GAP -- "3+ GAP hoặc TB duoi 40" --> L2["Level 2 — Augmented"]
    GAP -- "toi da 2 GAP, TB 40-65" --> L3["Level 3 — Standard"]
    GAP -- "toi da 1 GAP, TB 65-80" --> L34["Level 3 to 4"]
    GAP -- "0 GAP, TB tren 80" --> L4["Level 4 — Automated ✅"]
    L4 --> L5Q{"Moi harness tren 70
+ Multi-Agent?"}
    L5Q -- "có" --> L5["Level 5 — Native"]
    L5Q -- "chưa" --> L4

    style L4 fill:#d0ffd0,stroke:#1e8449,stroke-width:2px
    style L5 fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px
    style L2 fill:#ffe8d0,stroke:#b9770e
```

**Quy tắc "harness thấp nhất quyết định trần":** 1 harness < 30 (GAP) → cả pipeline không thể là Level 4, dù các harness khác cao.

---

## 7. Luồng chọn MODEL (Ollama vs OpenAI)

```mermaid
flowchart TB
    Q{"Có gì để chạy model?"} 
    Q -- "Ollama ở nhà" --> A["Path A: SSH tunnel → 127.0.0.1:11434"]
    Q -- "Ollama trên Mac" --> B["Path B: ollama serve local
(không cần Linux server)"]
    Q -- "OpenAI key" --> C{"model-call.py hỗ trợ?"}
    C -- "STUB chưa cài" --> C1["⚠️ fail: cloud_backend_not_implemented
→ cần patch ~20 dòng (Runbook Mục 4)"]
    C -- "sau khi patch" --> C2["Path C: openai:gpt-4o-mini
(không cần Ollama/server)"]
    A --> RUN["Chạy pipeline / self-scoring"]
    B --> RUN
    C2 --> RUN

    style C1 fill:#ffd0d0,stroke:#c0392b,stroke-width:2px
    style RUN fill:#d0ffd0,stroke:#1e8449
```

**Nhắc:** OpenAI backend hiện là **stub** — có key vẫn phải patch mới chạy. Ollama local trên Mac = bỏ được Linux server.

---

## 8. Bản đồ 3 harness trọng tâm × mô hình tấn công

```mermaid
mindmap
  root((CASAN H4 H5 H6))
    H4 Security
      Direct injection rc2
      Paraphrase then semantic model
      Leetspeak whitespace
      Indirect via artifact
      Secret and PII block
      Red-team recall over regex
    H5 Governance
      Tamper 1 char then HASH_MISMATCH
      Re-forge chain then RSA anchor
      Secrets-scan
      No-bypass no-verify
      Tool audit trace
    H6 AgentOps
      Cost-spike 3x then exit2
      Negative control then exit0
      Drift-detect
      Telemetry token that
      Hallucination scan
```

---

## 9. Ghi chú đọc biểu đồ

- **Mở bằng:** VS Code (cài extension *Markdown Preview Mermaid Support*) hoặc đẩy lên GitHub (render tự động).
- Màu quy ước: 🔴 đỏ = H4 Security · 🔵 xanh dương = H5 Governance · 🟢 xanh lá = H6 AgentOps · 🟣 tím = H7 · vàng = H1/H2/H3.
- Chi tiết số liệu & lệnh: xem `CASAN_MASTER_RUNBOOK.md`, `CASAN_TEAM_QA.md`, `CASAN_OLD_vs_CASAN5_Executive_Assessment.md`.

---

_Biểu đồ mô tả luồng thật của pipeline (`scripts/run-casan-pipeline.mjs` + `casan-step.mjs` + `.specify/scripts/bash/*`). Các verdict/exit code trong biểu đồ là kết quả đã kiểm chứng trong phiên đánh giá._