yam-flow 2.0.0 → 2.2.0

package/dist/lib/trust-kernel.js

@@ -236,24 +236,32 @@ export function buildLoopReport(input = {}) {
         ? input.stages.map((stage) => buildLoopStage(stage))
         : [];
     const evidence = asList(input.evidence);
+    const touchedFiles = asList(input.touched_files || input.touched_file);
+    const readFiles = asList(input.read_files || input.read_file);
+    const verifiedFiles = asList(input.verified_files || input.verified_file);
+    const skippedChecks = asList(input.skipped_checks || input.skipped_check);
+    const stopCondition = shortText(input.stop_condition);
+    const resumeHint = shortText(input.resume_hint);
+    const readinessState = normalizeReadinessState(input.readiness_state);
     const coveredRequirements = asList(input.covered_requirements || input.covered_requirement);
     const uncoveredRequirements = asList(input.uncovered_requirements || input.uncovered_requirement);
     const blockers = asList(input.blockers || input.blocked);
     const blockedBy = asList(input.blocked_by);
-    const blockedKind = shortText(input.blocked_kind || (uncoveredRequirements.length ? 'requirement_uncovered' : blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+    const blockedKind = shortText(input.blocked_kind || (readinessState === 'blocked' ? 'readiness_blocked' : uncoveredRequirements.length ? 'requirement_uncovered' : blockers.length || blockedBy.length ? 'evidence_missing' : ''));
     const failureCause = shortText(input.failure_cause);
     const recoveryHint = shortText(input.recovery_hint);
     const avoidanceNote = shortText(input.avoidance_note);
     const evidenceStamp = shortText(input.evidence_stamp || input.source_digest, 320);
     const sourceDigest = shortText(input.source_digest || input.evidence_stamp, 320);
     const hasBlockedStage = stages.some((stage) => stage.status === 'blocked' || stage.status === 'failed');
-    const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length);
+    const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length || readinessState === 'blocked');
     const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
     const derivedTruth = hasBlockerSignal || hasBlockedStage ? 'blocked'
         : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
             : evidence.length || stages.length ? 'partial'
                 : 'assumed';
-    const truth = requestedTruth ? weakestTruth(requestedTruth, derivedTruth) : derivedTruth;
+    const readinessCap = readinessState === 'blocked' ? 'blocked' : readinessState === 'degraded' ? 'partial' : '';
+    const truth = requestedTruth ? weakestTruth(requestedTruth, derivedTruth, readinessCap) : weakestTruth(derivedTruth, readinessCap);
     const studyNote = buildStudyNote(input.study_note && typeof input.study_note === 'object' ? input.study_note : input);
     const intentLabel = normalizeToolIntentLabel(input.intent_label || input.tool_intent);
     return {
@@ -270,6 +278,13 @@ export function buildLoopReport(input = {}) {
         evidence_level: normalizeLoopEvidenceLevel(input.evidence_level),
         evidence_stamp: evidenceStamp,
         source_digest: sourceDigest,
+        touched_files: touchedFiles,
+        read_files: readFiles,
+        verified_files: verifiedFiles,
+        skipped_checks: skippedChecks,
+        stop_condition: stopCondition,
+        resume_hint: resumeHint,
+        readiness_state: readinessState,
         covered_requirements: coveredRequirements,
         uncovered_requirements: uncoveredRequirements,
         blockers,
@@ -278,7 +293,7 @@ export function buildLoopReport(input = {}) {
         truth_status: truth,
         intent_label: intentLabel,
         tool_intent: intentLabel,
-        next_action: shortText(input.next_action || (uncoveredRequirements.length ? `cover requirement before claiming complete: ${uncoveredRequirements[0]}` : hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
+        next_action: shortText(input.next_action || (readinessState === 'blocked' ? 'restore readiness before claiming this loop complete' : uncoveredRequirements.length ? `cover requirement before claiming complete: ${uncoveredRequirements[0]}` : hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
         safe_retry: shortText(input.safe_retry || (hasBlockerSignal ? 'retry only after the blocker is resolved and new evidence is recorded' : 'not required')),
         recovery_hint: recoveryHint,
         fix_first_items: asList(input.fix_first_items || input.fix_first_item),
@@ -305,6 +320,7 @@ export function buildUeyeRunReport(input = {}) {
     const blockedReason = String(input.blocked_reason || '');
     const comparisonResult = String(input.comparison_result || 'not-verified');
     const hasImplementation = implementations.length > 0;
+    const deepVisualReview = buildUeyeDeepVisualReview(input.deep_visual_review);
     const derivedTruth = blockedReason ? 'blocked'
         : !references.length && !hasImplementation ? 'assumed'
             : comparisonResult === 'matched' && hasImplementation ? 'verified'
@@ -319,7 +335,8 @@ export function buildUeyeRunReport(input = {}) {
         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;
+    const deepTruthCap = deepVisualReview.truth_status === 'assumed' ? '' : deepVisualReview.truth_status;
+    const finalTruth = shouldApplyDesignGate ? weakestTruth(derivedTruth, gate.truth_status, deepTruthCap) : weakestTruth(derivedTruth, deepTruthCap);
     return {
         schema: 'yam.ueye-run-report.v1',
         reference_sources: references,
@@ -329,13 +346,74 @@ export function buildUeyeRunReport(input = {}) {
             truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : finalTruth
         }),
         design_completion_gate: gate,
+        deep_visual_review: deepVisualReview,
         comparison_result: comparisonResult,
         design_quality: String(input.design_quality || 'not-checked'),
         blocked_reason: blockedReason,
-        next_action: String(input.next_action || gate.blockers[0] || (finalTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
+        next_action: String(input.next_action || gate.blockers[0] || deepVisualReview.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 buildUeyeDeepVisualReview(input = {}) {
+    const acceptanceCriteria = asList(input.acceptance_criteria || input.acceptance_criterion);
+    const touchedFiles = asList(input.touched_files || input.touched_file);
+    const readFiles = asList(input.read_files || input.read_file);
+    const verifiedFiles = asList(input.verified_files || input.verified_file);
+    const skippedChecks = asList(input.skipped_checks || input.skipped_check);
+    const residualRisks = asList(input.residual_risks || input.residual_risk);
+    const deepVisualChecks = asList(input.deep_visual_checks || input.deep_visual_check);
+    const designSystemEvidence = asList(input.design_system_evidence || input.design_system);
+    const implementationEvidence = asList(input.implementation_evidence || input.implementation_evidence_item);
+    const stateMatrix = buildStateMatrix(input.state_matrix, input);
+    const stopCondition = shortText(input.stop_condition);
+    const resumeHint = shortText(input.resume_hint);
+    const blockers = [
+        ...asList(input.blockers || input.blocked),
+        ...(Object.values(stateMatrix).some((status) => status === 'fail' || status === 'blocked') ? ['state_matrix: fix failed or blocked UI states before claiming done'] : [])
+    ];
+    const warnings = [
+        ...asList(input.warnings || input.warning),
+        ...skippedChecks.map((check) => `skipped: ${check}`),
+        ...residualRisks.map((risk) => `risk: ${risk}`),
+        ...(acceptanceCriteria.length && !implementationEvidence.length ? ['implementation_evidence: record how the UI was checked against acceptance criteria'] : [])
+    ];
+    const hasAnySignal = Boolean(acceptanceCriteria.length ||
+        touchedFiles.length ||
+        readFiles.length ||
+        verifiedFiles.length ||
+        skippedChecks.length ||
+        residualRisks.length ||
+        stopCondition ||
+        resumeHint ||
+        deepVisualChecks.length ||
+        designSystemEvidence.length ||
+        implementationEvidence.length ||
+        Object.keys(stateMatrix).length);
+    const truth = blockers.length ? 'blocked'
+        : hasAnySignal && skippedChecks.length ? 'partial'
+            : hasAnySignal && implementationEvidence.length ? 'verified'
+                : hasAnySignal ? 'partial'
+                    : 'assumed';
+    return {
+        schema: 'yam.ueye-deep-visual-review.v1',
+        acceptance_criteria: acceptanceCriteria,
+        touched_files: touchedFiles,
+        read_files: readFiles,
+        verified_files: verifiedFiles,
+        skipped_checks: skippedChecks,
+        residual_risks: residualRisks,
+        stop_condition: stopCondition,
+        resume_hint: resumeHint,
+        deep_visual_checks: deepVisualChecks,
+        design_system_evidence: designSystemEvidence,
+        state_matrix: stateMatrix,
+        implementation_evidence: implementationEvidence,
+        blockers,
+        warnings,
+        next_action: shortText(input.next_action || blockers[0] || warnings[0] || (hasAnySignal ? 'continue with the recorded Ueye verification boundary' : 'record acceptance criteria and visual evidence when Ueye needs deep verification')),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : truth
+    };
+}
 function buildStudyNoteSection(section, fallback, kind) {
     const source = section && typeof section === 'object' ? section : fallback;
     const code = shortText(source.code);
@@ -432,6 +510,50 @@ function normalizeLoopEvidenceLevel(value = '') {
         return text;
     return 'none';
 }
+function normalizeReadinessState(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['usable', 'degraded', 'blocked', 'unknown'].includes(text))
+        return text;
+    return 'unknown';
+}
+function buildStateMatrix(rawStateMatrix = null, input = {}) {
+    const result = {};
+    if (rawStateMatrix && typeof rawStateMatrix === 'object' && !Array.isArray(rawStateMatrix)) {
+        for (const [key, value] of Object.entries(rawStateMatrix)) {
+            const name = shortText(key, 80);
+            if (name)
+                result[name] = normalizeStateCheckStatus(value);
+        }
+    }
+    for (const item of asList(input.state_check)) {
+        const [name = '', rawStatus = 'checked'] = item.split(':');
+        const key = shortText(name, 80);
+        if (key)
+            result[key] = normalizeStateCheckStatus(rawStatus);
+    }
+    for (const key of ['default', 'loading', 'error', 'empty', 'disabled', 'hover', 'focus', 'mobile']) {
+        const value = input[`${key}_state`];
+        if (value !== undefined)
+            result[key] = normalizeStateCheckStatus(value);
+    }
+    return result;
+}
+function normalizeStateCheckStatus(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['pass', 'checked', 'verified', 'ok'].includes(text))
+        return 'pass';
+    if (['fail', 'failed', 'broken'].includes(text))
+        return 'fail';
+    if (['blocked', 'missing'].includes(text))
+        return 'blocked';
+    if (['skipped', 'skip'].includes(text))
+        return 'skipped';
+    if (['partial', 'needs_polish', 'warning'].includes(text))
+        return 'partial';
+    if (['not_checked', 'unknown'].includes(text))
+        return 'not_checked';
+    return shortText(value, 80) || 'checked';
+}
 function shortText(value = '', limit = 240) {
     const text = String(value || '').trim().replace(/\s+/g, ' ');
     if (text.length <= limit)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -59,6 +59,7 @@
     "pack:dry-run": "npm pack --dry-run",
     "publish:dry": "npm publish --dry-run --access public",
     "forbidden-names:check": "node ./scripts/check-forbidden-names.mjs",
+    "study-note:check": "node ./dist/bin/yam.js study-note check --json",
     "package-boundary:check": "node ./scripts/check-package-boundary.mjs",
     "dist:freshness": "node ./scripts/check-dist-freshness.mjs",
     "registry:check": "node ./scripts/check-registry-version.mjs",

package/references/final-report.md

@@ -4,10 +4,10 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 
 ## Required Closing Check
 
-Include these when they are useful and keep them short:
+Always keep final reports short. Include these when they apply:
 
 - What changed or what was found.
-- Change insight for non-specialists: what the touched code does, how it changed, and why it matters.
+- Change insight for non-specialists: what the touched code or artifact does, what role it has, where it runs or is read, what changed, what behavior is expected, one useful syntax/structure insight, and what remains uncertain.
 - What verification ran.
 - What was not checked.
 - Truth status, when verification or runtime claims matter.
@@ -16,7 +16,7 @@ Include these when they are useful and keep them short:
 - Context pressure or cleanup findings when they could affect the next run.
 - Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.
-- Study Note for implementation work: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
+- Study Note whenever code, config, release metadata, documentation, or project artifacts changed, even if no yam skill was explicitly invoked. This item is required for changed artifacts, not optional.
 - Remaining tasks.
 - Fix-first items before planned tasks.
 - Recommended direction and why that next step matters when the handoff would otherwise be ambiguous.
@@ -58,15 +58,21 @@ Examples:
 
 ## Study Note
 
-Use this when implementation changed code or fixed an error and the user would benefit from learning:
+Use this whenever implementation changed code or any project artifact changed:
 
-- What code had the issue.
-- What role that code plays.
-- How the issue showed up.
-- What changed.
-- Why the change matters.
+- What code or artifact changed.
+- What role that code or artifact plays in the project.
+- Where it runs, renders, validates, builds, publishes, or is read.
+- What was wrong, missing, unclear, or risky.
+- What changed: before/after behavior or guidance, and what behavior the change should produce.
+- One small syntax, API, schema, or structure insight for a non-specialist.
+- Architecture hygiene when relevant: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
+- What was verified, or why verification is partial/skipped/blocked.
+- What remains uncertain.
 
-Keep it short. If the information is not known, say so instead of inventing it.
+Keep it short: 4-7 lines for ordinary work, longer only when risk, learning value, `$deep`, `$mission`, release, runtime, or DB work justifies it. If the information is not known, say so instead of inventing it.
+
+Use `references/study-note.md`.
 
 ## Handoff Direction
 
@@ -83,7 +89,7 @@ Use this when the next run needs a clear starting point:
 - Avoidance note when a repeated mistake should be easy to spot; durable memory still uses explicit `yam memory add`.
 - Owner route, scope owner, and side effects when more than one person or route may continue the work.
 
-`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `covered_requirements`, `uncovered_requirements`, `blocked_kind`, `failure_cause`, `recovery_hint`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, `side_effects`, and `avoidance_note`.
+`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `covered_requirements`, `uncovered_requirements`, `touched_files`, `read_files`, `verified_files`, `skipped_checks`, `stop_condition`, `resume_hint`, `readiness_state`, `blocked_kind`, `failure_cause`, `recovery_hint`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, `side_effects`, and `avoidance_note`.
 
 ## Route Weight
 

package/references/honest-completion.md

@@ -35,6 +35,19 @@ Verification: not run; change was limited to copy/CSS and inspected locally.
 
 For larger work, include proof summary and residual risk.
 
+Use the L0-L5 Verification Ladder:
+
+- L0 stated.
+- L1 inspected.
+- L2 local check.
+- L3 integrated.
+- L4 release/runtime/visual proof.
+- L5 bounded deep.
+
+Escalate when the claim touches public release, UI done, auth, payment, DB, runtime, deployment, broad refactor, security, high learning value, or explicit user intent.
+
+Bounded heavy verification must stop after the smallest meaningful proof set passes, or after three relevant checks have run and remaining uncertainty is listed as blocked, skipped, or remaining work.
+
 ## Runtime Guard
 
 Runtime work needs stronger evidence because long-running processes can create false success:

package/references/study-note.md

@@ -0,0 +1,69 @@
+# Study Note v3
+
+Study Note is required whenever code, config, release metadata, documentation, or project artifacts changed, even if no yam skill was explicitly invoked.
+
+The goal is not to write a tutorial for every change. The goal is to help a non-developer or non-specialist learn the meaning of the changed code or artifact a little at a time, without hiding uncertainty or padding the final report.
+
+Study Note v3 adds two expectations:
+
+- Explain where the changed code or artifact sits in the project flow: role, execution point, before/after behavior, and expected result.
+- Add a small architecture hygiene check when implementation touched UI, styles, data shape, or storage boundaries.
+
+## Final Report Shape
+
+This is final-report writing guidance, not a new CLI JSON schema. The current CLI artifact remains `yam.study-note.v1` with `problem`, `change`, `why_it_matters`, `learning_note`, `limits`, and `truth_status`. When using `yam loop report`, map the guidance below into the existing fields and put unknowns in `limits`.
+
+Keep the default note short: 4-7 lines for ordinary work, longer only for `$deep`, `$mission`, release, DB, runtime, or learning-heavy work.
+
+Include:
+
+- Touched code/artifact: the file, function, component, config, or artifact that changed.
+- Code/artifact role: what that code or artifact does in the project.
+- Execution point: when or where it runs, loads, renders, validates, builds, publishes, or is read by another tool.
+- Problem meaning: what was wrong, missing, unclear, or risky, and how the symptom appeared.
+- Before/after: what the old behavior or guidance allowed, and what the new behavior or guidance should produce.
+- Syntax or structure insight: one small language, API, schema, or structure insight for a non-specialist.
+- Verification note: what was checked, or why verification is partial/skipped/blocked.
+- Limits: what is not known; do not invent missing cause, behavior, or verification.
+
+When relevant, include an architecture hygiene line:
+
+- UI hygiene: do not dump unrelated state, data loading, actions, formatting, and large helper logic into `page.tsx`; keep route files focused and move reusable or complex work into local components, hooks, utilities, or server actions that match the project pattern.
+- CSS hygiene: do not dump one-off component styling into `global.css`; prefer existing tokens, component styles, modules, utility classes, or scoped styles unless the rule is genuinely global.
+- Data hygiene: do not use a broad DB `jsonb` blob as the default answer for structured product data; prefer named columns, typed tables, constraints, indexes, and migrations when the data has stable meaning, query needs, security policy, or reporting value.
+- Boundary hygiene: keep auth, payment, DB, secret, release, and public-facing surfaces explicit; note when a change did or did not touch those sensitive paths.
+
+## Compact Example
+
+```text
+Study Note:
+- Touched code: `buildLoopReport`, the function that turns loop inputs into report JSON.
+- Code role: it decides whether a loop can honestly say it is verified, partial, or blocked.
+- Execution point: it runs when `yam loop report` builds the final report artifact.
+- Before/after: before, unfinished requirements could be easy to miss; after, `uncovered_requirements` lowers the truth status to blocked and points the next action at the missing requirement.
+- Syntax/structure: the code uses an array length check plus a conditional default to choose safer report fields.
+- Verification: typecheck and CLI smoke covered the JSON shape.
+- Hygiene: report logic stayed in the report builder instead of spreading status rules across unrelated command code.
+- Limits: this does not infer requirements from prose; the agent or user still has to provide them.
+```
+
+## When Nothing Changed
+
+For pure Q&A, planning, scouting, or review with no changed artifact, do not force a Study Note. Say `No code or project artifact changed` when that prevents ambiguity.
+
+## Tone
+
+- Use plain language before implementation jargon.
+- Explain the code's responsibility before explaining the patch.
+- Explain the execution point before claiming behavior.
+- Prefer one practical syntax or structure insight over broad teaching.
+- Tie the note to evidence. If no check ran, say so.
+- Keep remaining tasks separate from Study Note.
+
+## What To Avoid
+
+- Do not guess root cause when it was not verified.
+- Do not over-explain common syntax when it distracts from the touched code.
+- Do not turn every final report into a long lesson.
+- Do not claim the user learned something; just leave a useful learning path.
+- Do not present "put it all in `page.tsx`", "put it all in `global.css`", or "store it all in `jsonb`" as the easy default when project structure should carry the responsibility.

package/references/tool-trust-layer.md

@@ -13,7 +13,8 @@ Every route carries a basic contract:
 - use context packs or memory before broad re-reading
 - verify only what was actually checked
 - report remaining tasks and fix-first issues when useful
-- explain what changed in plain language when code or behavior changes
+- include a Study Note when code, config, release metadata, documentation, or project artifacts changed
+- explain what changed, what role it has, what behavior is expected, and one useful syntax or structure insight in plain language
 - treat security as the first project lens
 - preserve source boundaries when outside references shaped the judgment
 
@@ -26,6 +27,8 @@ Then depth increases by route:
 - `$deep`: prove risky single-agent work with stronger runtime/tool evidence.
 - `$mission`: coordinate real subagents/team lanes with cross-verification.
 
+Verification should follow the L0-L5 ladder: stated, inspected, local check, integrated, release/runtime/visual proof, bounded deep. Serious claims can require serious evidence, but stop after the smallest meaningful proof set passes or after remaining uncertainty is clearly handed off.
+
 ## Surfaces To Wrap
 
 - Local CLI/app readiness.
@@ -94,6 +97,8 @@ On demand:
 
 - What the touched code or artifact is responsible for.
 - What changed in behavior, contract, UI, or safety posture.
+- What syntax, schema, or structure insight helps a non-specialist understand the change.
+- What verification level supports the claim.
 - Why the change matters to the product or user.
 - What remains uncertain or unverified.
 - What should be fixed first before the next planned task.

package/references/ueye-proof.md

@@ -26,12 +26,13 @@ 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 --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
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --acceptance-criterion "primary CTA remains visible on mobile" --design-system-evidence "uses existing button token" --implementation-evidence "browser screenshot reviewed" --state-check default:pass --state-check mobile:partial --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, surface context, design quality, blocked reason, next action, and truth status.
+- `report` can also record a deep visual review with acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
 - `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.
 
@@ -239,6 +240,46 @@ yam proof --route ueye --truth verified --visual "implementation screenshot evid
 
 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.
 
+### Deep Visual Review
+
+Purpose: let Ueye carry Deep-grade UI verification when the work is serious, without forcing a separate route.
+
+Use this when:
+
+- The user asks for strong UI/UX verification.
+- A done claim depends on multiple states, viewports, or design-system fit.
+- A previous Ueye review needs a resume-ready handoff.
+- Missing visual evidence should become an explicit residual risk instead of being hidden.
+
+Minimum useful fields:
+
+- `acceptance_criteria`
+- `touched_files`
+- `read_files`
+- `verified_files`
+- `skipped_checks`
+- `residual_risks`
+- `stop_condition`
+- `resume_hint`
+- `deep_visual_checks`
+- `design_system_evidence`
+- `state_matrix`
+- `implementation_evidence`
+- `truth_status`
+
+State matrix examples:
+
+```bash
+yam ueye report --state-check default:pass --state-check loading:pass --state-check error:partial --state-check mobile:blocked --json
+```
+
+Truth rules:
+
+- Failed or blocked state matrix rows block the deep visual review.
+- Skipped checks and residual risks keep the result honest as `partial` unless other evidence still supports a narrower claim.
+- Deep visual review evidence does not replace a real implementation screenshot when the claim needs visual proof.
+- A stop condition should explain when to stop verifying; a resume hint should explain the next safe visual action.
+
 ### Review Continuity And Comparison Report
 
 Use this when a Ueye task continues a previous visual review, rechecks a fix, or compares two review runs.

package/references/ueye.md

@@ -67,6 +67,7 @@ Use these when the task depends on visual truth, reference matching, or design q
 4. Design Quality Review.
 5. Review Continuity and Comparison Report.
 6. Design Completion Gate.
+7. Deep Visual Review, when Ueye needs Deep-grade verification.
 
 Default bound:
 
@@ -168,6 +169,30 @@ Gate behavior:
 - Missing required checks for a done claim should cap truth at partial.
 - Only claim done when the gate says `ready_to_claim_done: true`.
 
+### Deep Visual Review
+
+Use when Ueye should stay in the UI/design route but needs stronger verification than a quick screenshot note.
+
+Record:
+
+- acceptance criteria for the visual claim.
+- touched, read, and verified files.
+- skipped checks and why they are acceptable or still risky.
+- residual risks.
+- stop condition for bounded verification.
+- resume hint for the next visual pass.
+- deep visual checks that ran.
+- design-system evidence such as tokens, components, or nearby patterns read.
+- implementation evidence such as screenshot, browser check, source inspection, or responsive check.
+- state matrix for default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
+
+Behavior:
+
+- Failed or blocked state matrix rows should block the deep visual review.
+- Skipped checks and residual risks should keep the claim partial unless the remaining claim is narrow and explicitly bounded.
+- Deep visual review does not replace implementation screenshot evidence when the claim depends on seeing the real screen.
+- Stop conditions prevent endless visual proof loops; resume hints make the next pass cheap to restart.
+
 ### 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.
@@ -222,9 +247,10 @@ Keep this metadata descriptive. It should support honest visual claims, not forc
 7. Reference vs Implementation Matrix when reference fidelity matters.
 8. Design Quality Review.
 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.
+10. Deep Visual Review when the work needs acceptance criteria, state matrix, skipped checks, residual risks, stop condition, or resume hint.
+11. Review Continuity and Comparison Report when the work spans multiple passes.
+12. P0/P1 closeout.
+13. Truth status.
 
 ## Truth Caps