@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.1

package/src/graph/unit-artifact-probes.ts

@@ -0,0 +1,77 @@
+/**
+ * What a unit holds on disk, probed cheaply for `readUnitState` and `testCaseStates` (moved out of
+ * harness/next-step.ts unchanged). Every path here is legitimately absent at some point in a unit's
+ * life — the resolver exists to report exactly that — so nothing throws on a missing file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { featureFilesFor } from '../harness/unit-paths';
+import { readTextFile } from '../harness/read-text';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+
+/** `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env run the env (#868). */
+export const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
+
+export const readIfExists = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
+
+export function countScenarios(unitDir: string, unit: string): number {
+  let n = 0;
+  for (const f of featureFilesFor(unitDir, unit)) {
+    n += (readIfExists(f).match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
+  }
+  return n;
+}
+
+/**
+ * Does the selector text resolve at least one element? A scaffold resolves none: the web one holds
+ * only the `page` route, the mobile one only header comments. Matching the WORD "placeholder" was
+ * wrong both ways (#868): it flagged a real file whose key names an input's placeholder text, and
+ * missed both scaffolds, which never contain it.
+ */
+export function hasResolvedSelector(selectorText: string): boolean {
+  let doc: unknown;
+  try { doc = parseYaml(selectorText); } catch { return selectorText.trim().length >= 40; }
+  if (!doc || typeof doc !== 'object') return false;
+  // A real cell, not a marker left to be filled in. Numbers count (an id or index can be numeric).
+  const real = (v: unknown): boolean => (typeof v === 'string' || typeof v === 'number')
+    && String(v).trim() !== '' && !/^(?:todo|tbd|placeholder|replace me)$/i.test(String(v).trim());
+  return Object.values(doc as Record<string, unknown>).some((e) => {
+    if (!e || typeof e !== 'object') return false;
+    const { type, value, name, locator } = e as { type?: unknown; value?: unknown; name?: unknown; locator?: unknown };
+    // Every SelectorEntry shape: a CSS `locator`, or a non-page `type` with a value or a role name.
+    return real(locator) || (typeof type === 'string' && type !== 'page' && (real(value) || real(name)));
+  });
+}
+
+/** Where a unit's compiled spec and result files live. */
+export function generatedDirs(projectRoot: string, unit: string): string[] {
+  return [
+    path.join(projectRoot, 'specs', 'generated', 'flows', unit),
+    path.join(projectRoot, 'specs', 'generated', unit),
+  ];
+}
+
+export function isCompiled(projectRoot: string, unit: string): boolean {
+  return generatedDirs(projectRoot, unit).some((d) => {
+    try { return fs.readdirSync(d).some((f) => f.endsWith('.spec.ts')); } catch { return false; }
+  });
+}
+
+export function unitResultFiles(projectRoot: string, unit: string): string[] {
+  return generatedDirs(projectRoot, unit).flatMap((d) => {
+    try { return fs.readdirSync(d).filter((f) => RESULT_FILE.test(f)).map((f) => path.join(d, f)); } catch { return []; }
+  });
+}
+
+/** Final attempts that failed across the result files. An unreadable report counts nothing: "unknown" is never red. */
+export function countFailedResults(resultFiles: string[]): number {
+  return resultFiles.reduce((n, f) => n + [...(loadPlaywrightReport(f)?.values() ?? [])]
+    .filter((r) => r.status === 'failed' || r.status === 'timedOut' || r.status === 'interrupted').length, 0);
+}
+
+export function hasDeliverableFor(projectRoot: string, slug: string): boolean {
+  try {
+    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`));
+  } catch { return false; }                                    // nothing exported yet
+}

package/src/graph/unit-state-facts.ts

@@ -0,0 +1,112 @@
+/**
+ * The facts `readUnitState` adds for the graph's newer nodes — read through the same code the gate,
+ * the delivery and the Claude Code guard use, so `next` cannot disagree with them (red-team #12):
+ *
+ *   readTrustedAudit     audit.json through verifyAuditReport (OES-11.4, DOS-14.0): a stale, invalid
+ *                        or verdict-mismatched report counts as never audited, and says why
+ *   readContractFacts    the contract verdict rebuilt by buildContractVerdict (DOS-14.4) — the
+ *                        function `sungen contract check` and the delivery guard run — as the unit
+ *                        summary plus each case's class (phase 09: the test-case contract nodes)
+ */
+import { buildContractVerdict, ContractVerdict } from '../contract/build-contract-verdict';
+import { LOW_IDENTITY_FINDING } from '../contract/classify-trace-conformance';
+import { GUARD_GIT_TIMEOUT_MS, HeadSnapshot, headSnapshot, posixRel } from '../contract/contract-git';
+import { HARD_CLASSES } from '../contract/contract-schema';
+import { lockPathFor } from '../contract/contracts-lock-file';
+import type { UncommittedEntry } from '../contract/lock-vs-git-head';
+import { auditCounts, verifyAuditReport } from '../harness/gates/audit-report-verification';
+import type { TestCaseContract } from './test-case-state-shape';
+
+/** A report exists but does not count — `next` says "re-audit" exactly as gate and delivery block. */
+export interface AuditNotCounted { state: 'stale' | 'invalid'; reason: string }
+
+export interface ContractSummary {
+  verdict: 'pass' | 'review' | 'fail';
+  /** Scenarios with no approved lock entry (never block). */
+  proposed: number;
+  /** Approved scenarios changed, not weaker (`contract.hash-changed`) — review blocks delivery. */
+  review: number;
+  /** Approved scenarios that got weaker, changed target or lost a check (not `unproven`: no trace is no edit to undo). */
+  hard: number;
+  /** Approved free / impl:code scenarios no admissible trace proves (contract.unproven, hard) — a traced run, not a QA call. */
+  unproven?: number;
+  /** Approved free / impl:code scenarios whose trace is in review: opaque (incl. a low identity) or inconclusive. */
+  traceReview?: number;
+  /** Lock entries that are not what QA approved and committed (`contract.lock-uncommitted`). */
+  uncommitted: number;
+  /**
+   * What is wrong with them, the one to fix first: `tampered` (an entry no longer hashes to its steps),
+   * `untracked` (the lock was never committed), `edited` (a committed lock with uncommitted edits),
+   * `unverified` (no committed contract-approval decision vouches for an entry).
+   */
+  uncommittedKind?: 'tampered' | 'untracked' | 'edited' | 'unverified';
+  /** The first hard scenario, `<id> <class>`. */
+  headline?: string;
+  /** Set when the verdict could not be built (git unavailable with a lock, unreadable lock or feature). */
+  error?: string;
+}
+
+const message = (e: unknown): string => (e instanceof Error ? e.message : String(e)).split('\n')[0];
+
+export function readTrustedAudit(projectRoot: string, unit: string): { report: Record<string, unknown> | null; notCounted?: AuditNotCounted } {
+  try {
+    const v = verifyAuditReport(projectRoot, unit);
+    if (auditCounts(v)) return { report: v.report };
+    if (v.state === 'absent') return { report: null };
+    const reason = v.problems.map((p) => p.message).join('; ') || v.state;
+    return { report: null, notCounted: { state: v.state === 'stale' ? 'stale' : 'invalid', reason } };
+  } catch (e) {
+    return { report: null, notCounted: { state: 'invalid', reason: `the report could not be verified: ${message(e)}` } };
+  }
+}
+
+function uncommittedKindOf(entries: UncommittedEntry[], lockInHead: boolean): ContractSummary['uncommittedKind'] {
+  if (!entries.length) return undefined;
+  if (entries.some((e) => e.change === 'tampered')) return 'tampered';
+  if (entries.some((e) => e.change !== 'unverified')) return lockInHead ? 'edited' : 'untracked';
+  return 'unverified';
+}
+
+/** scenario id → its class, the finding behind it, and whether a low identity or an uncommitted lock entry is behind it. */
+function caseContracts(v: ContractVerdict): Map<string, TestCaseContract> {
+  const out = new Map<string, TestCaseContract>();
+  for (const s of v.scenarios) {
+    const lead = s.findings.find((f) => f.class === s.class) ?? s.findings[0];
+    out.set(s.id, {
+      class: s.class,
+      ...(lead ? { detail: lead.detail } : {}),
+      ...(s.findings.some((f) => f.class === 'opaque' && f.detail.startsWith(LOW_IDENTITY_FINDING)) ? { lowIdentity: true as const } : {}),
+    });
+  }
+  for (const u of v.uncommitted) out.set(u.id, { ...(out.get(u.id) ?? { class: 'match' }), uncommitted: true });
+  return out;
+}
+
+export interface ContractFacts { summary: ContractSummary; cases: Map<string, TestCaseContract> }
+
+export function readContractFacts(projectRoot: string, unit: string, unitDir: string, snapshot?: HeadSnapshot): ContractFacts {
+  try {
+    const snap = snapshot ?? headSnapshot(projectRoot, GUARD_GIT_TIMEOUT_MS);
+    const v = buildContractVerdict(projectRoot, { name: unit, dir: unitDir }, { snapshot: snap });
+    const count = (...classes: string[]): number => v.scenarios.filter((s) => classes.includes(s.class)).length;
+    const hard = v.scenarios.filter((s) => HARD_CLASSES.has(s.class) && s.class !== 'unproven');
+    const kind = uncommittedKindOf(v.uncommitted, Boolean(snap.blobs?.has(posixRel(projectRoot, lockPathFor(unitDir)))));
+    const summary: ContractSummary = {
+      verdict: v.verdict,
+      proposed: count('proposed'),
+      review: count('hash-changed'),
+      hard: hard.length,
+      uncommitted: v.uncommitted.length,
+      unproven: count('unproven'),
+      traceReview: count('opaque', 'inconclusive'),
+      ...(kind ? { uncommittedKind: kind } : {}),
+      ...(hard[0] ? { headline: `${hard[0].id} ${hard[0].class}` } : {}),
+    };
+    return { summary, cases: caseContracts(v) };
+  } catch (e) {
+    return { summary: { verdict: 'fail', proposed: 0, review: 0, hard: 0, uncommitted: 0, error: message(e) }, cases: new Map() };
+  }
+}
+
+export const readContractSummary = (projectRoot: string, unit: string, unitDir: string, snapshot?: HeadSnapshot): ContractSummary =>
+  readContractFacts(projectRoot, unit, unitDir, snapshot).summary;

package/src/harness/audit.ts

@@ -34,6 +34,9 @@ import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
 import { readTextFile, readViewpointText } from './read-text';
 import { uiInventoryCoverage, uiInventoryFindings, UiInventoryResult } from './ui-inventory';
+import { defectLinkFindings } from './defects';
+import { auditGateContext, auditGateVerdict, decisionFindings, relevelProvidedDepth } from './gates/audit-gate-verdict';
+import { GateOverrideReport } from './gates/gate-override-report';
 
 export interface AuditReport {
   screen: string;
@@ -97,6 +100,16 @@ export interface AuditReport {
   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)
+  /** OES-11.6 — every gate-override touching this unit (applied / ineffective / rejected). */
+  gateOverrides: GateOverrideReport[];
+  /** OES-11.4 — the decisions this audit was judged under; readers re-audit when it moves. */
+  decisionsHash: string;
+  /** T3 — hash of .feature + spec + viewpoint + decisionsHash; a reader recomputes it. */
+  inputsHash: string;
+  /** T3 — what `sungen audit` exits with for this gateStatus (0 PASS · 2 FAIL). */
+  exitCode: number;
+  /** A capability gate sensor reported an error-level finding — recorded so a reader can re-evaluate the gate. */
+  gateSensorError: boolean;
 }
 
 /**
@@ -168,6 +181,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // `flows/<flow>`, `api/<area>`, `api/flows/<flow>`, else the bare screen. A bare screen matches
   // the old behaviour (so the audit-sample snapshot is unchanged); flows/api now resolve correctly.
   const catalogScreenName = catalogIdFromScreenDir(screenDir);
+  // OES-11.2 — the unit's gate rules: the catalog plus the gate-overrides in force for it.
+  const gates = auditGateContext(screenDir);
 
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
   const featureText = readUnitFeatureText(screenDir, screenName);
@@ -215,10 +230,16 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     ? { ...catalog, page_types: {} } as Catalog
     : catalog;
   const capGate = scoringCap?.gateProvider as
-    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
-  const provided = capGate?.({ scenarios, viewpoints, catalog: gateCatalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, gateCatalog, platform === 'mobile', viewpointText);
-  const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(gateCatalog, gate.pageType), intent.focus);
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[]; isMobile: boolean; viewpointText: string }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  // The capability gate gets the SAME isMobile + viewpoint text as the in-core fallback, or a declared
+  // `page-type:` is ignored wherever driver-ui scores — every web project, and a mobile project whose
+  // CLI cannot resolve driver-mobile (#864).
+  const isMobile = platform === 'mobile';
+  const provided = capGate?.({ scenarios, viewpoints, catalog: gateCatalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods, isMobile, viewpointText });
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, gateCatalog, isMobile, viewpointText);
+  const depth = provided?.depth
+    ? relevelProvidedDepth(provided.depth, gates.rules)
+    : assertionDepth(scenarios, dataThemesFor(gateCatalog, gate.pageType), intent.focus, gates.rules);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
   // filter correctness) belongs in a FLOW, not on the screen. When a flow deeply covers a screen
@@ -241,7 +262,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       gate.coverageRatio = gate.themesTotal ? gate.themesCovered / gate.themesTotal : 1;
     }
   }
-  const claim = claimProof(scenarios, intent.focus);
+  const claim = claimProof(scenarios, intent.focus, gates.rules);
   const taxonomy = taxonomyLint(scenarios);
   const balance = coverageBalance(scenarios);
   const duplicates = duplicateClusters(scenarios);
@@ -618,9 +639,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #414 — serial-cascade masking: an @serial suite of independent (re-navigating) scenarios hides
   // failures, because Playwright's describe.serial SKIPS everything after the first red. Isolation is
   // the default, so this only fires when @serial was added to a suite that didn't need it.
-  const cascadeN = serialCascadeRisk(featureText, scenarios.length);
-  if (cascadeN) {
-    findings.push(`SERIAL-CASCADE-RISK: this \`@serial\` suite has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
+  // `@serial` is a property of ONE feature file — only that file compiles to `describe.serial` — so
+  // each file is judged on its own text and its own scenarios. The unit-wide text paired one
+  // feature's @serial with another's navigating Background and counted every scenario of the unit,
+  // telling QA to drop @serial from a genuinely ordered 2-scenario feature (#887).
+  for (const file of featureFiles.filter((f) => fs.existsSync(f))) {
+    const cascadeN = serialCascadeRisk(readTextFile(file), scenarios.filter((s) => s.sourceFile === file).length);
+    if (cascadeN) {
+      findings.push(`SERIAL-CASCADE-RISK: the \`@serial\` suite ${path.basename(file)} has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
+    }
   }
   if (flowDepth.stateful && flowDepth.missing.length) {
     // The advice names the collection the CONTRACT declared. It used to say "the cart" whatever
@@ -647,6 +674,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const m of taxonomy.mislabeled) {
     findings.push(`VP-MISLABEL: "${m.name}" is coded VP-${m.current} but reads as ${m.suggested} (signal: "${m.signal}") → re-tag VP-${m.suggested}-NNN so the coverage matrix isn't skewed.`);
   }
+  // Scenario ↔ defect record links (qa/defects/) — advisory, never scored.
+  findings.push(...defectLinkFindings(projectRootFromScreenDir(screenDir), catalogScreenName, featureText, scenarios.map((sc) => sc.name)));
   if (balance.unclassifiedRatio > 0.4) {
     findings.push(`TAXONOMY-UNCLASSIFIED: ${balance.note} → align the VP-<CATEGORY> codes with the catalog (or extend the bucket keywords) so coverage-balance is meaningful.`);
   } else if (balance.imbalanced && !flowScored) {
@@ -899,9 +928,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // taxonomy-match (scenarios must use the project's viewpoint IDs when defined),
   // AND scenario-id uniqueness — a reused id reaches the customer's deliverable as two rows
   // under one testcase id, and has already shipped a never-executed testcase as "Passed" (#694).
-  const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch && !gateSensorError
-    && reusedIds.length === 0 ? 'PASS' : 'FAIL';
+  // The conjunction lives in gates/audit-gate-terms.ts, where the report reader re-evaluates it (OES-11.2).
+  findings.push(...decisionFindings(gates));
+  const verdict = auditGateVerdict(gates, { gate, depth, claim, spec, taxonomyMismatch, gateSensorError, reusedScenarioIds: reusedIds }, screenDir, screenName);
+  const gateStatus = verdict.gateStatus;
 
   return {
     screen: screenName,
@@ -933,5 +963,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings,
     intent,
     provenance: getProvenance(),
+    gateOverrides: verdict.gateOverrides,
+    decisionsHash: verdict.decisionsHash,
+    inputsHash: verdict.inputsHash,
+    exitCode: verdict.exitCode,
+    gateSensorError,
   };
 }