yam-harness 0.1.0 → 0.1.2

package/COMMANDS.md

@@ -22,6 +22,8 @@ $quick
 ```text
 $ueye
 첨부한 레퍼런스 이미지의 분위기를 참고해서 가격 카드 UI를 고급스럽게 개선해줘.
+구현 전에 레퍼런스에서 읽은 디자인 특징을 짧게 증명하고,
+구현 후 레퍼런스와 결과물을 비교해서 비슷한 점과 다른 점을 정리해줘.
 이 프로젝트의 디자인 방향성과 맞게 구현하고,
 가능하면 기본/모바일/오류 상태를 실제 화면 기준으로 확인해줘.
 ```
@@ -33,6 +35,10 @@ $ueye
 가능한 안전한 수정안을 제안해줘.
 ```
 
+```text
+yam template ueye-comparison
+```
+
 ## Review-Only
 
 ```text

package/README.md

@@ -17,7 +17,7 @@ End with remaining tasks and fix-first items.
 ## Routes
 
 - `$quick`: fast scoped implementation, small fixes, and quick error scans.
-- `$ueye`: design-heavy UI/UX implementation and screenshot-led visual review.
+- `$ueye`: tight UI/UX/design implementation and visual review with reference-read proof, comparison, and quality judgment.
 - `$question`: direct Q&A without turning simple questions into research projects.
 - `$scout`: bounded investigation and recommendation.
 - `$deep`: single-agent heavy verification by request, including runtime/tmux/browser/process proof when needed.
@@ -134,6 +134,7 @@ node ./bin/yam.js hook disable lite --global
 node ./bin/yam.js budget ueye
 node ./bin/yam.js measure ueye --files 5 --commands 2 --report-lines 12 --seconds 180
 node ./bin/yam.js template ueye
+node ./bin/yam.js template ueye-comparison
 node ./bin/yam.js template mission
 node ./bin/yam.js template proof
 node ./bin/yam.js tune-log /path/to/project
@@ -150,8 +151,8 @@ node ./bin/yam.js init-project /path/to/project
 The package exposes the `yam` binary. It does not mutate your home directory during package installation.
 
 ```bash
-npx yam-harness list
-npx yam-harness install
+npx -y --package yam-harness yam list
+npx -y --package yam-harness yam install
 npm install -g yam-harness
 yam status
 ```

package/ROADMAP.md

@@ -64,12 +64,13 @@ Tasks:
 
 ### 5. Ueye Workflow
 
-Goal: make screenshot/UI review more repeatable.
+Goal: make screenshot/UI review and reference-led design implementation more repeatable.
 
 Tasks:
 
 - Merge `ui`, `eye`, and `review` into `ueye`. Done.
 - Add Ueye checklist refinements. Done.
+- Add Visual Evidence Inventory, Reference Read Proof, Reference vs Implementation Matrix, and Design Quality Review. Done.
 - Add optional browser/screenshot capture notes.
 - Keep image generation optional, never a gate.
 
@@ -252,6 +253,7 @@ Borrowed from Open Design local code and contribution rules:
 - Real preview/screenshot evidence.
 - Compact design direction.
 - P0 visual quality gates over placeholder output.
+- Post-implementation design quality judgment across hierarchy, spacing, typography, color, component detail, interaction, responsiveness, accessibility, and brand fit.
 
 Kept out by design:
 

package/bin/yam.js

@@ -39,7 +39,7 @@ const RETIRED_SKILLS = [
 
 const DEST = process.env.YAM_SKILLS_HOME || process.env.TIMETO_SKILLS_HOME || path.join(os.homedir(), '.agents', 'skills');
 const CODEX_MIRROR = process.env.YAM_CODEX_MIRROR || process.env.TIMETO_CODEX_MIRROR || path.join(os.homedir(), '.codex', 'skills');
-const VERSION = '0.1.0';
+const VERSION = '0.1.1';
 const PROJECT_PACK = 'yam.project.md';
 const LEGACY_PROJECT_PACK = 'timeto.project.md';
 const PACK_STALE_DAYS = 30;
@@ -65,10 +65,10 @@ const ROUTE_BUDGETS = {
     limits: { files: 8, commands: 2, reportLines: 16, seconds: 300 }
   },
   ueye: {
-    files: 'project direction, target UI surface, visual evidence, nearby component/styles',
+    files: 'project direction, target UI surface, reference/before/after evidence, nearby component/styles',
     commands: 'browser/screenshot when feasible; inspect 1-3 primary images by default; typecheck/build only if UI implementation changed code',
-    report: 'design work, source evidence, max 5 inventory rows, states checked, P0-P3 ledger, before/after, truth cap',
-    expand: 'when direction, reference image, or visual evidence requires it; do not do broad design archaeology for simple tweaks',
+    report: 'visual evidence inventory, reference read proof, reference-vs-implementation matrix, design quality review, P0-P3 ledger, truth cap',
+    expand: 'when reference fidelity, responsive/state risk, or visual evidence requires it; do not do broad design archaeology for simple tweaks',
     limits: { files: 10, commands: 3, reportLines: 28, seconds: 600 }
   },
   question: {
@@ -291,6 +291,7 @@ async function verify({ quiet = false } = {}) {
     'risk-escalation.md',
     'quick.md',
     'ueye.md',
+    'ueye-proof.md',
     'ui-quality.md',
     'question.md',
     'mission.md',
@@ -319,7 +320,7 @@ async function verify({ quiet = false } = {}) {
       if (!hasHeading(projectTemplate, section)) issues.push(`project template missing section: ${section}`);
     }
   }
-  for (const template of ['ueye-review.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md']) {
+  for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md']) {
     if (!await exists(path.join(ROOT, 'templates', template))) issues.push(`missing template: ${template}`);
   }
 
@@ -1653,6 +1654,8 @@ async function printTemplate(name = '') {
   const map = {
     project: PROJECT_PACK,
     ueye: 'ueye-review.md',
+    'ueye-comparison': 'ueye-comparison.md',
+    ueyecompare: 'ueye-comparison.md',
     mission: 'mission-plan.md',
     proof: 'runtime-proof.md',
     runtime: 'runtime-proof.md',
@@ -1660,7 +1663,7 @@ async function printTemplate(name = '') {
   };
   const file = map[key];
   if (!file) {
-    console.error('usage: yam template <project|ueye|mission|proof|tuning>');
+    console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning>');
     process.exitCode = 1;
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-harness",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Progressive proof-first Codex harness: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/ueye-proof.md

@@ -0,0 +1,109 @@
+# Ueye Proof
+
+Ueye proof keeps visual claims honest without turning design review into a heavy release gate.
+
+## When To Use
+
+Use Ueye proof artifacts when:
+
+- The user asks for UI/UX/design review.
+- A reference image, screenshot, or target design is part of the task.
+- The final answer needs to claim visual quality, visual parity, or responsive correctness.
+- A screenshot or browser check exists and should be tied to the conclusion.
+
+Skip or compress them when:
+
+- The change is text-only or documentation-only.
+- The user asks for a quick opinion and no visual source exists.
+- The only possible evidence is code reading; mark the result `assumed` or `partial`.
+
+## Artifact Set
+
+### Visual Evidence Inventory
+
+Purpose: identify what visual sources were inspected.
+
+Minimum useful fields:
+
+- Label:
+- Type:
+- Path/URL:
+- Dimensions:
+- sha256:
+- Viewport:
+- State:
+- Role:
+
+Bounds:
+
+- Default to 1-3 primary visual sources.
+- Cap ordinary inventories at 5 rows.
+- Record missing dimensions or hashes as `unknown`, not as failure.
+- Use generated annotations only as derivative aids.
+
+### Reference Read Proof
+
+Purpose: separate reading the reference from judging the implementation.
+
+Capture:
+
+- Layout:
+- Hierarchy:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Brand/mood:
+
+Keep this concise. It should explain what the reference asks for, not become a full design essay.
+
+### Reference vs Implementation Matrix
+
+Purpose: compare reference direction against the actual implementation evidence.
+
+Status values:
+
+- `matched`
+- `similar`
+- `different`
+- `not-verified`
+- `not-applicable`
+
+Rows to use only when relevant:
+
+- Layout and spacing.
+- Visual hierarchy.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility-relevant visuals.
+- Brand and mood fit.
+
+### Design Quality Review
+
+Purpose: judge the implemented UI on design quality after evidence is established.
+
+Dimensions:
+
+- Visual hierarchy.
+- Layout and spacing.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility.
+- Brand and mood fit.
+
+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`.
+
+## Truth Caps
+
+- Full visual verification requires real implementation evidence and relevant recheck.
+- 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`.

package/references/ueye.md

@@ -57,6 +57,94 @@ Bound:
 - Generated callout images are optional and should usually be at most one per review pass.
 - P0/P1 issues can expand the review; P2/P3 should stay top-few unless the user asks for a full polish pass.
 
+## Ueye Proof Artifacts
+
+Use these when the task depends on visual truth, reference matching, or design quality judgment. They are proof aids, not a separate lite/deep split.
+
+1. Visual Evidence Inventory.
+2. Reference Read Proof.
+3. Reference vs Implementation Matrix.
+4. Design Quality Review.
+
+Default bound:
+
+- Use only the artifacts that support the claim being made.
+- Keep evidence to the smallest set of screenshots, references, or URLs that can honestly support the result.
+- Prefer paths, URLs, dimensions, and hashes for images when available.
+- Do not require voxel grids, exhaustive callouts, or generated annotations.
+- Do not let proof artifacts turn Ueye into always-on heavy orchestration.
+
+### Visual Evidence Inventory
+
+Record the real screens and image sources behind the review.
+
+Include when known:
+
+- Label.
+- Type: implementation screenshot, browser URL, user screenshot, reference image, artifact export, generated annotation.
+- Path or URL.
+- Dimensions.
+- sha256.
+- Viewport or device.
+- State: default, loading, error, empty, disabled, hover/focus, mobile, or unknown.
+- Role: proof, reference direction, annotation, or partial evidence.
+
+Images without hashes or dimensions can still be useful, but mark the missing fields plainly.
+
+### Reference Read Proof
+
+Before judging a reference match, state what was actually read from the reference.
+
+Keep it visual and bounded:
+
+- Layout structure.
+- Hierarchy and emphasis.
+- Typography feel.
+- Color and contrast.
+- Component shapes and details.
+- Interaction or motion cues when visible.
+- Responsive implication if the reference includes multiple sizes.
+- Brand or mood fit.
+
+Reference read proof describes the direction. It is not proof that the implementation matches.
+
+### Reference vs Implementation Matrix
+
+Use when a user supplies, names, or implies a reference visual.
+
+Compare only meaningful dimensions:
+
+- Layout and spacing.
+- Visual hierarchy.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility-relevant visual behavior.
+- Brand or mood fit.
+
+For each row, record `matched`, `similar`, `different`, `not-verified`, or `not-applicable`, plus the smallest evidence note.
+
+### Design Quality Review
+
+Use as the judgment layer after evidence is separated and reference comparison is complete.
+
+Review dimensions:
+
+- Visual hierarchy.
+- Layout and spacing.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility.
+- Brand and mood fit.
+
+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.
+
 ## P0-P3 Ledger
 
 - P0: blocker, unusable, impossible to complete primary workflow, severe accessibility or responsive failure.
@@ -67,12 +155,15 @@ Bound:
 ## Implementation Loop
 
 1. Direction fit.
-2. Source-screen inventory.
-3. Nearby pattern and token scan.
-4. Implementation.
-5. Screenshot/browser recheck when feasible.
-6. P0/P1 closeout.
-7. Truth status.
+2. Visual Evidence Inventory.
+3. Reference Read Proof when a reference is used.
+4. Nearby pattern and token scan.
+5. Implementation.
+6. Screenshot/browser recheck when feasible.
+7. Reference vs Implementation Matrix when reference fidelity matters.
+8. Design Quality Review.
+9. P0/P1 closeout.
+10. Truth status.
 
 ## Truth Caps
 

package/skills/ueye/SKILL.md

@@ -9,6 +9,7 @@ Use for:
 
 - Design-heavy UI/UX implementation.
 - Reference-image-based UI direction.
+- Reference-image-based visual fidelity work where the result must be compared against the reference.
 - Screenshot, URL, or current-screen UX review.
 - Pre-fix and post-fix visual QA.
 - UI states, responsive behavior, hierarchy, CTA, contrast, alignment, spacing, and affordance.
@@ -23,6 +24,8 @@ Do not use for:
 
 - Direction before execution.
 - Visual evidence before visual claims.
+- Ueye is the tight UX/UI/design route, not Quick with screenshots.
+- Reference-based work requires reference read proof before implementation and reference comparison after implementation.
 - Context-reuse first.
 - Token economy is part of quality.
 - Product fit beats decoration.
@@ -31,6 +34,7 @@ Do not use for:
 - Text-only visual critique cannot be reported as fully verified when screenshot evidence was required.
 - Generated annotated images are optional, not a default gate.
 - Image evidence should stay bounded: inspect the primary screen first, then only the states/images needed to support the claim.
+- Open Design-style quality judgment belongs after implementation/review: compare to the reference first, then judge whether the result is good design.
 
 ## Workflow
 
@@ -41,17 +45,53 @@ Do not use for:
    - local/browser screenshot
    - exported static artifact image
    - URL/current screen, when accessible
-4. Inspect nearby UI patterns, tokens, styles, and state handling.
-5. Implement the smallest coherent design improvement when implementation is requested.
-6. Check default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
-7. Run browser/screenshot verification when feasible.
-8. Produce a P0-P3 visual issue ledger and fix path.
-9. Recheck changed/high-risk screens after fixes when feasible.
+4. When a reference image/screen is used, produce Reference Read Proof before changing UI:
+   - 5-8 concrete observations about layout, spacing, typography, color, hierarchy, component shape, interaction/motion, and brand mood.
+   - Mark any ambiguous or unobservable detail instead of inventing it.
+5. Inspect nearby UI patterns, tokens, styles, and state handling.
+6. Implement the smallest coherent design improvement when implementation is requested.
+7. Check default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
+8. Run browser/screenshot verification when feasible.
+9. Compare reference and implementation when reference fidelity was requested:
+   - matched, similar, different, not-applicable, or not-verified.
+   - Separate "faithful to reference" from "good design."
+10. Run Design Quality Review after implementation/review:
+   - visual hierarchy
+   - layout and spacing
+   - typography
+   - color and contrast
+   - component detail
+   - interaction and motion
+   - responsiveness
+   - 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.
+
+## Required Ueye Artifacts
+
+Use these artifacts for reference-led implementation or serious visual review. Keep them compact for small screens, but do not omit them when the claim depends on reference fidelity.
+
+1. Visual Evidence Inventory:
+   - reference, before, and after evidence when available.
+   - path or URL, source type, state, viewport, and visual verification cap.
+   - sha256 and dimensions when an image file is locally available.
+2. Reference Read Proof:
+   - concrete observations from the reference before implementation.
+   - no implementation claim should depend on an unrecorded reference observation.
+3. Reference vs Implementation Matrix:
+   - compare the implemented result against the reference by aspect.
+   - record matched, similar, different, not-applicable, or not-verified.
+4. 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.
 
 ## Visual Truth Caps
 
 - Full visual verification requires real source-screen evidence.
 - Reference images guide direction; they do not prove the implemented screen unless compared with real source-screen evidence.
+- Reference fidelity claims require both Reference Read Proof and Reference vs Implementation Matrix.
 - Generated or annotated images are derivative evidence; they cannot upgrade missing real screen evidence to `verified`.
 - 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.
@@ -84,6 +124,8 @@ Report:
 
 - What changed visually or what was reviewed.
 - Source evidence used.
+- Reference Read Proof and reference comparison result when a reference was used.
+- Design Quality Review result when implementation or serious visual review was requested.
 - P0-P3 issues or confirmation that no blockers were found.
 - States/viewports checked.
 - Truth status and visual verification cap.

package/templates/ueye-comparison.md

@@ -0,0 +1,78 @@
+# yam Ueye Reference Comparison
+
+## Input
+
+- Implementation screenshot/URL:
+- Reference screenshot/URL/path:
+- Product or screen:
+- Review bound:
+
+## Visual Evidence Inventory
+
+| Label | Type | Path/URL | Dimensions | sha256 | Viewport | State | Role |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| implementation |  |  | unknown | unknown |  |  | proof |
+| reference |  |  | unknown | unknown |  |  | reference direction |
+
+## Reference Read Proof
+
+- Layout:
+- Visual hierarchy:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Brand/mood fit:
+
+## Reference vs Implementation Matrix
+
+Use `matched`, `similar`, `different`, `not-verified`, or `not-applicable`.
+
+| Dimension | Status | Evidence | Suggested Fix |
+| --- | --- | --- | --- |
+| Layout and spacing | not-verified |  |  |
+| Visual hierarchy | not-verified |  |  |
+| Typography | not-verified |  |  |
+| Color and contrast | not-verified |  |  |
+| Component detail | not-verified |  |  |
+| Interaction and motion | not-verified |  |  |
+| Responsiveness | not-verified |  |  |
+| Accessibility visuals | not-verified |  |  |
+| Brand and mood fit | not-verified |  |  |
+
+## Design Quality Review
+
+Use `pass`, `needs-polish`, or `fails` for each relevant design dimension before listing actionable issues.
+
+| Dimension | Result | Evidence |
+| --- | --- | --- |
+| Visual hierarchy | needs-polish |  |
+| Layout/spacing | needs-polish |  |
+| Typography | needs-polish |  |
+| Color/contrast | needs-polish |  |
+| Component detail | needs-polish |  |
+| Interaction/motion | needs-polish |  |
+| Responsiveness | needs-polish |  |
+| Accessibility | needs-polish |  |
+| Brand/mood fit | needs-polish |  |
+
+### P0 Blockers
+
+- None.
+
+### P1 Major
+
+- None.
+
+### P2 Quality
+
+- None.
+
+### P3 Polish
+
+- None.
+
+## Truth Status
+
+- verified / partial / skipped / blocked / assumed:

package/templates/ueye-review.md

@@ -12,14 +12,61 @@
 - Fits project direction:
 - Mismatch:
 
-## Source-Screen Inventory
+## Visual Evidence Inventory
 
 - Evidence bound: 1-3 primary images, max 5 inventory rows by default.
-- Source type:
-- State:
+- Label:
+- Type:
+- Path/URL:
+- Dimensions:
+- sha256:
 - Viewport:
+- State:
+- Role: proof / reference direction / annotation / partial evidence
 - Visual verification cap:
-- Reference/generated image used only as direction or annotation:
+
+## Reference Read Proof
+
+- Layout:
+- Visual hierarchy:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Brand/mood fit:
+
+## Reference vs Implementation Matrix
+
+| Dimension | Status | Evidence |
+| --- | --- | --- |
+| Layout and spacing | not-verified |  |
+| Visual hierarchy | not-verified |  |
+| Typography | not-verified |  |
+| Color and contrast | not-verified |  |
+| Component detail | not-verified |  |
+| Interaction and motion | not-verified |  |
+| Responsiveness | not-verified |  |
+| Accessibility visuals | not-verified |  |
+| Brand and mood fit | not-verified |  |
+
+Status values: matched / similar / different / not-verified / not-applicable.
+
+## Design Quality Review
+
+| Dimension | Result | Evidence |
+| --- | --- | --- |
+| Visual hierarchy | needs-polish |  |
+| Layout/spacing | needs-polish |  |
+| Typography | needs-polish |  |
+| Color/contrast | needs-polish |  |
+| Component detail | needs-polish |  |
+| Interaction/motion | needs-polish |  |
+| Responsiveness | needs-polish |  |
+| Accessibility | needs-polish |  |
+| Brand/mood fit | needs-polish |  |
+
+Result values: pass / needs-polish / fails.
 
 ## P0-P3 Issues
 
@@ -41,14 +88,15 @@
 
 ## Checks
 
-- Hierarchy:
-- CTA:
-- Spacing:
-- Alignment:
-- Contrast:
-- Density:
-- Text fit:
-- Mobile:
+- Visual hierarchy:
+- Layout/spacing:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Accessibility:
+- Brand/mood fit:
 - Empty/loading/error/disabled/hover/focus states:
 
 ## Safe Fix Path

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -22,7 +22,7 @@
     {
       "id": "ueye",
       "stage": "v0.3",
-      "purpose": "Design-heavy UI/UX implementation and screenshot-led visual review with P0-P3 issue tracking."
+      "purpose": "Tight UI/UX/design implementation and visual review with reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
     },
     {
       "id": "question",