@sun-asterisk/sungen 3.0.0 → 3.0.1

package/dist/orchestrator/templates/ai-instructions/claude-skill-ingest-legacy.md

@@ -0,0 +1,79 @@
+---
+name: sungen-ingest-legacy
+description: 'Import a legacy manual testcase suite from Google Sheets (multi-tab) or a local file into Sungen — fetch via MCP, then sungen ingest. Use when the user wants to convert/evaluate an existing manual testcase spreadsheet.'
+user-invocable: true
+---
+
+# sungen-ingest-legacy
+
+Bring an existing **manual testcase workbook** into Sungen for evaluation + conversion. The
+fetch (Google login + pick file) is done here via MCP; the parsing/audit is deterministic
+(`sungen ingest`). **Security:** the workbook is the user's project data — read it on
+consent, keep the output in their project, never upload or commit the content.
+
+## Flow
+
+1. **Locate the source.**
+   - **Google Sheets (recommended):** use the Google Drive MCP. Authenticate if needed, then
+     `search_files` / list to find the workbook; confirm the file with the user.
+   - **Local:** if the user points to a `.xlsx`/`.csv`, skip to step 4.
+
+2. **List the tabs.** Read the workbook's sheet/tab names (Drive MCP file metadata or a values
+   read). A legacy workbook usually has **many** tabs — some are testcases, some are
+   viewpoint/UI matrices.
+
+3. **Assemble a JSON sheet-bundle.** For each tab, read its cell values (a 2-D array of
+   strings) and write a local bundle in the user project (e.g.
+   `qa/screens/<screen>/requirements/legacy/bundle.json`):
+   ```json
+   { "source": "<workbook name>", "sheets": [ { "name": "<tab>", "rows": [["TC ID","Page",…],["TC-01",…]] } ] }
+   ```
+   Record only the **source link** in `requirements/legacy/source.yaml` — never the content.
+
+4. **Classify the tabs.** Run:
+   ```bash
+   sungen ingest --legacy <bundle.json|file.xlsx|file.csv> --list-sheets
+   ```
+   It prints each tab + detected type (`testcase` / `viewpoint-matrix` / `ui-checklist`).
+
+5. **Confirm which tabs to ingest.** Use `AskUserQuestion` to let the user pick the
+   **testcase** tabs (matrix/UI tabs feed the viewpoint layer later, not the inventory).
+
+6. **Ingest + reconcile.**
+   ```bash
+   sungen ingest --legacy <source> --screen <screen> --sheets "<Tab A>,<Tab B>" --emit-gherkin
+   ```
+   Produces: `inventory.json` (+ baseline audit), `*.legacy-draft.feature` + `legacy-trace.json`
+   (parity: `@legacy:<id>` per scenario), and `test-viewpoint.draft.md` with **blind-spots**
+   (catalog-expected viewpoints the legacy suite lacks).
+
+7. **Hand off to quality.** Tell the user the next step is `/sungen:create-test <screen>` —
+   it discovers + refines the draft into real `[Reference]` steps and fills the blind-spots;
+   then `sungen audit <screen>` gates quality. A 1:1 convert is NOT the deliverable; the
+   harness raises the legacy floor to catalog quality.
+
+## Governance block (important)
+
+Many orgs mark confidential files as **"ineligible for generative AI contexts"** — the
+Google Drive MCP will then **refuse** to read the file (metadata + download both error).
+This is the org's DLP policy, not a bug, and it is the *expected* outcome for a
+confidential testcase suite. When you hit it, **do not retry** — fall back:
+
+> "This sheet is restricted by your org's data policy, so I can't read it through the
+> AI connector. Two ways to proceed, both running as **you**, not AI:
+>  (1) `sungen ingest --gsheet <url>` — fetches under your own Google identity
+>      (read-only; Viewer/Commenter is enough). It offers to install `googleapis`
+>      and to open the Google login in your browser (pick your account), then
+>      retries automatically. Needs the gcloud SDK for the browser login.
+>  (2) Export it manually (**File → Download → Microsoft Excel `.xlsx`**) and I'll run
+>      `sungen ingest --legacy <file>.xlsx`."
+
+The local-file path is deterministic and **never sends the content through AI** — the
+correct, governance-compliant channel for confidential data. The MCP auto-pick is only
+for files the org does *not* restrict.
+
+## Notes
+- Multiple local CSVs (one per tab) also work: `--legacy tab1.csv tab2.csv …`.
+- Re-run only re-fetches when the user asks; otherwise reuse the saved bundle.
+- Do not invent testcases. Only ingest what the workbook contains; the *augmentation*
+  (blind-spots) happens in `/sungen:create-test`, flagged for human review.

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

@@ -105,6 +105,9 @@ Auto-detected by `create-test` before invoking this skill:
   2. Each row / bullet / item = 1 viewpoint → add to `Viewpoint items` in Coverage Map.
   3. Do NOT pre-classify into buckets before scanning — classify only when
      writing the scenario.
+  4. **If it declares viewpoint IDs** (e.g. `VP0`, `VP1`…`VP12`, `MS-HP-001`), capture each
+     item WITH its ID and **reuse that ID as the scenario code** — do not invent a generic
+     `VP-<CAT>` scheme (the harness Taxonomy-match gate FAILs on mismatch).
 - `qa/context.md` — project-wide context set by the QA lead. Read ONCE before building the Coverage Map; apply to every screen. Extraction rules:
   - **Roles** → for each role in the table: add to the `@auth:X` tag pool; generate a VP-SEC blocked-access scenario for every role boundary relevant to this screen.
   - **Testing strategy → Focus areas** → if `security` listed: VP-SEC is mandatory Tier 1 for every free-text input regardless of spec risk level; if `ui` not listed: all VP-UI scenarios move to Tier 2 minimum.
@@ -260,6 +263,27 @@ Security:         [S1 – admin only]
 
 **Balance:** cover all the above (deep) BEFORE expanding subscription / UI-presence / extra validation edge cases. Do not over-invest in subscription while cart/detail/filter correctness are shallow.
 
+#### Harness gates — satisfy on the FIRST pass (don't make the repair loop fix them)
+
+`sungen audit` enforces these. Generate compliant output up front:
+
+1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
+3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
+   - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.
+4. **Downstream-scope** (`DOWNSTREAM-SCOPE-MISSING`) — when the spec's Navigation Flow / success target is **another screen** (e.g. a confirmation/sent page), don't stop at a terminal `see [X] page`. Either cover that screen's content/guards (if its viewpoint items are in scope — they often have their own `MS-*` IDs), or scaffold it (`sungen add --screen <name>`) and note the handoff. Do not silently drop the downstream surface.
+5. **Manual-oracle** (`MANUAL-STEPS-INSUFFICIENT`) — every `@manual` scenario needs **setup · action · observable expected · oracle/tool**, not a one-line note. Use this comment shape:
+   ```gherkin
+   @high @manual
+   Scenario: VP-… <claim>
+     # MANUAL: <why it can't be automated — needs network capture / inbox / screen-reader / multi-tab>
+     # Tester verifies:
+     #   1. <setup>            e.g. seed a registered email; throttle the network
+     #   2. <action>           e.g. click [Submit] with the request in flight
+     #   3. <observable>       e.g. only ONE POST is dispatched
+     #   4. Oracle: <tool>     e.g. DevTools Network panel / mail-catcher / NVDA
+   ```
+
 #### Tier 1 guard — minimum before writing scenarios
 
 | Spec section | Minimum requirement | Tag |
@@ -376,7 +400,7 @@ Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
 **Files:** `qa/screens/<screen>/features/<screen>.feature` + `qa/screens/<screen>/test-data/<screen>.yaml`
 
 Use step patterns and element types from `sungen-gherkin-syntax`.
-**Naming**: `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
+**Naming**: reuse the **project's `test-viewpoint.md` IDs** when it declares them (e.g. `VP0`, `MS-HP-001`); otherwise `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
 
 **Test data** — grouped by section, loaded at runtime:
 

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

@@ -78,6 +78,16 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 
 ---
 
+## XLSX sheets — Auto / Manual split
+
+The `.xlsx` is split into two sheets so QA manages the sets separately:
+- **`Auto`** — automatable test cases (`Auto` + `Not compiled`).
+- **`Manual`** — `@manual` test cases (always present, header-only when there are none).
+
+Multi-locale (no `SUNGEN_ENV`): one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual.
+
+---
+
 ## Excluded from CSV
 
 - `@steps:<name>` **base** scenarios — these are setup-only, inlined into `@extend:...` scenarios at compile time

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-ingest-legacy.md

@@ -0,0 +1,79 @@
+---
+name: sungen-ingest-legacy
+description: 'Import a legacy manual testcase suite from Google Sheets (multi-tab) or a local file into Sungen — fetch via MCP, then sungen ingest. Use when the user wants to convert/evaluate an existing manual testcase spreadsheet.'
+user-invocable: true
+---
+
+# sungen-ingest-legacy
+
+Bring an existing **manual testcase workbook** into Sungen for evaluation + conversion. The
+fetch (Google login + pick file) is done here via MCP; the parsing/audit is deterministic
+(`sungen ingest`). **Security:** the workbook is the user's project data — read it on
+consent, keep the output in their project, never upload or commit the content.
+
+## Flow
+
+1. **Locate the source.**
+   - **Google Sheets (recommended):** use the Google Drive MCP. Authenticate if needed, then
+     `search_files` / list to find the workbook; confirm the file with the user.
+   - **Local:** if the user points to a `.xlsx`/`.csv`, skip to step 4.
+
+2. **List the tabs.** Read the workbook's sheet/tab names (Drive MCP file metadata or a values
+   read). A legacy workbook usually has **many** tabs — some are testcases, some are
+   viewpoint/UI matrices.
+
+3. **Assemble a JSON sheet-bundle.** For each tab, read its cell values (a 2-D array of
+   strings) and write a local bundle in the user project (e.g.
+   `qa/screens/<screen>/requirements/legacy/bundle.json`):
+   ```json
+   { "source": "<workbook name>", "sheets": [ { "name": "<tab>", "rows": [["TC ID","Page",…],["TC-01",…]] } ] }
+   ```
+   Record only the **source link** in `requirements/legacy/source.yaml` — never the content.
+
+4. **Classify the tabs.** Run:
+   ```bash
+   sungen ingest --legacy <bundle.json|file.xlsx|file.csv> --list-sheets
+   ```
+   It prints each tab + detected type (`testcase` / `viewpoint-matrix` / `ui-checklist`).
+
+5. **Confirm which tabs to ingest.** Use `AskUserQuestion` to let the user pick the
+   **testcase** tabs (matrix/UI tabs feed the viewpoint layer later, not the inventory).
+
+6. **Ingest + reconcile.**
+   ```bash
+   sungen ingest --legacy <source> --screen <screen> --sheets "<Tab A>,<Tab B>" --emit-gherkin
+   ```
+   Produces: `inventory.json` (+ baseline audit), `*.legacy-draft.feature` + `legacy-trace.json`
+   (parity: `@legacy:<id>` per scenario), and `test-viewpoint.draft.md` with **blind-spots**
+   (catalog-expected viewpoints the legacy suite lacks).
+
+7. **Hand off to quality.** Tell the user the next step is `/sungen:create-test <screen>` —
+   it discovers + refines the draft into real `[Reference]` steps and fills the blind-spots;
+   then `sungen audit <screen>` gates quality. A 1:1 convert is NOT the deliverable; the
+   harness raises the legacy floor to catalog quality.
+
+## Governance block (important)
+
+Many orgs mark confidential files as **"ineligible for generative AI contexts"** — the
+Google Drive MCP will then **refuse** to read the file (metadata + download both error).
+This is the org's DLP policy, not a bug, and it is the *expected* outcome for a
+confidential testcase suite. When you hit it, **do not retry** — fall back:
+
+> "This sheet is restricted by your org's data policy, so I can't read it through the
+> AI connector. Two ways to proceed, both running as **you**, not AI:
+>  (1) `sungen ingest --gsheet <url>` — fetches under your own Google identity
+>      (read-only; Viewer/Commenter is enough). It offers to install `googleapis`
+>      and to open the Google login in your browser (pick your account), then
+>      retries automatically. Needs the gcloud SDK for the browser login.
+>  (2) Export it manually (**File → Download → Microsoft Excel `.xlsx`**) and I'll run
+>      `sungen ingest --legacy <file>.xlsx`."
+
+The local-file path is deterministic and **never sends the content through AI** — the
+correct, governance-compliant channel for confidential data. The MCP auto-pick is only
+for files the org does *not* restrict.
+
+## Notes
+- Multiple local CSVs (one per tab) also work: `--legacy tab1.csv tab2.csv …`.
+- Re-run only re-fetches when the user asks; otherwise reuse the saved bundle.
+- Do not invent testcases. Only ingest what the workbook contains; the *augmentation*
+  (blind-spots) happens in `/sungen:create-test`, flagged for human review.

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

@@ -105,6 +105,17 @@ Auto-detected by `create-test` before invoking this skill:
   2. Each row / bullet / item = 1 viewpoint → add to `Viewpoint items` in Coverage Map.
   3. Do NOT pre-classify into buckets before scanning — classify only when
      writing the scenario.
+  4. **If it declares viewpoint IDs** (e.g. `VP0`, `VP1`…`VP12`, `MS-HP-001`), capture each
+     item WITH its ID and **reuse that ID as the scenario code** — do not invent a generic
+     `VP-<CAT>` scheme (the harness Taxonomy-match gate FAILs on mismatch).
+- `qa/context.md` — project-wide context set by the QA lead. Read ONCE before building the Coverage Map; apply to every screen. Extraction rules:
+  - **Roles** → for each role in the table: add to the `@auth:X` tag pool; generate a VP-SEC blocked-access scenario for every role boundary relevant to this screen.
+  - **Testing strategy → Focus areas** → if `security` listed: VP-SEC is mandatory Tier 1 for every free-text input regardless of spec risk level; if `ui` not listed: all VP-UI scenarios move to Tier 2 minimum.
+  - **Testing strategy → Mandatory coverage** → each line is a hard override applied to this screen regardless of spec risk; document in `Context constraints` of the Coverage Map.
+  - **Testing strategy → Deprioritize/skip** → record in `Context constraints`; suppress those VP categories from Tier 1 generation.
+  - **Global business rules** → add each to the `Business rules` section tagged `[G]` (e.g. `[G1 – soft-delete only]`); treat as `HIGH` risk unless stated otherwise.
+  - **Error patterns** → use as fallback only when `spec.md` does not give exact error text; never override spec-specified messages.
+  - If `qa/context.md` is absent: proceed without it — no impact on the generation flow.
 
 **Single screen focus**: one URL = one screen. Modals on same page = part of this screen.
 This means: do not test other screens' UI layout or navigation. It does NOT mean skip documenting business outcomes that your screen's actions cause on other surfaces. Those cross-surface outcomes must appear in the Coverage Map and be covered by at least `@manual` scenarios.
@@ -129,6 +140,11 @@ Read `spec.md` fully, then extract into a Coverage Map **before writing any scen
 **Risk tags:** HIGH = complex business rules, cascading fields, multi-step state changes, auth/integration. LOW = display-only, static labels, read-only fields.
 
 ```
+Context constraints: [populated from qa/context.md before writing any scenario]
+                     roles: [list roles, e.g. admin / manager / staff]
+                     strategy: [active overrides, e.g. "VP-SEC mandatory T1", "VP-UI → T2 only"]
+                     global rules: [G1 – ...] → also appear in Business rules below tagged [G]
+                     → leave empty if qa/context.md is absent or has no entries applicable to this screen
 User journeys:       [J1 – ...], [J2 – ...]
 Validation rules:    [V1 – field → "exact error text"], [V2 – ...]
 Business rules:      [B1 HIGH – ...], [B2 LOW – ...]
@@ -221,7 +237,7 @@ Security:         [S1 – admin only]
 | **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]`.
+- Card info: assert at **card level** (image+name+price together), e.g. `User see all [Product Card] contain {{...}}` — not `see [Section]` (section-level passes even if one card lacks price).
 - Cross-screen consistency (detail/cart): **capture then compare** —
   ```gherkin
   When User remember [Product Name] text as {{selected_product_name}}
@@ -239,13 +255,34 @@ Security:         [S1 – admin only]
 - **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.
+**First-pass anti-patterns (these are exactly what the gate/reviewer reject — avoid them):**
+- Title↔steps mismatch: e.g. a "no-result state" scenario that clicks a query which **returns** products. Steps must create the condition the title claims.
+- Tautology `Then`: `click [Next Slide]` → `see [Carousel] section` (always visible, proves nothing). Assert the change (new slide title differs).
+- Business-critical scenario ending at `see [Added] modal` / `see [Cart] page` / `see [Category Products] 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.
+**Balance:** cover all the above (deep) BEFORE expanding subscription / UI-presence / extra validation edge cases. Do not over-invest in subscription while cart/detail/filter correctness are shallow.
+
+#### Harness gates — satisfy on the FIRST pass (don't make the repair loop fix them)
+
+`sungen audit` enforces these. Generate compliant output up front:
+
+1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
+3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
+   - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.
+4. **Downstream-scope** (`DOWNSTREAM-SCOPE-MISSING`) — when the spec's Navigation Flow / success target is **another screen** (e.g. a confirmation/sent page), don't stop at a terminal `see [X] page`. Either cover that screen's content/guards (if its viewpoint items are in scope — they often have their own `MS-*` IDs), or scaffold it (`sungen add --screen <name>`) and note the handoff. Do not silently drop the downstream surface.
+5. **Manual-oracle** (`MANUAL-STEPS-INSUFFICIENT`) — every `@manual` scenario needs **setup · action · observable expected · oracle/tool**, not a one-line note. Use this comment shape:
+   ```gherkin
+   @high @manual
+   Scenario: VP-… <claim>
+     # MANUAL: <why it can't be automated — needs network capture / inbox / screen-reader / multi-tab>
+     # Tester verifies:
+     #   1. <setup>            e.g. seed a registered email; throttle the network
+     #   2. <action>           e.g. click [Submit] with the request in flight
+     #   3. <observable>       e.g. only ONE POST is dispatched
+     #   4. Oracle: <tool>     e.g. DevTools Network panel / mail-catcher / NVDA
+   ```
 
 #### Tier 1 guard — minimum before writing scenarios
 
@@ -363,7 +400,7 @@ Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
 **Files:** `qa/screens/<screen>/features/<screen>.feature` + `qa/screens/<screen>/test-data/<screen>.yaml`
 
 Use step patterns and element types from `sungen-gherkin-syntax`.
-**Naming**: `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
+**Naming**: reuse the **project's `test-viewpoint.md` IDs** when it declares them (e.g. `VP0`, `MS-HP-001`); otherwise `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
 
 **Test data** — grouped by section, loaded at runtime:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,8 +12,8 @@
     "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": "tsx tests/golden/run.ts && tsx tests/audit/run.ts",
-    "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts",
+    "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
   "keywords": [

package/src/cli/commands/audit.ts

@@ -58,6 +58,25 @@ function render(r: AuditReport): void {
   L(`  ⑥ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
   L(`      ${r.trace.note}`);
   L('');
+  if (r.spec.hasSpec && (r.spec.frTotal > 0 || r.spec.triggerGaps.length > 0 || r.spec.verdict !== 'pass')) {
+    L(`  ⑦ Spec coverage — FR ${r.spec.frCovered}/${r.spec.frTotal} covered  [${r.spec.verdict.toUpperCase()}]`);
+    for (const g of r.spec.triggerGaps) L(`      ✗ TRIGGER-UNCOVERED: "${g.constraint}"${g.code ? ` (${g.code})` : ''} mandated on [${g.required.join(', ')}], only tested on [${g.found.join(', ') || 'none'}] → missing ${g.missing.join(', ')}`);
+    for (const u of r.spec.uncoveredMust.slice(0, 6)) L(`      ✗ SPEC-UNCOVERED: ${u.id} (MUST) — "${u.text}"`);
+    if (!r.spec.triggerGaps.length && !r.spec.uncoveredMust.length) L('      ✓ every MUST FR + per-constraint trigger covered');
+    L('');
+  }
+  if (r.ledger.hasViewpoint && r.ledger.total > 0) {
+    L(`  ⑧ Viewpoint atomic coverage — ${r.ledger.covered}/${r.ledger.total} items (${(r.ledger.ratio * 100).toFixed(0)}%)`);
+    for (const m of r.ledger.missing.slice(0, 8)) L(`      ○ missing: ${m.id ? m.id + ' — ' : ''}${m.text.slice(0, 70)}`);
+    if (r.ledger.missing.length > 8) L(`      … +${r.ledger.missing.length - 8} more`);
+    L('');
+  }
+  if (r.calibration) {
+    const ax = Object.entries(r.calibration.axes).map(([k, v]) => `${k}=${(v * 100).toFixed(0)}%`).join(' · ');
+    L(`  ⑨ Calibration — ${ax}`);
+    L(`      weakest: ${r.calibration.weakest.axis} ${(r.calibration.weakest.value * 100).toFixed(0)}%${r.calibration.inflated ? '  ⚠ SCORE-INFLATED-BY-BREADTH' : ''}`);
+    L('');
+  }
   L('  ── Findings (Repair targets) ──');
   if (r.findings.length === 0) L('      ✓ none — output passes the harness');
   for (const f of r.findings) L(`      • ${f}`);

package/src/cli/commands/delivery.ts

@@ -20,7 +20,7 @@ import {
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
-import { renderXlsx, renderXlsxMultiSheet, writeXlsx } from '../../exporters/xlsx-exporter';
+import { renderXlsxMultiSheet, writeXlsx } from '../../exporters/xlsx-exporter';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow } from '../../exporters/types';
 
 const COLOR = {
@@ -421,7 +421,14 @@ async function exportTarget(
       const tempSummary = buildSummary(label, rows, '');
       const csv = renderCsv(tempSummary, rows, specLink);
       const csvPath = writeCsv(cwd, target.featureBaseName, csv);
-      const wb = renderXlsx(tempSummary, rows, specLink);
+      // XLSX: two sheets — "Auto" (automatable: Auto + Not compiled) and "Manual" (@manual) —
+      // so QA manages the automated vs manual test-case sets separately. (CSV keeps every row.)
+      const autoRows = rows.filter((r) => r.testcaseType !== 'Manual');
+      const manualRows = rows.filter((r) => r.testcaseType === 'Manual');
+      const wb = renderXlsxMultiSheet([
+        { sheetName: 'Auto', summary: buildSummary(label, autoRows, ''), rows: autoRows, specLink },
+        { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
+      ]);
       await writeXlsx(cwd, target.featureBaseName, wb);
       return buildSummary(label, rows, path.relative(cwd, csvPath));
     }
@@ -429,7 +436,12 @@ async function exportTarget(
     const variants = discoverLocaleVariants(cwd, target);
     let primarySummary: ScreenSummary | null = null;
     let primaryCsvPath = '';
-    const sheets: { sheetName: string; summary: ScreenSummary; rows: TestCaseRow[]; specLink: string }[] = [];
+    // XLSX is split by automation type: an "Auto" sheet (automatable TCs, results differ per
+    // locale) and a single shared "Manual" sheet (@manual TCs don't execute and are the same
+    // across locales). With multiple locales, Auto sheets are prefixed by locale code.
+    const autoSheets: { sheetName: string; summary: ScreenSummary; rows: TestCaseRow[]; specLink: string }[] = [];
+    let manualRows: TestCaseRow[] = [];
+    const multiLocale = variants.length > 1;
 
     for (const variant of variants) {
       // For the base variant the overlay merge is skipped (`locale: null`);
@@ -446,33 +458,37 @@ async function exportTarget(
         env,
         selectorKeyMap,
       });
-      const variantSummary = buildSummary(label, variantRows, '');
 
-      // CSV: always one file per locale (CSV has no sheet concept).
+      // CSV: always one file per locale, every row (CSV has no sheet concept).
       const csvLocale = variant.locale || null; // '' or 'en' → '' / 'en'
-      const csv = renderCsv(variantSummary, variantRows, specLink);
+      const csv = renderCsv(buildSummary(label, variantRows, ''), variantRows, specLink);
       const csvPath = writeCsv(cwd, target.featureBaseName, csv, csvLocale);
 
-      sheets.push({
-        sheetName: `${target.featureBaseName}-${variant.displayCode}`,
-        summary: variantSummary,
-        rows: variantRows,
+      const autoRows = variantRows.filter((r) => r.testcaseType !== 'Manual');
+      autoSheets.push({
+        sheetName: multiLocale ? `${variant.displayCode} Auto` : 'Auto',
+        summary: buildSummary(label, autoRows, ''),
+        rows: autoRows,
         specLink,
       });
 
-      // Use the base variant's summary as the "primary" return value so the
-      // top-level reporter rolls up base-locale numbers.
+      // Use the base variant for the shared Manual sheet + the rolled-up "primary" summary.
       if (variant.locale === '') {
+        manualRows = variantRows.filter((r) => r.testcaseType === 'Manual');
         primarySummary = buildSummary(label, variantRows, path.relative(cwd, csvPath));
         primaryCsvPath = csvPath;
       }
     }
 
-    // XLSX: single-sheet when only base, multi-sheet when 2+ locales found.
-    const wb = sheets.length >= 2 ? renderXlsxMultiSheet(sheets) : renderXlsx(sheets[0].summary, sheets[0].rows, specLink);
+    // All Auto sheets, then one "Manual" sheet — always present for a predictable structure.
+    const sheets = [
+      ...autoSheets,
+      { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
+    ];
+    const wb = renderXlsxMultiSheet(sheets);
     await writeXlsx(cwd, target.featureBaseName, wb);
 
-    return primarySummary ?? buildSummary(label, sheets[0].rows, primaryCsvPath);
+    return primarySummary ?? buildSummary(label, (autoSheets[0]?.rows ?? []).concat(manualRows), primaryCsvPath);
   } catch (err) {
     console.error(`${COLOR.red}Error exporting ${label}:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
     return null;

package/src/cli/commands/eval.ts

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import { lintSkills, defaultSkillDir } from '../../harness/eval/skill-lint';
+
+export function registerEvalCommand(program: Command): void {
+  program
+    .command('eval')
+    .description('Eval harness: quality checks on Sungen\'s own skills/instructions (dev/CI)')
+    .option('--skills', 'Static skill-lint: frontmatter, line budget, claude↔github sync, registration')
+    .option('--dir <path>', 'Templates dir to lint (default: bundled ai-instructions)')
+    .option('--json', 'Output the raw findings JSON')
+    .action((options) => {
+      try {
+        if (!options.skills) throw new Error('Provide --skills (the only eval mode today)');
+        const dir = options.dir || defaultSkillDir();
+        const r = lintSkills(dir);
+        if (options.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.errors > 0 ? 2 : 0); }
+        console.log('');
+        console.log(`━━━ Skill-lint: ${r.checked} skill template(s) ━━━`);
+        if (!r.findings.length) console.log('  ✓ all skills pass (frontmatter · line-budget · variant-sync · registration)');
+        for (const f of r.findings) console.log(`  ${f.level === 'error' ? '✗' : '⚠'} [${f.rule}] ${f.file} — ${f.detail}`);
+        console.log('');
+        process.exit(r.errors > 0 ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/ingest.ts

@@ -0,0 +1,141 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { parseLegacyFile, listSheets, baselineAudit, BaselineReport, LegacyInventory, inventoryToGherkin, reconcileViewpoints, renderViewpointOverview, fetchGoogleSheet } from '../../ingest';
+
+function renderInventoryMd(inv: LegacyInventory, r: BaselineReport): string {
+  const lines: string[] = [];
+  lines.push(`# Legacy Testcase Inventory — ${inv.source.file}`, '');
+  lines.push(`Total testcases: **${r.total}**`, '');
+  lines.push('## Sheets', '', '| Sheet | Type | Rows |', '|---|---|---|');
+  for (const s of r.sheets) lines.push(`| ${s.name} | ${s.type} | ${s.rows} |`);
+  lines.push('', '## By category', '');
+  for (const [k, v] of Object.entries(r.byCategory).sort((a, b) => b[1] - a[1])) lines.push(`- ${k}: ${v}`);
+  lines.push('', `Depth: **${(r.depthRatio * 100).toFixed(0)}%** (${r.deepCount}/${r.total} assert a concrete expected value)`, '');
+  return lines.join('\n');
+}
+
+function render(inv: LegacyInventory, r: BaselineReport): void {
+  const L = console.log;
+  const pct = (x: number) => (r.total ? Math.round((x / r.total) * 100) : 0);
+  L('');
+  L(`━━━ Legacy Ingest — ${inv.source.file} ━━━`);
+  L('');
+  L(`  Sheets:`);
+  for (const s of r.sheets) L(`    • ${s.name} — ${s.type} (${s.rows})`);
+  L('');
+  L(`  TOTAL testcases: ${r.total}`);
+  L('');
+  L('  ── QA baseline ──');
+  L(`  By category: ${Object.entries(r.byCategory).sort((a, b) => b[1] - a[1]).slice(0, 12).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  L(`  By priority: ${Object.entries(r.byPriority).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  L(`  By result:   ${Object.entries(r.byResult).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  L(`  Depth:       ${r.deepCount}/${r.total} (${(r.depthRatio * 100).toFixed(0)}%) assert a concrete expected value → convert to DEEP Gherkin`);
+  L(`  Duplicates:  ${r.duplicateClusters} same-shape cluster(s), ${r.exactDuplicates} likely exact`);
+  L('');
+  L('  ── Capability Plan (which driver, if any) ──');
+  L(`    UI automatable      : ${r.reasons.ui}  (${pct(r.reasons.ui)}%)`);
+  L(`    cross-screen → flow : ${r.reasons.crossScreen}  (${pct(r.reasons.crossScreen)}%)`);
+  L(`    capability-manual   : ${r.reasons.capabilityManual}  (${pct(r.reasons.capabilityManual)}%)`);
+  L(`    keep-manual         : ${r.reasons.keepManual}  (${pct(r.reasons.keepManual)}%)`);
+  if (r.reasons.driverCandidates.length)
+    L(`    driver candidates   : ${r.reasons.driverCandidates.map((d) => `${d.driver}×${d.count}`).join('  ')}`);
+  else
+    L(`    driver candidates   : none (no capability-manual at scale → no driver justified)`);
+  L('');
+}
+
+export function registerIngestCommand(program: Command): void {
+  program
+    .command('ingest')
+    .description('Ingest a legacy manual testcase workbook (CSV/XLSX/JSON-bundle) → normalized inventory + QA baseline audit')
+    .option('--legacy <file...>', 'Path(s) to the legacy testcase file(s): .csv, .xlsx, or a .json sheet-bundle')
+    .option('--gsheet <urlOrId>', 'Fetch a Google Sheet (all tabs) under YOUR Google identity (ADC, read-only) → bundle. Needs: npm i googleapis + gcloud auth application-default login')
+    .option('-s, --screen <name>', 'Screen name (output goes under qa/screens/<name>/requirements/legacy/)')
+    .option('--out <dir>', 'Output directory (overrides the default screen path)')
+    .option('--sheets <names>', 'Comma-separated tab names to ingest (default: all). Workbooks carry many tabs.')
+    .option('--list-sheets', 'List the tabs + detected type (testcase/viewpoint-matrix/ui-checklist) and exit')
+    .option('--emit-gherkin', 'Also emit a traceable Gherkin DRAFT (.legacy-draft.feature) + trace map (P-B)')
+    .option('--json', 'Print the raw inventory + baseline JSON')
+    .action(async (options) => {
+      try {
+        if (!options.legacy && !options.gsheet) throw new Error('Provide --legacy <file...> or --gsheet <url|id>');
+
+        const outDir = options.out
+          ? path.resolve(process.cwd(), options.out)
+          : options.screen
+            ? path.join(process.cwd(), 'qa', 'screens', options.screen, 'requirements', 'legacy')
+            : path.join(process.cwd(), '.sungen', 'legacy');
+        fs.mkdirSync(outDir, { recursive: true });
+
+        let files: string[];
+        if (options.gsheet) {
+          // Fetch as the user (not AI) — bypasses the AI-context DLP legitimately.
+          const bundle = await fetchGoogleSheet(String(options.gsheet));
+          const bundlePath = path.join(outDir, 'bundle.json');
+          fs.writeFileSync(bundlePath, JSON.stringify(bundle, null, 0));
+          console.log(`  Fetched Google Sheet "${bundle.source}" → ${bundle.sheets.length} tab(s) → ${path.relative(process.cwd(), bundlePath)}`);
+          files = [bundlePath];
+        } else {
+          files = (Array.isArray(options.legacy) ? options.legacy : [options.legacy])
+            .map((f: string) => path.resolve(process.cwd(), f));
+          for (const f of files) if (!fs.existsSync(f)) throw new Error(`File not found: ${f}`);
+        }
+
+        if (options.listSheets) {
+          const sheets = await listSheets(files);
+          console.log('');
+          console.log('  Tabs found:');
+          for (const s of sheets) console.log(`    • ${s.name} — ${s.type} (${s.rows} rows)`);
+          console.log('');
+          console.log(`  Ingest the testcase tab(s) with: --sheets "${sheets.filter((s) => s.type === 'testcase').map((s) => s.name).join(',')}"`);
+          console.log('');
+          return;
+        }
+
+        const onlySheets: string[] | undefined = options.sheets ? String(options.sheets).split(',') : undefined;
+        const inv = await parseLegacyFile(files, onlySheets);
+        const report = baselineAudit(inv);
+        fs.writeFileSync(path.join(outDir, 'inventory.json'), JSON.stringify({ inventory: inv, baseline: report }, null, 2));
+        fs.writeFileSync(path.join(outDir, 'inventory.md'), renderInventoryMd(inv, report));
+
+        let convert;
+        let recon;
+        if (options.emitGherkin) {
+          const featureName = options.screen || (files.length === 1 ? path.basename(files[0]).replace(/\.[^.]+$/, '') : 'legacy');
+          convert = inventoryToGherkin(inv, featureName);
+          fs.writeFileSync(path.join(outDir, `${featureName}.legacy-draft.feature`), convert.feature);
+          fs.writeFileSync(path.join(outDir, 'legacy-trace.json'), JSON.stringify(convert.trace, null, 2));
+          // Viewpoint reconciliation: legacy coverage vs catalog → blind-spots (P-C)
+          recon = reconcileViewpoints(inv);
+          fs.writeFileSync(path.join(outDir, 'test-viewpoint.draft.md'), renderViewpointOverview(featureName, recon));
+        }
+
+        if (options.json) console.log(JSON.stringify({ inventory: inv, baseline: report, convert, reconciliation: recon }, null, 2));
+        else {
+          render(inv, report);
+          if (convert) {
+            const g = convert.gap;
+            console.log('  ── Gherkin draft (P-B) ──');
+            console.log(`    ${g.total} scenario(s) drafted → ui=${g.ui} · cross-screen=${g.crossScreen} · @manual(capability)=${g.manualCapability} · @manual(keep)=${g.manualKeep}`);
+            if (g.noExpected) console.log(`    ⚠ ${g.noExpected} testcase(s) without an Expected → needs review`);
+            console.log(`    Draft: ${path.relative(process.cwd(), outDir)}/*.legacy-draft.feature (refine via /sungen:create-test)`);
+          }
+          if (recon) {
+            console.log('  ── Viewpoint reconciliation (legacy vs catalog) ──');
+            console.log(`    page-type: ${recon.pageType ?? 'unknown'} · legacy covers ${recon.themesCovered}/${recon.themesTotal} catalog themes (${(recon.coverageRatio * 100).toFixed(0)}%)`);
+            if (recon.blindSpots.length)
+              console.log(`    ⚠ BLIND-SPOTS (catalog expects, legacy lacks): ${recon.blindSpots.map((b) => `${b.theme}[${b.status}]`).join(', ')}`);
+            else
+              console.log(`    ✓ no catalog blind-spots — legacy covers the expected themes`);
+            console.log(`    Draft viewpoint: ${path.relative(process.cwd(), outDir)}/test-viewpoint.draft.md → seed /sungen:create-test`);
+          }
+          console.log(`  Inventory: ${path.relative(process.cwd(), outDir)}/inventory.json`);
+          console.log('');
+        }
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}