@sun-asterisk/sungen 2.7.0-beta.1 → 3.0.0-beta.72

package/src/harness/catalog/universal-viewpoints.yaml

@@ -0,0 +1,114 @@
+# Seed Universal Viewpoint Catalog (bundled, local — NOT a server).
+# Role: REFERENCE for the Harness Coverage Gate (the "answer key" sensors check
+# against). The AI still GENERATES the viewpoint-overview; this catalog only
+# verifies that critical themes for a page-type were not missed.
+#
+# Each page-type lists must-cover themes. A theme is "covered" when the project's
+# viewpoint-overview (or generated scenarios) contains one of its keywords.
+# See docs/orchestration-spec.md §5.2 and reports/sungen_refactor_spec.md §9.
+#
+# `depth:` (optional, harness-roadmap P1) marks a theme as DATA-correctness:
+#   requires: data-assertion  → scenarios on this theme must assert DATA (not just
+#                               visibility) to count as "deep". Drives the depth gate.
+#   cross_screen: true        → genuine depth needs another screen → use a flow
+#                               (P5 `remember` / `see all … contain`); on one screen
+#                               it should be @manual + deferred-to-flow, not shallow.
+#   keywords:                 → PRECISE data-noun keywords for depth matching (kept
+#                               separate from coverage keywords to avoid matching
+#                               navigation scenarios like "API list page").
+#   template:                 → the deep step the generator should emit by default.
+# Themes with no `depth:` are visibility/navigation — landing/seeing IS the assertion.
+
+page_types:
+  ecommerce-list:
+    detect_keywords: [cart, product, checkout, catalog, brand, category, "add to cart"]
+    must_cover:
+      - theme: list-data
+        keywords: [list, displayed, card, "product card", grid]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["product price", "product card", "every card", "all product", "product name", "displays a price", "card displays"]
+          template: "User see all [Product Price] contain {{currency}}   (and name/image per card)"
+      - theme: product-detail-consistency
+        keywords: [consistent, consistency, match, "same product", "correct product"]
+        depth:
+          requires: data-assertion
+          cross_screen: true
+          keywords: ["product detail", "detail page", "same product name", "matching name", "consistency", "same price"]
+          template: "User remember [Product Name] text as {{v}} … User see [Detail Product Name] header with {{v}}"
+      - theme: cart-correctness
+        keywords: ["cart contains", quantity, "price", subtotal, "in cart", "cart content", "cart product"]
+        depth:
+          requires: data-assertion
+          cross_screen: true
+          keywords: ["cart product", "cart contains", "in cart", "cart item", "appears in the cart", "cart line", "subtotal", "quantity"]
+          template: "User remember [Product Name] text as {{v}} … User see all [Cart Product Name] contain {{v}}"
+      - theme: category-filter-correctness
+        keywords: ["belong to the selected category", "category result", "matching the selected category", "products belong to", "only products that belong to the selected category"]
+        depth:
+          requires: data-assertion
+          cross_screen: true
+          keywords: ["belong to the selected category", "category result", "products that belong", "matching the selected category"]
+          template: "User see all [Result Product Name] contain {{selected_category}}"
+      - theme: brand-filter-correctness
+        keywords: ["belong to the selected brand", "brand result", "only products ... brand", "products that belong to the selected brand", "all displayed products belong to"]
+        depth:
+          requires: data-assertion
+          cross_screen: true
+          keywords: ["belong to the selected brand", "brand result", "products that belong to the selected brand"]
+          template: "User see all [Result Product Name] contain {{selected_brand}}"
+      - theme: add-to-cart
+        keywords: ["add to cart", added, "added to cart"]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["add to cart", "added to cart", "added confirmation", "added message"]
+          template: "User see [Added Message] text contains {{added_message}}   (not just the modal)"
+
+  form:
+    detect_keywords: [form, submit, field, input, validation]
+    must_cover:
+      - theme: required-validation
+        keywords: [required, empty, "must be", validation]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["required", "must be", "error message", "validation message"]
+          template: "User see [Field Error] message with {{error_text}}"
+      - theme: format-boundary
+        keywords: [format, invalid, boundary, length, range]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["invalid format", "boundary", "max length", "min length", "out of range"]
+          template: "User see [Field Error] message with {{error_text}}"
+      - theme: submit-success
+        keywords: [submit, success, saved, created]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["success message", "saved", "created", "confirmation"]
+          template: "User see [Success] message with {{success_text}}"
+
+  auth:
+    detect_keywords: [login, logout, password, signin, "sign in", credential]
+    must_cover:
+      - theme: valid-login
+        keywords: ["valid", login, success]
+      - theme: invalid-credential
+        keywords: ["invalid", "wrong password", error, incorrect]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["wrong password", "incorrect", "invalid credential", "error message"]
+          template: "User see [Login Error] message with {{error_text}}"
+      - theme: access-control
+        keywords: ["unauthorized", "redirect", "not logged in", permission]
+
+# Universal themes worth checking on ANY page-type (low-weight reminders).
+universal:
+  - theme: error-empty-state
+    keywords: ["empty", "no data", "no result", "failed", "error state"]
+  - theme: accessibility
+    keywords: ["keyboard", "tab order", "accessible", "aria", "focus"]

package/src/harness/challenge.ts

@@ -0,0 +1,131 @@
+/**
+ * Challenge / Exploration Harness (harness-roadmap P4) — Loop 2.
+ *
+ * Production mode (Loop 1: create-test → audit gate → repair) is deterministic by
+ * design: same spec + viewpoint → same official suite. That is the *feature* for
+ * delivery/CI, but it can feel like "a machine that always outputs the same thing".
+ *
+ * The Challenge Harness is the antidote: it does NOT regenerate the suite — it
+ * ATTACKS the existing one to surface what production missed. It is advisory
+ * (never auto-merges) and read-only.
+ *
+ * This module is the DETERMINISTIC spine — three structural critics:
+ *   1. Coverage   — over-covered (low-value) areas + shallow gate themes.
+ *   2. Depth      — titles that claim a collection but assert a single element.
+ *   3. Novelty    — risk-based prompts the AI `sungen-challenge` agent expands into
+ *                   concrete novelty candidates (semantic — not deterministic here).
+ *
+ * The AI agent layer adds the semantic + novelty judgement on top of this spine.
+ */
+import * as path from 'path';
+import { loadScenarios, ScenarioInfo } from './parse';
+import { runAudit } from './audit';
+
+export interface ChallengeFinding {
+  scenario?: string;
+  issue: string;
+  suggestion: string;
+}
+
+export interface ChallengeReport {
+  screen: string;
+  // Coverage critic
+  overCovered: { bucket: string; count: number; note: string }[];
+  shallowThemes: string[];
+  // Depth critic
+  collectionClaimSingular: ChallengeFinding[];
+  // Novelty critic (deterministic prompts → AI agent fills candidates)
+  noveltyPrompts: string[];
+  // Roll-up
+  explorationReadiness: string[];
+}
+
+// A collection claim = a PLURAL set noun (or an explicit quantifier) used with a
+// DISPLAY verb. Plural-only avoids false-positives on single-item actions like
+// "Adding A product ... shows the dialog" (which correctly asserts one item).
+const PLURAL_NOUN = /\b(cards|items|products|rows|results|prices|entries|records)\b/i;
+const QUANTIFIER = /\b(all|every|each)\b/i;
+const DISPLAY_VERB = /\b(displays?|shows?|lists?|grid|contains?)\b/i;
+
+/** Risk lenses the Novelty critic prompts the AI to explore (beyond the catalog). */
+const NOVELTY_LENSES = [
+  'double-submit / rapid repeat of the primary action (duplicate side-effects?)',
+  'state after partial / slow load (assert against a not-yet-ready page)',
+  'boundary & unusual data (very long text, 0 / max quantity, special chars)',
+  'concurrency / back-button / refresh mid-flow',
+  'historical-incident mindset — what has broken on similar screens before?',
+];
+
+export function buildChallenge(screenDir: string, screenName: string): ChallengeReport {
+  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const audit = runAudit(screenDir, screenName);
+
+  // 1. Coverage critic — over-covered buckets (secondary >> business-core) + shallow themes.
+  const buckets = audit.balance.byBucket;
+  const core = buckets['business-core'] || 0;
+  const overCovered: ChallengeReport['overCovered'] = [];
+  for (const [bucket, count] of Object.entries(buckets)) {
+    if (['business-core', 'other'].includes(bucket)) continue;
+    if (core > 0 && count > core * 1.5) {
+      overCovered.push({ bucket, count, note: `${count} scenarios vs ${core} business-core — likely low-value expansion; trim toward correctness.` });
+    }
+  }
+  const shallowThemes = audit.gate.gaps.filter((g) => g.status === 'shallow').map((g) => g.theme);
+
+  // 2. Depth critic — title claims a collection but the assertion is singular (no "see all").
+  const collectionClaimSingular: ChallengeFinding[] = [];
+  for (const s of scenarios) {
+    if (s.manual || s.category === 'NAV') continue;
+    const claimsCollection = (PLURAL_NOUN.test(s.name) || QUANTIFIER.test(s.name)) && DISPLAY_VERB.test(s.name);
+    const assertsAll = /\bsee all\b/.test(s.haystack);
+    if (claimsCollection && !assertsAll) {
+      collectionClaimSingular.push({
+        scenario: s.name,
+        issue: 'Title implies a set (cards/items/all) but the assertion targets a single element.',
+        suggestion: 'Prove EVERY member: `Then User see all [<Card/Row>] contain {{...}}` instead of a single `see [X]`.',
+      });
+    }
+  }
+
+  // 3. Novelty critic — deterministic prompts; the AI agent expands these into candidates.
+  const noveltyPrompts = NOVELTY_LENSES.map((l) => `Find 1 non-obvious, valuable scenario via: ${l}`);
+
+  // Roll-up — exploration readiness signals (not a fake score).
+  const explorationReadiness: string[] = [];
+  if (collectionClaimSingular.length) explorationReadiness.push(`${collectionClaimSingular.length} title↔assertion gap(s) — deterministic depth critic flagged these; an AI Business-Depth critic should confirm + fix.`);
+  if (overCovered.length) explorationReadiness.push(`${overCovered.length} possibly over-covered area(s) — rebalance toward correctness.`);
+  if (shallowThemes.length) explorationReadiness.push(`Shallow themes: ${shallowThemes.join(', ')}.`);
+  explorationReadiness.push('Novelty candidates are NOT generated deterministically — run the `sungen-challenge` agent (Claude) or its inline criteria (Copilot) to propose them, then QA accept/reject (≤20% of official, no auto-merge).');
+
+  return { screen: screenName, overCovered, shallowThemes, collectionClaimSingular, noveltyPrompts, explorationReadiness };
+}
+
+/** Render the Challenge Report as Markdown (advisory — not part of the official suite). */
+export function renderChallengeMarkdown(r: ChallengeReport): string {
+  const lines: string[] = [];
+  lines.push(`# Challenge Report — ${r.screen}`, '');
+  lines.push('> Advisory (Loop 2 / exploration mode). Does NOT change the official suite — it attacks it to surface blind spots. QA decides what to adopt.', '');
+
+  lines.push('## Depth — title claims a collection but asserts a single element');
+  if (r.collectionClaimSingular.length) {
+    lines.push('| Scenario | Issue | Suggested |', '|---|---|---|');
+    for (const f of r.collectionClaimSingular) lines.push(`| ${f.scenario} | ${f.issue} | ${f.suggestion} |`);
+  } else lines.push('_none_');
+  lines.push('');
+
+  lines.push('## Coverage — possibly over-covered / shallow');
+  if (r.overCovered.length) for (const o of r.overCovered) lines.push(`- **${o.bucket}** — ${o.note}`);
+  if (r.shallowThemes.length) lines.push(`- Shallow themes: ${r.shallowThemes.join(', ')}`);
+  if (!r.overCovered.length && !r.shallowThemes.length) lines.push('_balanced_');
+  lines.push('');
+
+  lines.push('## Novelty — prompts for the AI critic (expand into candidates, ≤20% of official, no auto-merge)');
+  for (const p of r.noveltyPrompts) lines.push(`- ${p}`);
+  lines.push('');
+
+  lines.push('## Exploration readiness');
+  for (const e of r.explorationReadiness) lines.push(`- ${e}`);
+  lines.push('');
+  return lines.join('\n');
+}

package/src/harness/feedback.ts

@@ -0,0 +1,84 @@
+/**
+ * Feedback — local-first capture of QA feedback. The most valuable use of
+ * feedback is closing the learning loop WITHIN a project (feed reuse/regenerate
+ * + improve the Guide), which needs no server. A future opt-in `feedback sync`
+ * can push anonymized metadata to a central API (Nấc 2) — not implemented here.
+ *
+ * Two purposes are kept distinct:
+ *   - test-design: a viewpoint/scenario is wrong / missing / duplicate  → knowledge
+ *   - product:     Sungen itself did X wrong                            → telemetry/issue
+ *
+ * Storage: .sungen/feedback/feedback.jsonl (append-only)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type FeedbackType = 'test-design' | 'product' | 'other';
+export type FeedbackDecision = 'accept' | 'reject' | 'edit' | 'add' | 'none';
+
+export interface FeedbackEntry {
+  ts: string;
+  type: FeedbackType;
+  screen?: string;
+  target?: string;        // viewpoint id / scenario / command / artifact the feedback is about
+  decision?: FeedbackDecision;
+  message: string;
+  reason?: string;
+  source: string;         // who (default: qa)
+  auditScore?: number;    // snapshot of current audit score if available
+}
+
+function feedbackPath(): string {
+  return path.join(process.cwd(), '.sungen', 'feedback', 'feedback.jsonl');
+}
+
+function currentAuditScore(screen?: string): number | undefined {
+  if (!screen) return undefined;
+  const p = path.join(process.cwd(), '.sungen', 'reports', `${screen}-audit.json`);
+  if (!fs.existsSync(p)) return undefined;
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8'))?.score?.overall; } catch { return undefined; }
+}
+
+export function recordFeedback(entry: Omit<FeedbackEntry, 'ts' | 'source' | 'auditScore'> & { ts?: string; source?: string }): string {
+  const p = feedbackPath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const full: FeedbackEntry = {
+    ts: entry.ts ?? new Date().toISOString(),
+    type: entry.type,
+    screen: entry.screen,
+    target: entry.target,
+    decision: entry.decision ?? 'none',
+    message: entry.message,
+    reason: entry.reason,
+    source: entry.source ?? 'qa',
+    auditScore: currentAuditScore(entry.screen),
+  };
+  fs.appendFileSync(p, JSON.stringify(full) + '\n', 'utf-8');
+  return p;
+}
+
+export function readFeedback(): FeedbackEntry[] {
+  const p = feedbackPath();
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+export interface FeedbackSummary {
+  total: number;
+  byType: Record<string, number>;
+  byDecision: Record<string, number>;
+  entries: FeedbackEntry[];
+}
+
+export function summarize(filter?: { screen?: string; type?: FeedbackType }): FeedbackSummary {
+  let entries = readFeedback();
+  if (filter?.screen) entries = entries.filter((e) => e.screen === filter.screen);
+  if (filter?.type) entries = entries.filter((e) => e.type === filter.type);
+  const byType: Record<string, number> = {};
+  const byDecision: Record<string, number> = {};
+  for (const e of entries) {
+    byType[e.type] = (byType[e.type] || 0) + 1;
+    byDecision[e.decision || 'none'] = (byDecision[e.decision || 'none'] || 0) + 1;
+  }
+  return { total: entries.length, byType, byDecision, entries };
+}

package/src/harness/flow-check.ts

@@ -0,0 +1,99 @@
+/**
+ * Flow first-class checks (flow_firstclass_spec).
+ *
+ * A. Deferral integrity — every screen `@manual` "deferred to a flow (X -> Y)" must
+ *    be backed by a real flow scenario that covers Y (deeply). Otherwise the
+ *    cross-screen (XS) manual is a hidden gap, not "flow-covered".
+ * B. Run-test contract — surface the fragile cross-screen patterns (same-card
+ *    identity scope, shared-state isolation under @parallel) as explicit checks.
+ *
+ * Deterministic + read-only. No test execution, no selector resolution.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadScenarios } from './parse';
+import { parseScenarios } from './capability-plan';
+
+const KNOWN_TARGETS = ['cart', 'category', 'brand', 'detail', 'checkout', 'wishlist', 'order', 'payment', 'login'];
+
+export interface Deferral { screen: string; scenario: string; hint: string; targets: string[]; verdict: 'covered' | 'shallow' | 'missing'; via?: string }
+export interface Contract { flow: string; kind: 'SAME-CARD' | 'ISOLATION'; scenario?: string; message: string }
+export interface FlowCheckReport {
+  screens: string[]; flows: string[];
+  deferrals: Deferral[];
+  contracts: Contract[];
+  missing: number;
+}
+
+function listDirs(p: string): string[] {
+  return fs.existsSync(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+}
+function featurePath(base: string, kind: 'screens' | 'flows', name: string): string {
+  return path.join(base, 'qa', kind, name, 'features', `${name}.feature`);
+}
+function featureTags(fp: string): string[] {
+  if (!fs.existsSync(fp)) return [];
+  for (const line of fs.readFileSync(fp, 'utf-8').split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('Feature:')) break;
+    if (t.startsWith('@')) return t.split(/\s+/).filter((x) => x.startsWith('@'));
+  }
+  return [];
+}
+function targetsFromHint(hint: string): string[] {
+  const h = hint.toLowerCase();
+  const hits = KNOWN_TARGETS.filter((k) => h.includes(k));
+  if (hits.length) return hits;
+  // fallback: significant words after "->"
+  const after = h.split('->').pop() || h;
+  return after.split(/[^a-z]+/).filter((w) => w.length > 3 && !['home', 'page', 'flow', 'products', 'product', 'result'].includes(w));
+}
+
+export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport {
+  const screens = listDirs(path.join(cwd, 'qa', 'screens'));
+  const flows = (onlyFlow ? [onlyFlow] : listDirs(path.join(cwd, 'qa', 'flows')));
+
+  // Index flow scenarios (name + haystack + depth).
+  const flowScenarios: { flow: string; name: string; haystack: string; deep: boolean }[] = [];
+  for (const f of listDirs(path.join(cwd, 'qa', 'flows'))) {
+    for (const s of loadScenarios(featurePath(cwd, 'flows', f))) {
+      flowScenarios.push({ flow: f, name: s.name, haystack: s.haystack, deep: s.hasDataAssertion });
+    }
+  }
+
+  // A. Deferral integrity (screens).
+  const deferrals: Deferral[] = [];
+  for (const sc of screens) {
+    for (const s of parseScenarios(featurePath(cwd, 'screens', sc))) {
+      if (!s.manual || !/deferred to a flow/i.test(s.reason)) continue;
+      const targets = targetsFromHint(s.reason);
+      const matches = flowScenarios.filter((fs2) => targets.some((t) => fs2.haystack.includes(t)));
+      let verdict: Deferral['verdict'] = 'missing';
+      let via: string | undefined;
+      if (matches.some((m) => m.deep)) { verdict = 'covered'; via = matches.find((m) => m.deep)!.flow; }
+      else if (matches.length) { verdict = 'shallow'; via = matches[0].flow; }
+      deferrals.push({ screen: sc, scenario: s.name, hint: s.reason, targets, verdict, via });
+    }
+  }
+
+  // B. Run-test contract (per flow).
+  const contracts: Contract[] = [];
+  for (const f of flows) {
+    const fp = featurePath(cwd, 'flows', f);
+    const parallel = featureTags(fp).some((t) => /^@parallel$/i.test(t));
+    const scs = loadScenarios(fp);
+    let cartStateCount = 0;
+    for (const s of scs) {
+      const h = s.haystack;
+      if (/\bremember\b/.test(h) && /(add to cart|view product)/.test(h)) {
+        contracts.push({ flow: f, kind: 'SAME-CARD', scenario: s.name, message: 'remember + Add To Cart/View Product → scope to ONE card at run-test, else the identity proof is hollow.' });
+      }
+      if (/(add to cart|remove|\bcart\b|quantity)/.test(h)) cartStateCount++;
+    }
+    if (parallel && cartStateCount >= 2) {
+      contracts.push({ flow: f, kind: 'ISOLATION', message: `@parallel + ${cartStateCount} cart/state scenarios → give each a fresh browser context, else count/quantity asserts are flaky.` });
+    }
+  }
+
+  return { screens, flows, deferrals, contracts, missing: deferrals.filter((d) => d.verdict === 'missing').length };
+}

package/src/harness/flow-plan.ts

@@ -0,0 +1,135 @@
+/**
+ * Flow Capability Planner (Phase 2c) — flow-aware, deterministic, recommend-only.
+ *
+ * Decomposes a flow into per-screen LEGS (from [Screen:Element] refs), reports each
+ * leg's SELECTOR READINESS + capability, folds in the manual-reason taxonomy
+ * (capability-plan) and the run-test contract (flow-check), and emits a run-test
+ * PLAN. Automates the manual diagnosis done while healing cart-and-filter.
+ * See reports/sungen_phase2c_spec.md.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { MANUAL_REASONS, inferReasonCode } from './capability-plan';
+import { buildFlowCheck, Contract } from './flow-check';
+
+const REF_RE = /\[([A-Za-z][\w ]*?):([\w &.-]+?)\]/g;
+
+interface FlowScenario { name: string; manual: boolean; reason: string; tags: string[]; refs: { screen: string; element: string }[] }
+
+function parseFlowScenarios(featurePath: string): FlowScenario[] {
+  if (!fs.existsSync(featurePath)) return [];
+  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const out: FlowScenario[] = [];
+  const idx: number[] = [];
+  lines.forEach((l, i) => { if (/^\s*Scenario:/.test(l)) idx.push(i); });
+  for (let s = 0; s < idx.length; s++) {
+    const i = idx[s];
+    const end = s + 1 < idx.length ? idx[s + 1] : lines.length;
+    const name = lines[i].replace(/^\s*Scenario:\s*/, '').trim();
+    // tags + reason from the lines above + first comment in body
+    const tags: string[] = []; let reason = '';
+    for (let j = i - 1; j >= 0; j--) {
+      const t = lines[j].trim();
+      if (t === '') break;
+      if (/^@/.test(t)) tags.unshift(...t.split(/\s+/).filter((x) => x.startsWith('@')));
+      else if (/^#/.test(t)) { if (!reason) reason = t.replace(/^#+\s*/, ''); }
+      else break;
+    }
+    const body = lines.slice(i, end).join('\n');
+    if (!reason) { const m = body.match(/^\s*#\s*(.+)$/m); if (m) reason = m[1].trim(); }
+    const refs: FlowScenario['refs'] = [];
+    let mm: RegExpExecArray | null;
+    REF_RE.lastIndex = 0;
+    while ((mm = REF_RE.exec(body))) refs.push({ screen: mm[1].trim(), element: mm[2].trim() });
+    out.push({ name, manual: tags.some((t) => /^@manual\b/i.test(t)), reason, tags, refs });
+  }
+  return out;
+}
+
+function selectorKeys(selectorsPath: string): Set<string> {
+  if (!fs.existsSync(selectorsPath)) return new Set();
+  try {
+    const y = parseYaml(fs.readFileSync(selectorsPath, 'utf-8')) || {};
+    return new Set(Object.keys(y).map((k) => k.toLowerCase()));
+  } catch { return new Set(); }
+}
+
+export interface LegPlan {
+  screen: string;
+  scenarios: number;
+  refs: string[];
+  haveKeys: number;
+  readiness: 'ready' | 'partial' | 'missing';
+  touchedByAutomated: boolean;
+}
+export interface FlowPlan {
+  flow: string;
+  total: number;
+  legs: LegPlan[];
+  byReason: Record<string, number>;
+  capabilityManual: number;
+  judgmentManual: number;
+  contracts: Contract[];
+  readiness: 'ready' | 'not-ready';
+  missingLegs: string[];
+  plan: string[];
+}
+
+export function buildFlowPlan(cwd: string, flow: string): FlowPlan {
+  const featurePath = path.join(cwd, 'qa', 'flows', flow, 'features', `${flow}.feature`);
+  const selectorsPath = path.join(cwd, 'qa', 'flows', flow, 'selectors', `${flow}.yaml`);
+  const scenarios = parseFlowScenarios(featurePath);
+  const keys = selectorKeys(selectorsPath);
+
+  // Legs = distinct screen namespaces.
+  const legMap = new Map<string, { scenarios: Set<string>; refs: Set<string>; automated: boolean }>();
+  const byReason: Record<string, number> = {};
+  let capabilityManual = 0, judgmentManual = 0;
+
+  for (const sc of scenarios) {
+    if (sc.manual) {
+      const { code } = inferReasonCode(sc.tags, sc.reason);
+      byReason[code] = (byReason[code] || 0) + 1;
+      const cls = MANUAL_REASONS[code]?.cls;
+      if (cls === 'capability') capabilityManual++; else if (cls === 'keep') judgmentManual++;
+    }
+    for (const r of sc.refs) {
+      const leg = r.screen.toLowerCase();
+      const entry = legMap.get(leg) || { scenarios: new Set(), refs: new Set(), automated: false };
+      entry.scenarios.add(sc.name);
+      entry.refs.add(`${leg}:${r.element.toLowerCase()}`);
+      if (!sc.manual) entry.automated = true;
+      legMap.set(leg, entry);
+    }
+  }
+
+  const legs: LegPlan[] = [...legMap.entries()].map(([screen, e]) => {
+    const refs = [...e.refs];
+    const haveKeys = refs.filter((rk) => keys.has(rk)).length;
+    const readiness: LegPlan['readiness'] = haveKeys === refs.length ? 'ready' : haveKeys === 0 ? 'missing' : 'partial';
+    return { screen, scenarios: e.scenarios.size, refs, haveKeys, readiness, touchedByAutomated: e.automated };
+  }).sort((a, b) => b.scenarios - a.scenarios);
+
+  const missingLegs = legs.filter((l) => l.touchedByAutomated && l.readiness !== 'ready').map((l) => l.screen);
+  const fc = buildFlowCheck(cwd, flow);
+  const contracts = fc.contracts.filter((c) => c.flow === flow);
+
+  const readiness: FlowPlan['readiness'] = missingLegs.length ? 'not-ready' : 'ready';
+  const plan: string[] = [];
+  if (missingLegs.length) {
+    plan.push(`Run \`/sungen:run-test ${flow}\` → Phase 0 generates selectors for: ${missingLegs.join(', ')} (from the live pages).`);
+  }
+  if (contracts.some((c) => c.kind === 'SAME-CARD')) plan.push('Honour SAME-CARD: scope remember + Add To Cart/View Product to ONE card at run-test.');
+  if (contracts.some((c) => c.kind === 'ISOLATION')) plan.push('Honour ISOLATION: fresh browser context per cart/state scenario (@parallel).');
+  const driverReasons = Object.keys(byReason).filter((c) => MANUAL_REASONS[c]?.cls === 'capability');
+  if (driverReasons.length) {
+    const drivers = [...new Set(driverReasons.flatMap((c) => MANUAL_REASONS[c].drivers))];
+    if (drivers.length) plan.push(`Consider drivers (recommend-only): ${drivers.join(', ')} — for capability-manual (${driverReasons.join('/')}).`);
+  } else {
+    plan.push('No capability driver needed — all automated legs are @ui.');
+  }
+  if (readiness === 'ready') plan.unshift('Selectors present for every automated leg — ready to compile + run.');
+
+  return { flow, total: scenarios.length, legs, byReason, capabilityManual, judgmentManual, contracts, readiness, missingLegs, plan };
+}

package/src/harness/intent.ts

@@ -0,0 +1,58 @@
+/**
+ * Intent Profile (harness-roadmap P3) — lets the gate flex to project intent.
+ *
+ * Read from qa/context.md so a project can declare what it cares about:
+ *
+ *   ## Intent
+ *   focus: security          # functional | e-commerce | security | smoke
+ *   risk_tier: high          # high | normal | low   (reserved — future weighting)
+ *   tier_scope: full         # tier-1 | full         (reserved)
+ *
+ * Keys may appear anywhere in context.md (a heading is optional). Unknown / missing
+ * values fall back to the safe default (functional), so behaviour is unchanged for
+ * projects that haven't declared an intent.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type IntentFocus = 'functional' | 'e-commerce' | 'security' | 'smoke';
+
+export interface IntentProfile {
+  focus: IntentFocus;
+  riskTier: 'high' | 'normal' | 'low';
+  tierScope: 'tier-1' | 'full';
+  source: 'context.md' | 'default';
+}
+
+const DEFAULT_INTENT: IntentProfile = {
+  focus: 'functional', riskTier: 'normal', tierScope: 'full', source: 'default',
+};
+
+const FOCI: IntentFocus[] = ['functional', 'e-commerce', 'security', 'smoke'];
+
+/** Resolve project root from a screen/flow dir (…/qa/screens/<name>). */
+export function projectRootFromScreenDir(screenDir: string): string {
+  return path.resolve(screenDir, '..', '..', '..');
+}
+
+export function readIntent(projectRoot: string): IntentProfile {
+  const ctx = path.join(projectRoot, 'qa', 'context.md');
+  if (!fs.existsSync(ctx)) return DEFAULT_INTENT;
+  let text: string;
+  try { text = fs.readFileSync(ctx, 'utf-8').toLowerCase(); } catch { return DEFAULT_INTENT; }
+
+  const grab = (key: string): string | undefined => {
+    const m = text.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*:\\s*([a-z0-9-]+)`));
+    return m?.[1];
+  };
+
+  const focusRaw = grab('focus');
+  const focus = (FOCI.includes(focusRaw as IntentFocus) ? focusRaw : DEFAULT_INTENT.focus) as IntentFocus;
+  const risk = grab('risk_tier');
+  const riskTier = (['high', 'normal', 'low'].includes(risk as string) ? risk : DEFAULT_INTENT.riskTier) as IntentProfile['riskTier'];
+  const scope = grab('tier_scope');
+  const tierScope = (['tier-1', 'full'].includes(scope as string) ? scope : DEFAULT_INTENT.tierScope) as IntentProfile['tierScope'];
+
+  const found = focusRaw || risk || scope;
+  return { focus, riskTier, tierScope, source: found ? 'context.md' : 'default' };
+}