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

package/src/harness/audit.ts

@@ -7,6 +7,7 @@
  * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
  */
 import * as path from 'path';
+import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
@@ -14,6 +15,7 @@ import {
 } from './sensors';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
+import { specCoverage, SpecCoverageResult } from './spec-coverage';
 
 export interface AuditReport {
   screen: string;
@@ -37,15 +39,20 @@ export interface AuditReport {
   findings: string[];           // human-actionable, what the Repair loop would target
   intent: IntentProfile;        // P3 — the intent profile that drove the thresholds
   provenance: Provenance;       // D1 — sungen version + catalog hash (diagnose cross-user score gaps)
+  spec: SpecCoverageResult;     // G2 — spec-clause coverage (FR + validation-trigger matrix)
 }
 
 export function runAudit(screenDir: string, screenName: string): AuditReport {
   const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
   const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
 
+  const specPath = path.join(screenDir, 'requirements', 'spec.md');
+  const featureText = fs.existsSync(featurePath) ? fs.readFileSync(featurePath, 'utf-8') : '';
+
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
   const catalog = loadCatalog();
+  const spec = specCoverage(specPath, scenarios, featureText);
 
   const gate = viewpointGate(scenarios, viewpoints, catalog);
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
@@ -100,16 +107,22 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (gate.universalGaps.length) {
     findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
   }
+  for (const g of spec.triggerGaps) {
+    findings.push(`TRIGGER-UNCOVERED: spec validates "${g.constraint}"${g.code ? ` (${g.code})` : ''} on [${g.required.join(', ')}] but scenarios only exercise it on [${g.found.join(', ') || 'none'}] → add a ${g.missing.join(', ')}-trigger scenario for this constraint (don't collapse the trigger × input matrix).`);
+  }
+  for (const u of spec.uncoveredMust) {
+    findings.push(`SPEC-UNCOVERED: ${u.id} (MUST) has no covering scenario — "${u.text}" → add a scenario or tag one @spec:${u.id}.`);
+  }
 
-  // Gate now spans coverage (viewpoint themes) AND depth (data-correctness).
-  // A depth 'fail' (below the intent threshold) fails the gate; 'warn' does not.
+  // Gate spans coverage (viewpoint themes), depth (data-correctness), claim-proof,
+  // AND spec-clause coverage (every MUST clause + every mandated validation trigger).
   const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' ? 'PASS' : 'FAIL';
+    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' ? 'PASS' : 'FAIL';
 
   return {
     screen: screenName,
     scenarioCount: scenarios.length,
-    gate, depth, claim, taxonomy, balance, duplicates, trace,
+    gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability-plan.ts

@@ -43,6 +43,17 @@ const INFER: { code: string; re: RegExp }[] = [
   { code: 'M9', re: /\b(judgment|human|subjective|manual review)\b/i },
 ];
 
+/**
+ * Classify free text (e.g. a legacy testcase's precondition+steps+expected) into a
+ * manual-reason code, or '' when nothing matches (→ UI-automatable). Reuses the same
+ * INFER patterns as the scenario planner so legacy-ingest and the Gherkin planner agree.
+ */
+export function classifyReason(text: string): string {
+  const t = (text || '').toLowerCase();
+  for (const { code, re } of INFER) if (re.test(t)) return code;
+  return '';
+}
+
 interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason: string }
 
 /** Parse scenarios with their tags + the reason comment line above (for @manual). */

package/src/harness/spec-coverage.ts

@@ -0,0 +1,139 @@
+/**
+ * Spec-clause coverage (harness G2) — the spec-layer faithfulness check.
+ *
+ * Parses the structured parts of a screen `spec.md` (Functional Requirements + the
+ * Validation Rules table) and verifies (a) every MUST FR is covered by a scenario and
+ * (b) for EACH validation constraint, every trigger the spec mandates is actually
+ * exercised. The trigger check is PER-CONSTRAINT — so "validate format on blur AND on
+ * submit" tested only on blur is caught even when other constraints do use submit.
+ * Generic: no project data.
+ */
+import * as fs from 'fs';
+import { ScenarioInfo } from './parse';
+
+export type Modality = 'MUST' | 'SHOULD' | 'MAY';
+
+export interface TriggerGap { constraint: string; code: string; required: string[]; found: string[]; missing: string[] }
+
+export interface SpecCoverageResult {
+  hasSpec: boolean;
+  frTotal: number;
+  frCovered: number;
+  uncoveredMust: { id: string; text: string }[];
+  triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
+  verdict: 'pass' | 'warn' | 'fail';
+}
+
+interface FrClause { id: string; text: string; modality: Modality }
+interface ValRow { constraint: string; code: string; triggers: string[] }
+
+// Parsing the spec's Trigger CELL: loose word match ("blur, submit").
+const SPEC_TRIGGER: { trigger: string; re: RegExp }[] = [
+  { trigger: 'blur', re: /\b(blur|on blur|focus[- ]?out)\b/i },
+  { trigger: 'submit', re: /\b(submit|on submit)\b/i },
+];
+// Detecting the trigger ACTION in a scenario: must be an actual action, NOT the word
+// "submit" in a "[Submit] button is disabled" assertion.
+const ACTION_TRIGGER: { trigger: string; re: RegExp }[] = [
+  { trigger: 'blur', re: /\b(press tab|blur|focus[- ]?out|loses? focus|tab away|tab out)\b/i },
+  { trigger: 'submit', re: /(click \[submit\]|press enter|\benter key\b|送信する)/i },
+];
+
+function modalityOf(text: string): Modality {
+  if (/\bMUST\b/.test(text)) return 'MUST';
+  if (/\bSHOULD\b/.test(text)) return 'SHOULD';
+  return 'MAY';
+}
+
+function specTriggersIn(text: string): string[] {
+  return SPEC_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
+}
+function actionTriggersIn(text: string): string[] {
+  return ACTION_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
+}
+
+export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows: ValRow[] } {
+  if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
+  const lines = fs.readFileSync(specPath, 'utf-8').split('\n');
+
+  const frs: FrClause[] = [];
+  for (const line of lines) {
+    const m = line.match(/\*\*FR-(\d+)\*\*\s*:\s*(.+)$/);
+    if (m) frs.push({ id: `FR-${m[1]}`, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+  }
+
+  // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
+  const valRows: ValRow[] = [];
+  let cTrigger = -1, cConstraint = -1, cCode = -1, inTable = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith('|') && /\btrigger\b/i.test(line) && cTrigger < 0) {
+      const cells = line.split('|').map((c) => c.trim());
+      cTrigger = cells.findIndex((c) => /^trigger$/i.test(c));
+      cConstraint = cells.findIndex((c) => /constraint/i.test(c));
+      cCode = cells.findIndex((c) => /code/i.test(c));
+      inTable = cTrigger >= 0;
+      continue;
+    }
+    if (inTable) {
+      if (!line.startsWith('|')) { inTable = false; cTrigger = -1; continue; }
+      if (/^\|[\s|:-]+\|?$/.test(line)) continue;
+      const cells = line.split('|').map((c) => c.trim());
+      const triggers = [...new Set((cells[cTrigger] || '').split(/,|\band\b/i).flatMap((p) => specTriggersIn(p)))];
+      if (!triggers.length) continue; // server-only rows etc.
+      const constraint = (cConstraint >= 0 ? cells[cConstraint] : '').replace(/`/g, '') || 'validation';
+      const codeM = (cCode >= 0 ? cells[cCode] : line).match(/M\d+/);
+      valRows.push({ constraint, code: codeM ? codeM[0] : '', triggers });
+    }
+  }
+  return { frs, valRows };
+}
+
+/** Split a feature file into per-scenario blocks (tags + comments + steps), keyed by blank lines. */
+function scenarioBlocks(featureText: string): string[] {
+  return featureText.split(/\n\s*\n/).filter((b) => /\bScenario:/.test(b)).map((b) => b.toLowerCase());
+}
+
+export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
+  const { frs, valRows } = parseSpecClauses(specPath);
+  if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
+    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], triggerGaps: [], verdict: 'pass' };
+  }
+  const featLower = featureText.toLowerCase();
+
+  // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
+  const uncoveredMust: { id: string; text: string }[] = [];
+  let frCovered = 0;
+  for (const fr of frs) {
+    const idLower = fr.id.toLowerCase();
+    const cited = featLower.includes(idLower);
+    const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
+      .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
+    const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));
+    if (cited || kwHit) frCovered++;
+    else if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+  }
+
+  // Per-constraint trigger coverage — the matrix-collapse catch.
+  // generic words that don't identify a constraint (would over-match happy-path scenarios)
+  const GENERIC = new Set(['valid', 'local', 'part', 'domain', 'email', 'address', 'must', 'exist', 'store', 'field', 'input', 'value', 'formed', 'well', 'character', 'characters']);
+  const blocks = scenarioBlocks(featureText);
+  const triggerGaps: TriggerGap[] = [];
+  for (const row of valRows) {
+    const kw = (row.constraint.toLowerCase().match(/[a-z]{4,}/g) || []).filter((w) => !GENERIC.has(w));
+    // blocks that belong to this constraint: cite its msg code (primary), or mention a
+    // DISTINCTIVE constraint word (generic words filtered to avoid matching happy paths).
+    const own = blocks.filter((b) =>
+      (row.code && b.includes(row.code.toLowerCase())) || kw.some((w) => b.includes(w)),
+    );
+    if (!own.length) continue; // constraint has no scenarios at all — FR/viewpoint gate covers that
+    const found = [...new Set(own.flatMap((b) => actionTriggersIn(b)))];
+    const missing = row.triggers.filter((t) => !found.includes(t));
+    if (missing.length) triggerGaps.push({ constraint: row.constraint, code: row.code, required: row.triggers, found, missing });
+  }
+
+  const verdict: SpecCoverageResult['verdict'] =
+    uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
+
+  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, triggerGaps, verdict };
+}

package/src/ingest/baseline-audit.ts

@@ -0,0 +1,100 @@
+/**
+ * QA baseline audit over a legacy testcase inventory (P-A). Reuses the harness
+ * duplicate sensor + the capability-plan reason classifier so the legacy view and
+ * the Gherkin view agree. Advisory — evaluates the *existing* manual suite and the
+ * automation/driver opportunity; it does not gate anything.
+ */
+import { LegacyInventory, LegacyTestcase } from './legacy-parser';
+import { duplicateClusters } from '../harness/sensors';
+import { ScenarioInfo } from '../harness/parse';
+import { classifyReason, MANUAL_REASONS } from '../harness/capability-plan';
+
+export interface BaselineReport {
+  total: number;
+  sheets: { name: string; type: string; rows: number }[];
+  byCategory: Record<string, number>;
+  byPriority: Record<string, number>;
+  byResult: Record<string, number>;
+  depthRatio: number;          // % of TC whose Expected asserts a concrete value
+  deepCount: number;
+  duplicateClusters: number;
+  exactDuplicates: number;
+  reasons: {                   // capability-plan style distribution
+    ui: number; crossScreen: number; capabilityManual: number; keepManual: number;
+    byCode: Record<string, number>;
+    driverCandidates: { driver: string; count: number }[];
+  };
+}
+
+/** An Expected that asserts a concrete value (not just "displayed/visible"). */
+function isDeep(tc: LegacyTestcase): boolean {
+  const e = (tc.expected || '').trim().toLowerCase();
+  if (!e) return false;
+  const shallowOnly = /^(.{0,40})(表示される|hiển thị|displayed|shown|is visible|表示)$/.test(e);
+  const hasValue = /(=|equals?|bằng|giá trị|\bvalue\b|"|「|\bmessage\b|エラー|error|\bcount\b|số lượng|\bformat\b|định dạng)/.test(e);
+  return hasValue || (!shallowOnly && e.length > 30);
+}
+
+/** Synthesize a ScenarioInfo-lite so we can reuse harness sensors on the inventory. */
+export function legacyToScenarioInfo(tc: LegacyTestcase): ScenarioInfo {
+  const skeleton = (tc.steps || '')
+    .replace(/\{\{[^}]*\}\}/g, '{}').replace(/"[^"]*"/g, '""')
+    .replace(/\d+/g, 'N').replace(/\s+/g, ' ').trim().toLowerCase();
+  const hay = `${tc.category} ${tc.steps} ${tc.expected}`.toLowerCase();
+  return {
+    name: `${tc.category}: ${tc.id}`,
+    category: (tc.category || '').toUpperCase().replace(/[^A-Z0-9]+/g, '-').slice(0, 16),
+    priority: tc.priority,
+    manual: true,
+    thenCount: tc.expected ? 1 : 0,
+    hasDataAssertion: isDeep(tc),
+    shallow: !isDeep(tc),
+    stepSkeleton: skeleton,
+    haystack: hay,
+  } as ScenarioInfo;
+}
+
+export function baselineAudit(inv: LegacyInventory): BaselineReport {
+  const tcs = inv.testcases;
+  const inc = (m: Record<string, number>, k: string) => { m[k] = (m[k] || 0) + 1; };
+
+  const byCategory: Record<string, number> = {};
+  const byPriority: Record<string, number> = {};
+  const byResult: Record<string, number> = {};
+  let deepCount = 0;
+  const byCode: Record<string, number> = {};
+  let ui = 0, crossScreen = 0, capabilityManual = 0, keepManual = 0;
+  const driverHits: Record<string, number> = {};
+
+  for (const tc of tcs) {
+    inc(byCategory, tc.category || '(uncategorized)');
+    inc(byPriority, tc.priority);
+    inc(byResult, (tc.result || '(not-run)').trim() || '(not-run)');
+    if (isDeep(tc)) deepCount++;
+
+    const code = classifyReason(`${tc.precondition || ''} ${tc.steps} ${tc.expected} ${tc.testData || ''}`);
+    if (!code) { ui++; continue; }
+    inc(byCode, code);
+    if (code === 'XS') { crossScreen++; continue; }
+    const def = MANUAL_REASONS[code];
+    if (def?.cls === 'keep') keepManual++;
+    else { capabilityManual++; for (const d of def?.drivers || []) driverHits[d] = (driverHits[d] || 0) + 1; }
+  }
+
+  const dup = duplicateClusters(tcs.map(legacyToScenarioInfo));
+
+  return {
+    total: tcs.length,
+    sheets: inv.sheets,
+    byCategory, byPriority, byResult,
+    depthRatio: tcs.length ? deepCount / tcs.length : 0,
+    deepCount,
+    duplicateClusters: dup.clusters.length,
+    exactDuplicates: dup.exactDuplicateCount,
+    reasons: {
+      ui, crossScreen, capabilityManual, keepManual, byCode,
+      driverCandidates: Object.entries(driverHits).map(([driver, count]) => ({ driver, count }))
+        .sort((a, b) => b.count - a.count),
+    },
+  };
+}

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