@sun-asterisk/sungen 3.0.0 → 3.0.1

package/src/ingest/reconcile.ts

@@ -0,0 +1,80 @@
+/**
+ * Viewpoint Reconciliation (P-C) — the link between a legacy suite and the Harness.
+ *
+ * A 1:1 convert reproduces the legacy suite's blind spots. Reconciliation runs the
+ * harness viewpoint-gate over the legacy-derived scenarios to answer: which catalog-
+ * expected viewpoints does the legacy suite ALREADY cover, and which are MISSING
+ * (blind spots the old QA never wrote)? It emits a draft viewpoint overview that
+ * seeds `/sungen:create-test` + the harness coverage-gate, so the generated suite is
+ * raised to catalog quality instead of merely mirroring the legacy.
+ */
+import { LegacyInventory } from './legacy-parser';
+import { legacyToScenarioInfo } from './baseline-audit';
+import { loadCatalog, viewpointGate } from '../harness/sensors';
+
+export interface Reconciliation {
+  pageType: string | null;
+  coverageRatio: number;
+  themesCovered: number;
+  themesTotal: number;
+  blindSpots: { theme: string; status: 'missing' | 'shallow' }[];  // catalog themes the legacy suite lacks/under-covers
+  universalGaps: string[];
+  legacyViewpoints: { vpGroup: string; count: number }[];           // what the legacy suite implies
+}
+
+function vpGroupOf(category: string): string {
+  const c = (category || '').toLowerCase();
+  if (/search|filter|điều kiện|条件/.test(c)) return 'SEARCH';
+  if (/input|validation|nhập|入力/.test(c)) return 'VAL';
+  if (/display|hiển thị|表示|data/.test(c)) return 'DISPLAY';
+  if (/layout|responsive|tab order|ui|giao diện/.test(c)) return 'UI';
+  if (/flow|navigation|遷移|chuyển|event/.test(c)) return 'NAV';
+  if (/paging|sort|phân trang/.test(c)) return 'LIST';
+  return (c.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').toUpperCase().slice(0, 8)) || 'GEN';
+}
+
+export function reconcileViewpoints(inv: LegacyInventory): Reconciliation {
+  const scenarios = inv.testcases.map(legacyToScenarioInfo);
+  const catalog = loadCatalog();
+  const gate = viewpointGate(scenarios, [], catalog);
+
+  const groups: Record<string, number> = {};
+  for (const tc of inv.testcases) {
+    const g = vpGroupOf(tc.category);
+    groups[g] = (groups[g] || 0) + 1;
+  }
+
+  return {
+    pageType: gate.pageType,
+    coverageRatio: gate.coverageRatio,
+    themesCovered: gate.themesCovered,
+    themesTotal: gate.themesTotal,
+    blindSpots: gate.gaps.map((g) => ({ theme: g.theme, status: g.status })),
+    universalGaps: gate.universalGaps,
+    legacyViewpoints: Object.entries(groups).map(([vpGroup, count]) => ({ vpGroup, count }))
+      .sort((a, b) => b.count - a.count),
+  };
+}
+
+/** A draft test-viewpoint.md: legacy-derived viewpoints + catalog blind-spots to fill. */
+export function renderViewpointOverview(featureName: string, r: Reconciliation): string {
+  const L: string[] = [];
+  L.push(`# Test Viewpoint — ${featureName} (drafted from legacy + reconciled with the catalog)`, '');
+  L.push('> Auto-drafted by `sungen ingest`. Rows from the legacy suite are listed first;');
+  L.push('> rows marked **⚠ BLIND-SPOT** are catalog-expected viewpoints the legacy suite does');
+  L.push('> NOT cover — add scenarios for them via `/sungen:create-test`. Refine before use.', '');
+  L.push(`Detected page-type: \`${r.pageType ?? 'unknown'}\` · legacy covers ${r.themesCovered}/${r.themesTotal} catalog themes (${(r.coverageRatio * 100).toFixed(0)}%)`, '');
+  L.push('## Priority Viewpoints', '', '| VP | Priority | Reason |', '|---|---|---|');
+  let n = 1;
+  for (const v of r.legacyViewpoints) {
+    L.push(`| VP-${v.vpGroup}-${String(n).padStart(3, '0')} | Medium | legacy suite: ${v.count} testcase(s) |`);
+    n++;
+  }
+  for (const b of r.blindSpots) {
+    L.push(`| VP-GAP-${String(n).padStart(3, '0')} | High | ⚠ BLIND-SPOT — catalog expects "${b.theme}" (${b.status}); legacy has none |`);
+    n++;
+  }
+  if (r.universalGaps.length)
+    L.push('', `> Universal reminders not covered: ${r.universalGaps.join(', ')}`);
+  return L.join('\n') + '\n';
+}

package/src/ingest/to-gherkin.ts

@@ -0,0 +1,108 @@
+/**
+ * Legacy inventory → Gherkin DRAFT + traceability + gap report (P-B).
+ *
+ * Deterministic SCAFFOLDING only: it preserves every legacy testcase as a scenario
+ * with its source (TC id + verbatim Steps/Expected as comments), the right priority +
+ * @manual tags (from the capability classifier), and a Given seeded from the
+ * precondition. The free-text → real `[Reference] type` step mapping is a SEMANTIC step
+ * done by the AI layer (`/sungen:create-test`) on top of this draft — the draft makes
+ * that refinement traceable and correctly scoped, it is not final runnable Gherkin.
+ */
+import { LegacyInventory, LegacyTestcase } from './legacy-parser';
+import { classifyReason, MANUAL_REASONS } from '../harness/capability-plan';
+
+export interface TraceEntry {
+  tcId: string;
+  scenario: string;
+  vpGroup: string;
+  mode: 'ui' | 'cross-screen' | 'manual-capability' | 'manual-keep';
+  reasonCode: string;       // '' for ui
+  drivers: string[];
+}
+
+export interface ConvertResult {
+  feature: string;          // the draft .feature text
+  trace: TraceEntry[];
+  gap: {
+    total: number; ui: number; crossScreen: number;
+    manualCapability: number; manualKeep: number; noExpected: number;
+  };
+}
+
+// Map a legacy category phrase → a VP group code (best-effort; falls back to a slug).
+function vpGroupOf(category: string): string {
+  const c = (category || '').toLowerCase();
+  if (/search|filter|điều kiện|条件/.test(c)) return 'SEARCH';
+  if (/input|validation|nhập|入力/.test(c)) return 'VAL';
+  if (/display|hiển thị|表示|data/.test(c)) return 'DISPLAY';
+  if (/layout|responsive|tab order|ui|giao diện/.test(c)) return 'UI';
+  if (/flow|navigation|遷移|chuyển|event/.test(c)) return 'NAV';
+  if (/paging|sort|phân trang/.test(c)) return 'LIST';
+  const slug = c.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').toUpperCase().slice(0, 8);
+  return slug || 'GEN';
+}
+
+function oneLine(s: string | undefined, max = 60): string {
+  return (s || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function classify(tc: LegacyTestcase): { mode: TraceEntry['mode']; code: string; drivers: string[] } {
+  const code = classifyReason(`${tc.precondition || ''} ${tc.steps} ${tc.expected} ${tc.testData || ''}`);
+  if (!code) return { mode: 'ui', code: '', drivers: [] };
+  if (code === 'XS') return { mode: 'cross-screen', code, drivers: [] };
+  const def = MANUAL_REASONS[code];
+  if (def?.cls === 'keep') return { mode: 'manual-keep', code, drivers: [] };
+  return { mode: 'manual-capability', code, drivers: def?.drivers || [] };
+}
+
+export function inventoryToGherkin(inv: LegacyInventory, featureName: string): ConvertResult {
+  const tcs = inv.testcases;
+  const trace: TraceEntry[] = [];
+  const gap = { total: tcs.length, ui: 0, crossScreen: 0, manualCapability: 0, manualKeep: 0, noExpected: 0 };
+  const seq: Record<string, number> = {};
+
+  const lines: string[] = [];
+  lines.push('@legacy');
+  lines.push(`Feature: ${featureName} (drafted from legacy testcases: ${inv.source.file})`);
+  lines.push('');
+  lines.push('  # Auto-drafted by `sungen ingest --emit-gherkin` from a legacy manual testcase suite.');
+  lines.push('  # Each scenario carries its source TC id (@legacy:<id>) + the original');
+  lines.push('  # precondition/steps/expected as comments. REFINE the When/Then into real');
+  lines.push('  # [Reference] type steps with /sungen:create-test — the free-text → step');
+  lines.push('  # mapping is an AI step; this draft only fixes structure + traceability.');
+  lines.push('');
+
+  for (const tc of tcs) {
+    const vp = vpGroupOf(tc.category);
+    seq[vp] = (seq[vp] || 0) + 1;
+    const code = `VP-${vp}-${String(seq[vp]).padStart(3, '0')}`;
+    const desc = oneLine(tc.subCategory || tc.steps) || tc.id;
+    const title = `${code} ${desc}`;
+    const { mode, code: reason, drivers } = classify(tc);
+    if (!tc.expected) gap.noExpected++;
+    if (mode === 'ui') gap.ui++;
+    else if (mode === 'cross-screen') gap.crossScreen++;
+    else if (mode === 'manual-capability') gap.manualCapability++;
+    else gap.manualKeep++;
+
+    const tags = [`@${tc.priority === 'unknown' ? 'normal' : tc.priority}`];
+    if (mode !== 'ui') tags.push('@manual');
+    tags.push(`@legacy:${tc.id}`);
+
+    lines.push(`  ${tags.join(' ')}`);
+    lines.push(`  Scenario: ${title}`);
+    if (mode === 'manual-capability') lines.push(`    # @manual:${reason} — needs ${drivers.join('/') || 'capability'} (driver candidate)`);
+    else if (mode === 'manual-keep') lines.push(`    # @manual:${reason} — judgment floor, keep manual`);
+    else if (mode === 'cross-screen') lines.push(`    # cross-screen → model as a flow (/sungen:add-flow)`);
+    if (tc.precondition) lines.push(`    # precondition: ${oneLine(tc.precondition, 120)}`);
+    lines.push(`    # steps: ${oneLine(tc.steps, 160)}`);
+    lines.push(`    # expected: ${oneLine(tc.expected, 160)}`);
+    if (tc.precondition) lines.push(`    Given User is on [${featureName}] page`);
+    lines.push('    # TODO(create-test): map the steps above to real When/Then [Reference] steps');
+    lines.push('');
+
+    trace.push({ tcId: tc.id, scenario: title, vpGroup: vp, mode, reasonCode: reason, drivers });
+  }
+
+  return { feature: lines.join('\n'), trace, gap };
+}

package/src/orchestrator/ai-rules-updater.ts

@@ -47,6 +47,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
   ['claude-skill-harness-audit.md', '.claude/skills/sungen-harness-audit/SKILL.md'],
+  ['claude-skill-ingest-legacy.md', '.claude/skills/sungen-ingest-legacy/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
   ['claude-skill-viewpoint-group-a-data-entry.md', '.claude/skills/sungen-viewpoint/group-a-data-entry.md'],
   ['claude-skill-viewpoint-group-b-data-ops.md', '.claude/skills/sungen-viewpoint/group-b-data-ops.md'],
@@ -78,6 +79,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
   ['github-skill-sungen-harness-audit.md', '.github/skills/sungen-harness-audit/SKILL.md'],
+  ['github-skill-sungen-ingest-legacy.md', '.github/skills/sungen-ingest-legacy/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
   ['github-skill-sungen-viewpoint-group-a-data-entry.md', '.github/skills/sungen-viewpoint/group-a-data-entry.md'],
   ['github-skill-sungen-viewpoint-group-b-data-ops.md', '.github/skills/sungen-viewpoint/group-b-data-ops.md'],

package/src/orchestrator/templates/ai-instructions/claude-agent-reviewer.md

@@ -14,6 +14,7 @@ You are an **independent Senior QA Reviewer**. You did **not** write these tests
 
 ## What to judge (semantic — the gate misses these)
 1. **Title ↔ steps proof.** For every scenario, do the **steps actually prove the title/viewpoint**? Flag "title claims X but steps only assert Y". (e.g. title "adds the selected product, not a random one" but Then only `see [Added] modal`.)
+   - **Negative / "does-not-happen" claims** (any language — "does not", "no", "prevents", "không", "chưa"): the proof must be a step whose result **differs** between the claim holding and not holding. Ask: *would this `Then` still pass if the bad thing happened?* If yes, it proves nothing. The classic trap: title "browser back does **not** re-submit" with `Then see [sent] page` — that page is identical whether or not the request re-fired. Demand a **contrast/count** proof (record count unchanged, state hidden/empty, error shown) or a justified `@manual` with a setup→action→assert-absence oracle. This generalises to every side-effect (re-charge, duplicate order, resend OTP, data leak), not just re-submit.
 2. **Observable Then.** Is each `Then` an **observable outcome**, not a restated action or a tautology (e.g. `Then User see [Carousel] section` after clicking next — proves nothing changed)?
 3. **Business-critical depth.** For cart / product-detail / filter / list viewpoints, do steps assert **DATA** (name, price, quantity, all-items-belong) — not just page/modal visibility? Recommend the concrete deep step: `User remember [X] text as {{v}}` + `... with {{v}}`, or `User see all [X] contain {{v}}`.
 4. **@manual justification.** Is each `@manual` genuinely unautomatable (cross-screen/external/visual) — or a cop-out to dodge the gate? Cross-screen → should be a flow.

package/src/orchestrator/templates/ai-instructions/claude-skill-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/src/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/src/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/src/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/src/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/src/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: