@sun-asterisk/sungen 2.7.0-beta.1 → 3.0.0-beta.72

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-harness-audit.md

@@ -0,0 +1,84 @@
+---
+name: sungen-harness-audit
+description: 'How to read `sungen audit` output and repair test-design findings. Auto-loaded by the design orchestrator.'
+user-invocable: false
+---
+
+## What `sungen audit` measures
+
+`sungen audit --screen <name>` runs deterministic sensors over `features/<name>.feature` + `requirements/test-viewpoint.md` and writes `.sungen/reports/<name>-audit.json`. It is the **gate** the orchestrator repairs against. Run with `--json` to parse it.
+
+### Report shape (key fields)
+```jsonc
+{
+  "score": { "overall": 3.9, "coverage": 0.4, "businessDepth": 0.18, "balance": 0.5, "traceability": 0.7 },
+  "gateStatus": "PASS" | "FAIL",
+  "gate": { "pageType": "ecommerce-list", "themesCovered": 2, "themesTotal": 5,
+            "gaps": [ { "theme": "cart-correctness", "keywords": [...] } ] },
+  "depth": { "businessCriticalShallow": 9, "businessCriticalTotal": 11,
+             "shallowBusinessCritical": [ { "name": "...", "category": "PRODUCT" } ] },
+  "balance": { "imbalanced": true, "coreCount": 11, "secondaryCount": 22, "byBucket": {...} },
+  "duplicates": { "clusters": [ { "sameDataLikely": false, "scenarios": [...] } ] },
+  "trace": { "mappedRatio": 0.4, "note": "..." },
+  "findings": [ "GATE: ...", "DEPTH: ...", "BALANCE: ...", "TRACE: ..." ]
+}
+```
+- **`overall` score is business-weighted** (coverage 0.4 + businessDepth 0.3 + balance 0.15 + traceability 0.15). It is intentionally strict on business value — a high count with shallow business coverage scores low. Don't optimize the count; optimize coverage + depth.
+- Exit code **2** when `gateStatus == FAIL` (usable in CI / loop).
+
+## Finding → repair mapping
+
+| Finding prefix | Meaning | Repair action |
+|---|---|---|
+| **GATE** | a critical theme for the page-type has no covering scenario | Generate scenarios for that theme. **If cross-screen** (cart-correctness, product-detail-consistency, filter-result-correctness, multi-item cart) → do NOT fake it on a single screen; plan a **flow** (`/sungen:add-flow`) and record the deferral. |
+| **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
+| **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
+| **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
+| **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
+
+## P5 steps for deep cross-screen / list coverage
+
+Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detail/filter correctness). They need **runtime data mode** (the default).
+
+- **Capture a value to compare across screens** (product-detail-consistency, cart-correctness):
+  ```gherkin
+  When User remember [Product Name] text as {{selected_product_name}}
+  And User remember [Product Price] text as {{selected_product_price}}
+  And User click [View Product] link
+  Then User see [Detail Product Name] header with {{selected_product_name}}
+  And User see [Detail Product Price] text with {{selected_product_price}}
+  ```
+  `remember` stores the element's text/value at runtime; later `{{var}}` resolves to it. This proves the detail/cart shows the SAME product, not a random one.
+
+- **Assert every item in a result matches** (category/brand-filter-correctness):
+  ```gherkin
+  When User click [Women] link
+  And User click [Dress] link
+  Then User see all [Result Product Name] contain {{selected_category}}
+  ```
+  `see all [X] contain {{v}}` asserts EVERY matching element contains the value → "all displayed products belong to the selected category/brand", not just one.
+
+> Cross-screen flows (home → detail/cart): if the target screen is a separate screen, prefer a **flow** (`/sungen:add-flow`) so the journey is one test. On a single screen, keep the cross-screen assertion but tag `@manual` with a `# Deferred to a flow` comment.
+
+## Repair loop rules
+
+1. **Budget = 3 rounds.** Re-run `sungen audit` after each repair; track score delta.
+2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted.
+3. **Never fake a pass.** A shallow `see [Cart] page` does not satisfy `cart-correctness`. If a gap is genuinely cross-screen or needs capabilities the DSL lacks (e.g. capture an element value to compare elsewhere), **report it as a residual gap / flow item** instead of forcing a green gate.
+4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
+
+## Discovery / fallback tree (when input is limited)
+
+```
+spec.md đủ tốt?      → YES: Spec-first
+  │ NO
+source code có?      → YES: Source-first (mine behavior từ code)
+  │ NO
+testcase cũ tương tự?→ YES: History-first
+  │ NO
+domain rủi ro+defect?→ YES: Defect-first
+  │ NO
+→ hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
+```
+
+See `docs/orchestration-spec.md` for the full flow and `reports/sungen_refactor_spec.md` for the design rationale.

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -117,7 +117,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    | 5 | `text` | Plain text node (not inside interactive component) |
    | 6 | `locator` (CSS) | Last resort — `#id` or `[attr=value]` only, never classes or XPath |
 
-   See `sungen-figma-source` skill for the authoritative heuristics table mapping Figma signals to YAML entry types.
+   See `sungen-capture` skill (mode figma-pat) for the authoritative heuristics table mapping Figma signals to YAML entry types.
 
 4. **Write entries**: add each entry to `selectors.yaml`, prefixed with the required comment:
    ```yaml

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -7,7 +7,7 @@ user-invocable: false
 ## ⚠️ Gotchas — read before generating
 
 - `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
-  → PAT auth flow already done by `sungen-figma-source`; re-calling fails or duplicates work.
+  → PAT auth flow already done by `sungen-capture` (mode figma-pat); re-calling fails or duplicates work.
 
 - `selectors.yaml` → do **NOT** generate — handled by `run-test`
   → Selectors need live DOM inspection via Playwright MCP, only `run-test` triggers it.
@@ -208,6 +208,45 @@ Security:         [S1 – admin only]
 
 **✅ Good** — see admin notice example above: `Display surfaces` lists every URL spec mentions as output, `Cross-surface rules` maps each admin action to its user-facing outcome, `Inclusive bounds` flags every `<=`/`>=` for BVA. Every item maps to a VP-ID in `Tier 1 output`.
 
+#### Critical business-viewpoint pre-gate — pass `sungen audit` on the FIRST pass
+
+> The harness gate FAILS (and forces repair rounds → wasted tokens) when a page-type's critical **business** viewpoints are missing or **shallow**. Generate them correctly the first time. A business-critical `Then` must assert **DATA**, never just `see [X] page/section/modal`.
+
+**By page-type, generate a DEEP scenario for each (before expanding UI/validation/subscription):**
+
+| Page-type | Must-cover viewpoints (each with a data assertion) |
+|---|---|
+| **e-commerce list / home** | list-data (card has image+name+price+add) · product-detail-consistency · cart-correctness · category-filter-correctness · **brand-filter-correctness (separate from category)** · add-to-cart success · nav-core |
+| **form** | required-validation · format/boundary · submit-success |
+| **auth** | valid-login · invalid-credential · access-control |
+
+**Required assertion shapes (use these, not bare visibility):**
+- Card info: assert at **card level** (image+name+price together), e.g. `User see all [Product Card] contain {{...}}` — not `see [Section]`.
+- Cross-screen consistency (detail/cart): **capture then compare** —
+  ```gherkin
+  When User remember [Product Name] text as {{selected_product_name}}
+  And User remember [Product Price] text as {{selected_product_price}}
+  And User click [View Product] link
+  Then User see [Detail Product Name] header with {{selected_product_name}}
+  And User see [Detail Product Price] text contains {{selected_product_price}}
+  ```
+  Cross-screen target → tag `@manual` + `# Deferred to a flow (home -> detail)`.
+- Filter result (category AND brand, separately): `Then User see all [Result Product Name] contain {{selected_category}}` — proves EVERY item belongs, not one.
+
+**Depth is a GATE dimension (harness-roadmap P1) — self-raise, never silently go shallow:**
+- For every data-correctness theme the catalog marks `depth.requires: data-assertion`, emit its `depth.template` shape by **default** — don't wait for the repair loop. `sungen audit` measures `businessDepth` (ratio of these scenarios that assert data) against an intent threshold (functional ≥ 0.70); below it the **gate FAILs**.
+- `depth.cross_screen: true` (cart / detail / filter / brand correctness) → write the deep capture/compare shape but tag `@manual` + `# Deferred to a flow (...)`. These are excluded from the ratio (they're correctly deferred), so they don't hurt depth.
+- **If the spec lacks the concrete value** a deep assertion needs (exact message, price, count): still write the deep shape with a `{{var}}` placeholder and leave a `# SPEC-GAP: <field> value not in spec` comment — do **not** downgrade to `see [X] section`. A visible gap is better than a silent shallow pass.
+- **Blind-Spot Memory:** before finishing, run `sungen blindspot list --prompt` (Bash) and make sure the suite satisfies each recorded pattern (e.g. "for any Add/Create action: check success + resulting data state + duplicate/double-submit"). These are gaps QA hit before — don't repeat them.
+
+**First-pass anti-patterns (exactly what the gate/reviewer reject — avoid them):**
+- Title↔steps mismatch (e.g. a "no-result" scenario that clicks a query which returns products).
+- Tautology `Then`: `click [Next Slide]` → `see [Carousel] section` (proves nothing).
+- Business-critical scenario ending at `see [Added] modal` / `see [Cart] page` with no data assertion.
+- Brand filter covered only as navigation (must assert products belong to the brand).
+
+**Balance:** cover all the above (deep) BEFORE expanding subscription / UI-presence / extra validation edge cases.
+
 #### Tier 1 guard — minimum before writing scenarios
 
 | Spec section | Minimum requirement | Tag |

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

@@ -41,19 +41,33 @@ export class TestDataLoader {
   }
 
   get(key: string): string {
-    const parts = key.split('.');
-    let current: any = this.data;
-    for (const part of parts) {
-      if (current == null || typeof current !== 'object') {
-        throw new Error(`Test data key not found: ${key} (failed at '${part}')`);
+    // Captured/runtime vars (set() below) are stored under their literal — possibly
+    // dotted — key (e.g. "cart.product_name"), so check the flat key first.
+    let current: any = this.data[key];
+    if (current === undefined || current === null) {
+      // Fall back to nested navigation for YAML-structured keys (e.g. "cart.qty_two").
+      current = this.data;
+      for (const part of key.split('.')) {
+        if (current == null || typeof current !== 'object') {
+          throw new Error(`Test data key not found: ${key} (failed at '${part}')`);
+        }
+        current = current[part];
       }
-      current = current[part];
     }
     if (current === undefined || current === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
     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.