@sun-asterisk/sungen 3.2.2 → 3.2.3-beta.3

package/src/harness/journey.ts

@@ -0,0 +1,434 @@
+/**
+ * Journey board (epic #381, story S1) — the durable, read-only "you are here" view.
+ *
+ * Reconstructs the QA's position from artifacts ALREADY on disk (no recomputation, no context
+ * needed): the audit report (`.sungen/reports/<slug>-audit.json`) supplies the obligation status
+ * via its calibration axes + gate + findings; the ledger (`.sungen/ledger/<slug>.jsonl`) supplies
+ * the phase history ("you are here"). The output answers the three QA questions — what's next /
+ * what to review / what's doubtful — and persists `.sungen/journey/<slug>.{json,board.md}`.
+ *
+ * S1 = the read-only synthesis. S2 (this file) adds the **writable lifecycle**: persisted
+ * waivers (reason-required, anti-amnesia), reconcile (auto-close satisfied; re-surface a waiver
+ * when its evidence changed), via `runJourney` + `waive`. Gate-bound predicates + inter-phase
+ * gates are S3. Pure-deterministic, no AI.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { reportSlug } from './unit-paths';
+
+export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
+
+export interface Obligation {
+  id: string;
+  title: string;
+  status: ObStatus;
+  detail: string;
+  waivedReason?: string;   // S2 — set when the QA explicitly waived this obligation
+}
+
+/** S5 — a parsed anchor so an IDE can jump straight to what needs review. */
+export interface Anchor { vpId?: string; file?: string; line?: number; }
+export interface ReviewItem { text: string; anchor: Anchor; }
+
+export interface JourneyReport {
+  unit: string;
+  generatedFrom: string[];          // which artifacts were available
+  youAreHere: string;               // last ledger phase, or 'not started'
+  phasesDone: string[];
+  gateStatus: string | null;
+  score: number | null;
+  obligations: Obligation[];
+  needsYou: ReviewItem[];           // S5 — the review queue: human-judgment findings, each with an anchor
+  nextSuggested: string;
+}
+
+function readJSON(p: string): any {
+  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null; } catch { return null; }
+}
+
+function readLedgerPhases(p: string): string[] {
+  if (!fs.existsSync(p)) return [];
+  const out: string[] = [];
+  for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+    if (!line.trim()) continue;
+    try { const d = JSON.parse(line); if (d.step) out.push(String(d.step)); } catch { /* skip */ }
+  }
+  return out;
+}
+
+/** Findings that ask for HUMAN judgment (the review-queue seed), vs pure machine-repair targets. */
+function isHumanFinding(f: string): boolean {
+  return /@manual|MANUAL-|DEPTH-DEFERRED|UNSOURCEABLE|CAPABILITY-SUGGESTION|judgment|oracle|review/i.test(f);
+}
+
+/** S5 — pull an IDE-jumpable anchor out of a finding (VP id, scenario, or `file.ext:line`). */
+function extractAnchor(text: string): Anchor {
+  const vp = text.match(/\bVP-[A-Z0-9-]+\b/);
+  const fl = text.match(/([\w./-]+\.(?:md|feature|ts|yaml)):(\d+)/);
+  return { vpId: vp ? vp[0] : undefined, file: fl ? fl[1] : undefined, line: fl ? Number(fl[2]) : undefined };
+}
+
+const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
+
+function computeFresh(projectRoot: string, unit: string): JourneyReport {
+  const slug = reportSlug(unit);
+  const audit = readJSON(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  const phases = readLedgerPhases(path.join(projectRoot, '.sungen', 'ledger', `${slug}.jsonl`));
+
+  const from: string[] = [];
+  if (audit) from.push('audit');
+  if (phases.length) from.push('ledger');
+
+  const youAreHere = phases.length ? phases[phases.length - 1] : 'not started';
+  const ran = (p: string) => phases.some((s) => s === p || s.startsWith(p));
+
+  const obligations: Obligation[] = [];
+  const needsYou: ReviewItem[] = [];
+
+  if (!audit) {
+    // Nothing measured yet — the journey hasn't really begun.
+    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: 'No audit report yet — run /sungen:create-test.' });
+    return {
+      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null,
+      obligations, needsYou, nextSuggested: 'Run `/sungen:create-test ' + unit + '` to begin.',
+    };
+  }
+
+  const ax = (audit.calibration && audit.calibration.axes) || {};
+  const depthThreshold = (audit.depth && audit.depth.threshold) || SAT;
+  const ob = (id: string, title: string, val: number | undefined, thr: number, detail: string): Obligation => ({
+    id, title,
+    status: val === undefined ? 'pending' : val >= thr ? 'satisfied' : 'needs-work',
+    detail: val === undefined ? detail : `${Math.round(val * 100)}% (need ${Math.round(thr * 100)}%) — ${detail}`,
+  });
+
+  obligations.push(ob('OB-spec', 'Spec readiness', ax.specFR, 1, 'FR/sections sufficient to design from'));
+  obligations.push(ob('OB-coverage', 'Viewpoint coverage', ax.coverage, SAT, 'critical themes covered'));
+  obligations.push(ob('OB-depth', 'Assertion depth', ax.businessDepth, depthThreshold, 'business-critical scenarios assert data'));
+  obligations.push(ob('OB-trace', 'Traceability', ax.taxonomy ?? ax.traceability, SAT, 'scenarios trace to viewpoints'));
+
+  // Automation obligation: automatable @manual still pending a driver = needs-work.
+  const autoPending = audit.automatableManual && audit.automatableManual.automatable > 0;
+  obligations.push({
+    id: 'OB-automation', title: 'Automation coverage',
+    status: autoPending ? 'needs-work' : 'satisfied',
+    detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
+  });
+
+  // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
+  // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
+  // the aggregate "DEPTH:" finding string (which names no scenario, so points nowhere). Then
+  // supplement with the remaining human-judgment findings.
+  const shallowBC: { name: string; category?: string }[] = (audit.depth && audit.depth.shallowBusinessCritical) || [];
+  for (const s of shallowBC) {
+    needsYou.push({
+      text: `DEEPEN — "${s.name}": assert data, not just visibility (\`… with {{value}}\` / \`see all … contain {{v}}\`), or defer cross-screen with @manual + reason.`,
+      anchor: extractAnchor(s.name),
+    });
+  }
+  const haveStructuredDepth = shallowBC.length > 0;
+  for (const f of (audit.findings || [])) {
+    if (!isHumanFinding(f)) continue;
+    if (haveStructuredDepth && /^\s*DEPTH\b/i.test(f)) continue; // superseded by the per-scenario items above
+    needsYou.push({ text: f, anchor: extractAnchor(f) });
+  }
+
+  // Human sign-off: always pending until S5 explicit signoff; carries the now-final review-queue count.
+  const manualCount = (audit.manualOracle && (audit.manualOracle.manualTotal ?? audit.manualOracle.total)) || 0;
+  obligations.push({
+    id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
+    detail: `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`,
+  });
+
+  // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
+  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
+  let nextSuggested: string;
+  if (firstGap) nextSuggested = `Repair "${firstGap.title}" (${firstGap.detail}).`;
+  else if (!ran('run')) nextSuggested = `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+  else nextSuggested = `All obligations satisfied — review the ${needsYou.length} queued item(s), then sign off & deliver.`;
+
+  return {
+    unit, generatedFrom: from, youAreHere, phasesDone: phases,
+    gateStatus: audit.gateStatus ?? null, score: (audit.score && audit.score.overall) ?? null,
+    obligations, needsYou, nextSuggested,
+  };
+}
+
+// ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
+
+interface Waiver { reason: string; at: string; auditHashAtWaive: string; }
+interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5
+interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; signoff?: Signoff; }
+
+function statePath(projectRoot: string, slug: string): string {
+  return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
+}
+/** Evidence cursor: the audit report's content hash. A waiver is invalidated when this changes. */
+function auditHashOf(projectRoot: string, slug: string): string {
+  const p = path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`);
+  return fs.existsSync(p) ? crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex') : '';
+}
+function loadState(p: string): JourneyState | null { return readJSON(p); }
+function saveState(p: string, s: JourneyState): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(s, null, 2), 'utf-8');
+}
+
+/** Recompute nextSuggested AFTER waivers are applied (a waived obligation is not a gap). */
+function computeNext(r: JourneyReport, unit: string): string {
+  const gap = r.obligations.find((o) => o.status !== 'satisfied' && o.status !== 'waived' && o.id !== 'OB-signoff');
+  if (gap) return `Repair "${gap.title}" (${gap.detail}).`;
+  if (!r.phasesDone.some((s) => s === 'run' || s.startsWith('run'))) return `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
+  return `All obligations satisfied/waived — review the ${r.needsYou.length} queued item(s), then sign off & deliver.`;
+}
+
+/**
+ * The public entry: compute fresh, then RECONCILE with the persisted state —
+ *  - auto-close is automatic (fresh recompute reflects the current artifacts);
+ *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
+ *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
+ * Then persist the current evidence cursor.
+ */
+export function runJourney(projectRoot: string, unit: string): JourneyReport {
+  const slug = reportSlug(unit);
+  const report = computeFresh(projectRoot, unit);
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  const curHash = auditHashOf(projectRoot, slug);
+
+  for (const ob of report.obligations) {
+    const w = state.waivers[ob.id];
+    if (!w) continue;
+    if (w.auditHashAtWaive === curHash) {
+      ob.status = 'waived';
+      ob.waivedReason = w.reason;
+      ob.detail = `waived — ${w.reason}`;
+    } else {
+      report.needsYou.unshift({ text: `⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`, anchor: { vpId: ob.id } });
+    }
+  }
+  // S5 — sign-off reconcile: a recorded sign-off satisfies OB-signoff while its evidence holds;
+  // if the audit changed since, the sign-off is STALE → re-surface for re-review (anti-amnesia).
+  const signoffOb = report.obligations.find((o) => o.id === 'OB-signoff');
+  if (signoffOb && state.signoff) {
+    if (state.signoff.auditHashAtSignoff === curHash) {
+      signoffOb.status = 'satisfied';
+      signoffOb.detail = `signed off${state.signoff.by ? ' by ' + state.signoff.by : ''} at ${state.signoff.at}`;
+    } else {
+      report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
+    }
+  }
+  report.nextSuggested = computeNext(report, unit);
+  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers, signoff: state.signoff });
+  return report;
+}
+
+/**
+ * Waive an obligation — REQUIRES a reason (anti-amnesia: a waiver leaves a recorded "why").
+ * Records the current evidence cursor so reconcile can invalidate it if the audit changes.
+ */
+export function waive(projectRoot: string, unit: string, obId: string, reason: string): JourneyReport {
+  if (!reason || !reason.trim()) {
+    throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
+  }
+  const slug = reportSlug(unit);
+  const fresh = computeFresh(projectRoot, unit);
+  const valid = fresh.obligations.map((o) => o.id);
+  if (!valid.includes(obId)) {
+    throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
+  }
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  state.waivers[obId] = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
+  saveState(sp, state);
+  return runJourney(projectRoot, unit);
+}
+
+/**
+ * Sign off — the single human gate (S5). Allowed ONLY when every other deliver-required
+ * obligation is satisfied or waived (you cannot sign off an unclean suite). Records who/when +
+ * the evidence cursor; reconcile invalidates it (stale → re-review) if the suite later changes.
+ */
+export function signoff(projectRoot: string, unit: string, by?: string): JourneyReport {
+  const before = runJourney(projectRoot, unit);
+  const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived');
+  if (blockers.length) {
+    throw new Error(`Cannot sign off — still open: ${blockers.map((b) => b.id).join(', ')}. Fix, or waive each with a reason, first.`);
+  }
+  const slug = reportSlug(unit);
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  state.signoff = { by, at: new Date().toISOString(), auditHashAtSignoff: auditHashOf(projectRoot, slug) };
+  saveState(sp, state);
+  return runJourney(projectRoot, unit);
+}
+
+const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
+
+export function renderJourneyBoard(r: JourneyReport): string {
+  const L: string[] = [];
+  L.push(`# Journey — ${r.unit}`);
+  L.push('');
+  L.push(`📍 **You are here:** ${r.youAreHere}` + (r.phasesDone.length ? `  (phases: ${r.phasesDone.join(' → ')})` : ''));
+  if (r.gateStatus) L.push(`   gate: **${r.gateStatus}** · score: ${r.score ?? '—'}/10`);
+  L.push('');
+  L.push('## What must still be true');
+  for (const o of r.obligations) L.push(`- ${ICON[o.status]} **${o.title}** — ${o.detail}`);
+  L.push('');
+  L.push(`## 🔎 Review queue — needs your judgment (${r.needsYou.length})`);
+  if (r.needsYou.length) {
+    for (const it of r.needsYou.slice(0, 20)) {
+      const a = it.anchor;
+      const tag = [a.vpId, a.file && `${a.file}${a.line ? ':' + a.line : ''}`].filter(Boolean).join(' · ');
+      L.push(`- ${it.text}${tag ? `  〔${tag}〕` : ''}`);
+    }
+  } else L.push('- (nothing queued)');
+  L.push('');
+  L.push(`## → Next`);
+  L.push(`${r.nextSuggested}`);
+  L.push('');
+  return L.join('\n');
+}
+
+// ---------------- S3: inter-phase gate — obligations as HALT predicates (#398) ----------------
+//
+// A phase boundary is a deterministic gate: before the next phase may run, this phase's required
+// obligations must each be `satisfied` OR `waived` (S2 — an explicit, reasoned human acceptance).
+// A required obligation still `needs-work`/`pending` is a BLOCKER → HALT (no silent bad output
+// crosses the boundary, §9). Reuses runJourney → obligations already reflect waivers/reconcile.
+
+export type GatePhase = 'create' | 'run' | 'deliver';
+
+export interface GateVerdict {
+  unit: string;
+  phase: GatePhase;
+  status: 'pass' | 'halt';
+  required: string[];
+  blockers: { id: string; title: string; detail: string }[];
+  waivedCredit: { id: string; title: string }[]; // required obligations accepted via an explicit waiver
+}
+
+const PHASE_REQUIRED: Record<GatePhase, string[]> = {
+  // post-create (design quality): spec + coverage + depth + traceability must hold.
+  create: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace'],
+  // post-run: the design gates + automation coverage.
+  run: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation'],
+  // pre-delivery: everything automated PLUS the single human sign-off (S5).
+  deliver: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation', 'OB-signoff'],
+};
+
+export function runGate(projectRoot: string, unit: string, phase: GatePhase): GateVerdict {
+  const r = runJourney(projectRoot, unit);
+  const required = PHASE_REQUIRED[phase];
+  const reqObs = r.obligations.filter((o) => required.includes(o.id));
+  const blockers = reqObs
+    .filter((o) => o.status !== 'satisfied' && o.status !== 'waived')
+    .map((o) => ({ id: o.id, title: o.title, detail: o.detail }));
+  const waivedCredit = reqObs.filter((o) => o.status === 'waived').map((o) => ({ id: o.id, title: o.title }));
+  return { unit, phase, status: blockers.length ? 'halt' : 'pass', required, blockers, waivedCredit };
+}
+
+export function renderGate(v: GateVerdict): string {
+  const L: string[] = [];
+  L.push('');
+  L.push(`━━━ Gate: ${v.unit} @ phase "${v.phase}" → ${v.status === 'pass' ? '✅ PASS' : '⛔ HALT'} ━━━`);
+  if (v.blockers.length) {
+    L.push('  Blocking obligations (must be satisfied or explicitly waived):');
+    for (const b of v.blockers) L.push(`   • ${b.id} ${b.title} — ${b.detail}`);
+    L.push('  → Self-correct (repair / run-test), or `sungen journey --screen ' + v.unit + ' --waive <OB> --reason "..."` if accepted.');
+  } else {
+    L.push('  All required obligations satisfied' + (v.waivedCredit.length ? ` (${v.waivedCredit.length} accepted via waiver)` : '') + '.');
+  }
+  L.push('');
+  return L.join('\n');
+}
+
+// ---------------- #409: project-level roll-up across all units ----------------
+//
+// Multi-unit fan-out PARALLELISES generation but human review/sign-off must stay SERIAL — you can't
+// judge N boards at once. This roll-up is that serial surface: one row per unit (gate · score · phase
+// · what it still needs), and a single "review this next" pointer. The per-unit board is unchanged;
+// this only aggregates the same read-only `runJourney` synthesis.
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+export interface UnitSummary {
+  unit: string;
+  kind: UnitKind;
+  score: number | null;
+  gateStatus: string | null;
+  youAreHere: string;
+  obligationsOpen: number;   // non-satisfied, non-waived (excludes OB-signoff)
+  reviewQueue: number;
+  signedOff: boolean;
+  started: boolean;          // has an audit report yet
+}
+
+/** Discover every unit under qa/screens, qa/flows, and qa/api top-level areas. */
+export function listUnits(projectRoot: string): { unit: string; kind: UnitKind }[] {
+  const out: { unit: string; kind: UnitKind }[] = [];
+  const scan = (sub: string, kind: UnitKind) => {
+    const d = path.join(projectRoot, 'qa', sub);
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      // 'flows' under qa/api is a container for api-flows (a nested tier) — not a unit itself.
+      if (e.isDirectory() && !(sub === 'api' && e.name === 'flows')) out.push({ unit: e.name, kind });
+    }
+  };
+  scan('screens', 'screen');
+  scan('flows', 'flow');
+  scan('api', 'api');
+  return out;
+}
+
+/** Roll up every unit's journey into one table of summaries (serial review surface). */
+export function rollupJourney(projectRoot: string): UnitSummary[] {
+  return listUnits(projectRoot).map(({ unit, kind }) => {
+    const r = runJourney(projectRoot, unit);
+    const signedOff = r.obligations.find((o) => o.id === 'OB-signoff')?.status === 'satisfied';
+    const obligationsOpen = r.obligations.filter(
+      (o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived',
+    ).length;
+    return {
+      unit, kind, score: r.score, gateStatus: r.gateStatus, youAreHere: r.youAreHere,
+      obligationsOpen, reviewQueue: r.needsYou.length, signedOff,
+      started: r.generatedFrom.includes('audit'),
+    };
+  });
+}
+
+function unitStatusLabel(r: UnitSummary): string {
+  if (!r.started) return '◻️ not started';
+  if (r.signedOff) return '✅ signed off';
+  if (r.obligationsOpen > 0) return `⏳ ${r.obligationsOpen} obligation(s) open`;
+  if (r.reviewQueue > 0) return `🔎 review ${r.reviewQueue} item(s)`;
+  return '🟡 ready to sign off';
+}
+
+export function renderRollupBoard(rows: UnitSummary[]): string {
+  const L: string[] = [];
+  L.push('# Journey roll-up — all units');
+  L.push('');
+  if (!rows.length) {
+    L.push('No units found under `qa/screens`, `qa/flows`, or `qa/api`.');
+    return L.join('\n');
+  }
+  L.push('| Unit | Kind | Score | Gate | Phase | Needs |');
+  L.push('|---|---|---|---|---|---|');
+  for (const r of rows) {
+    L.push(`| ${r.unit} | ${r.kind} | ${r.score ?? '—'} | ${r.gateStatus ?? '—'} | ${r.youAreHere} | ${unitStatusLabel(r)} |`);
+  }
+  L.push('');
+  const blocked = rows.filter((r) => r.started && (r.obligationsOpen > 0));
+  const toReview = rows.filter((r) => r.started && r.obligationsOpen === 0 && !r.signedOff && r.reviewQueue >= 0);
+  const notStarted = rows.filter((r) => !r.started);
+  L.push(`**${rows.filter((r) => r.signedOff).length}/${rows.length} signed off** · ${blocked.length} with open obligations · ${notStarted.length} not started.`);
+  L.push('');
+  L.push('## → Next (review is serial — one unit at a time)');
+  const next = blocked[0] || toReview[0] || notStarted[0];
+  if (!next) L.push('All units signed off — `sungen delivery` to export.');
+  else if (!next.started) L.push(`Generate **${next.unit}** — \`/sungen:create-test ${next.unit}\`.`);
+  else L.push(`Review **${next.unit}** (${unitStatusLabel(next)}) — \`sungen journey --screen ${next.unit}\`, then sign off.`);
+  L.push('');
+  return L.join('\n');
+}

package/src/harness/quality-gates.ts

@@ -42,6 +42,26 @@ export function isolationRisk(featureText: string, stateful: boolean): boolean {
   return !/@cleanup:cart\b|@isolate\b|empty cart|fresh (?:browser )?context|new context/i.test(featureText);
 }
 
+/**
+ * #414 — the complement of isolationRisk. Per-scenario isolation is the DEFAULT now, so untagged
+ * suites can't cascade. `@serial` opts INTO a shared-page `test.describe.serial` suite, whose
+ * Playwright semantics SKIP every test after the first failure. That is correct ONLY for a genuinely
+ * stateful ordered sequence; for INDEPENDENT scenarios — each re-establishing its own start state via
+ * a navigating Background — `@serial` buys no correctness, only a cascade that *masks* failures (one
+ * early red turns the rest into greens-by-omission). Returns the scenario count when `@serial` should
+ * be dropped (the default isolation is safer), else 0.
+ *
+ * Conservative on purpose — only fires on `@serial` suites whose every scenario provably restarts (a
+ * `Background` that navigates `on [..] page`), so a real stateful sequence keeps its `@serial`.
+ */
+export function serialCascadeRisk(featureText: string, scenarioCount: number): number {
+  if (!/@serial\b/i.test(featureText)) return 0;        // isolated by default → no cascade
+  if (scenarioCount < 8) return 0;                      // small blast radius — not worth the churn
+  const navBackground = /Background:[\s\S]*?\bon \[[^\]]+\] page\b/i.test(featureText);
+  if (!navBackground) return 0;                         // no per-scenario reset → genuinely stateful; @serial is right
+  return scenarioCount;
+}
+
 export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
   const routes = downstreamRoutes(specText);
   const underCovered: { route: string; slug: string }[] = [];

package/src/harness/sensors.ts

@@ -59,9 +59,17 @@ export function loadCatalog(): Catalog {
   return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
 }
 
+// Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
+// simple plural/verb suffixes) but NOT as a substring of a larger word — e.g. `form` must not
+// match inside `Format` or `@platform`, while `product` still matches `products`. Multi-word
+// keywords ("add to cart", "is hidden") match the phrase with a boundary at each end.
+const wordRe = (kw: string) => {
+  const esc = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${esc}(?:s|es|ed|ing)?\\b`);
+};
 const has = (haystacks: string[], kw: string) => {
-  const k = kw.toLowerCase();
-  return haystacks.some((h) => h.includes(k));
+  const re = wordRe(kw);
+  return haystacks.some((h) => re.test(h));
 };
 
 // ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
@@ -75,16 +83,21 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog): GateResult {
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
   ];
 
-  // Detect page-type by detect_keywords hit count
+  // Detect page-type by detect_keywords hit count. `mobile-*` page-types are candidates ONLY for
+  // mobile targets; web targets never consider them. Mobile targets still consider the web types
+  // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
+  // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
+  // null → no themes required → the gate passes leniently rather than false-FAILing.
   let pageType: string | null = null;
   let best = 0;
   for (const [pt, def] of Object.entries(catalog.page_types)) {
+    if (pt.startsWith('mobile-') && !isMobile) continue;
     const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
     if (hits > best) { best = hits; pageType = pt; }
   }
@@ -97,10 +110,14 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
       // Scenarios that cover this theme by keyword (include @manual — a manual
       // scenario with a real assertion still covers the viewpoint for design).
       const coverers = scenarios.filter((s) => t.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
-      const deep = coverers.some((s) => s.hasDataAssertion);
-      if (deep) covered++;
-      else if (coverers.length > 0) gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
-      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' });
+      if (coverers.length === 0) { gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' }); continue; }
+      // A theme WITHOUT `depth:` is visibility/navigation — landing/seeing/leaving IS the
+      // assertion, so mere presence covers it. Only DATA-correctness themes (depth.requires:
+      // data-assertion) need a data assertion to count as deeply covered.
+      const needsDepth = t.depth?.requires === 'data-assertion';
+      if (!needsDepth) { covered++; continue; }
+      if (coverers.some((s) => s.hasDataAssertion)) covered++;
+      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
     }
   }