@sun-asterisk/sungen 3.0.0-beta.75 → 3.0.0-beta.78

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-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-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.