@sun-asterisk/sungen 3.1.2 → 3.2.0-beta.142

package/docs/orchestration-spec.md

@@ -1,267 +0,0 @@
-# Sungen Orchestration & Harness — Detailed Spec
-
-> Spec triển khai cho lần refactor lớn: chuyển từ **"Context Engine + Skill" (workflow tuyến tính)** sang **Orchestration + Harness Engine**.
-> Mục tiêu chính: **nâng chất lượng testcase** (đo & gate thay vì nhờ AI). Bất biến: `generate`, auto-fix selector, `delivery`, reports.
-> Tài liệu nền: `docs/spec/sungen_direction_solution.md`, `docs/spec/sungen_refactor_spec.md`.
-
----
-
-## 0. TL;DR cho người triển khai
-
-- **Orchestration** = bộ não điều phối: *khám phá input → chọn route → gọi AI sinh artifact → đo bằng Harness → repair → hội tụ → ghi ledger*.
-- **Harness** = lớp kiểm soát chất lượng: **Guide** (skill markdown, đã có) + **Sensor** (code tất định, MỚI) + **Repair loop** + **QA checkpoint**.
-- **Nguyên tắc vàng:** chất lượng đến từ **đo & gate** (Sensor), không từ "nhờ AI làm đúng" (Guide). Bằng chứng: case `home` 6.5/10 — viewpoint AI tốt nhưng không gì enforce.
-- **Refactor Phase 1 (làm trước, tất định, verify được):** `sungen audit` = 4 Sensor + Viewpoint Gate + score + report. Đây là phần code lõi của lần refactor này.
-- **Orchestrator AI** (`/sungen:design`) gọi `sungen audit` trong vòng repair. Skill cũ giữ làm Guide.
-
----
-
-## 1. Trách nhiệm của Orchestration (Orchestrator làm gì)
-
-Orchestrator KHÔNG sinh testcase trực tiếp. Nó trả lời và điều phối theo các câu hỏi:
-
-| # | Câu hỏi | Thành phần phụ trách | Output |
-|---|---|---|---|
-| 1 | Goal là gì? Loại test gì (web-ui/api/mobile/perf)? | Goal Resolver | `goal` |
-| 2 | Có những input nào? Đầy đủ tới đâu? Mâu thuẫn gì? | **Context Discovery** | `discovery-report` |
-| 3 | Nên đi route nào (và song song không)? | **Route Planner** | `route-plan` |
-| 4 | Sinh viewpoint-overview + Gherkin | AI (qua Guide skill) | `viewpoint-overview`, `.feature` |
-| 5 | Output đã đủ tốt chưa? Thiếu/trùng/nông ở đâu? | **Harness Sensors** | `audit-report` |
-| 6 | Chưa đạt → sửa ở đâu, sinh bù gì? | **Repair Loop** | artifact mới |
-| 7 | Spec đã đổi chưa? Phần nào tái dùng/tái tạo? | **Change Planner** | `change-plan` |
-| 8 | Tốn bao nhiêu tài nguyên, ở bước nào? | **Usage Ledger** | `usage-report` |
-| 9 | QA quyết định gì? Học được gì? | **QA Checkpoint + Feedback** | `feedback.jsonl` |
-
-**Bất biến:** Orchestrator dừng ở ranh giới artifact (`.feature`/`test-data`/`selectors`). Từ đó trở đi là `generate → run-test (auto-fix) → delivery` — **không đổi**.
-
----
-
-## 2. FLOW CHÍNH (Main Flow) — Spec-first, web-ui
-
-```
-                          ┌─────────────────────────────┐
-   QA cung cấp:           │  /sungen:design <screen>     │
-   spec.md, figma,        │  (Orchestrator entrypoint)   │
-   screenshot, url,       └──────────────┬──────────────┘
-   prompt                                │
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (1)   │  CONTEXT DISCOVERY            │  đọc MỌI nguồn, không bắt chọn
-                          │  - liệt kê nguồn + độ đầy đủ  │
-                          │  - phát hiện mâu thuẫn         │
-                          │  - RECOMMEND route + nguồn ưu  │──► discovery-report.json
-                          └──────────────┬──────────────┘
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (2)   │  ROUTE PLANNER               │  mặc định: Spec-first
-                          │  chọn 1..n route (song song)  │──► route-plan.json
-                          └──────────────┬──────────────┘
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (3)   │  VIEWPOINT PLANNER (AI+Guide) │  LUÔN sinh overview trước
-                          │  → viewpoint-overview         │──► test-viewpoint.md
-                          │    (id, priority, evidence)   │
-                          └──────────────┬──────────────┘
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (4)   │  VIEWPOINT GATE (Sensor)     │◄── seed Universal Catalog (reference)
-                          │  Required/High đã đủ chưa?    │
-                          └───────┬──────────────┬───────┘
-                            FAIL  │              │ PASS
-                       (sinh bù viewpoint)        ▼
-                                         ┌─────────────────────────────┐
-                    (5)   │  GHERKIN GENERATOR (AI+Guide)│  Tier critical+high trước
-                          │  → .feature + test-data       │
-                          └──────────────┬──────────────┘
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (6)   │  HARNESS SENSORS (sungen audit)         │
-                          │  ① traceability ② coverage-balance      │──► audit-report.json
-                          │  ③ assertion-depth ④ duplicate          │    + score
-                          └───────┬──────────────────────┬─────────┘
-                            FAIL  │                       │ PASS
-                                  ▼                       │
-                          ┌───────────────┐               │
-                    (7)   │ REPAIR LOOP   │  ngân sách N vòng
-                          │ sửa đúng chỗ  │  (vd: sinh bù VP-DATA-CONSISTENCY,
-                          │ sensor chỉ ra │   nâng assertion nông → có {{data}})
-                          └──────┬────────┘
-                                 └──────────► quay lại (5)/(6)
-                                         │ (đạt gate hoặc hết ngân sách → báo gap)
-                                         ▼
-                          ┌─────────────────────────────┐
-                    (8)   │  CONVERGE + LEDGER + CHECKPOINT          │
-                          │  artifact contract đầy đủ + usage-report │
-                          │  + manifest (scenario↔vp↔spec-hash)      │
-                          │  → QA review/feedback                    │
-                          └──────────────┬──────────────┘
-                                         ▼
-                            [BẤT BIẾN]  generate → run-test(auto-fix) → delivery → dashboard
-```
-
-Điểm khác biệt cốt lõi so với hiện tại: **(1) Discovery + recommend** thay cho hỏi-chọn; **(4) Gate** + **(6) Sensors** thay cho "nhờ AI tự đủ"; **(7) Repair** có ngân sách; **(8) Ledger + manifest** để đo & tái dùng.
-
----
-
-## 3. FLOW BỔ SUNG (Supplementary Routes)
-
-Tất cả route hội tụ về cùng **artifact contract** (Mục 6). Route chỉ khác ở *nguồn tri thức đầu vào*.
-
-| Route | Khi nào kích hoạt | Khác biệt so với main |
-|---|---|---|
-| **A. Spec-first** (mặc định) | spec.md đủ tốt | Như Mục 2 |
-| **B. Source-first** | spec mỏng/thiếu, có source code | Bước (3) thay bằng *Source Behavior Miner*: trích endpoint/screen/state/validation/permission từ code → viewpoint |
-| **C. History-first** | có testcase cũ tương tự (cần Lớp 2/feedback) | Bước (3): search cluster testcase cũ → trích viewpoint chung → recommend |
-| **D. Defect-first** | feature vùng rủi ro cao (cần defect history) | Ưu tiên viewpoint từng bắt defect; risk-based |
-| **E. QA-guided** | QA bổ sung viewpoint / AI confidence thấp | QA thêm viewpoint → phân loại → check trùng → sinh variant |
-
-**Parallel execution:** khi nhiều nguồn cùng có (vd spec + source + history), Route Planner chạy song song (Agent đọc spec / Agent đọc source / Agent search history) → **merge viewpoint candidates → khử trùng → rank theo risk/coverage/evidence**. Đây cũng là cách trả lời yêu cầu "recommend thay vì bắt chọn": tất cả nguồn được *gộp*, không chọn 1.
-
----
-
-## 4. CÂY QUYẾT ĐỊNH KHI GẶP HẠN CHẾ (Discovery / Fallback)
-
-> "Khi gặp hạn chế thì khám phá hoặc phát triển theo flow nào" — đây là logic fallback của Orchestrator. Nguyên tắc: **không đứt giữa chừng**; luôn có bước kế tiếp; nếu bí thì *output assumption rõ ràng* thay vì im lặng.
-
-```
-Bắt đầu: cần sinh viewpoint/Gherkin cho <screen>
-│
-├─ spec.md đủ tốt? ───────────── YES ─► Route A (Spec-first)
-│        │ NO
-│        ▼
-├─ có source code? ───────────── YES ─► Route B (Source-first): mine behavior từ code
-│        │ NO
-│        ▼
-├─ có testcase/lịch sử tương tự? ─ YES ─► Route C (History-first): trích viewpoint từ cluster
-│        │ NO
-│        ▼
-├─ thuộc domain rủi ro + có defect history? ─ YES ─► Route D (Defect-first)
-│        │ NO
-│        ▼
-└─ HỎI QA (Route E) ─► QA chưa phản hồi? ─► OUTPUT với ASSUMPTION LIST rõ ràng (đánh dấu cần xác minh)
-
-Trong quá trình chạy, nếu Sensor (bước 6) FAIL:
-│
-├─ Viewpoint Gate FAIL (thiếu Required/High) ─► Repair: sinh bù viewpoint + scenario cho VP thiếu
-├─ Assertion-depth FAIL (quá nhiều Then nông) ─► Repair: nâng assertion (thêm {{data}}/observable), hoặc
-│                                                 nếu thiếu data cụ thể → cần spec/flow ► gợi ý add-flow (cross-screen)
-├─ Coverage-balance FAIL (VP phụ expand sâu, VP High mỏng) ─► Repair: dừng expand VP phụ, sinh VP High
-├─ Duplicate FAIL (cluster trùng nghĩa) ─► Repair: merge/loại, giữ 1 đại diện + ghi rõ EP variants
-└─ Traceability FAIL (scenario không map viewpoint) ─► Repair: gắn vp-id vào scenario
-
-Hết ngân sách repair (N vòng) mà vẫn FAIL:
-└─► KHÔNG lặp vô hạn. Ghi gap vào audit-report + đưa QA checkpoint (human-in-the-loop).
-```
-
-**Quy tắc "khám phá thêm khi nông":** nếu assertion-depth sensor báo một viewpoint critical chỉ assert "see page/section" (vụ home: Cart/Detail/Filter), Orchestrator phải nhận diện đây là **cross-screen** → khuyến nghị chuyển sang **flow** (`add-flow`) và/hoặc cần **năng lực DSL capture biến** (xem `docs/spec/sungen_refactor_spec.md` §5.4) — thay vì giả vờ pass bằng assertion nông.
-
----
-
-## 5. HARNESS — Guide / Sensor / Repair / Checkpoint
-
-### 5.1 Guide (AI, giữ nguyên skill markdown)
-Skill hiện có (`sungen-tc-generation`, `sungen-viewpoint`, `sungen-test-design-techniques`) là **nửa Guide** — steer AI làm đúng từ đầu. **Giữ**, nhưng đồng bộ threshold với Sensor.
-
-### 5.2 Sensor (tất định — code MỚI, phần lõi refactor)
-Bốn sensor + một gate. Input: `.feature` (qua GherkinParser) + `test-viewpoint.md` + (optional) `spec.md`.
-
-| Sensor | Đo | Output | Tất định? |
-|---|---|---|---|
-| **Viewpoint Gate** | mỗi viewpoint Required/High có ≥1 scenario phủ | pass/fail + danh sách thiếu | heuristic keyword (hybrid) |
-| **Traceability** | scenario map được tới viewpoint id; có evidence | % traceable | tất định |
-| **Coverage-balance** | phân bố scenario theo VP-group & priority; phát hiện lệch | cảnh báo imbalance | tất định |
-| **Assertion-depth** | tỉ lệ `Then` nông (chỉ see page/section) vs có data assert | % shallow | tất định |
-| **Duplicate** | cluster scenario cùng shape/nghĩa | cluster + đề xuất | heuristic |
-
-> Trung thực: Gate & Duplicate (ngữ nghĩa) là **hybrid** — heuristic rẻ chặn phần rõ, AI-judge cho vùng xám. Không hứa thuần tất định cho ngữ nghĩa.
-
-### 5.3 Repair Loop
-- Sensor trả **phản hồi cụ thể** (vd: "VP-DATA-CONSISTENCY Required nhưng 0 scenario; gợi ý: add-flow checkout").
-- Orchestrator đưa phản hồi này lại bước sinh. **Ngân sách N vòng** (mặc định 2–3, như vòng auto-fix selector). Hết ngân sách → báo gap, không lặp vô hạn.
-
-### 5.4 QA Checkpoint
-- QA accept/reject/edit/add viewpoint. Mọi quyết định ghi `feedback.jsonl` (xem `docs/spec/sungen_refactor_spec.md` §8).
-
----
-
-## 5b. Agent layer (tầng thứ 4 — isolation / independence / parallel)
-
-Prompt (command) + Skill + Harness (deterministic) là đủ cho work tuần tự. **Agent** (context LLM riêng) chỉ thêm khi cần **isolation**, **góc nhìn độc lập**, hoặc **parallel**. Nguyên tắc chọn:
-
-| Loại | Khi nào | Sungen |
-|---|---|---|
-| Deterministic (code) | đo/gate/fingerprint | `sungen audit/manifest/ledger` — KHÔNG agent-hóa |
-| Skill (tri thức) | quy tắc context chính theo | gherkin-syntax, tc-generation, viewpoint, harness-audit |
-| **Agent (context riêng)** | khám phá tốn token cần tóm gọn; cần phán xử độc lập; chạy song song | **discovery, reviewer** |
-
-> "Senior QA" đã là role-prompt trong command — KHÔNG cần agent riêng cho nó.
-
-**Hai agent (Claude Code sub-agent; Copilot chạy inline, fallback tuần tự):**
-
-1. **`sungen-reviewer` (Judge — đòn bẩy cao nhất).** Reviewer độc lập, KHÔNG viết test, chỉ phán xử **ngữ nghĩa** mà gate tất định bỏ sót: steps có *chứng minh* title/viewpoint không; `Then` có observable không; business-critical có assertion sâu không; `@manual` có chính đáng không. Trả `VERDICT + ISSUES(+fix)`. Nhúng vào **repair loop** (step 5.5): `audit (structural) → reviewer (semantic) → merge → repair`. Generator và reviewer **tách context** → không rubber-stamp. Giải đúng vấn đề kẹt ~6.7 ("title đúng nhưng steps chưa prove").
-
-2. **`sungen-discovery` (Explorer).** Đọc mọi nguồn (spec/figma/ui/live) trong **context riêng**, trả **discovery-report cô đọng** (sources/completeness/conflicts/route/key-facts) → orchestrator chính giữ context sạch để generate. Dùng ở bước discovery.
-
-**Lưu ý:** mỗi agent tốn token → **ledger phải đo per-agent**; output agent phải có **schema rõ** (verdict / discovery-report) tránh chat lan man; **parallel route agents** (spec/source/history/defect) hoãn tới khi multi-source thật sự cần.
-
-## 6. Convergence Contract (artifact bắt buộc — mọi route hội tụ về đây)
-
-```
-qa/screens/<screen>/requirements/test-viewpoint.md   # viewpoint-overview (id, priority, evidence)
-qa/screens/<screen>/features/<screen>.feature         # Gherkin (format hiện tại — downstream không đổi)
-qa/screens/<screen>/test-data/<screen>.yaml
-.sungen/manifest/<screen>.json        # scenario ↔ viewpoint ↔ spec-section fingerprint  (cho reuse)
-.sungen/reports/<screen>-audit.json   # sensor + gate + score
-.sungen/reports/<screen>-usage.json   # token/cost/time ledger theo bước
-.sungen/feedback/*.jsonl              # QA feedback (local-first)
-```
-
-`.feature`/`test-data`/`selectors` giữ schema cũ → `generate`/`delivery` không đổi.
-
----
-
-## 7. Orchestrator command (AI) — `/sungen:design` (sketch)
-
-Lệnh AI mới điều phối flow chính; thay thế dần phần "hỏi-chọn" trong `create-test`. (`create-test` cũ vẫn chạy được — `design` là superset có harness.)
-
-```
-Role: Test Design Orchestrator.
-Steps:
- 1. CONTEXT DISCOVERY: đọc spec.md, spec_figma.md, ui/*, (live url nếu có). KHÔNG hỏi "chọn nguồn".
-    → Tóm tắt nguồn + độ đầy đủ + mâu thuẫn + RECOMMEND route. Trình bày recommendation (QA override được).
- 2. VIEWPOINT PLANNER: sinh test-viewpoint.md (id/priority/evidence) — LUÔN làm, kể cả có sẵn (diff & bổ sung).
- 3. Chạy `sungen audit --screen <s> --gate viewpoint` → nếu thiếu Required/High: sinh bù.
- 4. GHERKIN: sinh .feature + test-data (critical+high trước), gắn vp-id (traceability).
- 5. Chạy `sungen audit --screen <s>` (full). Đọc audit-report.
- 6. REPAIR (≤ N vòng): sửa đúng chỗ sensor chỉ ra. Hết ngân sách → báo gap.
- 7. Ghi usage-ledger + manifest. Trình bày score + gap cho QA (checkpoint).
- 8. AskUserQuestion next: review / run-test / feedback.
-```
-
-Skill được auto-load: `sungen-viewpoint`, `sungen-tc-generation`, `sungen-test-design-techniques`, `sungen-gherkin-syntax` (Guide); `sungen-harness-audit` (mới — mô tả cách đọc audit-report & repair).
-
----
-
-## 8. Mở rộng (test-type packs + executor providers)
-
-Orchestrator/Harness/Discovery là **chung**. Chỉ thay theo loại test:
-- **Test-type pack** = (viewpoint catalog + sensor set + contract): `web-ui`, `mobile-ui`, `api`, `performance`, `db-verify`.
-- **Executor provider** = sinh code: Playwright / Appium / k6 / SQL runner (xem `reports/mobile-proposal.md`).
-
-Ví dụ: pack `performance` thay Assertion-depth sensor bằng "Threshold sensor" (có p95/error-rate?), Viewpoint Gate dùng catalog load-profile. Cùng một orchestration loop.
-
----
-
-## 9. Phase triển khai (không phá luồng cũ)
-
-```
-P1 (refactor lõi, TẤT ĐỊNH — làm trong lần này):
-   sungen audit = 4 sensor + viewpoint gate + score + report JSON + seed catalog
-   → verify trên examples/automationexercise home: phải tái hiện gap 6.5/10
-P2: /sungen:design (orchestrator AI) gọi audit trong repair loop; discovery+recommend
-P3: manifest + spec-fingerprint (reuse); usage ledger
-P4: feedback local (Nấc 1)
-P5: test-type packs (api/perf/db) + executor providers (Appium…)
-```
-
-P1 là phần code của lần refactor này (Mục 5.2). Các phase sau bám thin-first: 1 workflow thật → học → mở rộng.