yam-flow 2.1.0 → 2.2.1

package/AGENTS.md

@@ -16,7 +16,8 @@
 14. For UI work, inspect real states and responsive behavior when feasible.
 15. For long-running processes, do not claim cleanup unless process exit is checked.
 16. When code, config, release metadata, documentation, or project artifacts changed, include a Study Note even if no yam skill was explicitly invoked.
-17. Explain useful change insight for non-specialists: what the touched code or artifact does, what role it has, what was wrong or missing, what changed, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+17. Explain useful change insight for non-specialists: what the touched code or artifact does, what role it has, where it runs or is read, what was wrong or missing, what changed before/after, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
 18. Use external references deliberately, preserve source clarity in research/proof notes, and rework good ideas into yam style.
 19. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
 20. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
+21. When relevant, include architecture hygiene in the Study Note: 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.

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.2.1 - 2026-07-09
+
+### Improved
+
+- Strengthened `$scout` into a wider research harness with source mapping, evidence ledger, opposition pass, and blocked-source fallback guidance.
+- Added `references/scout-wide-scan.md` for broad searches across tools, agent systems, protocols, harnesses, markets, and third-party ecosystems.
+- Clarified that `insane-search` should be used as blocked-source acquisition for high-signal sources, not as Scout's default search path.
+- Clarified that real subagent or parallel research lanes are explicit-only and should not turn ordinary scouting into `$mission`.
+
+## v2.2.0 - 2026-07-07
+
+### Added
+
+- Added `yam study-note check` as a read-only Study Note Guard Lite for changed files and supplied final-report text.
+- Added an opt-in `study-note` hook profile via `yam hook enable study-note --global` for prompt-time Study Note reminders without auto-generating or editing reports.
+- Extended `yam loop report --json` with resume-ready handoff fields: touched/read/verified files, skipped checks, stop condition, resume hint, and readiness state.
+- Added Ueye deep visual review fields for acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
+
+### Improved
+
+- Strengthened Study Note v3 guidance for non-developer learning with execution point, before/after behavior, expected behavior, and architecture hygiene checks for `page.tsx`, `global.css`, and DB `jsonb` boundaries.
+- Strengthened Ueye guidance so serious UI work can carry Deep-grade verification inside the Ueye route without requiring a separate Deep route.
+
 ## v2.1.0 - 2026-06-30
 
 ### Added

package/COMMANDS.md

@@ -45,7 +45,7 @@ Opt-in visual evidence helpers:
 yam ueye preflight /path/to/project --json
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --brief-dimension "primary CTA clarity" --constraint "mobile first" --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --brief-dimension "primary CTA clarity" --constraint "mobile first" --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 --skipped-check "hover state not checked on touch viewport" --residual-risk "tablet breakpoint still needs visual pass" --stop-condition "stop after primary states are checked and residual risk is recorded" --resume-hint "capture tablet screenshot next" --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
@@ -148,7 +148,8 @@ yam tools doctor /path/to/project
 yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
-yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
+yam study-note check /path/to/project --text "Study Note: Touched code role before/after verification limits." --json
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
@@ -196,12 +197,14 @@ Supported report shapes:
 - Runtime evidence mini: command/process, observation, cleanup, truth status, next action.
 - Patch queue lite: mission lane status, changed files, verification hint, rollback hint, truth status.
 - Verification Ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, L5 bounded deep with stop condition and skipped/remaining work.
-- Loop report: intent, guided stage outcomes, evidence level/stamp, blockers, blocker kind, safe retry, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route/scope, side effects, and study note.
-- Study note: short non-specialist explanation of the changed code/artifact, its role, what was wrong or missing, expected behavior, one syntax/structure insight, verification, and uncertainty.
+- Loop report: intent, guided stage outcomes, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, evidence level/stamp, blockers, blocker kind, safe retry, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route/scope, side effects, and study note.
+- Study note: non-specialist explanation of the changed code/artifact, its role, execution point, before/after behavior, expected behavior, one syntax/structure insight, verification, uncertainty, and architecture hygiene around `page.tsx`, `global.css`, and DB `jsonb`.
+- Study Note guard: read-only check for changed files and supplied final-report text; opt into prompt-time reminders with `yam hook enable study-note --global`.
 - Benchmark optimization loop lite: baseline, one change, rerun, keep/revert decision.
 - Structured diagnostic next action: severity, evidence, owner route, next action, truth status.
 - Ueye continuity/comparison: previous report, current report, comparison delta, design quality, next action.
 - Ueye design brief/anti-slop: brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom P0 blockers.
+- Ueye deep visual review: acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
 - Context pressure: project pack age/size, memory summary, dirty scope, scripts, instruction surfaces, and route hint.
 - Cleanup scan: advisory-only list of confusing surfaces with destructive=false.
 
@@ -212,5 +215,7 @@ Advisory-only hook. It does not run checks or force routes.
 ```bash
 yam hook status --global
 yam hook enable lite --global
+yam hook enable study-note --global
 yam hook disable lite --global
+yam hook disable study-note --global
 ```

package/README.md

@@ -134,6 +134,7 @@ yam tools doctor /path/to/project
 yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
+yam study-note check /path/to/project --text "Study Note: ..." --json
 yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
@@ -141,17 +142,18 @@ yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"refe
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
 yam ueye preflight /path/to/project --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --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 --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --acceptance-criterion "primary CTA remains visible on mobile" --state-check default:pass --state-check mobile:partial --implementation-evidence "browser screenshot reviewed" --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 --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
 yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
-yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam release report --json
 yam safety "supabase db reset"
 yam detect /path/to/project
 yam pack /path/to/project
 yam hook status --global
 yam hook enable lite --global
+yam hook enable study-note --global
 yam hook disable lite --global
 yam budget ueye
 yam measure ueye --files 5 --commands 2 --report-lines 12 --seconds 180
@@ -220,8 +222,9 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Patch queue lite: `$mission` lane records with pending/applied/verified/reverted/blocked state, changed files, verification hint, rollback hint, truth status, and next action.
 - Verification Ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, and L5 bounded deep. Heavier claims require heavier evidence, but stop conditions prevent endless proof loops.
 - Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, readiness receipt, and final truth status.
-- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, tool intent, truth status, and study note.
-- Study note: `yam.study-note.v1` and `references/study-note.md` keep non-specialist explanations for what code/artifact changed, what role it plays, what was wrong or missing, what behavior is expected, one syntax/structure insight, what was verified, and what remains uncertain. Missing details stay in `limits` instead of being guessed.
+- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, tool intent, truth status, and study note.
+- Study note: `yam.study-note.v1` and `references/study-note.md` keep non-specialist explanations for what code/artifact changed, what role it plays, where it runs, what changed from before to after, what behavior is expected, one syntax/structure insight, what was verified, and what remains uncertain. Missing details stay in `limits` instead of being guessed. Study Note v3 also asks whether work was dumped into `page.tsx`, `global.css`, or broad DB `jsonb` when a smaller component, style module/token, typed column, relation, or validation schema would teach and scale better.
+- Study Note guard: `yam study-note check` is a read-only missing-note guard. It checks changed files against supplied final-report text and can be used directly or through the opt-in `yam hook enable study-note --global` advisory hook.
 - Avoidance note: loop reports may include one short mistake-to-avoid note, but durable memory stays explicit through `yam memory add`; `yam loop report` does not write `.yam/memory`.
 - Publish blocker evidence: release reports classify common npm auth, permission, OTP, immutable-version, cache, registry, and tarball failures into safe next actions.
 - Publish readiness evidence: release reports run read-only registry/auth/version probes, redact account/token details, keep npm publish outside the report, and include a `yam.release-readiness-receipt.v1` basis for the readiness judgment.
@@ -233,6 +236,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Ueye design completion gate: `$ueye` can stay fast for draft work, but a `done` claim is capped until implementation evidence, comparison/design-quality status, P0/P1 status, key states, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, and direction/reference-read proof are recorded when relevant.
 - Ueye design brief and anti-slop review: `$ueye` reports can record operator-provided brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom anti-slop blockers. P0 anti-slop findings block `done` claims.
+- Ueye deep visual review: `$ueye` can record acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and a state matrix so serious UI work can carry Deep-grade verification without leaving the Ueye route.
 
 ## Ueye Capture And Compare
 
@@ -242,14 +246,14 @@ These shapes keep reports machine-readable without turning normal work into a he
 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 preflight . --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --brief-dimension "primary CTA clarity" --constraint "mobile first" --anti-slop "placeholder copy remains" --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 --brief-dimension "primary CTA clarity" --constraint "mobile first" --anti-slop "placeholder copy remains" --acceptance-criterion "pricing card 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 --skipped-check "hover state not checked on touch viewport" --residual-risk "tablet breakpoint still needs visual pass" --stop-condition "stop after primary states are checked and residual risk is recorded" --resume-hint "capture tablet screenshot next" --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 Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
 
 `compare` is local-only and dependency-free. It records file hashes, dimensions, comparison result, and proof-ready visual provenance. Exact image matches can be `verified`; different screenshots stay `partial` so visual parity is not overclaimed.
 
-`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, design completion gate, surface context, and next action into one compact proof-ready JSON object. Draft and needs-polish work can stay fast; `--completion-claim done` turns on the stricter design gate.
+`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, design completion gate, deep visual review, surface context, and next action into one compact proof-ready JSON object. Draft and needs-polish work can stay fast; `--completion-claim done` turns on the stricter design gate.
 
 `preflight` does not claim visual verification. It is a pre-work checklist for reference source, target states, mobile/responsive needs, CTA/contrast/accessibility risk, screenshot availability, and likely P0/P1 candidates.
 

package/dist/bin/yam.js

@@ -50,6 +50,7 @@ const PROJECT_PACK = 'yam.project.md';
 const LEGACY_PROJECT_PACK = 'timeto.project.md';
 const PACK_STALE_DAYS = 30;
 const YAM_LITE_HOOK_COMMAND = `node ${path.join(ROOT, 'dist', 'bin', 'yam.js')} hook run lite`;
+const YAM_STUDY_NOTE_HOOK_COMMAND = `node ${path.join(ROOT, 'dist', 'bin', 'yam.js')} hook run study-note`;
 const REQUIRED_PACK_SECTIONS = [
     'Product Direction',
     'UI Direction',
@@ -122,6 +123,7 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam study-note check [dir] [--report file|--text text] [--json]
   yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
@@ -134,7 +136,7 @@ Usage:
   yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
-  yam hook <status|enable|disable|run> [lite] [--global|--project dir]
+  yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
   yam template <project|ueye|mission|proof|tuning>
   yam tune-log [dir]
   yam install
@@ -531,6 +533,12 @@ function normalizeLoopEvidenceLevelFlag(value = '') {
         return text;
     return 'none';
 }
+function normalizeReadinessStateFlag(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['usable', 'degraded', 'blocked', 'unknown'].includes(text))
+        return text;
+    return 'unknown';
+}
 function uniqueNextActionDetails(actions = []) {
     const seen = new Set();
     const unique = [];
@@ -708,6 +716,124 @@ async function cleanup(args = []) {
     console.error(`unknown cleanup command: ${subcommand}`);
     return cleanupUsage();
 }
+async function studyNote(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return studyNoteUsage();
+    if (subcommand === 'check')
+        return studyNoteCheck(args.slice(1));
+    console.error(`unknown study-note command: ${subcommand}`);
+    return studyNoteUsage();
+}
+function studyNoteUsage() {
+    console.log(`yam study-note
+
+Usage:
+  yam study-note check [dir] [--report file|--text text] [--json]
+
+Notes:
+  Read-only guard. It checks whether changed work has a Study Note and whether relevant UI/CSS/DB hygiene was reported.
+  It does not generate, edit, or infer the Study Note for you.
+`);
+}
+async function studyNoteCheck(args = []) {
+    const flags = parseSimpleFlags(args, new Set(['report', 'text', 'json']));
+    const dir = path.resolve(firstPositional(args) || process.cwd());
+    const changedFiles = await gitChangedFiles(dir);
+    const reportText = await readStudyNoteReportText(flags, dir);
+    const needsStudyNote = changedFiles.length > 0;
+    const hygieneRequirements = studyNoteHygieneRequirements(changedFiles);
+    const checks = [
+        studyNoteGuardCheck('changed_files', needsStudyNote ? 'pass' : 'skipped', needsStudyNote ? 'changed files detected; Study Note is required before final completion' : 'no changed files detected'),
+        studyNoteGuardCheck('study_note_present', !needsStudyNote || hasStudyNoteMarker(reportText) ? 'pass' : 'fail', 'final report should include a Study Note when project artifacts changed'),
+        studyNoteGuardCheck('role_or_responsibility', !needsStudyNote || /(\brole\b|\bresponsib|\bdoes\b|역할|기능)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should explain what the touched code/artifact does'),
+        studyNoteGuardCheck('before_after_or_change', !needsStudyNote || /(\bbefore\b|\bafter\b|before\/after|changed|change meaning|바뀌|변경|수정)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should explain what changed from before to after'),
+        studyNoteGuardCheck('verification_or_limits', !needsStudyNote || /(verification|verified|checked|limits|uncertain|검증|확인|한계|모르는)/i.test(reportText) ? 'pass' : 'fail', 'Study Note should say what was checked and what remains uncertain')
+    ];
+    for (const requirement of hygieneRequirements) {
+        checks.push(studyNoteGuardCheck(requirement.id, requirementSatisfied(reportText, requirement), requirement.note));
+    }
+    const blockers = checks.filter((check) => check.status === 'fail').map((check) => `${check.id}: ${check.next_action}`);
+    const result = {
+        schema: 'yam.study-note-guard.v1',
+        generated_at: new Date().toISOString(),
+        project: dir,
+        changed_files: changedFiles,
+        changed_file_count: changedFiles.length,
+        report_source: flags.report ? path.resolve(dir, String(flags.report)) : flags.text ? 'inline_text' : 'not_provided',
+        checks,
+        blockers,
+        next_action: blockers[0] || (needsStudyNote ? 'Study Note guard passed for the supplied report text' : 'no Study Note required because no changed files were detected'),
+        truth_status: blockers.length ? 'blocked' : needsStudyNote ? 'verified' : 'skipped'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Study Note guard');
+    if (blockers.length)
+        process.exitCode = 1;
+}
+function firstPositional(args = []) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = String(args[index] || '');
+        if (arg.startsWith('--')) {
+            if (!arg.includes('=') && !['--json'].includes(arg))
+                index += 1;
+            continue;
+        }
+        if (arg === 'check')
+            continue;
+        return arg;
+    }
+    return '';
+}
+async function gitChangedFiles(dir) {
+    const output = runReadOnlyCommandIn(dir, 'git', ['status', '--short']);
+    return output
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => line.replace(/^..\s+/, '').replace(/^.* -> /, ''))
+        .map((line) => line.trim())
+        .filter((file) => file && !file.startsWith('dist/') && !file.endsWith('.tgz'));
+}
+async function readStudyNoteReportText(flags, dir) {
+    if (flags.text)
+        return String(flags.text || '');
+    if (!flags.report)
+        return '';
+    const file = path.resolve(dir, String(flags.report));
+    try {
+        return await fsp.readFile(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function hasStudyNoteMarker(text = '') {
+    return /(study note|study-note|학습\s*노트|스터디\s*노트)/i.test(text);
+}
+function studyNoteGuardCheck(id, status, nextAction) {
+    return {
+        id,
+        status,
+        next_action: nextAction,
+        truth_status: status === 'pass' ? 'verified' : status === 'fail' ? 'blocked' : status === 'skipped' ? 'skipped' : 'partial'
+    };
+}
+function studyNoteHygieneRequirements(files = []) {
+    const requirements = [];
+    if (files.some((file) => /(^|\/)page\.tsx$/i.test(file))) {
+        requirements.push({ id: 'page_tsx_hygiene', terms: ['page.tsx', 'component', 'hook', 'helper', 'server action', 'route'], note: 'Study Note should say whether page.tsx stayed focused or needs component/hook/helper/server-action separation' });
+    }
+    if (files.some((file) => /(^|\/)global\.css$/i.test(file))) {
+        requirements.push({ id: 'global_css_hygiene', terms: ['global.css', 'token', 'component', 'scoped', 'module', 'utility'], note: 'Study Note should say whether CSS belongs globally or should move to tokens/scoped/component styles' });
+    }
+    if (files.some((file) => /(migration|schema|db|database|sql|prisma|drizzle|supabase)/i.test(file))) {
+        requirements.push({ id: 'jsonb_hygiene', terms: ['jsonb', 'column', 'table', 'constraint', 'index', 'schema', 'relation'], note: 'Study Note should say whether structured product data belongs in typed columns/tables/constraints/indexes instead of broad DB jsonb' });
+    }
+    return requirements;
+}
+function requirementSatisfied(text = '', requirement) {
+    const normalized = String(text || '').toLowerCase();
+    return requirement.terms.some((term) => normalized.includes(term.toLowerCase())) ? 'pass' : 'fail';
+}
 function cleanupUsage() {
     console.log(`yam cleanup
 
@@ -1271,20 +1397,20 @@ function hookUsage() {
 
 Usage:
   yam hook status [--global|--project dir]
-  yam hook enable lite [--global|--project dir]
-  yam hook disable [lite] [--global|--project dir]
-  yam hook run lite
+  yam hook enable <lite|study-note> [--global|--project dir]
+  yam hook disable [lite|study-note] [--global|--project dir]
+  yam hook run <lite|study-note>
 
 Notes:
-  yam-lite is opt-in and advisory-only. It does not run checks, tmux, subagents, or proof gates.
+  hooks are opt-in and advisory-only. They do not run tmux, subagents, or proof gates.
 `);
 }
 function parseHookArgs(args = []) {
     const result = { mode: 'project', projectDir: process.cwd(), profile: 'lite' };
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
-        if (arg === 'lite') {
-            result.profile = 'lite';
+        if (arg === 'lite' || arg === 'study-note') {
+            result.profile = arg;
         }
         else if (arg === '--global') {
             result.mode = 'global';
@@ -1309,13 +1435,19 @@ function hookPathFor(parsed) {
 function isYamLiteHook(handler = {}) {
     return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run lite');
 }
-function stripYamLiteHooks(config = {}) {
+function isYamStudyNoteHook(handler = {}) {
+    return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run study-note');
+}
+function isYamHookProfile(handler = {}, profile = 'lite') {
+    return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
+}
+function stripYamHooks(config = {}, profile = 'lite') {
     const next = { ...config };
     for (const event of Object.keys(next)) {
         const entries = Array.isArray(next[event]) ? next[event] : [];
         const keptEntries = [];
         for (const entry of entries) {
-            const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamLiteHook(handler)) : [];
+            const hooks = Array.isArray(entry?.hooks) ? entry.hooks.filter((handler) => !isYamHookProfile(handler, profile)) : [];
             const rest = { ...entry, hooks };
             if (hooks.length > 0)
                 keptEntries.push(rest);
@@ -1327,14 +1459,14 @@ function stripYamLiteHooks(config = {}) {
     }
     return next;
 }
-function withYamLiteHook(config = {}) {
-    const next = stripYamLiteHooks(config);
+function withYamHook(config = {}, profile = 'lite') {
+    const next = stripYamHooks(config, profile);
     const event = 'UserPromptSubmit';
     const entry = {
         hooks: [
             {
                 type: 'command',
-                command: YAM_LITE_HOOK_COMMAND,
+                command: profile === 'study-note' ? YAM_STUDY_NOTE_HOOK_COMMAND : YAM_LITE_HOOK_COMMAND,
                 timeout: 5
             }
         ]
@@ -1346,26 +1478,29 @@ async function hookStatus(args = []) {
     const parsed = parseHookArgs(args);
     const target = hookPathFor(parsed);
     const config = await readJsonOrDefault(target, {});
-    const enabled = hookConfigHasYamLite(config);
-    console.log(`yam-lite hook: ${enabled ? 'enabled' : 'disabled'}`);
+    console.log(`yam-lite hook: ${hookConfigHasProfile(config, 'lite') ? 'enabled' : 'disabled'}`);
+    console.log(`yam-study-note hook: ${hookConfigHasProfile(config, 'study-note') ? 'enabled' : 'disabled'}`);
     console.log(`scope: ${parsed.mode}`);
     console.log(`file: ${target}`);
 }
 function hookConfigHasYamLite(config = {}) {
+    return hookConfigHasProfile(config, 'lite');
+}
+function hookConfigHasProfile(config = {}, profile = 'lite') {
     return Object.values(config).some((entries) => Array.isArray(entries) && entries.some((entry) => {
-        return Array.isArray(entry?.hooks) && entry.hooks.some(isYamLiteHook);
+        return Array.isArray(entry?.hooks) && entry.hooks.some((handler) => isYamHookProfile(handler, profile));
     }));
 }
 async function hookEnable(args = []) {
     const parsed = parseHookArgs(args);
-    if (parsed.profile !== 'lite') {
-        console.error('Only yam-lite hook is supported: yam hook enable lite');
+    if (!['lite', 'study-note'].includes(parsed.profile)) {
+        console.error('Only lite and study-note hooks are supported: yam hook enable <lite|study-note>');
         process.exitCode = 1;
         return;
     }
     const target = hookPathFor(parsed);
     const current = await readJsonOrDefault(target, {});
-    const next = withYamLiteHook(current);
+    const next = withYamHook(current, parsed.profile);
     await fsp.mkdir(path.dirname(target), { recursive: true });
     if (await exists(target)) {
         const backup = `${target}.yam-backup-${timestampId()}`;
@@ -1373,29 +1508,29 @@ async function hookEnable(args = []) {
         console.log(`backup: ${backup}`);
     }
     await fsp.writeFile(target, `${JSON.stringify(next, null, 2)}\n`);
-    console.log(`yam-lite hook enabled (${parsed.mode}): ${target}`);
+    console.log(`yam-${parsed.profile} hook enabled (${parsed.mode}): ${target}`);
     console.log('Restart Codex or start a new thread if the app does not pick up hook changes immediately.');
 }
 async function hookDisable(args = []) {
     const parsed = parseHookArgs(args);
     const target = hookPathFor(parsed);
     const current = await readJsonOrDefault(target, {});
-    if (!hookConfigHasYamLite(current)) {
-        console.log(`yam-lite hook already disabled (${parsed.mode}): ${target}`);
+    if (!hookConfigHasProfile(current, parsed.profile)) {
+        console.log(`yam-${parsed.profile} hook already disabled (${parsed.mode}): ${target}`);
         return;
     }
-    const next = stripYamLiteHooks(current);
+    const next = stripYamHooks(current, parsed.profile);
     if (Object.keys(next).length === 0) {
         await rmrf(target);
     }
     else {
         await fsp.writeFile(target, `${JSON.stringify(next, null, 2)}\n`);
     }
-    console.log(`yam-lite hook disabled (${parsed.mode}): ${target}`);
+    console.log(`yam-${parsed.profile} hook disabled (${parsed.mode}): ${target}`);
 }
 async function hookRun(args = []) {
     const profile = args[0] || 'lite';
-    if (profile !== 'lite') {
+    if (!['lite', 'study-note'].includes(profile)) {
         console.log(JSON.stringify({ continue: true }));
         return;
     }
@@ -1403,7 +1538,9 @@ async function hookRun(args = []) {
     const event = input?.hook_event_name || input?.hookEventName || input?.event || 'UserPromptSubmit';
     const cwd = String(input?.cwd || process.cwd());
     const prompt = extractPrompt(input);
-    const additionalContext = await buildYamLiteContext({ cwd, prompt });
+    const additionalContext = profile === 'study-note'
+        ? await buildStudyNoteHookContext({ cwd })
+        : await buildYamLiteContext({ cwd, prompt });
     const output = {
         continue: true,
         hookSpecificOutput: {
@@ -1461,6 +1598,26 @@ async function buildYamLiteContext({ cwd, prompt }) {
         lines.push(routeHint);
     return lines.join('\n');
 }
+async function buildStudyNoteHookContext({ cwd }) {
+    const dir = path.resolve(cwd || process.cwd());
+    const changedFiles = await gitChangedFiles(dir);
+    const lines = [
+        'yam Study Note guard active: if this turn changes code, config, release metadata, docs, or project artifacts, include a Study Note in the final response.'
+    ];
+    if (!changedFiles.length) {
+        lines.push('No changed files were detected at prompt time; if you change artifacts during this turn, add the Study Note before final.');
+        return lines.join('\n');
+    }
+    lines.push(`Changed files detected (${Math.min(changedFiles.length, 8)} shown): ${changedFiles.slice(0, 8).join(', ')}`);
+    lines.push('Study Note minimum: touched code/artifact, role, execution point, before/after change, expected behavior, one syntax/structure insight, verification, and limits.');
+    const hygiene = studyNoteHygieneRequirements(changedFiles);
+    if (hygiene.length) {
+        lines.push(`Architecture hygiene required: ${hygiene.map((item) => item.id).join(', ')}.`);
+        lines.push('Report whether the change avoided dumping unrelated logic into page.tsx, one-off CSS into global.css, or structured product data into broad DB jsonb.');
+    }
+    lines.push('This hook is advisory; it does not generate or edit the Study Note.');
+    return lines.join('\n');
+}
 function yamLiteRouteHint(prompt = '') {
     const text = String(prompt || '').toLowerCase();
     if (!text)
@@ -2023,13 +2180,13 @@ function loopUsage() {
 Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, next action, handoff fields, and a short study note. It does not run agents, start processes, publish packages, or write files.
 
 Usage:
-  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
+  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--touched-file file] [--read-file file] [--verified-file file] [--skipped-check text] [--stop-condition text] [--resume-hint text] [--readiness-state usable|degraded|blocked|unknown] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
 `);
 }
 async function loopReport(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return loopUsage();
-    const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'touched-file', 'read-file', 'verified-file', 'skipped-check', 'stop-condition', 'resume-hint', 'readiness-state', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
     const blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
     const report = buildLoopReport({
         route: normalizeRoute(flags.route) || String(flags.route || ''),
@@ -2041,6 +2198,13 @@ async function loopReport(args = []) {
         evidence_level: normalizeLoopEvidenceLevelFlag(flags.evidence_level),
         evidence_stamp: String(flags.evidence_stamp || ''),
         source_digest: String(flags.source_digest || ''),
+        touched_files: arrayFlag(flags.touched_file),
+        read_files: arrayFlag(flags.read_file),
+        verified_files: arrayFlag(flags.verified_file),
+        skipped_checks: arrayFlag(flags.skipped_check),
+        stop_condition: String(flags.stop_condition || ''),
+        resume_hint: String(flags.resume_hint || ''),
+        readiness_state: normalizeReadinessStateFlag(flags.readiness_state),
         covered_requirements: arrayFlag(flags.covered_requirement),
         uncovered_requirements: arrayFlag(flags.uncovered_requirement),
         blockers,
@@ -2099,7 +2263,7 @@ Usage:
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
   yam ueye preflight [dir] [--json]
-  yam ueye report [--reference ref.png] [--actual screenshot.png] [--preflight-id id] [--p0-risk text] [--quality-gate-note text] [--brief-dimension text] [--constraint text] [--anti-slop text] [--invented-metric] [--placeholder-copy] [--generic-visual] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--completion-claim draft|needs-polish|done] [--strict] [--design-score n] [--p0 text] [--p1 text] [--states-checked] [--mobile-checked] [--contrast-checked] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--preflight-id id] [--p0-risk text] [--quality-gate-note text] [--brief-dimension text] [--constraint text] [--anti-slop text] [--invented-metric] [--placeholder-copy] [--generic-visual] [--acceptance-criterion text] [--touched-file file] [--read-file file] [--verified-file file] [--skipped-check text] [--residual-risk text] [--stop-condition text] [--resume-hint text] [--deep-visual-check text] [--design-system-evidence text] [--implementation-evidence text] [--state-check default:pass] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--completion-claim draft|needs-polish|done] [--strict] [--design-score n] [--p0 text] [--p1 text] [--states-checked] [--mobile-checked] [--contrast-checked] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
 
 Notes:
   capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
@@ -2340,7 +2504,7 @@ async function ueyeCompare(args = []) {
 async function ueyeReport(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
-    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'preflight-id', 'p0-risk', 'quality-gate-note', 'brief-dimension', 'constraint', 'anti-slop', 'invented-metric', 'placeholder-copy', 'generic-visual', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'completion-claim', 'completion-status', 'gate-mode', 'strict', 'design-score', 'min-design-score', 'p0', 'p1', 'open-p0', 'open-p1', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'comparison-result', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'preflight-id', 'p0-risk', 'quality-gate-note', 'brief-dimension', 'constraint', 'anti-slop', 'invented-metric', 'placeholder-copy', 'generic-visual', 'acceptance-criterion', 'touched-file', 'read-file', 'verified-file', 'skipped-check', 'residual-risk', 'stop-condition', 'resume-hint', 'deep-visual-check', 'design-system-evidence', 'implementation-evidence', 'state-check', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'completion-claim', 'completion-status', 'gate-mode', 'strict', 'design-score', 'min-design-score', 'p0', 'p1', 'open-p0', 'open-p1', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'comparison-result', 'json']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     const referenceSources = [];
@@ -2446,6 +2610,20 @@ async function ueyeReport(args = []) {
             direction_locked: Boolean(flags.direction_locked),
             reference_read: Boolean(flags.reference_read)
         },
+        deep_visual_review: {
+            acceptance_criteria: arrayFlag(flags.acceptance_criterion),
+            touched_files: arrayFlag(flags.touched_file),
+            read_files: arrayFlag(flags.read_file),
+            verified_files: arrayFlag(flags.verified_file),
+            skipped_checks: arrayFlag(flags.skipped_check),
+            residual_risks: arrayFlag(flags.residual_risk),
+            stop_condition: String(flags.stop_condition || ''),
+            resume_hint: String(flags.resume_hint || ''),
+            deep_visual_checks: arrayFlag(flags.deep_visual_check),
+            design_system_evidence: arrayFlag(flags.design_system_evidence),
+            implementation_evidence: arrayFlag(flags.implementation_evidence),
+            state_check: arrayFlag(flags.state_check)
+        },
         blocked_reason: blockedReason,
         next_action: String(flags.next_visual_action || flags.next_action || '')
     });
@@ -4200,6 +4378,8 @@ async function main() {
         return tools(process.argv.slice(3));
     if (command === 'proof')
         return proof(process.argv.slice(3));
+    if (command === 'study-note')
+        return studyNote(process.argv.slice(3));
     if (command === 'loop')
         return loop(process.argv.slice(3));
     if (command === 'ueye')