yam-flow 0.1.4 → 0.1.6

package/dist/lib/trust-kernel.js

@@ -19,6 +19,11 @@ export function buildUeyeVisualProvenance(input = {}) {
         source_hash: String(input.source_hash || 'unknown'),
         reference_id: String(input.reference_id || ''),
         screenshot_id: String(input.screenshot_id || ''),
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
         local_only: Boolean(input.local_only),
         redacted: Boolean(input.redacted),
         operator_provided: Boolean(input.operator_provided),
@@ -26,6 +31,114 @@ export function buildUeyeVisualProvenance(input = {}) {
         truth_status: truth
     };
 }
+export function buildUeyeSurfaceContext(input = {}) {
+    return {
+        schema: 'yam.ueye-surface-context.v1',
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || input.provider_context || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
+        control_mode: String(input.control_mode || 'not-recorded'),
+        route: String(input.route || 'ueye'),
+        mode: String(input.mode || 'report'),
+        url: String(input.url || ''),
+        viewport: String(input.viewport || ''),
+        screenshot_id: String(input.screenshot_id || ''),
+        evidence_id: String(input.evidence_id || ''),
+        preserved_state: Boolean(input.preserved_state),
+        preserved_url: String(input.preserved_url || ''),
+        local_only: input.local_only !== undefined ? Boolean(input.local_only) : true,
+        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',
@@ -78,15 +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 : 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 = {}) {
@@ -199,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)));
     }
@@ -232,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`);
     }
@@ -289,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),
@@ -364,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.4",
+  "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.

package/references/ueye-proof.md

@@ -26,12 +26,12 @@ 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 --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.
 - `compare` is local-only and dependency-free. It records hashes, dimensions, comparison result, and visual provenance. Different screenshots stay `partial`; exact file matches can be `verified`.
-- `report` records the Ueye run as reference sources, implementation sources, comparison result, design quality, blocked reason, next action, and truth status.
+- `report` records the Ueye run as reference sources, implementation sources, comparison result, surface context, design quality, blocked reason, next action, and truth status.
 - `report` may include continuity fields when a previous review or screenshot is being rechecked.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
@@ -93,6 +93,11 @@ Record these fields when a reference or screenshot materially affects the claim:
 - `source_hash`
 - `reference_id`
 - `screenshot_id`
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
 - `viewport`
 - `state`
 - `local_only`
@@ -103,6 +108,28 @@ Record these fields when a reference or screenshot materially affects the claim:
 
 Use `unknown` for missing hashes and `not-verified` for comparisons that were not actually rechecked. Do not upgrade a visual claim only because a reference was supplied.
 
+### Surface Context
+
+Purpose: preserve where and how a visual claim was observed without turning Ueye into an always-on capture gate.
+
+Record these fields when they affect the visual claim:
+
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
+- `control_mode`
+- `url`
+- `viewport`
+- `screenshot_id`
+- `evidence_id`
+- `preserved_state`
+- `preserved_url`
+- `truth_status`
+
+Use `not-recorded` when the field was not observed. Prefer `partial` over `verified` when surface context exists but no actual implementation screenshot was captured or supplied.
+
 ### Reference Read Proof
 
 Purpose: separate reading the reference from judging the implementation.
@@ -163,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.
@@ -195,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.
@@ -164,7 +186,23 @@ Record:
 - next visual action.
 - truth status.
 
-Use `yam ueye report --previous-report previous.json --review-session-id current-pass --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+Use `yam ueye report --previous-report previous.json --review-session-id current-pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+
+### Surface Context
+
+Use surface context when a Ueye claim depends on preserving the current app/browser state or explaining where visual evidence came from.
+
+Fields:
+
+- provider context and badge.
+- execution surface.
+- app surface.
+- browser surface.
+- control mode.
+- preserved URL/state.
+- evidence id.
+
+Keep this metadata descriptive. It should support honest visual claims, not force a heavy browser workflow for every Ueye run.
 
 ## P0-P3 Ledger
 
@@ -183,9 +221,10 @@ Use `yam ueye report --previous-report previous.json --review-session-id current
 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
 
@@ -194,3 +233,4 @@ Use `yam ueye report --previous-report previous.json --review-session-id current
 - 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

@@ -38,8 +38,12 @@ Do not use for:
 - Keep Ueye as one route: start fast, then opt into `yam ueye capture` and `yam ueye compare` only when a `verified` visual claim needs real screen evidence.
 - Use `yam ueye report` when reference, implementation screenshot, comparison result, design quality, and next action should be recorded as one compact run report.
 - For follow-up visual reviews, keep continuity explicit: previous report/source, current report/source, comparison delta, resolved findings, new findings, and next action.
+- 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
 
@@ -61,7 +65,7 @@ Do not use for:
    - Do not silently use a profile-dependent browser as a fallback. If the in-app browser cannot capture or inspect, report the visual cap as `partial` or `blocked`.
    - Use `yam ueye capture --url URL --out path.png` when a project-local capture backend is available and the claim needs real browser evidence.
    - Use `yam ueye compare --reference ref.png --actual shot.png` when reference fidelity needs a proof-ready local comparison record.
-   - Use `yam ueye report --reference ref.png --actual shot.png --design-quality needs-polish --json` to preserve the run-level visual provenance and next action.
+   - Use `yam ueye report --reference ref.png --actual shot.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json` to preserve the run-level visual provenance, surface context, and next action.
    - When continuing a prior review, include previous/current report or screenshot identifiers and mark the comparison as improved, regressed, unchanged, or not-verified.
 9. Compare reference and implementation when reference fidelity was requested:
    - matched, similar, different, not-applicable, or not-verified.
@@ -77,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
 
@@ -91,18 +104,25 @@ Use these artifacts for reference-led implementation or serious visual review. K
 2. Visual Provenance:
    - source kind, path, hash, reference id, screenshot id, redaction/locality flags, operator-provided flag, comparison result, and truth status.
    - use this to prove the route from reference reading to implementation recheck.
-3. Reference Read Proof:
+3. Surface Context:
+   - provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, evidence id, and truth status.
+   - use this to explain where and how visual evidence was observed without forcing capture for every Ueye run.
+4. Reference Read Proof:
    - concrete observations from the reference before implementation.
    - no implementation claim should depend on an unrecorded reference observation.
-4. Reference vs Implementation Matrix:
+5. Reference vs Implementation Matrix:
    - compare the implemented result against the reference by aspect.
    - record matched, similar, different, not-applicable, or not-verified.
-5. Design Quality Review:
+6. Design Quality Review:
    - judge whether the result is good UI/UX/design after reference comparison.
    - use pass, needs-polish, or fails for each relevant design dimension.
-6. Review Continuity and Comparison Report, when this is a follow-up review:
+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.
-7. 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.
@@ -116,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.