@sun-asterisk/sungen 2.7.0-beta.0 → 3.0.0-beta.71

package/dist/orchestrator/templates/specs-test-data.ts

@@ -54,6 +54,15 @@ export class TestDataLoader {
     }
     return String(current);
   }
+
+  /**
+   * Set a value at runtime (used by captured-variable steps:
+   * `User remember [X] text as {{var}}`). Stored at top level so a later
+   * `{{var}}` reference resolves via get().
+   */
+  set(key: string, value: string): void {
+    this.data[key] = value;
+  }
 }
 
 function loadYamlSync(filePath: string): Record<string, any> | null {

package/dist/tools/figma/figma-auth.d.ts

@@ -6,7 +6,9 @@
  *
  * Safeguards enforced on every save AND every assertSafeToUse call:
  *   1. .env must appear in .gitignore (abort if not).
- *   2. No tracked file may contain "FIGMA_PAT=" (git grep scan).
+ *   2. No tracked file may contain an assigned token value (FIGMA_PAT=<token>).
+ *      The scan matches a token-shaped value, not bare mentions of the key in
+ *      code or docs (those are not secrets).
  */
 /**
  * Load the Figma PAT.
@@ -28,7 +30,8 @@ export declare function savePat(cwd: string, token: string): Promise<void>;
 export declare function clearPat(cwd: string): void;
 /**
  * Run tracked-file scan on every Figma CLI / skill invocation.
- * Aborts with actionable message if FIGMA_PAT= is found in any tracked file.
+ * Aborts with an actionable message if an assigned token value is found in any
+ * tracked file (bare mentions of the key name are ignored).
  *
  * @throws Error with remediation instructions on safeguard failure.
  */

package/dist/tools/figma/figma-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figma-auth.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiEH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvD;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCvE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAM1C;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAShE"}
+{"version":3,"file":"figma-auth.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyEH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvD;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCvE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAM1C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAShE"}

package/dist/tools/figma/figma-auth.js

@@ -7,7 +7,9 @@
  *
  * Safeguards enforced on every save AND every assertSafeToUse call:
  *   1. .env must appear in .gitignore (abort if not).
- *   2. No tracked file may contain "FIGMA_PAT=" (git grep scan).
+ *   2. No tracked file may contain an assigned token value (FIGMA_PAT=<token>).
+ *      The scan matches a token-shaped value, not bare mentions of the key in
+ *      code or docs (those are not secrets).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -53,6 +55,13 @@ const exec_file_no_throw_1 = require("../../utils/exec-file-no-throw");
 const PAT_KEY = 'FIGMA_PAT';
 const ENV_FILE = '.env';
 const GITIGNORE_FILE = '.gitignore';
+// A real leak is an assigned token value (`FIGMA_PAT=<token>`), not a bare
+// mention of the key name in code or documentation. Figma PATs are long
+// (~40+ chars), so we only flag an assignment whose value looks like an actual
+// token: at least 16 non-space characters after `=` (an optional quote allowed).
+// This is an ERE pattern for `git grep -E`; it deliberately does NOT match this
+// file's own comments or template literals (`${PAT_KEY}=...`).
+const PAT_VALUE_PATTERN = `${PAT_KEY}=['"]?[^[:space:]]{16,}`;
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -89,11 +98,11 @@ function isEnvIgnored(cwd) {
     return /^\s*(\.env[\w.*]*|\*\.env)\s*$/m.test(content);
 }
 /**
- * Run `git grep -l "FIGMA_PAT="` in cwd.
+ * Scan tracked files for an assigned Figma token value (not bare key mentions).
  * Returns list of matching tracked file paths (empty = safe).
  */
 async function findTrackedFilesWithPat(cwd) {
-    const result = await (0, exec_file_no_throw_1.execFileNoThrow)('git', ['grep', '-l', `${PAT_KEY}=`], cwd);
+    const result = await (0, exec_file_no_throw_1.execFileNoThrow)('git', ['grep', '-lE', PAT_VALUE_PATTERN], cwd);
     if (result.status === 0 && result.stdout.trim()) {
         return result.stdout.trim().split('\n').filter(Boolean);
     }
@@ -131,12 +140,12 @@ async function savePat(cwd, token) {
         throw new Error(`Refusing to save FIGMA_PAT: ".env" is not listed in ${GITIGNORE_FILE}.\n` +
             `Add the following line to ${path.join(cwd, GITIGNORE_FILE)} and re-run:\n\n  .env\n`);
     }
-    // Safeguard 2: no tracked file may contain FIGMA_PAT=
+    // Safeguard 2: no tracked file may contain an assigned token value
     const leakedFiles = await findTrackedFilesWithPat(cwd);
     if (leakedFiles.length > 0) {
-        throw new Error(`Refusing to save FIGMA_PAT: token key found in tracked file(s):\n` +
+        throw new Error(`Refusing to save FIGMA_PAT: a token value appears in tracked file(s):\n` +
             leakedFiles.map((f) => `  ${f}`).join('\n') +
-            `\n\nRemove FIGMA_PAT from those files, commit the removal, then re-run.\n`);
+            `\n\nRemove the token from those files, commit the removal, then re-run.\n`);
     }
     // Upsert: replace existing line or append
     const lines = readEnvLines(cwd);
@@ -167,16 +176,17 @@ function clearPat(cwd) {
 }
 /**
  * Run tracked-file scan on every Figma CLI / skill invocation.
- * Aborts with actionable message if FIGMA_PAT= is found in any tracked file.
+ * Aborts with an actionable message if an assigned token value is found in any
+ * tracked file (bare mentions of the key name are ignored).
  *
  * @throws Error with remediation instructions on safeguard failure.
  */
 async function assertSafeToUse(cwd) {
     const leakedFiles = await findTrackedFilesWithPat(cwd);
     if (leakedFiles.length > 0) {
-        throw new Error(`Security check failed: FIGMA_PAT found in tracked file(s):\n` +
+        throw new Error(`Security check failed: a Figma token value appears in tracked file(s):\n` +
             leakedFiles.map((f) => `  ${f}`).join('\n') +
-            `\n\nRemove FIGMA_PAT from those files and commit the removal before using Figma commands.\n`);
+            `\n\nRemove the token from those files and commit the removal before using Figma commands.\n`);
     }
 }
 //# sourceMappingURL=figma-auth.js.map

package/dist/tools/figma/figma-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"figma-auth.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"figma-auth.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-auth.ts"],"names":[],"mappings":"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"}

package/docs/orchestration-spec.md

@@ -0,0 +1,267 @@
+# 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: `reports/sungen_direction_solution.md`, `reports/sungen_refactor_spec.md`, `reports/sungen_home_gherkin_viewpoint_coverage_review.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 `reports/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 `reports/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.7.0-beta.0",
+  "version": "3.0.0-beta.71",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "tsc && npm run copy-templates",
-    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html",
+    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd dashboard && npm install --silent && npm run build && cd .. && cp dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -26,7 +26,7 @@
     "automation",
     "qa"
   ],
-  "author": "ee team (engineer-excellence) — Sun Asterisk",
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -47,7 +47,7 @@
     "handlebars": "^4.7.8",
     "ora": "^9.0.0",
     "plop": "^4.0.4",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "yaml": "^2.8.2",
     "zod": "^4.1.13"
   },
@@ -67,11 +67,15 @@
   },
   "overrides": {
     "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "tmp": "^0.2.6",
+    "esbuild": "^0.28.1"
   },
   "resolutions": {
     "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "tmp": "^0.2.6",
+    "esbuild": "^0.28.1"
   },
   "files": [
     "dist",

package/src/cli/commands/add.ts

@@ -66,15 +66,15 @@ export function registerAddCommand(program: Command): void {
               console.log(`  qa/screens/${options.screen}/requirements/spec.md (stub created)`);
             }
 
-            // Loud banner: Tell the calling agent to
-            // invoke the `sungen-figma-source` skill to synthesize the narrative sections in spec_figma.md, since
+            // Loud banner: Tell the calling agent to invoke the `sungen-capture` skill
+            // (mode figma-pat) to synthesize the narrative sections in spec_figma.md, since
             // the CLI cannot do this (synthesis is LLM-driven off the cached raw JSON).
             console.log('');
             console.log('==============================================================');
             console.log('  NEXT STEP (REQUIRED — DO NOT SKIP)');
             console.log('==============================================================');
             console.log('  spec_figma.md envelope is written but narrative is EMPTY.');
-            console.log('  Invoke the `sungen-figma-source` skill NOW to synthesize');
+            console.log('  Invoke `sungen-capture` (mode figma-pat) NOW to synthesize');
             console.log('  the 7 sections (Purpose / ASCII Layout / Regions / Actions /');
             console.log('  Form Fields / Data Columns / Navigation) below the');
             console.log('  `<!-- SYNTHESIS-BELOW -->` marker.');

package/src/cli/commands/audit.ts

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runAudit, AuditReport } from '../../harness/audit';
+
+function findScreenDir(name: string): string | null {
+  const screen = path.join(process.cwd(), 'qa', 'screens', name);
+  if (fs.existsSync(screen)) return screen;
+  const flow = path.join(process.cwd(), 'qa', 'flows', name);
+  if (fs.existsSync(flow)) return flow;
+  return null;
+}
+
+function bar(ratio: number, width = 20): string {
+  const n = Math.round(ratio * width);
+  return '█'.repeat(n) + '░'.repeat(width - n);
+}
+
+function render(r: AuditReport): void {
+  const L = console.log;
+  L('');
+  L(`━━━ Harness Audit: ${r.screen} (${r.scenarioCount} scenarios) ━━━`);
+  L('');
+  L(`  Quality score (business-weighted): ${r.score.overall}/10   [Viewpoint Gate: ${r.gateStatus}]`);
+  L(`  Intent: focus=${r.intent.focus} · depth threshold ${r.depth.threshold.toFixed(2)} (${r.intent.source})`);
+  L(`    coverage      ${bar(r.score.coverage)} ${(r.score.coverage * 100).toFixed(0)}%`);
+  L(`    businessDepth ${bar(r.score.businessDepth)} ${(r.score.businessDepth * 100).toFixed(0)}%  [${r.depth.verdict.toUpperCase()}]`);
+  L(`    balance       ${bar(r.score.balance)} ${(r.score.balance * 100).toFixed(0)}%`);
+  L(`    traceability  ${bar(r.score.traceability)} ${(r.score.traceability * 100).toFixed(0)}%`);
+  L(`    (${r.score.formula})`);
+  L('');
+  L(`  ① Viewpoint Gate — page-type: ${r.gate.pageType ?? 'unknown'} — themes ${r.gate.themesCovered}/${r.gate.themesTotal} covered`);
+  if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
+  else L('      ✓ all critical themes covered (with data assertions)');
+  L('');
+  L(`  ② Assertion depth — ${r.depth.businessCriticalShallow}/${r.depth.businessCriticalTotal} business-critical scenarios are shallow (visibility/nav only)`);
+  for (const s of r.depth.shallowBusinessCritical.slice(0, 8)) L(`      ⚠ ${s.category}: ${s.name}`);
+  if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);
+  L('');
+  L(`  ③ Coverage balance — ${r.balance.imbalanced ? '⚠ IMBALANCED' : '✓ balanced'}`);
+  L(`      buckets: ${Object.entries(r.balance.byBucket).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  L('');
+  L(`  ④ Duplicate — ${r.duplicates.clusters.length} same-shape cluster(s), ${r.duplicates.exactDuplicateCount} likely exact dup(s)`);
+  for (const c of r.duplicates.clusters.slice(0, 3)) {
+    L(`      ${c.sameDataLikely ? '✗ exact' : '○ EP/data family'} (${c.scenarios.length}): ${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}`);
+  }
+  L('');
+  L(`  ⑤ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
+  L(`      ${r.trace.note}`);
+  L('');
+  L('  ── Findings (Repair targets) ──');
+  if (r.findings.length === 0) L('      ✓ none — output passes the harness');
+  for (const f of r.findings) L(`      • ${f}`);
+  L('');
+}
+
+export function registerAuditCommand(program: Command): void {
+  program
+    .command('audit')
+    .description('Harness: measure test-design quality (viewpoint gate, depth, balance, duplicates, traceability)')
+    .option('-s, --screen <name>', 'Screen or flow name to audit')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const dir = findScreenDir(name);
+        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${name} or qa/flows/${name}`);
+
+        const report = runAudit(dir, name);
+
+        // Persist report under .sungen/reports/
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = path.join(outDir, `${name}-audit.json`);
+        fs.writeFileSync(outPath, JSON.stringify(report, null, 2), 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          render(report);
+          console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
+          console.log('');
+        }
+        // Non-zero exit when the gate fails — usable in CI / repair loop.
+        process.exit(report.gateStatus === 'FAIL' ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/blindspot.ts

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import { addBlindspot, listBlindspots, blindspotsForPrompt } from '../../harness/blindspot';
+
+export function registerBlindspotCommand(program: Command): void {
+  const bs = program
+    .command('blindspot')
+    .description('Blind-Spot Memory: reusable patterns so the harness stops repeating a known miss');
+
+  bs
+    .command('add')
+    .description('Record a blind-spot pattern (promote a recurring miss to a reusable rule)')
+    .requiredOption('--pattern <name>', 'Short pattern name, e.g. "add-action-no-duplicate-check"')
+    .requiredOption('--rule <text>', 'The generalised rule to apply next time')
+    .option('--example <text>', 'A concrete instance that motivated it')
+    .option('--screen <name>', 'Where it was first noticed')
+    .option('--source <who>', 'qa | challenge | feedback', 'qa')
+    .action((o) => {
+      try {
+        addBlindspot({ pattern: o.pattern, rule: o.rule, example: o.example, screen: o.screen, source: o.source });
+        console.log(`✓ blindspot recorded: [${o.pattern}]`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  bs
+    .command('list')
+    .description('List recorded blind-spot patterns')
+    .option('--prompt', 'Output the compact bullet form used in generator/critic prompts')
+    .action((o) => {
+      try {
+        if (o.prompt) { const s = blindspotsForPrompt(); console.log(s || '(none)'); return; }
+        const all = listBlindspots();
+        if (!all.length) { console.log('No blind-spots recorded yet. Add one with `sungen blindspot add`.'); return; }
+        console.log(`\n━━━ Blind-Spot Memory (${all.length}) ━━━`);
+        for (const b of all) {
+          console.log(`  • [${b.pattern}]${b.screen ? ` (${b.screen})` : ''}`);
+          console.log(`      rule: ${b.rule}`);
+          if (b.example) console.log(`      e.g.: ${b.example}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}