yam-flow 2.1.0 → 2.2.1

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/scout/SKILL.md

@@ -16,6 +16,7 @@ Use for:
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing judgment.
 - Broad reference scans when the user needs wider perspective.
+- Wide search across source classes, markets, tools, harnesses, agent patterns, or third-party ecosystems.
 - Security-centered direction checks before implementation.
 - Finding patterns worth reworking into yam style.
 
@@ -31,6 +32,11 @@ Use for:
 - Do not change code unless the user asks.
 - Return a practical recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use an evidence ledger for wide scans: claim, source or local evidence, confidence, and uncertainty.
+- Run an opposition pass for broad recommendations: name the strongest reason the preferred direction may be wrong.
+- Use blocked-source acquisition only when a high-signal source is blocked, protected by WAF, or hosted on a platform that ordinary fetch cannot read.
+- Treat `insane-search` as a source acquisition subroutine, not as Scout's default search path.
+- Use real subagents or parallel agent lanes only when the user explicitly asks for delegation, subagents, or parallel agent work and the environment supports it.
 - Treat "objective" as evidence plus constraints, not certainty theater.
 - Treat "subjective" as named taste, product instinct, and likely user perception.
 - Security is the first lens: call out auth, payment, DB, secrets, permission, deployment, supply-chain, and public-release risks early.
@@ -46,13 +52,17 @@ Use for:
    - design/reference scan
    - product/technical direction memo
    - risk discovery
+   - wide scan
 3. Read `yam.project.md` first when project direction matters.
 4. Gather enough high-signal sources to support the decision; keep source quality higher than source volume.
-5. Compare options by fit, risk, cost, implementation effort, and durability.
-6. Identify security and trust implications before convenience or aesthetics.
-7. Give both objective and subjective judgment when useful.
-8. Recommend a direction and which ideas are worth reworking into yam style.
-9. State uncertainty and what would change the recommendation.
+5. For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community reports, contrarian sources, and local evidence.
+6. Recover blocked high-signal sources through the blocked-source fallback only when ordinary access fails or is predictably blocked.
+7. Compare options by fit, risk, cost, implementation effort, durability, and evidence quality.
+8. Identify security and trust implications before convenience or aesthetics.
+9. Give both objective and subjective judgment when useful.
+10. Run an opposition pass when making a broad recommendation.
+11. Recommend a direction and which ideas are worth reworking into yam style.
+12. State uncertainty and what would change the recommendation.
 
 ## Output
 
@@ -65,6 +75,8 @@ Use concise sections:
 - Alternatives.
 - Risks.
 - Security lens.
+- Evidence ledger.
+- Opposition pass.
 - Ideas to rework into yam style.
 - Sources or local evidence.
 - Remaining tasks or useful next improvements.
@@ -72,6 +84,7 @@ Use concise sections:
 Use `references/token-economy.md`; default to 3-7 high-signal sources unless the user asks for a broad research scan.
 Use `references/current-docs.md` for current SDK/API/cloud-service questions.
 Use `references/context-reuse.md`; do not rescout known decisions unless they may be stale.
+Use `references/scout-wide-scan.md` when the user asks for broad search, powerful outside patterns, harness/agent comparisons, or ecosystem scans.
 Use `references/markdown-management.md` before creating or updating project packs.
 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.

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.

package/src/bin/yam.ts

@@ -24,7 +24,7 @@ import {
   detectDbSafetyText as detectTrustDbSafetyText,
   isTruthStatus
 } from '../lib/trust-kernel.js';
-import type { LoopEvidenceLevel, ToolIntent } from '../lib/trust-kernel.js';
+import type { LoopEvidenceLevel, ReadinessState, ToolIntent } from '../lib/trust-kernel.js';
 
 type AnyRecord = Record<string, any>;
 
@@ -71,6 +71,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',
@@ -144,6 +145,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]
@@ -156,7 +158,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
@@ -532,6 +534,12 @@ function normalizeLoopEvidenceLevelFlag(value = ''): LoopEvidenceLevel {
   return 'none';
 }
 
+function normalizeReadinessStateFlag(value = ''): ReadinessState {
+  const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+  if (['usable', 'degraded', 'blocked', 'unknown'].includes(text)) return text as ReadinessState;
+  return 'unknown';
+}
+
 function uniqueNextActionDetails(actions = []) {
   const seen = new Set<string>();
   const unique = [];
@@ -708,6 +716,126 @@ async function cleanup(args = []) {
   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
 
@@ -1270,12 +1398,12 @@ 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.
 `);
 }
 
@@ -1283,8 +1411,8 @@ 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';
     } else if (arg === '--project') {
@@ -1308,13 +1436,21 @@ function isYamLiteHook(handler: AnyRecord = {}) {
   return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run lite');
 }
 
-function stripYamLiteHooks(config: AnyRecord = {}) {
+function isYamStudyNoteHook(handler: AnyRecord = {}) {
+  return handler?.type === 'command' && String(handler.command || '').includes('yam.js hook run study-note');
+}
+
+function isYamHookProfile(handler: AnyRecord = {}, profile = 'lite') {
+  return profile === 'study-note' ? isYamStudyNoteHook(handler) : isYamLiteHook(handler);
+}
+
+function stripYamHooks(config: AnyRecord = {}, 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);
     }
@@ -1324,14 +1460,14 @@ function stripYamLiteHooks(config: AnyRecord = {}) {
   return next;
 }
 
-function withYamLiteHook(config: AnyRecord = {}) {
-  const next = stripYamLiteHooks(config);
+function withYamHook(config: AnyRecord = {}, 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
       }
     ]
@@ -1344,28 +1480,32 @@ 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,7 +1513,7 @@ 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.');
 }
 
@@ -1381,22 +1521,22 @@ 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;
   }
@@ -1404,7 +1544,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: {
@@ -1458,6 +1600,27 @@ async function buildYamLiteContext({ cwd, prompt }) {
   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) return '';
@@ -2022,13 +2185,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 || ''),
@@ -2040,6 +2203,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,
@@ -2094,7 +2264,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.
@@ -2331,7 +2501,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 = [];
@@ -2436,6 +2606,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 || '')
   });
@@ -4193,6 +4377,7 @@ async function main() {
   if (command === 'measure') return measure(process.argv[3], process.argv.slice(4));
   if (command === 'tools') 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') return ueye(process.argv.slice(3));
   if (command === 'media') return media(process.argv.slice(3));