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

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/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-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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.0.0-beta.74",
+  "version": "3.0.0-beta.77",
   "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",
-    "test:update": "tsx tests/golden/run.ts --update",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/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

@@ -23,8 +23,10 @@ function render(r: AuditReport): void {
   L('');
   L(`  Quality score (business-weighted): ${r.score.overall}/10   [Viewpoint Gate: ${r.gateStatus}]`);
   L(`  Intent: focus=${r.intent.focus} · depth threshold ${r.depth.threshold.toFixed(2)} (${r.intent.source})`);
+  L(`  Provenance: sungen ${r.provenance.sungenVersion} · catalog ${r.provenance.catalogHash}  (same here on every machine → same score)`);
   L(`    coverage      ${bar(r.score.coverage)} ${(r.score.coverage * 100).toFixed(0)}%`);
   L(`    businessDepth ${bar(r.score.businessDepth)} ${(r.score.businessDepth * 100).toFixed(0)}%  [${r.depth.verdict.toUpperCase()}]`);
+  L(`    claimProof    ${bar(r.claim.ratio)} ${(r.claim.ratio * 100).toFixed(0)}%  [${r.claim.verdict.toUpperCase()}]`);
   L(`    balance       ${bar(r.score.balance)} ${(r.score.balance * 100).toFixed(0)}%`);
   L(`    traceability  ${bar(r.score.traceability)} ${(r.score.traceability * 100).toFixed(0)}%`);
   L(`    (${r.score.formula})`);
@@ -37,15 +39,23 @@ function render(r: AuditReport): void {
   for (const s of r.depth.shallowBusinessCritical.slice(0, 8)) L(`      ⚠ ${s.category}: ${s.name}`);
   if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);
   L('');
-  L(`  ③ Coverage balance — ${r.balance.imbalanced ? '⚠ IMBALANCED' : '✓ balanced'}`);
+  L(`  ③ Claim-Proof — ${r.claim.proven}/${r.claim.withClaims} titled claims proven by steps  [${r.claim.verdict.toUpperCase()}]`);
+  if (r.claim.unproven.length === 0) L('      ✓ every claim (all/only/single/correct/changes/hidden) is backed by an assertion');
+  for (const u of r.claim.unproven.slice(0, 8)) L(`      ${u.severity === 'fail' ? '✗' : '⚠'} [${u.claim}] ${u.name} → needs ${u.need}`);
+  if (r.claim.unproven.length > 8) L(`      … +${r.claim.unproven.length - 8} more`);
+  L('');
+  L(`  ③·5 Taxonomy — ${r.taxonomy.mislabeled.length === 0 ? '✓ VP codes match scenario semantics' : `⚠ ${r.taxonomy.mislabeled.length} mislabel(s)`}`);
+  for (const m of r.taxonomy.mislabeled.slice(0, 6)) L(`      ⚠ ${m.name} → VP-${m.current} reads as ${m.suggested} ("${m.signal}")`);
+  L('');
+  L(`  ④ Coverage balance — ${r.balance.imbalanced ? '⚠ IMBALANCED' : '✓ balanced'}`);
   L(`      buckets: ${Object.entries(r.balance.byBucket).map(([k, v]) => `${k}=${v}`).join('  ')}`);
   L('');
-  L(`  ④ Duplicate — ${r.duplicates.clusters.length} same-shape cluster(s), ${r.duplicates.exactDuplicateCount} likely exact dup(s)`);
+  L(`  ⑤ Duplicate — ${r.duplicates.clusters.length} same-shape cluster(s), ${r.duplicates.exactDuplicateCount} likely exact dup(s)`);
   for (const c of r.duplicates.clusters.slice(0, 3)) {
     L(`      ${c.sameDataLikely ? '✗ exact' : '○ EP/data family'} (${c.scenarios.length}): ${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}`);
   }
   L('');
-  L(`  ⑤ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
+  L(`  ⑥ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
   L(`      ${r.trace.note}`);
   L('');
   L('  ── Findings (Repair targets) ──');

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/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);
+      }
+    });
+}

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import { registerFigmaCommand } from './commands/figma';
 import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
 import { registerAuditCommand } from './commands/audit';
+import { registerIngestCommand } from './commands/ingest';
 import { registerManifestCommand } from './commands/manifest';
 import { registerLedgerCommand } from './commands/ledger';
 import { registerFeedbackCommand } from './commands/feedback';
@@ -60,6 +61,7 @@ async function main() {
   registerBlindspotCommand(program);
   registerCapabilityCommand(program);
   registerFlowCheckCommand(program);
+  registerIngestCommand(program);
 
   await program.parseAsync(process.argv);
 }