yam-flow 2.1.0 → 2.2.0

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

@@ -8,6 +8,7 @@ export type RuntimeClaim = 'not_started' | 'started' | 'observed' | 'stopped' |
 export type LoopStageStatus = 'passed' | 'failed' | 'blocked' | 'skipped' | 'partial' | 'pending' | 'recorded';
 export type LoopEvidenceLevel = 'none' | 'fixture' | 'smoke' | 'local' | 'real';
 export type ToolIntent = 'read_only' | 'write' | 'destructive' | 'runtime' | 'visual' | 'publish';
+export type ReadinessState = 'usable' | 'degraded' | 'blocked' | 'unknown';
 export interface SafetyHit {
     level: SafetyLevel;
     reason: string;
@@ -161,6 +162,13 @@ export interface LoopReport {
     evidence_level: LoopEvidenceLevel;
     evidence_stamp: string;
     source_digest: string;
+    touched_files: string[];
+    read_files: string[];
+    verified_files: string[];
+    skipped_checks: string[];
+    stop_condition: string;
+    resume_hint: string;
+    readiness_state: ReadinessState;
     covered_requirements: string[];
     uncovered_requirements: string[];
     blockers: string[];
@@ -191,14 +199,35 @@ export interface UeyeRunReport {
     implementation_sources: UeyeVisualProvenance[];
     surface_context: UeyeSurfaceContext;
     design_completion_gate: UeyeDesignCompletionGate;
+    deep_visual_review: UeyeDeepVisualReview;
     comparison_result: string;
     design_quality: string;
     blocked_reason: string;
     next_action: string;
     truth_status: TruthStatus;
 }
-export interface UeyeRunReportInput extends Partial<Omit<UeyeRunReport, 'design_completion_gate'>> {
+export interface UeyeRunReportInput extends Partial<Omit<UeyeRunReport, 'design_completion_gate' | 'deep_visual_review'>> {
     design_completion_gate?: Partial<UeyeDesignCompletionGate> & Record<string, unknown>;
+    deep_visual_review?: Partial<UeyeDeepVisualReview> & Record<string, unknown>;
+}
+export interface UeyeDeepVisualReview {
+    schema: 'yam.ueye-deep-visual-review.v1';
+    acceptance_criteria: string[];
+    touched_files: string[];
+    read_files: string[];
+    verified_files: string[];
+    skipped_checks: string[];
+    residual_risks: string[];
+    stop_condition: string;
+    resume_hint: string;
+    deep_visual_checks: string[];
+    design_system_evidence: string[];
+    state_matrix: Record<string, string>;
+    implementation_evidence: string[];
+    blockers: string[];
+    warnings: string[];
+    next_action: string;
+    truth_status: TruthStatus;
 }
 export interface MediaGenerationProof {
     schema: 'yam.media-generation-proof.v1';
@@ -294,6 +323,7 @@ export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBacke
 export declare function buildStudyNote(input?: Partial<StudyNote> & Record<string, unknown>): StudyNote;
 export declare function buildLoopReport(input?: Partial<LoopReport> & Record<string, unknown>): LoopReport;
 export declare function buildUeyeRunReport(input?: UeyeRunReportInput): UeyeRunReport;
+export declare function buildUeyeDeepVisualReview(input?: Partial<UeyeDeepVisualReview> & Record<string, unknown>): UeyeDeepVisualReview;
 export declare function buildMediaGenerationProof(input?: Partial<MediaGenerationProof>): MediaGenerationProof;
 export declare function isTruthStatus(value?: unknown): value is TruthStatus;
 export declare function weakestTruth(...statuses: unknown[]): TruthStatus;

package/dist/lib/trust-kernel.js

@@ -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.1.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

@@ -7,7 +7,7 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 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 or artifact does, what role it has, what changed, what behavior is expected, and what remains uncertain.
+- 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.
@@ -62,9 +62,11 @@ Use this whenever implementation changed code or any project artifact changed:
 
 - 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 and what behavior the change should produce.
+- 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.
 
@@ -87,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/study-note.md

@@ -1,8 +1,13 @@
-# Study Note
+# 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-specialist learn the meaning of the changed code a little at a time, without hiding uncertainty or padding the final report.
+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
 
@@ -14,23 +19,32 @@ 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.
-- Change meaning: what changed and what behavior the change should produce.
+- 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.
-- Problem meaning: a report could include unfinished requirements without making the completion risk obvious.
-- Change meaning: `uncovered_requirements` now lowers the truth status to blocked and points the next action at the missing requirement.
+- 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.
-- Limits: this does not infer requirements from prose; the agent/user still has to provide them.
+- 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
@@ -41,6 +55,7 @@ For pure Q&A, planning, scouting, or review with no changed artifact, do not for
 
 - 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.
@@ -51,3 +66,4 @@ For pure Q&A, planning, scouting, or review with no changed artifact, do not for
 - 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/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
 

package/skills/deep/SKILL.md

@@ -52,7 +52,7 @@ Use `references/db-supabase-safety-lite.md` for destructive DB/Supabase, migrati
 Use `references/current-docs.md` when SDK/API/cloud-service behavior may be current or version-sensitive.
 Use `references/trust-kernel.md` when the task asks how yam prevents false completion or fake real proof claims.
 Use `references/honest-completion.md`; do not overclaim verification, runtime, cleanup, or visual proof.
-Use `references/study-note.md` when any code, config, docs, release metadata, or project artifact changed.
+Use `references/study-note.md` when any code, config, docs, release metadata, or project artifact changed; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
@@ -77,7 +77,8 @@ Stop condition:
 Include:
 
 - What was changed or reviewed.
-- Study Note for changed artifacts: what changed, what role it has, what was wrong or missing, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Study Note for changed artifacts: what changed, what role it has, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Evidence gathered.
 - Truth status.
 - Blockers or remaining risk.

package/skills/mission/SKILL.md

@@ -87,7 +87,7 @@ Use `references/db-supabase-safety-lite.md` for destructive DB/Supabase, migrati
 Use `references/current-docs.md` when any lane depends on current SDK/API/cloud-service behavior.
 Use `references/verification-levels.md` for L4-L5 mission proof boundaries.
 Use `references/honest-completion.md`; do not overclaim.
-Use `references/study-note.md` for every lane that changes code, config, docs, release metadata, or project artifacts.
+Use `references/study-note.md` for every lane that changes code, config, docs, release metadata, or project artifacts; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items.
 Use `references/token-budget-reporter.md` when budget drift matters.
 
@@ -110,7 +110,8 @@ Report:
 
 - What the mission changed.
 - Role/cross-verification summary.
-- Study Note for any lane that changed code, config, docs, release metadata, or project artifacts: what changed, what role it has, what was wrong or missing, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Study Note for any lane that changed code, config, docs, release metadata, or project artifacts: what changed, what role it has, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Evidence gathered.
 - Truth status.
 - Cleanup status.

package/skills/quick/SKILL.md

@@ -70,7 +70,7 @@ Use `references/truth-matrix.md` for truth labels.
 Use `references/db-supabase-safety-lite.md` when a command or prompt contains DB/Supabase mutation signals.
 Use `references/token-economy.md` to keep context small.
 Use `references/context-reuse.md` before broad project reading.
-Use `references/study-note.md` when any code, config, docs, or project artifact changed.
+Use `references/study-note.md` when any code, config, docs, or project artifact changed; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
@@ -79,7 +79,8 @@ Use `references/token-budget-reporter.md` when a run needs measured budget feedb
 Keep it compact:
 
 - What changed or what the scan found.
-- Study Note when code, config, docs, or project artifacts changed: what changed, what role it has, what was wrong or missing, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Study Note when code, config, docs, or project artifacts changed: what changed, what role it has, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - What was checked.
 - What was skipped, blocked, or still risky.
 - Handoff when useful: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.

package/skills/ueye/SKILL.md

@@ -147,7 +147,7 @@ Use these artifacts for reference-led implementation or serious visual review. K
 
 Use `references/ueye.md` and `references/ui-quality.md`.
 Use `references/verification-levels.md` for visual proof levels and done-claim truth caps.
-Use `references/study-note.md` when UI code, design docs, config, or project artifacts changed.
+Use `references/study-note.md` when UI code, design docs, config, or project artifacts changed; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Always consider:
 
 - Direction fit.
@@ -173,6 +173,7 @@ Report:
 - Review continuity/comparison result when this continues a prior Ueye run.
 - P0-P3 issues or confirmation that no blockers were found.
 - States/viewports checked.
-- Study Note when UI code, design docs, config, or project artifacts changed: what changed, what role it has, what was wrong or missing, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Study Note when UI code, design docs, config, or project artifacts changed: what changed, what role it has, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated UI logic into `page.tsx`, one-off component styling into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Truth status and visual verification cap.
 - Handoff when useful: fix-first visual issues, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.