yam-flow 0.1.5 → 0.1.6

package/references/ueye-proof.md

@@ -26,7 +26,7 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```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 needs-polish --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 project-local capture backend when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
@@ -190,6 +190,55 @@ Dimensions:
 Report findings as P0-P3. Keep P2/P3 short unless the user requested a full polish pass.
 For each relevant design dimension, use `pass`, `needs-polish`, or `fails`.
 
+### Design Completion Gate
+
+Purpose: prevent Ueye from declaring visual work complete before the design evidence supports that claim.
+
+Use when the output says the UI is done, complete, polished, final, or verified.
+
+Minimum fields:
+
+- `completion_claim`: draft / needs-polish / done
+- `mode`: fast / strict
+- `ready_to_claim_done`
+- `design_score`, when used
+- `min_design_score`
+- `checks`
+- `p0`
+- `p1`
+- `warnings`
+- `blockers`
+- `next_action`
+- `truth_status`
+
+Required for a done claim when relevant:
+
+- direction locked
+- reference read proof for reference-led work
+- implementation screenshot or source-screen evidence
+- reference comparison for reference-led work
+- design quality pass
+- no P0 blockers
+- no unresolved P1 issues unless explicitly deferred
+- CTA affordance checked
+- primary states checked
+- mobile/responsive behavior checked
+- contrast/accessibility-relevant visuals checked
+
+Example:
+
+```bash
+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
+```
+
+Attach to proof when needed:
+
+```bash
+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"}'
+```
+
+The design completion gate is a completion judgment. Keep actual source-screen proof in visual evidence, visual provenance, or a Ueye run report. Do not use self-reported gate fields to pretend a missing screenshot was captured.
+
 ### Review Continuity And Comparison Report
 
 Use this when a Ueye task continues a previous visual review, rechecks a fix, or compares two review runs.
@@ -222,3 +271,4 @@ Do not claim continuity from memory alone. Link it to a previous report, screens
 - Reference-only evidence can support direction, not implementation proof.
 - Generated-only evidence can support ideation or annotation, not implemented-screen verification.
 - Missing screenshots, unavailable browser, or text-only review should cap the result at `partial`, `blocked`, or `assumed`.
+- A done claim with a missing or failing design completion gate should cap the result at `partial` or `blocked`.

package/references/ueye.md

@@ -66,6 +66,7 @@ Use these when the task depends on visual truth, reference matching, or design q
 3. Reference vs Implementation Matrix.
 4. Design Quality Review.
 5. Review Continuity and Comparison Report.
+6. Design Completion Gate.
 
 Default bound:
 
@@ -146,6 +147,27 @@ Review dimensions:
 For each relevant dimension, record `pass`, `needs-polish`, or `fails`.
 Keep actionable findings in P0-P3 order. Prefer fixing P0/P1 and cheap local P2 issues before broad polish.
 
+### Design Completion Gate
+
+Use before claiming a Ueye implementation or serious review is done. This is the design-side completion check, not a separate route.
+
+Record:
+
+- `completion_claim`: draft, needs-polish, or done.
+- `mode`: fast or strict.
+- `design_score`, when score-based completion is useful.
+- P0 and P1 open findings.
+- Whether direction, reference read proof, implementation evidence, comparison, design quality, CTA affordance, state coverage, mobile/responsive behavior, and contrast/accessibility visuals were checked.
+- blockers, warnings, next action, and truth status.
+
+Gate behavior:
+
+- Draft and needs-polish can stay fast.
+- `done` automatically behaves as strict.
+- P0 or blocked reason should return blocked.
+- Missing required checks for a done claim should cap truth at partial.
+- Only claim done when the gate says `ready_to_claim_done: true`.
+
 ### Review Continuity and Comparison Report
 
 Use when a screen has more than one visual pass, a reference needs follow-up, or a previous Ueye report should stay connected to the next one.
@@ -199,9 +221,10 @@ Keep this metadata descriptive. It should support honest visual claims, not forc
 6. Screenshot/browser recheck when feasible.
 7. Reference vs Implementation Matrix when reference fidelity matters.
 8. Design Quality Review.
-9. Review Continuity and Comparison Report when the work spans multiple passes.
-10. P0/P1 closeout.
-11. Truth status.
+9. Design Completion Gate before any done claim.
+10. Review Continuity and Comparison Report when the work spans multiple passes.
+11. P0/P1 closeout.
+12. Truth status.
 
 ## Truth Caps
 
@@ -210,3 +233,4 @@ Keep this metadata descriptive. It should support honest visual claims, not forc
 - Blocked: requested visual claim cannot be inspected.
 - Assumed: implementation follows code patterns but visual result was not observed.
 - Reference-only or generated-only evidence cannot upgrade a result to full visual verification.
+- A done claim without a passing design completion gate cannot upgrade beyond partial or blocked.

package/skills/ueye/SKILL.md

@@ -41,6 +41,9 @@ Do not use for:
 - Record surface context when it matters: provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Generated media can guide direction, but it cannot verify the implemented screen without implementation screenshot evidence.
 - Prefer the in-app browser for interactive visual checks. Do not switch to a profile-dependent browser unless the user explicitly asks or the task requires existing cookies, sessions, extensions, or profile state.
+- Ueye owns the design completion gate. Do not rely on a separate code-risk route to catch sloppy visual completion.
+- Draft or needs-polish work may stay fast; a `done` claim requires recorded design gate evidence.
+- Do not claim a Ueye result is done when implementation evidence, design quality, P0/P1 status, state coverage, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, or reference-read/comparison evidence is missing where relevant.
 
 ## Workflow
 
@@ -78,8 +81,17 @@ Do not use for:
    - accessibility
    - brand or mood fit
    - mark each relevant dimension as pass, needs-polish, or fails.
-11. Produce a P0-P3 visual issue ledger and fix path.
-12. Recheck changed/high-risk screens after fixes when feasible.
+11. Run the Design Completion Gate before any "done" claim:
+   - direction locked
+   - reference read proof exists when reference-led
+   - implementation screenshot or source-screen evidence exists
+   - reference comparison is recorded when reference-led
+   - design quality is pass
+   - P0 is empty
+   - P1 is fixed or explicitly deferred
+   - CTA, states, mobile/responsive behavior, and contrast/accessibility visuals were checked
+12. Produce a P0-P3 visual issue ledger and fix path.
+13. Recheck changed/high-risk screens after fixes when feasible.
 
 ## Required Ueye Artifacts
 
@@ -106,7 +118,11 @@ Use these artifacts for reference-led implementation or serious visual review. K
    - use pass, needs-polish, or fails for each relevant design dimension.
 7. Review Continuity and Comparison Report, when this is a follow-up review:
    - record previous source/report, current source/report, comparison delta, resolved findings, new findings, still-open findings, truth status, and next action.
-8. Media Generation Proof, when generated images are part of the task:
+8. Design Completion Gate, when implementation or review is claimed done:
+   - record completion claim, design score when used, P0/P1 status, gate checks, blockers, warnings, next action, and truth status.
+   - use `yam ueye report --completion-claim done --design-quality pass --direction-locked --states-checked --mobile-checked --contrast-checked --cta-checked --json` when a compact proof-ready gate is needed.
+   - if the gate is partial or blocked, report the Ueye result as partial or blocked instead of complete.
+9. Media Generation Proof, when generated images are part of the task:
    - record whether generation was requested, attempted, blocked, or produced an output.
    - use `yam media proof --requested --attempted --output path.png --wait-loop --json` when a generated image materially affects the design direction.
    - never use generated media proof as a substitute for implemented screen evidence.
@@ -120,6 +136,7 @@ Use these artifacts for reference-led implementation or serious visual review. K
 - Inspect 1-3 primary images by default; expand only for P0/P1 risk, responsive breakage, or user-requested deep visual QA.
 - Keep source-screen inventory to the 5 most important rows by default.
 - Screenshot unavailable: cap the result at `partial` or `blocked`.
+- Completion gate missing for a `done` claim: cap the result at `partial` or `blocked`.
 - Text-only review: cap the result at `partial`.
 - Mock or invented screenshots: cap the result at `partial` and mark the source.
 - Browser unavailable but source files reviewed: report implementation verification separately from visual verification.

package/src/bin/yam.ts

@@ -14,6 +14,7 @@ import {
   buildMissionPatchEnvelope,
   buildRollbackHint,
   buildRuntimeBackendEvidence,
+  buildUeyeDesignCompletionGate,
   buildUeyeVisualProvenance,
   buildUeyeRunReport,
   buildUeyeSurfaceContext,
@@ -1349,12 +1350,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.
 `);
 }
 
@@ -1520,7 +1521,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 = [];
@@ -1586,7 +1587,9 @@ 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) {
       comparisonResult = 'different';
@@ -1605,6 +1608,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 || '')
   });
@@ -1614,6 +1633,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),
@@ -1672,6 +1692,7 @@ function buildUeyeComparisonReport({
   referenceSources,
   implementationSources,
   surfaceContext,
+  designCompletionGate,
   comparisonResult,
   designQuality,
   similar,
@@ -1713,6 +1734,7 @@ function buildUeyeComparisonReport({
       implementation_count: implementationSources.length
     },
     surface_context: surfaceContext || buildUeyeSurfaceContext(),
+    design_completion_gate: designCompletionGate || null,
     comparison_result: comparisonResult,
     design_quality: designQuality,
     similar,
@@ -1732,6 +1754,12 @@ function buildUeyeComparisonReport({
   };
 }
 
+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') return mediaUsage();
@@ -2015,7 +2043,7 @@ function parseSimpleFlags(args = [], allowed = new Set<string>()) {
     const key = rawKey.slice(2);
     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;
     }
@@ -2165,6 +2193,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);
@@ -2260,6 +2289,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)],
@@ -2325,6 +2358,9 @@ function renderProofMarkdown(summary) {
     '## Media proof',
     ...renderProofMarkdownList(summary.mediaProof || []),
     '',
+    '## Design completion',
+    ...renderProofMarkdownList(summary.designCompletion || []),
+    '',
     '## Changed surfaces',
     ...renderProofMarkdownList(summary.changed),
     '',
@@ -2357,7 +2393,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
   const flags: AnyRecord = {};
   const positionals: string[] = [];
-  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('--')) {
@@ -2371,7 +2407,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 {
         flags[normalizedKey] = value;
@@ -2414,6 +2450,7 @@ function emptyProofArtifact() {
     missionEnvelope: [],
     rollbackHint: [],
     mediaProof: [],
+    designCompletion: [],
     cleanup: '',
     changed: [],
     skipped: [],
@@ -2441,6 +2478,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),
@@ -2471,6 +2509,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'),
@@ -2556,6 +2595,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 {
     return text;
@@ -2564,7 +2606,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) {

package/src/lib/trust-kernel.ts

@@ -88,6 +88,30 @@ export interface UeyeSurfaceContext {
   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[];
@@ -122,6 +146,7 @@ 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;
@@ -129,6 +154,10 @@ export interface UeyeRunReport {
   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;
@@ -171,6 +200,7 @@ export interface ProofSummary {
   rollbackHint?: unknown;
   runtimeBackendEvidence?: unknown;
   mediaProof?: unknown;
+  designCompletion?: unknown;
 }
 
 export interface ProofOptions {
@@ -206,6 +236,7 @@ export interface YamCompletionProof {
   rollbackHint: string[];
   runtimeBackendEvidence: string[];
   mediaProof: string[];
+  designCompletion: string[];
   cleanup: unknown;
   changed: string[];
   skipped: string[];
@@ -262,6 +293,94 @@ export function buildUeyeSurfaceContext(input: Partial<UeyeSurfaceContext> = {})
   };
 }
 
+export function buildUeyeDesignCompletionGate(input: Partial<UeyeDesignCompletionGate> & Record<string, unknown> = {}): UeyeDesignCompletionGate {
+  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: UeyeDesignGateCheck[] = [
+    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: TruthStatus = 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: unknown = ''): UeyeDesignCompletionGate['completion_claim'] {
+  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: string, label: string, status: UeyeDesignGateCheck['status'], required: boolean, nextAction: string): UeyeDesignGateCheck {
+  return {
+    id,
+    label,
+    status,
+    required,
+    next_action: nextAction
+  };
+}
+
+function numberOrNull(value: unknown = null): number | null {
+  if (value === undefined || value === null || value === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
 export function buildRollbackHint(input: Partial<RollbackHint> = {}): RollbackHint {
   return {
     schema: 'yam.rollback-hint.v1',
@@ -302,7 +421,7 @@ export function buildRuntimeBackendEvidence(input: Partial<RuntimeBackendEvidenc
   };
 }
 
-export function buildUeyeRunReport(input: Partial<UeyeRunReport> = {}): UeyeRunReport {
+export function buildUeyeRunReport(input: UeyeRunReportInput = {}): UeyeRunReport {
   const references = Array.isArray(input.reference_sources)
     ? input.reference_sources.map((item) => buildUeyeVisualProvenance(item))
     : [];
@@ -317,19 +436,30 @@ export function buildUeyeRunReport(input: Partial<UeyeRunReport> = {}): UeyeRunR
       : 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
   };
 }
 
@@ -444,6 +574,9 @@ export function classifyEvidenceTruth(summary: ProofSummary = {}, options: Proof
   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)));
   }
@@ -473,6 +606,14 @@ export function applyProofTruthCaps(summary: ProofSummary = {}, options: ProofOp
     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`);
   }
@@ -532,6 +673,7 @@ export function buildYamCompletionProof(summary: ProofSummary = {}, options: Pro
     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),
@@ -601,6 +743,12 @@ function readStructuredTruth(value: unknown = '', fallback: TruthStatus = 'parti
   }
 }
 
+function designCompletionCap(value: unknown = ''): TruthStatus | null {
+  const items = asList(value);
+  if (!items.length) return null;
+  return items.reduce<TruthStatus>((weakest, item) => weakestTruth(weakest, readStructuredTruth(item, 'partial')), 'proven');
+}
+
 function strongestSupportedTruth(rows: EvidenceRow[] = []): TruthStatus {
   if (rows.some((row) => row.truth === 'blocked')) return 'blocked';
   if (rows.some((row) => row.truth === 'real_required_missing')) return 'real_required_missing';