yam-flow 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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

package/COMMANDS.md

@@ -45,6 +45,7 @@ Opt-in visual evidence helpers:
 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 --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
 ```
@@ -150,6 +151,7 @@ yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"refe
 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 --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 --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --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
@@ -178,6 +179,7 @@ Publishing still requires confirming the final npm package name and account acce
 - 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
@@ -199,6 +201,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 - 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
 
@@ -207,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 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --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, surface context, 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, buildUeyeSurfaceContext, 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);
 }
@@ -1366,12 +1366,12 @@ 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] [--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] [--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 = []) {
@@ -1539,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', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', '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 = [];
@@ -1604,7 +1604,10 @@ async function ueyeReport(args = []) {
                 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) {
@@ -1624,6 +1627,22 @@ async function ueyeReport(args = []) {
         },
         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 || '')
     });
@@ -1633,6 +1652,7 @@ async function ueyeReport(args = []) {
         referenceSources,
         implementationSources,
         surfaceContext: report.surface_context,
+        designCompletionGate: report.design_completion_gate,
         comparisonResult,
         designQuality: String(flags.design_quality || 'not-checked'),
         similar: arrayFlag(flags.similar),
@@ -1686,7 +1706,7 @@ async function readPreviousUeyeReport(file = '') {
         };
     }
 }
-function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceSources, implementationSources, surfaceContext, 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';
@@ -1711,6 +1731,7 @@ function buildUeyeComparisonReport({ reviewSessionId, previousReport, referenceS
             implementation_count: implementationSources.length
         },
         surface_context: surfaceContext || buildUeyeSurfaceContext(),
+        design_completion_gate: designCompletionGate || null,
         comparison_result: comparisonResult,
         design_quality: designQuality,
         similar,
@@ -1729,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')
@@ -2026,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;
         }
@@ -2183,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);
@@ -2279,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)],
@@ -2343,6 +2375,9 @@ function renderProofMarkdown(summary) {
         '## Media proof',
         ...renderProofMarkdownList(summary.mediaProof || []),
         '',
+        '## Design completion',
+        ...renderProofMarkdownList(summary.designCompletion || []),
+        '',
         '## Changed surfaces',
         ...renderProofMarkdownList(summary.changed),
         '',
@@ -2373,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('--')) {
@@ -2389,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 {
@@ -2433,6 +2468,7 @@ function emptyProofArtifact() {
         missionEnvelope: [],
         rollbackHint: [],
         mediaProof: [],
+        designCompletion: [],
         cleanup: '',
         changed: [],
         skipped: [],
@@ -2459,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),
@@ -2489,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'),
@@ -2575,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 {
@@ -2583,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

@@ -68,6 +68,28 @@ export interface UeyeSurfaceContext {
     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[];
@@ -99,12 +121,16 @@ export interface UeyeRunReport {
     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;
@@ -145,6 +171,7 @@ export interface ProofSummary {
     rollbackHint?: unknown;
     runtimeBackendEvidence?: unknown;
     mediaProof?: unknown;
+    designCompletion?: unknown;
 }
 export interface ProofOptions {
     requireRealRuntime?: boolean;
@@ -177,6 +204,7 @@ export interface YamCompletionProof {
     rollbackHint: string[];
     runtimeBackendEvidence: string[];
     mediaProof: string[];
+    designCompletion: string[];
     cleanup: unknown;
     changed: string[];
     skipped: string[];
@@ -190,10 +218,11 @@ export interface YamCompletionProof {
 }
 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;

package/dist/lib/trust-kernel.js

@@ -52,6 +52,93 @@ export function buildUeyeSurfaceContext(input = {}) {
         truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
     };
 }
+export function buildUeyeDesignCompletionGate(input = {}) {
+    const completionClaim = normalizeUeyeCompletionClaim(input.completion_claim);
+    const mode = String(input.mode || '').toLowerCase() === 'strict' || completionClaim === 'done' ? 'strict' : 'fast';
+    const designScore = numberOrNull(input.design_score);
+    const minDesignScore = numberOrNull(input.min_design_score) ?? 8;
+    const p0 = asList(input.p0);
+    const p1 = asList(input.p1);
+    const hasReference = Boolean(input.has_reference);
+    const hasImplementation = Boolean(input.has_implementation_screenshot);
+    const comparisonResult = String(input.comparison_result || 'not-verified');
+    const designQuality = String(input.design_quality || 'not-checked');
+    const blockedReason = String(input.blocked_reason || '');
+    const strictOrDone = mode === 'strict' || completionClaim === 'done';
+    const checks = [
+        designGateCheck('direction_lock', 'Design direction and target screen were locked before judging completion', Boolean(input.direction_locked) ? 'pass' : 'not_checked', strictOrDone, 'record the target screen and design direction before claiming done'),
+        designGateCheck('reference_read', 'Reference read proof exists when reference is used', !hasReference ? 'not_checked' : Boolean(input.reference_read) ? 'pass' : 'fail', hasReference && strictOrDone, 'record concrete reference observations before claiming reference-led work is done'),
+        designGateCheck('implementation_screenshot', 'Real implementation screenshot or screen evidence exists', hasImplementation ? 'pass' : 'fail', strictOrDone, 'capture or provide implementation screenshot before claiming done'),
+        designGateCheck('reference_comparison', 'Reference comparison is recorded when reference is used', !hasReference ? 'not_checked' : ['matched', 'similar', 'not-applicable'].includes(comparisonResult) ? 'pass' : 'fail', hasReference, 'compare against the reference or mark the difference as intentional before claiming done'),
+        designGateCheck('design_quality', 'Design quality result is pass', designQuality === 'pass' ? 'pass' : designQuality === 'needs-polish' ? 'warning' : 'fail', strictOrDone, 'resolve design quality issues or keep the result as needs-polish/partial'),
+        designGateCheck('p0_clear', 'No P0 visual blockers remain', p0.length ? 'fail' : 'pass', true, 'fix P0 blockers before any done claim'),
+        designGateCheck('p1_clear', 'No P1 major visual issues remain', p1.length ? 'fail' : 'pass', strictOrDone, 'fix or explicitly defer P1 issues before claiming done'),
+        designGateCheck('cta_affordance', 'Primary CTA and interaction affordances were checked', Boolean(input.cta_checked) ? 'pass' : 'not_checked', strictOrDone, 'check primary CTA clarity and interaction affordances before claiming done'),
+        designGateCheck('state_coverage', 'Primary UI states were checked', Boolean(input.states_checked) ? 'pass' : 'not_checked', strictOrDone, 'check default/loading/error/empty/disabled states or keep completion partial'),
+        designGateCheck('mobile_coverage', 'Mobile/responsive behavior was checked', Boolean(input.mobile_checked || input.responsive_checked) ? 'pass' : 'not_checked', strictOrDone, 'check mobile/responsive behavior before claiming done'),
+        designGateCheck('accessibility_visuals', 'Contrast/accessibility-relevant visuals were checked', Boolean(input.contrast_checked || input.accessibility_checked) ? 'pass' : 'not_checked', strictOrDone, 'check contrast/accessibility-relevant visuals before claiming done')
+    ];
+    if (designScore !== null || strictOrDone) {
+        checks.push(designGateCheck('design_score', `Design score is at least ${minDesignScore}`, designScore !== null && designScore >= minDesignScore ? 'pass' : designScore === null ? 'not_checked' : 'fail', false, `record --design-score ${minDesignScore} or higher when using score-based completion`));
+    }
+    const blockers = [
+        ...p0.map((item) => `P0: ${item}`),
+        ...(blockedReason ? [blockedReason] : []),
+        ...checks
+            .filter((check) => check.required && check.status !== 'pass')
+            .map((check) => `${check.id}: ${check.next_action}`)
+    ];
+    const warnings = [
+        ...p1.map((item) => `P1: ${item}`),
+        ...checks
+            .filter((check) => !check.required && ['fail', 'warning', 'not_checked'].includes(check.status))
+            .map((check) => `${check.id}: ${check.next_action}`)
+    ];
+    const ready = completionClaim === 'done' && blockers.length === 0;
+    const truth = blockers.some((item) => item.startsWith('P0:')) || blockedReason ? 'blocked'
+        : ready ? 'verified'
+            : strictOrDone ? 'partial'
+                : hasImplementation ? 'partial'
+                    : 'assumed';
+    return {
+        schema: 'yam.ueye-design-completion-gate.v1',
+        mode,
+        completion_claim: completionClaim,
+        ready_to_claim_done: ready,
+        design_score: designScore,
+        min_design_score: minDesignScore,
+        checks,
+        p0,
+        p1,
+        warnings,
+        blockers,
+        next_action: blockers[0] || (ready ? 'done claim is supported by the recorded design gate' : warnings[0] || 'keep the Ueye result as draft or needs-polish until a done claim is needed'),
+        truth_status: truth
+    };
+}
+function normalizeUeyeCompletionClaim(value = '') {
+    const text = String(value || '').toLowerCase();
+    if (text === 'done' || text === 'complete' || text === 'completed')
+        return 'done';
+    if (text === 'needs-polish' || text === 'needs_polish' || text === 'polish')
+        return 'needs-polish';
+    return 'draft';
+}
+function designGateCheck(id, label, status, required, nextAction) {
+    return {
+        id,
+        label,
+        status,
+        required,
+        next_action: nextAction
+    };
+}
+function numberOrNull(value = null) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
 export function buildRollbackHint(input = {}) {
     return {
         schema: 'yam.rollback-hint.v1',
@@ -104,19 +191,30 @@ export function buildUeyeRunReport(input = {}) {
             : comparisonResult === 'matched' && hasImplementation ? 'verified'
                 : hasImplementation ? 'partial'
                     : 'partial';
+    const gate = buildUeyeDesignCompletionGate({
+        ...input.design_completion_gate,
+        has_reference: references.length > 0,
+        has_implementation_screenshot: hasImplementation,
+        comparison_result: comparisonResult,
+        design_quality: String(input.design_quality || 'not-checked'),
+        blocked_reason: blockedReason
+    });
+    const shouldApplyDesignGate = gate.mode === 'strict' || gate.completion_claim === 'done' || gate.blockers.length > 0;
+    const finalTruth = shouldApplyDesignGate ? weakestTruth(derivedTruth, gate.truth_status) : derivedTruth;
     return {
         schema: 'yam.ueye-run-report.v1',
         reference_sources: references,
         implementation_sources: implementations,
         surface_context: buildUeyeSurfaceContext({
             ...input.surface_context,
-            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : derivedTruth
+            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : finalTruth
         }),
+        design_completion_gate: gate,
         comparison_result: comparisonResult,
         design_quality: String(input.design_quality || 'not-checked'),
         blocked_reason: blockedReason,
-        next_action: String(input.next_action || (derivedTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
-        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : derivedTruth
+        next_action: String(input.next_action || gate.blockers[0] || (finalTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : finalTruth
     };
 }
 export function buildMediaGenerationProof(input = {}) {
@@ -229,6 +327,9 @@ export function classifyEvidenceTruth(summary = {}, options = {}) {
     for (const media of asList(summary.mediaProof)) {
         rows.push(evidenceRow('evidence', media, readStructuredTruth(media, 'partial')));
     }
+    for (const designCompletion of asList(summary.designCompletion)) {
+        rows.push(evidenceRow('visual', designCompletion, readStructuredTruth(designCompletion, 'partial')));
+    }
     for (const runtime of asList(summary.runtime)) {
         rows.push(evidenceRow('runtime', runtime, classifyRuntimeEvidence(runtime, options)));
     }
@@ -262,6 +363,15 @@ export function applyProofTruthCaps(summary = {}, options = {}) {
         cappedTruth = weakestTruth(cappedTruth, 'partial');
         unverified.push('real_visual_evidence_missing');
     }
+    const designCompletionTruth = designCompletionCap(summary.designCompletion);
+    if (designCompletionTruth) {
+        cappedTruth = weakestTruth(cappedTruth, designCompletionTruth);
+        if (designCompletionTruth === 'blocked')
+            blockers.push('ueye_design_completion_blocked');
+        if (!['verified', 'proven'].includes(designCompletionTruth)) {
+            unverified.push('ueye_design_completion_not_verified');
+        }
+    }
     if (requested !== cappedTruth) {
         caps.push(`requested ${requested} capped to ${cappedTruth} by evidence`);
     }
@@ -319,6 +429,7 @@ export function buildYamCompletionProof(summary = {}, options = {}) {
         rollbackHint: asList(summary.rollbackHint),
         runtimeBackendEvidence: asList(summary.runtimeBackendEvidence),
         mediaProof: asList(summary.mediaProof),
+        designCompletion: asList(summary.designCompletion),
         cleanup: summary.cleanup || '',
         changed: asList(summary.changed),
         skipped: asList(summary.skipped),
@@ -394,6 +505,12 @@ function readStructuredTruth(value = '', fallback = 'partial') {
         return fallback;
     }
 }
+function designCompletionCap(value = '') {
+    const items = asList(value);
+    if (!items.length)
+        return null;
+    return items.reduce((weakest, item) => weakestTruth(weakest, readStructuredTruth(item, 'partial')), 'proven');
+}
 function strongestSupportedTruth(rows = []) {
     if (rows.some((row) => row.truth === 'blocked'))
         return 'blocked';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -16,7 +16,7 @@
     "node": ">=18"
   },
   "bin": {
-    "yam": "./dist/bin/yam.js"
+    "yam": "dist/bin/yam.js"
   },
   "types": "dist/lib/trust-kernel.d.ts",
   "exports": {

package/references/trust-kernel.md

@@ -11,6 +11,7 @@ This is the small trust kernel that keeps `yam` honest without turning every tas
 - fake versus real evidence distinction
 - runtime truth matrix idea
 - visual evidence caps
+- Ueye design completion gate
 - DB/Supabase destructive-signal detection
 
 ## Rejected
@@ -38,6 +39,7 @@ The module provides:
 - fake/real policy
 - runtime truth matrix
 - completion proof object creation
+- Ueye design completion gate creation
 
 ## Policy
 
@@ -51,5 +53,6 @@ For example:
 - Mock/fixture evidence cannot become real runtime `proven`.
 - Required runtime evidence that is missing becomes `real_required_missing`.
 - Cleanup claims require cleanup evidence.
+- Ueye `done` claims require a passing design completion gate or stay capped at `partial` or `blocked`.
 
 This keeps the trust layer progressive and route-scoped.