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

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.1",
+  "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);
+      }
+    });
+}

package/src/cli/commands/challenge.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { buildChallenge, renderChallengeMarkdown } from '../../harness/challenge';
+
+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;
+}
+
+export function registerChallengeCommand(program: Command): void {
+  program
+    .command('challenge')
+    .description('Exploration mode (Loop 2): attack the existing suite for blind spots — advisory, never auto-merges')
+    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('--json', 'Output the raw JSON report')
+    .action((o) => {
+      try {
+        const dir = findScreenDir(o.screen);
+        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
+        const report = buildChallenge(dir, o.screen);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const md = renderChallengeMarkdown(report);
+        const outPath = path.join(outDir, `${o.screen}-challenge.md`);
+        fs.writeFileSync(outPath, md, 'utf-8');
+
+        if (o.json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Challenge (exploration mode): ${report.screen} ━━━`);
+        L('  Advisory — does NOT change the official suite; surfaces what production missed.\n');
+        L('  ① Depth — title claims a collection but asserts a single element');
+        if (report.collectionClaimSingular.length) {
+          for (const f of report.collectionClaimSingular) L(`     ⚠ ${f.scenario}\n        → ${f.suggestion}`);
+        } else L('     ✓ none');
+        L('  ② Coverage — over-covered / shallow');
+        if (report.overCovered.length) for (const o2 of report.overCovered) L(`     • ${o2.bucket}: ${o2.note}`);
+        if (report.shallowThemes.length) L(`     • shallow themes: ${report.shallowThemes.join(', ')}`);
+        if (!report.overCovered.length && !report.shallowThemes.length) L('     ✓ balanced');
+        L('  ③ Novelty — prompts for the `sungen-challenge` agent (≤20% of official, no auto-merge)');
+        for (const p of report.noveltyPrompts) L(`     • ${p}`);
+        L('  ── Exploration readiness ──');
+        for (const e of report.explorationReadiness) L(`     • ${e}`);
+        L(`\n  Report: ${path.relative(process.cwd(), outPath)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/feedback.ts

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { recordFeedback, summarize, FeedbackType, FeedbackDecision } from '../../harness/feedback';
+
+const TYPES = ['test-design', 'product', 'other'];
+const DECISIONS = ['accept', 'reject', 'edit', 'add', 'none'];
+
+export function registerFeedbackCommand(program: Command): void {
+  const fb = program
+    .command('feedback')
+    .description('Local-first QA feedback (test-design knowledge + product telemetry). Synced later when a server exists.');
+
+  fb
+    .command('record')
+    .description('Record a feedback entry')
+    .requiredOption('--message <text>', 'The feedback')
+    .option('--type <t>', `Feedback type (${TYPES.join('|')})`, 'test-design')
+    .option('-s, --screen <name>', 'Screen/flow the feedback relates to')
+    .option('--target <ref>', 'What it is about (viewpoint id / scenario / command / artifact)')
+    .option('--decision <d>', `QA decision (${DECISIONS.join('|')})`, 'none')
+    .option('--reason <text>', 'Why')
+    .option('--source <who>', 'Who gave the feedback', 'qa')
+    .action((o) => {
+      try {
+        if (!TYPES.includes(o.type)) throw new Error(`--type must be one of ${TYPES.join(', ')}`);
+        if (!DECISIONS.includes(o.decision)) throw new Error(`--decision must be one of ${DECISIONS.join(', ')}`);
+        const p = recordFeedback({
+          type: o.type as FeedbackType,
+          screen: o.screen,
+          target: o.target,
+          decision: o.decision as FeedbackDecision,
+          message: o.message,
+          reason: o.reason,
+          source: o.source,
+        });
+        console.log(`✓ feedback recorded (${o.type}${o.screen ? ' · ' + o.screen : ''}) → ${p}`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  fb
+    .command('list')
+    .description('List / summarise recorded feedback')
+    .option('-s, --screen <name>', 'Filter by screen')
+    .option('--type <t>', 'Filter by type')
+    .option('--json', 'Output raw JSON')
+    .action((o) => {
+      try {
+        const s = summarize({ screen: o.screen, type: o.type });
+        if (o.json) { console.log(JSON.stringify(s, null, 2)); return; }
+        console.log(`\n━━━ Feedback (${s.total}) ━━━`);
+        console.log(`  by type: ${Object.entries(s.byType).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}`);
+        console.log(`  by decision: ${Object.entries(s.byDecision).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}\n`);
+        for (const e of s.entries.slice(-20)) {
+          console.log(`  [${e.type}${e.decision && e.decision !== 'none' ? '/' + e.decision : ''}] ${e.screen ? e.screen + ' · ' : ''}${e.target ? e.target + ' — ' : ''}${e.message}`);
+          if (e.reason) console.log(`      reason: ${e.reason}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/generate.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
+import { scanTestDataSecrets } from '../../harness/secret-scan';
 
 /**
  * Find .feature files recursively in a directory
@@ -137,6 +138,24 @@ export function registerGenerateCommand(program: Command): void {
         );
 
         console.log(`\n${results.length} test file(s) generated.`);
+
+        // Security S0 — warn (never block) if test-data looks to hold a real secret.
+        const scanDirs: string[] = [];
+        if (screenName) scanDirs.push(path.join(process.cwd(), 'qa', 'screens', screenName));
+        else if (flowName) scanDirs.push(path.join(process.cwd(), 'qa', 'flows', flowName));
+        else {
+          for (const base of ['screens', 'flows']) {
+            const d = path.join(process.cwd(), 'qa', base);
+            if (fs.existsSync(d)) for (const n of fs.readdirSync(d)) scanDirs.push(path.join(d, n));
+          }
+        }
+        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
+        if (secretHits.length) {
+          console.log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
+          for (const h of secretHits.slice(0, 10)) console.log(`   ${h.file}:${h.line} — ${h.reason}`);
+          console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
+        }
+
         console.log(`Next step: npx playwright test --ui\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);