yam-flow 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to yam-flow are documented here.
 
+## v0.1.6 - 2026-06-07
+
+### Added
+
+- Added the Ueye Design Completion Gate so Ueye can own design/UI/UX completion quality instead of relying on a separate code-risk route to catch unfinished visual work.
+- Added `yam ueye report --completion-claim`, `--strict`, `--design-score`, P0/P1, CTA, state, mobile/responsive, contrast/accessibility, direction, and reference-read gate fields.
+- Added `yam proof --design-completion` so design completion evidence can cap proof truth status when a Ueye done claim is not supported.
+- Added design completion sections to Ueye review and comparison templates.
+
+### Improved
+
+- Ueye `done` claims now cap to partial or blocked when implementation evidence, design quality, P0/P1 status, state coverage, mobile/responsive checks, contrast/accessibility checks, CTA checks, or reference-read/comparison evidence is missing where relevant.
+- Ueye report JSON now includes `design_completion_gate` in both the main run report and comparison report.
+- Expanded CLI smoke coverage for Ueye completion gate success, partial, and blocked paths.
+
+## v0.1.5 - 2026-06-04
+
+### Added
+
+- Added Ueye surface context metadata for provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL, preserved state, and evidence id.
+- Added surface context output to `yam ueye capture`, `yam ueye compare`, and `yam ueye report` so visual evidence can say where and how it was observed.
+- Added provider and execution surface fields to Ueye visual provenance records.
+
+### Improved
+
+- Strengthened `yam ueye report` for fast UI state preservation without making capture or compare an always-on gate.
+- Updated Ueye docs and templates so visual proof can distinguish source files, local screenshots, in-app browser checks, and other execution surfaces.
+
 ## v0.1.4 - 2026-06-03
 
 ### Added

package/COMMANDS.md

@@ -44,7 +44,8 @@ Opt-in visual evidence helpers:
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
 ```
@@ -149,7 +150,8 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json
+yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam runtime evidence --backend terminal --claim observed --evidence-id dev-server-1 --command "npm run dev" --json
 yam mission queue --agent-id implementer --scope "checkout form" --changed src/checkout.tsx --verification-hint "npm run typecheck" --rollback-hint "revert checkout form patch if typecheck or smoke fails" --json

package/README.md

@@ -129,7 +129,8 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
+yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam release report --json
@@ -177,6 +178,8 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime truth matrix
 - visual evidence caps
 - Ueye visual run reports
+- Ueye surface context metadata
+- Ueye design completion gate
 - runtime backend evidence
 - runtime evidence mini summaries
 - mission patch queue lite records
@@ -197,6 +200,8 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Benchmark optimization loop lite: use `yam measure <route>` and `yam template tuning` to record baseline, one route wording change, rerun result, keep/revert decision, and stop condition.
 - Structured diagnostic next action: every doctor/release diagnostic should say what was observed, what evidence supports it, what to do next, owner route, severity, and truth status.
 - Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.
+- Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
+- Ueye design completion gate: `$ueye` can stay fast for draft work, but a `done` claim is capped until implementation evidence, comparison/design-quality status, P0/P1 status, key states, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, and direction/reference-read proof are recorded when relevant.
 
 ## Ueye Capture And Compare
 
@@ -205,14 +210,14 @@ These shapes keep reports machine-readable without turning normal work into a he
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 `capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
 
 `compare` is local-only and dependency-free. It records file hashes, dimensions, comparison result, and proof-ready visual provenance. Exact image matches can be `verified`; different screenshots stay `partial` so visual parity is not overclaimed.
 
-`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, and next action into one compact proof-ready JSON object.
+`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, design completion gate, surface context, and next action into one compact proof-ready JSON object. Draft and needs-polish work can stay fast; `--completion-claim done` turns on the stricter design gate.
 
 Generated media can guide visual direction, but it cannot prove the implemented UI by itself:
 

package/dist/bin/yam.js

@@ -8,7 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { TRUTH_STATUSES, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeVisualProvenance, buildUeyeRunReport, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
+import { TRUTH_STATUSES, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeDesignCompletionGate, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -122,7 +122,7 @@ Usage:
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
-  yam ueye report [--reference ref.png] [--actual screenshot.png] [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--provider-context local] [--execution-surface in-app-browser] [--json]
   yam media proof [--requested] [--attempted] [--output file] [--json]
   yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--json]
   yam mission queue [--agent-id id] [--scope text] [--changed file] [--verification-hint text] [--json]
@@ -808,7 +808,7 @@ function toolsDoctorNextActionDetails({ pack, rows, riskNotes, frameworkChecklis
     if (frameworkChecklist?.detected && !commands?.build && !commands?.typecheck)
         actions.push(nextActionDetail('verification-command', 'warning', 'build/typecheck command not detected', 'add or document a small build/typecheck command for implementation verification', 'yam pack .'));
     if (frameworkChecklist?.uiLike)
-        actions.push(nextActionDetail('ueye-evidence', 'info', 'UI-like project detected', 'for Ueye verified claims, record reference, actual screenshot, and comparison result', 'yam ueye report --reference ref.png --actual shot.png --json'));
+        actions.push(nextActionDetail('ueye-evidence', 'info', 'UI-like project detected', 'for Ueye verified claims, record reference, actual screenshot, comparison result, and surface context', 'yam ueye report --reference ref.png --actual shot.png --provider-context local --execution-surface in-app-browser --json'));
     return uniqueNextActionDetails(actions);
 }
 async function scanSqlFiles(rootDir, { maxFiles = 30, maxBytes = 200000, maxDepth = 5 } = {}) {
@@ -1366,18 +1366,18 @@ Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/c
 Usage:
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
-  yam ueye report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--completion-claim draft|needs-polish|done] [--strict] [--design-score n] [--p0 text] [--p1 text] [--states-checked] [--mobile-checked] [--contrast-checked] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
 
 Notes:
   capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
   compare uses local files only and reports sha256, dimensions, comparison_result, and proof-ready visual provenance.
-  report produces a proof-ready Ueye visual run report and continuity/comparison record without requiring a new capture.
+  report produces a proof-ready Ueye visual run report, design completion gate, and continuity/comparison record without requiring a new capture.
 `);
 }
 async function ueyeCapture(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
-    const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'evidence-id', 'screenshot-id', 'json']));
     const url = String(flags.url || '');
     const out = String(flags.out || '');
     if (!url || !out) {
@@ -1401,6 +1401,24 @@ async function ueyeCapture(args = []) {
         await page.goto(url, { waitUntil, timeout });
         await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
         const info = await imageFileInfo(target);
+        const surfaceContext = buildUeyeSurfaceContext({
+            provider_context: String(flags.provider_context || 'local-playwright'),
+            provider_badge: String(flags.provider_badge || flags.provider_context || 'local-playwright'),
+            execution_surface: String(flags.execution_surface || 'browser-capture'),
+            app_surface: String(flags.app_surface || 'local-project'),
+            browser_surface: String(flags.browser_surface || 'playwright'),
+            control_mode: String(flags.control_mode || 'automated-capture'),
+            route: 'ueye',
+            mode: 'capture',
+            url,
+            viewport: `${viewport.width}x${viewport.height}`,
+            screenshot_id: String(flags.screenshot_id || path.basename(target)),
+            evidence_id: String(flags.evidence_id || `ueye-capture-${timestampId()}`),
+            preserved_state: Boolean(flags.preserved_state),
+            preserved_url: String(flags.preserved_url || url),
+            local_only: true,
+            truth_status: 'verified'
+        });
         const result = {
             schema: 'yam.ueye-capture.v1',
             status: 'verified',
@@ -1410,6 +1428,7 @@ async function ueyeCapture(args = []) {
             full_page: Boolean(flags.full_page),
             sha256: info.sha256,
             dimensions: info.dimensions,
+            surface_context: surfaceContext,
             visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
         };
         printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
@@ -1435,7 +1454,7 @@ async function ueyeCapture(args = []) {
 async function ueyeCompare(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
-    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id']));
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'viewport', 'evidence-id']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     if (!reference || !actual) {
@@ -1455,12 +1474,35 @@ async function ueyeCompare(args = []) {
         const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
         const comparisonResult = exactMatch ? 'matched' : 'different';
         const truthStatus = exactMatch ? 'verified' : 'partial';
+        const surfaceContext = buildUeyeSurfaceContext({
+            provider_context: String(flags.provider_context || 'local-file'),
+            provider_badge: String(flags.provider_badge || flags.provider_context || 'local-file'),
+            execution_surface: String(flags.execution_surface || 'local-file-compare'),
+            app_surface: String(flags.app_surface || 'local-project'),
+            browser_surface: String(flags.browser_surface || 'not-used'),
+            control_mode: String(flags.control_mode || 'local-compare'),
+            route: 'ueye',
+            mode: 'compare',
+            url: String(flags.url || ''),
+            viewport: String(flags.viewport || ''),
+            screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+            evidence_id: String(flags.evidence_id || `ueye-compare-${timestampId()}`),
+            preserved_state: Boolean(flags.preserved_state),
+            preserved_url: String(flags.preserved_url || flags.url || ''),
+            local_only: true,
+            truth_status: truthStatus
+        });
         const provenance = buildUeyeVisualProvenance({
             source_kind: 'implementation_screenshot',
             source_path: actualPath,
             source_hash: actualInfo.sha256,
             reference_id: String(flags.reference_id || path.basename(referencePath)),
             screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+            provider_context: surfaceContext.provider_context,
+            provider_badge: surfaceContext.provider_badge,
+            execution_surface: surfaceContext.execution_surface,
+            app_surface: surfaceContext.app_surface,
+            browser_surface: surfaceContext.browser_surface,
             local_only: true,
             redacted: false,
             operator_provided: false,
@@ -1475,6 +1517,7 @@ async function ueyeCompare(args = []) {
             same_dimensions: sameDimensions,
             reference: referenceInfo,
             actual: actualInfo,
+            surface_context: surfaceContext,
             visual_evidence: `browser/local screenshot comparison executed: reference=${referencePath}, actual=${actualPath}, result=${comparisonResult}`,
             visual_provenance: provenance,
             proof_hint: `yam proof --route ueye --truth ${truthStatus} --visual "browser/local screenshot comparison executed: ${comparisonResult}" --visual-provenance '${JSON.stringify(provenance)}' --require-visual`
@@ -1496,7 +1539,7 @@ async function ueyeCompare(args = []) {
 async function ueyeReport(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
-    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'completion-claim', 'completion-status', 'gate-mode', 'strict', 'design-score', 'min-design-score', 'p0', 'p1', 'open-p0', 'open-p1', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'comparison-result', 'json']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     const referenceSources = [];
@@ -1505,6 +1548,24 @@ async function ueyeReport(args = []) {
     let blockedReason = String(flags.blocked_reason || '');
     const reviewSessionId = String(flags.review_session_id || `ueye-${timestampId()}`);
     const previousReport = await readPreviousUeyeReport(flags.previous_report);
+    const surfaceContext = buildUeyeSurfaceContext({
+        provider_context: String(flags.provider_context || 'not-recorded'),
+        provider_badge: String(flags.provider_badge || flags.provider_context || 'not-recorded'),
+        execution_surface: String(flags.execution_surface || flags.capture_backend || 'not-recorded'),
+        app_surface: String(flags.app_surface || 'not-recorded'),
+        browser_surface: String(flags.browser_surface || flags.capture_backend || 'not-recorded'),
+        control_mode: String(flags.control_mode || 'not-recorded'),
+        route: 'ueye',
+        mode: 'report',
+        url: String(flags.url || flags.preserved_url || ''),
+        viewport: String(flags.viewport || ''),
+        screenshot_id: String(flags.current_screenshot_id || flags.screenshot_id || ''),
+        evidence_id: String(flags.evidence_id || reviewSessionId),
+        preserved_state: Boolean(flags.preserved_state),
+        preserved_url: String(flags.preserved_url || flags.url || ''),
+        local_only: true,
+        truth_status: actual ? 'partial' : 'assumed'
+    });
     try {
         if (reference) {
             const info = await imageFileInfo(reference);
@@ -1513,6 +1574,11 @@ async function ueyeReport(args = []) {
                 source_path: info.path,
                 source_hash: info.sha256,
                 reference_id: String(flags.reference_id || path.basename(info.path)),
+                provider_context: surfaceContext.provider_context,
+                provider_badge: surfaceContext.provider_badge,
+                execution_surface: surfaceContext.execution_surface,
+                app_surface: surfaceContext.app_surface,
+                browser_surface: surfaceContext.browser_surface,
                 local_only: true,
                 operator_provided: true,
                 comparison_result: 'reference-recorded',
@@ -1527,13 +1593,21 @@ async function ueyeReport(args = []) {
                 source_hash: info.sha256,
                 reference_id: String(flags.reference_id || referenceSources[0]?.reference_id || ''),
                 screenshot_id: String(flags.current_screenshot_id || flags.screenshot_id || path.basename(info.path)),
+                provider_context: surfaceContext.provider_context,
+                provider_badge: surfaceContext.provider_badge,
+                execution_surface: surfaceContext.execution_surface,
+                app_surface: surfaceContext.app_surface,
+                browser_surface: surfaceContext.browser_surface,
                 local_only: true,
                 operator_provided: false,
                 comparison_result: 'implementation-recorded',
                 truth_status: 'partial'
             }));
         }
-        if (reference && actual && referenceSources[0]?.source_hash === implementationSources[0]?.source_hash) {
+        if (flags.comparison_result) {
+            comparisonResult = normalizeUeyeComparisonResult(flags.comparison_result);
+        }
+        else if (reference && actual && referenceSources[0]?.source_hash === implementationSources[0]?.source_hash) {
             comparisonResult = 'matched';
         }
         else if (reference && actual) {
@@ -1546,8 +1620,29 @@ async function ueyeReport(args = []) {
     const report = buildUeyeRunReport({
         reference_sources: referenceSources,
         implementation_sources: implementationSources,
+        surface_context: {
+            ...surfaceContext,
+            screenshot_id: surfaceContext.screenshot_id || String(flags.current_screenshot_id || flags.screenshot_id || implementationSources[0]?.screenshot_id || ''),
+            truth_status: blockedReason ? 'blocked' : implementationSources.length ? 'partial' : 'assumed'
+        },
         comparison_result: comparisonResult,
         design_quality: String(flags.design_quality || 'not-checked'),
+        design_completion_gate: {
+            mode: flags.strict || flags.gate_mode === 'strict' ? 'strict' : 'fast',
+            completion_claim: flags.completion_claim || flags.completion_status || 'draft',
+            design_score: numberOrNull(flags.design_score),
+            min_design_score: numberOrNull(flags.min_design_score) ?? 8,
+            p0: [...arrayFlag(flags.p0), ...arrayFlag(flags.open_p0)],
+            p1: [...arrayFlag(flags.p1), ...arrayFlag(flags.open_p1)],
+            states_checked: Boolean(flags.states_checked),
+            mobile_checked: Boolean(flags.mobile_checked),
+            responsive_checked: Boolean(flags.responsive_checked),
+            contrast_checked: Boolean(flags.contrast_checked),
+            accessibility_checked: Boolean(flags.accessibility_checked),
+            cta_checked: Boolean(flags.cta_checked),
+            direction_locked: Boolean(flags.direction_locked),
+            reference_read: Boolean(flags.reference_read)
+        },
         blocked_reason: blockedReason,
         next_action: String(flags.next_visual_action || flags.next_action || '')
     });
@@ -1556,6 +1651,8 @@ async function ueyeReport(args = []) {
         previousReport,
         referenceSources,
         implementationSources,
+        surfaceContext: report.surface_context,
+        designCompletionGate: report.design_completion_gate,
         comparisonResult,
         designQuality: String(flags.design_quality || 'not-checked'),
         similar: arrayFlag(flags.similar),
@@ -1609,7 +1706,7 @@ async function readPreviousUeyeReport(file = '') {
         };
     }
 }
-function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, comparisonResult, designQuality, similar, different, missing, notes, resolved, newFindings, stillOpen, regressions, previousScreenshotId, currentScreenshotId, viewport, state, nextAction, truthStatus }) {
+function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, surfaceContext, designCompletionGate, comparisonResult, designQuality, similar, different, missing, notes, resolved, newFindings, stillOpen, regressions, previousScreenshotId, currentScreenshotId, viewport, state, nextAction, truthStatus }) {
     const hasReference = referenceSources.length > 0;
     const hasImplementation = implementationSources.length > 0;
     const continuityTruth = previousReport?.blocked_reason ? 'blocked' : previousReport ? 'partial' : 'assumed';
@@ -1633,6 +1730,8 @@ function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceS
             reference_count: referenceSources.length,
             implementation_count: implementationSources.length
         },
+        surface_context: surfaceContext || buildUeyeSurfaceContext(),
+        design_completion_gate: designCompletionGate || null,
         comparison_result: comparisonResult,
         design_quality: designQuality,
         similar,
@@ -1651,6 +1750,12 @@ function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceS
         truth_status: truthStatus
     };
 }
+function normalizeUeyeComparisonResult(value = '') {
+    const text = String(value || '').toLowerCase();
+    if (['matched', 'similar', 'different', 'not-verified', 'not-applicable'].includes(text))
+        return text;
+    return 'not-verified';
+}
 async function media(args = []) {
     const subcommand = args[0] || 'help';
     if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
@@ -1948,7 +2053,7 @@ function parseSimpleFlags(args = [], allowed = new Set()) {
         if (allowed.size && !allowed.has(key))
             continue;
         const normalizedKey = key.replace(/-/g, '_');
-        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked'].includes(key)) {
+        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read'].includes(key)) {
             flags[normalizedKey] = true;
             continue;
         }
@@ -2105,6 +2210,7 @@ async function proof(args = []) {
     printProofList('Mission patch envelope', summary.missionEnvelope || []);
     printProofList('Rollback hint', summary.rollbackHint || []);
     printProofList('Media proof', summary.mediaProof || []);
+    printProofList('Design completion', summary.designCompletion || []);
     printProofList('Changed surfaces', summary.changed);
     printProofList('Skipped', summary.skipped);
     printProofList('Blocked', summary.blocked);
@@ -2201,6 +2307,10 @@ function buildProofSummary(parsed, artifact) {
             ...structuredEvidenceList(artifact.mediaProof),
             ...structuredEvidenceList(parsed.flags.media_proof)
         ],
+        designCompletion: [
+            ...structuredEvidenceList(artifact.designCompletion),
+            ...structuredEvidenceList(parsed.flags.design_completion)
+        ],
         cleanup: parsed.flags.cleanup || artifact.cleanup || '',
         changed: [...artifact.changed, ...arrayFlag(parsed.flags.changed)],
         skipped: [...artifact.skipped, ...arrayFlag(parsed.flags.skipped)],
@@ -2265,6 +2375,9 @@ function renderProofMarkdown(summary) {
         '## Media proof',
         ...renderProofMarkdownList(summary.mediaProof || []),
         '',
+        '## Design completion',
+        ...renderProofMarkdownList(summary.designCompletion || []),
+        '',
         '## Changed surfaces',
         ...renderProofMarkdownList(summary.changed),
         '',
@@ -2295,7 +2408,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
     const flags = {};
     const positionals = [];
-    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'runtime-backend', 'runtime-claim', 'runtime-evidence-id', 'runtime-command', 'cleanup-checked', 'runtime-note', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
+    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'runtime-backend', 'runtime-claim', 'runtime-evidence-id', 'runtime-command', 'cleanup-checked', 'runtime-note', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'design-completion', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg.startsWith('--')) {
@@ -2311,7 +2424,7 @@ function parseProofArgs(args = []) {
             const value = inlineValue ?? args[index + 1] ?? '';
             if (inlineValue === undefined)
                 index += 1;
-            if (['command', 'evidence', 'visual', 'runtime', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
+            if (['command', 'evidence', 'visual', 'runtime', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'design-completion', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
                 flags[normalizedKey] = [...arrayFlag(flags[normalizedKey]), value];
             }
             else {
@@ -2355,6 +2468,7 @@ function emptyProofArtifact() {
         missionEnvelope: [],
         rollbackHint: [],
         mediaProof: [],
+        designCompletion: [],
         cleanup: '',
         changed: [],
         skipped: [],
@@ -2381,6 +2495,7 @@ async function parseProofJson(file, empty) {
             missionEnvelope: structuredEvidenceList(data.missionEnvelope || data.mission_envelope),
             rollbackHint: structuredEvidenceList(data.rollbackHint || data.rollback_hint),
             mediaProof: structuredEvidenceList(data.mediaProof || data.media_proof),
+            designCompletion: structuredEvidenceList(data.designCompletion || data.design_completion),
             cleanup: String(data.cleanup || data.cleanupStatus || ''),
             changed: arrayFlag(data.changed || data.files),
             skipped: arrayFlag(data.skipped),
@@ -2411,6 +2526,7 @@ async function parseProofMarkdown(file, empty) {
         missionEnvelope: readProofList(text, 'Mission patch envelope'),
         rollbackHint: readProofList(text, 'Rollback hint'),
         mediaProof: readProofList(text, 'Media proof'),
+        designCompletion: readProofList(text, 'Design completion'),
         cleanup: readProofField(text, 'Cleanup') || readProofField(text, 'Cleanup status'),
         changed: firstProofList(text, ['Changed surfaces', 'Files']),
         skipped: readProofList(text, 'Skipped'),
@@ -2497,6 +2613,9 @@ function formatStructuredEvidence(value) {
         if (data.schema === 'yam.media-generation-proof.v1' || data.generation_requested || data.output_hash) {
             return JSON.stringify(buildMediaGenerationProof(data));
         }
+        if (data.schema === 'yam.ueye-design-completion-gate.v1' || data.completion_claim || data.ready_to_claim_done !== undefined) {
+            return JSON.stringify(buildUeyeDesignCompletionGate(data));
+        }
         return JSON.stringify(data);
     }
     catch {
@@ -2505,7 +2624,7 @@ function formatStructuredEvidence(value) {
 }
 function hasProofEvidence(parsed) {
     const flags = parsed.flags || {};
-    return ['command', 'evidence', 'visual', 'runtime', 'runtime_backend_evidence', 'visual_provenance', 'mission_envelope', 'rollback_hint', 'media_proof', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup || flags.runtime_backend || flags.runtime_claim);
+    return ['command', 'evidence', 'visual', 'runtime', 'runtime_backend_evidence', 'visual_provenance', 'mission_envelope', 'rollback_hint', 'media_proof', 'design_completion', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup || flags.runtime_backend || flags.runtime_claim);
 }
 function printProofList(label, values) {
     console.log(`- ${label}:`);

package/dist/lib/trust-kernel.d.ts

@@ -38,12 +38,58 @@ export interface UeyeVisualProvenance {
     source_hash: string;
     reference_id: string;
     screenshot_id: string;
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
     local_only: boolean;
     redacted: boolean;
     operator_provided: boolean;
     comparison_result: string;
     truth_status: TruthStatus;
 }
+export interface UeyeSurfaceContext {
+    schema: 'yam.ueye-surface-context.v1';
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
+    control_mode: string;
+    route: string;
+    mode: string;
+    url: string;
+    viewport: string;
+    screenshot_id: string;
+    evidence_id: string;
+    preserved_state: boolean;
+    preserved_url: string;
+    local_only: boolean;
+    truth_status: TruthStatus;
+}
+export interface UeyeDesignGateCheck {
+    id: string;
+    label: string;
+    status: 'pass' | 'fail' | 'warning' | 'not_checked';
+    required: boolean;
+    next_action: string;
+}
+export interface UeyeDesignCompletionGate {
+    schema: 'yam.ueye-design-completion-gate.v1';
+    mode: 'fast' | 'strict';
+    completion_claim: 'draft' | 'needs-polish' | 'done';
+    ready_to_claim_done: boolean;
+    design_score: number | null;
+    min_design_score: number;
+    checks: UeyeDesignGateCheck[];
+    p0: string[];
+    p1: string[];
+    warnings: string[];
+    blockers: string[];
+    next_action: string;
+    truth_status: TruthStatus;
+}
 export interface RollbackHint {
     schema: 'yam.rollback-hint.v1';
     touched_files: string[];
@@ -74,12 +120,17 @@ export interface UeyeRunReport {
     schema: 'yam.ueye-run-report.v1';
     reference_sources: UeyeVisualProvenance[];
     implementation_sources: UeyeVisualProvenance[];
+    surface_context: UeyeSurfaceContext;
+    design_completion_gate: UeyeDesignCompletionGate;
     comparison_result: string;
     design_quality: string;
     blocked_reason: string;
     next_action: string;
     truth_status: TruthStatus;
 }
+export interface UeyeRunReportInput extends Partial<Omit<UeyeRunReport, 'design_completion_gate'>> {
+    design_completion_gate?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>;
+}
 export interface MediaGenerationProof {
     schema: 'yam.media-generation-proof.v1';
     tool_name: string;
@@ -120,6 +171,7 @@ export interface ProofSummary {
     rollbackHint?: unknown;
     runtimeBackendEvidence?: unknown;
     mediaProof?: unknown;
+    designCompletion?: unknown;
 }
 export interface ProofOptions {
     requireRealRuntime?: boolean;
@@ -152,6 +204,7 @@ export interface YamCompletionProof {
     rollbackHint: string[];
     runtimeBackendEvidence: string[];
     mediaProof: string[];
+    designCompletion: string[];
     cleanup: unknown;
     changed: string[];
     skipped: string[];
@@ -164,10 +217,12 @@ export interface YamCompletionProof {
     runtimeTruth: RuntimeTruthMatrix;
 }
 export declare function buildUeyeVisualProvenance(input?: Partial<UeyeVisualProvenance>): UeyeVisualProvenance;
+export declare function buildUeyeSurfaceContext(input?: Partial<UeyeSurfaceContext>): UeyeSurfaceContext;
+export declare function buildUeyeDesignCompletionGate(input?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>): UeyeDesignCompletionGate;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;
-export declare function buildUeyeRunReport(input?: Partial<UeyeRunReport>): UeyeRunReport;
+export declare function buildUeyeRunReport(input?: UeyeRunReportInput): UeyeRunReport;
 export declare function buildMediaGenerationProof(input?: Partial<MediaGenerationProof>): MediaGenerationProof;
 export declare function isTruthStatus(value?: unknown): value is TruthStatus;
 export declare function weakestTruth(...statuses: unknown[]): TruthStatus;