@sun-asterisk/sungen 3.0.0-beta.74 → 3.0.0-beta.77

package/src/ingest/gsheet-fetch.ts

@@ -0,0 +1,152 @@
+/**
+ * Fetch a Google Sheet's tabs as a sheet-bundle — runs under the USER's own Google
+ * identity (Application Default Credentials), read-only. This is NOT an AI context, so
+ * it is not subject to the "ineligible for generative AI contexts" DLP that blocks AI
+ * connectors; and read access (Viewer/Commenter is enough) is all it needs.
+ *
+ * `googleapis` is an OPTIONAL dependency (lazy-required) — the core install stays lean;
+ * users who want the Google fetch run `npm i googleapis` + authenticate once with
+ * `gcloud auth application-default login` (or set GOOGLE_APPLICATION_CREDENTIALS).
+ */
+import * as path from 'path';
+import * as readline from 'readline';
+import { execSync } from 'child_process';
+import { RawSheet } from './legacy-parser';
+
+export interface SheetBundle { source: string; sheets: RawSheet[] }
+
+const SCOPE = 'https://www.googleapis.com/auth/spreadsheets.readonly';
+
+/** Accept a full Sheets URL or a bare spreadsheet ID. */
+export function parseSpreadsheetId(idOrUrl: string): string {
+  const m = idOrUrl.match(/\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/);
+  return m ? m[1] : idOrUrl.trim();
+}
+
+function ask(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+/** Load `googleapis`; if missing, ask to install it (default Yes) and install into the
+ * sungen package dir, then load it. Throws with manual instructions if declined/failed. */
+async function ensureGoogleapis(): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('googleapis').google;
+  } catch { /* not installed → offer to install */ }
+
+  const manual = '\n  Install it manually:  npm i googleapis\n' +
+    '  Then authenticate:    gcloud auth application-default login --scopes=' + SCOPE;
+
+  if (!process.stdin.isTTY) {
+    throw new Error('`--gsheet` needs the optional dependency `googleapis` (non-interactive shell — cannot prompt).' + manual);
+  }
+  const answer = (await ask('  `--gsheet` needs the `googleapis` package (read-only Google Sheets). Install it now? [Y/n] ')).toLowerCase();
+  if (answer && !/^y(es)?$/.test(answer)) {
+    throw new Error('Skipped install — `--gsheet` needs `googleapis`.' + manual);
+  }
+  const pkgDir = path.resolve(__dirname, '..', '..'); // dist/ingest|src/ingest → package root
+  console.log('  Installing googleapis (local to sungen, not saved to your project)…');
+  try {
+    // --no-save: keep sungen's core lean; this machine gets googleapis without declaring a dep.
+    execSync('npm install googleapis --no-save', { cwd: pkgDir, stdio: 'inherit' });
+  } catch {
+    throw new Error('npm install googleapis failed (permissions?).' + manual);
+  }
+  // Node caches the negative module lookup from process start, so requiring a just-installed
+  // package in THIS process is unreliable. Ask for a clean re-run (next process finds it).
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(require.resolve('googleapis', { paths: [pkgDir] })).google;
+  } catch {
+    console.log('\n  ✓ googleapis installed. Please re-run the same `sungen ingest --gsheet …` command.\n');
+    process.exit(0);
+  }
+}
+
+/** Open the Google login in the browser (via gcloud ADC) so the user picks THEIR
+ * account, then store read-only credentials. Returns false if gcloud is unavailable. */
+async function tryInteractiveLogin(): Promise<boolean> {
+  try {
+    execSync('gcloud --version', { stdio: 'ignore' });
+  } catch {
+    console.log('\n  (gcloud not found — install the Google Cloud SDK, or export the sheet to .xlsx and use --legacy.)');
+    return false;
+  }
+  const ans = (await ask('  Open Google login in your browser now (pick the account that can see the sheet)? [Y/n] ')).toLowerCase();
+  if (ans && !/^y(es)?$/.test(ans)) return false;
+  try {
+    execSync(`gcloud auth application-default login --scopes=${SCOPE},https://www.googleapis.com/auth/cloud-platform`, { stdio: 'inherit' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function fetchGoogleSheet(idOrUrl: string): Promise<SheetBundle> {
+  const google = await ensureGoogleapis();
+  const spreadsheetId = parseSpreadsheetId(idOrUrl);
+  const doFetch = async () => {
+    // ADC: the user's own credentials (gcloud ADC). Fresh client each attempt so a
+    // just-completed login is picked up.
+    const auth = new google.auth.GoogleAuth({ scopes: [SCOPE] });
+    const sheets = google.sheets({ version: 'v4', auth });
+    const m = await sheets.spreadsheets.get({ spreadsheetId, fields: 'properties.title,sheets.properties.title' });
+    const tabs: string[] = (m.data?.sheets || []).map((s: any) => s.properties.title);
+    const r = await sheets.spreadsheets.values.batchGet({ spreadsheetId, ranges: tabs, majorDimension: 'ROWS' });
+    return { m, r };
+  };
+
+  let meta: any, resp: any;
+  try {
+    ({ m: meta, r: resp } = await doFetch());
+  } catch (e: any) {
+    const msg = String(e?.message || e);
+    const noCreds = /default credentials|could not load|invalid_grant|reauth|unauthenticated/i.test(msg);
+    // Tool-driven browser login: on missing/expired creds, offer to open the Google
+    // login (gcloud ADC) so the user picks THEIR account, then retry once.
+    if (noCreds && process.stdin.isTTY && await tryInteractiveLogin()) {
+      ({ m: meta, r: resp } = await doFetch());
+    } else if (noCreds) {
+      throw new Error(
+        'Google login needed (no usable credentials for your account).\n' +
+        '  Run:  gcloud auth application-default login --scopes=' + SCOPE + '\n' +
+        '  (opens a browser — pick the account that can see the sheet). Then re-run.\n' +
+        '  No gcloud? Export the sheet to .xlsx and use --legacy instead.',
+      );
+    } else if (/access_denied|app is blocked|blocked this access|disallowed_useragent|admin|policy|org_internal|403/i.test(msg)) {
+      throw new Error(
+        'Blocked by your organization\'s Google Workspace policy (admin App-access control):\n' +
+        '  "' + msg.split('\n')[0] + '"\n' +
+        '  Your org blocks OAuth apps from reading Sheets (a sensitive scope). This affects gcloud,\n' +
+        '  a custom OAuth app, AND the AI connector equally — it is an admin decision, not a sungen bug.\n' +
+        '  → Use the local path instead: have an owner export the sheet to .xlsx and run\n' +
+        '       sungen ingest --legacy <file>.xlsx\n' +
+        '    (no API, no admin needed). Or ask a Workspace admin to trust an app for the\n' +
+        '    spreadsheets.readonly scope (Admin Console → Security → API controls).',
+      );
+    } else if (/no access|permission|not found|insufficient|API has not been used/i.test(msg)) {
+      throw new Error(
+        'Google access failed: ' + msg.split('\n')[0] + '\n' +
+        '  Ensure the logged-in account has Viewer/Commenter on the sheet and the Sheets API is enabled.\n' +
+        '  If your org blocks programmatic access to this file, ask an owner to export .xlsx → use --legacy.',
+      );
+    } else {
+      throw e;
+    }
+  }
+
+  const title: string = meta.data?.properties?.title || spreadsheetId;
+  const tabNames: string[] = (meta.data?.sheets || []).map((s: any) => s.properties.title);
+  const ranges: any[] = resp.data?.valueRanges || [];
+
+  const out: RawSheet[] = tabNames.map((name, i) => ({
+    name,
+    rows: (ranges[i]?.values || []).map((row: any[]) => row.map((c) => (c == null ? '' : String(c)))),
+  }));
+
+  return { source: title, sheets: out };
+}

package/src/ingest/index.ts

@@ -0,0 +1,5 @@
+export * from './legacy-parser';
+export * from './baseline-audit';
+export * from './to-gherkin';
+export * from './reconcile';
+export * from './gsheet-fetch';

package/src/ingest/legacy-parser.ts

@@ -0,0 +1,184 @@
+/**
+ * Legacy testcase ingest (P-A) — parse a manual testcase workbook (CSV or XLSX)
+ * into a normalized inventory. Deterministic: pure function of the input file
+ * (no network, no MCP). The AI skill handles the Google-Sheets/MCP fetch upstream.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type SheetType = 'testcase' | 'viewpoint-matrix' | 'ui-checklist' | 'unknown';
+export type Priority = 'high' | 'normal' | 'low' | 'unknown';
+
+export interface LegacyTestcase {
+  id: string;
+  page: string;
+  category: string;
+  subCategory?: string;
+  precondition?: string;
+  testData?: string;
+  steps: string;
+  expected: string;
+  priority: Priority;
+  type?: string;
+  result?: string;
+  sheet: string;
+}
+
+export interface SheetInfo { name: string; type: SheetType; rows: number }
+
+export interface LegacyInventory {
+  source: { file: string };
+  sheets: SheetInfo[];
+  testcases: LegacyTestcase[];
+}
+
+// ---- quote-aware CSV parser (embedded commas + newlines) ----
+export function parseCSV(text: string): string[][] {
+  const rows: string[][] = []; let row: string[] = [], field = '', q = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (q) {
+      if (c === '"') { if (text[i + 1] === '"') { field += '"'; i++; } else q = false; }
+      else field += c;
+    } else if (c === '"') q = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+    else if (c !== '\r') field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+const norm = (s: string | undefined) => (s || '').replace(/\*/g, '').trim().toLowerCase();
+
+function detectSheetType(rows: string[][]): { type: SheetType; headerRow: number } {
+  for (let i = 0; i < Math.min(rows.length, 40); i++) {
+    const cells = rows[i].map(norm);
+    if (cells.some((c) => /^tc\s*id$/.test(c)) && cells.some((c) => /steps?|expected/.test(c)))
+      return { type: 'testcase', headerRow: i };
+    if (cells.some((c) => /item type/.test(c)) || (cells[0] === 'id' && cells.some((c) => /^item/.test(c))))
+      return { type: 'ui-checklist', headerRow: i };
+    if (cells.some((c) => /^id\/function$/.test(c)) || cells.some((c) => /viewpoint/.test(c)))
+      return { type: 'viewpoint-matrix', headerRow: i };
+  }
+  return { type: 'unknown', headerRow: -1 };
+}
+
+function colMap(header: string[]): Record<string, number> {
+  const m: Record<string, number> = {};
+  header.forEach((h, i) => { const k = norm(h); if (k && !(k in m)) m[k] = i; });
+  return m;
+}
+
+function toPriority(raw: string): Priority {
+  const p = (raw || '').toLowerCase();
+  if (/high|cao/.test(p)) return 'high';
+  if (/low|thấp/.test(p)) return 'low';
+  if (/medium|normal|trung/.test(p)) return 'normal';
+  return 'unknown';
+}
+
+function parseTestcaseSheet(rows: string[][], headerRow: number, sheet: string): LegacyTestcase[] {
+  const cm = colMap(rows[headerRow]);
+  if (cm['tc id'] == null) return [];
+  const col = (r: string[], key: string) => (cm[key] != null ? (r[cm[key]] || '').trim() : '');
+  const out: LegacyTestcase[] = [];
+  // Fill-down ONLY the grouping columns (genuinely merged across rows). Precondition is
+  // kept PER-ROW: filling it down would bleed one row's "needs API/DB/login" into unrelated
+  // rows and falsely inflate the capability/driver signal.
+  const fd = { page: '', category: '', sub: '' };
+  for (let i = headerRow + 1; i < rows.length; i++) {
+    const r = rows[i];
+    const id = col(r, 'tc id');
+    if (!id || /^(total|module|test environment)/i.test(id)) continue;
+    fd.page = col(r, 'page name') || fd.page;
+    fd.category = col(r, 'category') || fd.category;
+    fd.sub = col(r, 'sub-category') || fd.sub;
+    const steps = col(r, 'steps');
+    const expected = col(r, 'expected results') || col(r, 'expected result');
+    if (!steps && !expected) continue; // skip noise / spacer rows
+    out.push({
+      id, sheet, page: fd.page, category: fd.category || '(uncategorized)',
+      subCategory: fd.sub || undefined, precondition: col(r, 'pre-condition') || undefined,
+      testData: col(r, 'test data') || undefined, steps, expected,
+      priority: toPriority(col(r, 'priority')),
+      type: col(r, 'testcase type') || undefined,
+      result: col(r, 'test result') || col(r, 'test result\nchrome (100%)') || undefined,
+    });
+  }
+  return out;
+}
+
+export interface RawSheet { name: string; rows: string[][] }
+
+/** Load sheets from one input file: CSV (1 sheet), XLSX (all sheets), or a JSON
+ * sheet-bundle (the shape the Google-Sheets/MCP skill produces). */
+async function loadSheets(filePath: string): Promise<RawSheet[]> {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.csv') {
+    return [{ name: path.basename(filePath, '.csv'), rows: parseCSV(fs.readFileSync(filePath, 'utf8')) }];
+  }
+  if (ext === '.json') {
+    // Bundle shapes: { sheets: [{name, rows}] } | [{name, rows}] | { "<tab>": [[..]] }
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const arr = Array.isArray(data) ? data : Array.isArray(data.sheets) ? data.sheets : null;
+    if (arr) return arr.map((s: any) => ({ name: String(s.name), rows: s.rows as string[][] }));
+    if (data && typeof data === 'object')
+      return Object.entries(data).map(([name, rows]) => ({ name, rows: rows as string[][] }));
+    throw new Error('Invalid JSON sheet-bundle: expected { sheets: [{name, rows}] }');
+  }
+  if (ext === '.xlsx') {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const ExcelJS = require('exceljs');
+    const wb = new ExcelJS.Workbook();
+    await wb.xlsx.readFile(filePath);
+    const out: RawSheet[] = [];
+    wb.eachSheet((ws: any) => {
+      const rows: string[][] = [];
+      ws.eachRow((row: any) => {
+        const cells: string[] = [];
+        row.eachCell({ includeEmpty: true }, (cell: any) => { cells.push(cell.text != null ? String(cell.text) : ''); });
+        rows.push(cells);
+      });
+      out.push({ name: ws.name, rows });
+    });
+    return out;
+  }
+  throw new Error(`Unsupported file type: ${ext} (use .csv, .xlsx, or a .json sheet-bundle)`);
+}
+
+/** Classify sheets without parsing testcases — for `--list-sheets`. */
+export async function listSheets(filePaths: string | string[]): Promise<SheetInfo[]> {
+  const files = Array.isArray(filePaths) ? filePaths : [filePaths];
+  const out: SheetInfo[] = [];
+  for (const f of files) {
+    for (const s of await loadSheets(f)) {
+      const { type } = detectSheetType(s.rows);
+      out.push({ name: s.name, type, rows: s.rows.length });
+    }
+  }
+  return out;
+}
+
+/** Parse one or more inputs (CSV/XLSX/JSON-bundle) into an inventory. Optionally
+ * restrict to a set of tab names (`onlySheets`) — workbooks carry many tabs. */
+export async function parseLegacyFile(filePaths: string | string[], onlySheets?: string[]): Promise<LegacyInventory> {
+  const files = Array.isArray(filePaths) ? filePaths : [filePaths];
+  const want = onlySheets && onlySheets.length ? new Set(onlySheets.map((s) => s.trim().toLowerCase())) : null;
+
+  const inv: LegacyInventory = {
+    source: { file: files.map((f) => path.basename(f)).join(', ') },
+    sheets: [], testcases: [],
+  };
+  for (const f of files) {
+    for (const s of await loadSheets(f)) {
+      if (want && !want.has(s.name.trim().toLowerCase())) continue;
+      const { type, headerRow } = detectSheetType(s.rows);
+      let tcs: LegacyTestcase[] = [];
+      if (type === 'testcase' && headerRow >= 0) tcs = parseTestcaseSheet(s.rows, headerRow, s.name);
+      inv.sheets.push({ name: s.name, type, rows: tcs.length || s.rows.length });
+      inv.testcases.push(...tcs);
+    }
+  }
+  return inv;
+}

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-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-gherkin-syntax.md

@@ -74,6 +74,18 @@ User switch to [T] frame | [main] frame
 # 8. Page: User see [T] page
 ```
 
+### Collection / all-card (P5)
+
+```
+# Every element's TEXT matches a value (filter correctness, all items belong):
+User see all [Result Product Name] text contains {{category_term}}
+# Every CONTAINER holds a CHILD element (structural per-card proof — prove "each card has X"):
+User see all [Product Card] contain [Product Name]
+User see all [Product Card] contain [Add To Cart] button
+```
+
+Use the all-card form whenever a title claims *every / each* card/row exposes something — a single `User see [Add To Cart] button` does NOT prove "each card" and the harness Claim-Proof gate will flag it.
+
 ### Table
 
 ```

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.