@sun-asterisk/sungen 2.7.0-beta.0 → 3.0.0-beta.71

package/src/harness/audit.ts

@@ -0,0 +1,112 @@
+/**
+ * Harness Audit — runs all sensors over a screen's test-design artifacts and
+ * produces a structured report + a business-weighted quality score.
+ *
+ * The score is INTENTIONALLY weighted toward business-critical coverage/depth
+ * (not breadth), so it surfaces the gaps a count-based view hides. See
+ * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
+ */
+import * as path from 'path';
+import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import {
+  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult,
+} from './sensors';
+import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
+
+export interface AuditReport {
+  screen: string;
+  scenarioCount: number;
+  gate: GateResult;
+  depth: DepthResult;
+  balance: BalanceResult;
+  duplicates: DuplicateResult;
+  trace: TraceResult;
+  score: {
+    overall: number;            // 0..10, business-weighted
+    coverage: number;           // 0..1
+    businessDepth: number;      // 0..1
+    balance: number;            // 0..1
+    traceability: number;       // 0..1
+    formula: string;
+  };
+  gateStatus: 'PASS' | 'FAIL';
+  findings: string[];           // human-actionable, what the Repair loop would target
+  intent: IntentProfile;        // P3 — the intent profile that drove the thresholds
+}
+
+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 scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
+  const catalog = loadCatalog();
+
+  const gate = viewpointGate(scenarios, viewpoints, catalog);
+  // P3 — intent profile from qa/context.md drives the depth threshold (focus).
+  const intent = readIntent(projectRootFromScreenDir(screenDir));
+  const depth = assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+  const balance = coverageBalance(scenarios);
+  const duplicates = duplicateClusters(scenarios);
+  const trace = traceability(scenarios, viewpoints);
+
+  // Sub-scores
+  const coverage = gate.coverageRatio;
+  const businessDepth = depth.bcDepthRatio;
+  const balanceScore = balance.coreCount + balance.secondaryCount > 0
+    ? Math.min(1, balance.coreCount / Math.max(1, balance.secondaryCount))
+    : 1;
+  const traceScore = 0.5 * trace.withVpCodeRatio + 0.5 * trace.mappedRatio;
+
+  // Business-weighted overall (coverage + depth dominate)
+  const overall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
+
+  const findings: string[] = [];
+  for (const g of gate.gaps) {
+    if (g.status === 'shallow') {
+      findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);
+    } else {
+      findings.push(`GATE: critical theme "${g.theme}" for page-type "${gate.pageType}" has NO covering scenario → generate it (often cross-screen → consider add-flow).`);
+    }
+  }
+  if (depth.businessCriticalShallow > 0) {
+    const tag = depth.verdict === 'fail' ? 'DEPTH-FAIL' : depth.verdict === 'warn' ? 'DEPTH-WARN' : 'DEPTH';
+    findings.push(
+      `${tag}: ${depth.businessCriticalShallow}/${depth.businessCriticalTotal} data-correctness scenarios assert only visibility ` +
+      `(ratio ${depth.bcDepthRatio.toFixed(2)} < threshold ${depth.threshold.toFixed(2)} for focus "${depth.focus}") → ` +
+      `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
+    );
+  }
+  if (balance.imbalanced) {
+    findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
+  }
+  if (trace.mappedRatio < 0.5) {
+    findings.push(`TRACE: ${trace.note}`);
+  }
+  if (gate.universalGaps.length) {
+    findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
+  }
+
+  // Gate now spans coverage (viewpoint themes) AND depth (data-correctness).
+  // A depth 'fail' (below the intent threshold) fails the gate; 'warn' does not.
+  const gateStatus: 'PASS' | 'FAIL' =
+    gate.gaps.length === 0 && depth.verdict !== 'fail' ? 'PASS' : 'FAIL';
+
+  return {
+    screen: screenName,
+    scenarioCount: scenarios.length,
+    gate, depth, balance, duplicates, trace,
+    score: {
+      overall: Math.round(overall * 10) / 10,
+      coverage: Math.round(coverage * 100) / 100,
+      businessDepth: Math.round(businessDepth * 100) / 100,
+      balance: Math.round(balanceScore * 100) / 100,
+      traceability: Math.round(traceScore * 100) / 100,
+      formula: 'overall = (0.4*coverage + 0.3*businessDepth + 0.15*balance + 0.15*traceability) * 10',
+    },
+    gateStatus,
+    findings,
+    intent,
+  };
+}

package/src/harness/blindspot.ts

@@ -0,0 +1,51 @@
+/**
+ * Blind-Spot Memory (harness-roadmap P5).
+ *
+ * A deterministic harness reliably repeats whatever its rules/viewpoints miss. When
+ * a QA (or the challenge critic) finds a recurring gap, don't just patch one test —
+ * promote it to a reusable PATTERN here. Loop 1 (generation pre-gate) and Loop 2
+ * (challenge critic) read these so the same blind spot doesn't come back.
+ *
+ * Store: .sungen/blindspots/blindspots.jsonl (append-only, project-local).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface Blindspot {
+  ts: string;
+  pattern: string;    // short name, e.g. "add-action-no-duplicate-check"
+  rule: string;       // the generalised rule to apply next time
+  example?: string;   // a concrete instance that motivated it
+  screen?: string;    // where it was first noticed
+  source?: string;    // 'qa' | 'challenge' | 'feedback'
+}
+
+function storePath(): string {
+  return path.join(process.cwd(), '.sungen', 'blindspots', 'blindspots.jsonl');
+}
+
+export function addBlindspot(entry: Omit<Blindspot, 'ts'> & { ts?: string }): string {
+  const p = storePath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const full: Blindspot = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+  fs.appendFileSync(p, JSON.stringify(full) + '\n', 'utf-8');
+  return p;
+}
+
+export function listBlindspots(): Blindspot[] {
+  const p = storePath();
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l) as Blindspot; } catch { return null; }
+  }).filter(Boolean) as Blindspot[];
+}
+
+/** Compact bullet list for injecting into generator / critic prompts. */
+export function blindspotsForPrompt(): string {
+  const all = listBlindspots();
+  if (!all.length) return '';
+  // De-dupe by pattern (latest rule wins).
+  const byPattern = new Map<string, Blindspot>();
+  for (const b of all) byPattern.set(b.pattern, b);
+  return [...byPattern.values()].map((b) => `- [${b.pattern}] ${b.rule}`).join('\n');
+}

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