yam-flow 2.1.0 → 2.2.1

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

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

package/dist/lib/trust-kernel.js

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

package/package.json

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

package/references/final-report.md

@@ -7,7 +7,7 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 Always keep final reports short. Include these when they apply:
 
 - What changed or what was found.
-- Change insight for non-specialists: what the touched code or artifact does, what role it has, what changed, what behavior is expected, and what remains uncertain.
+- Change insight for non-specialists: what the touched code or artifact does, what role it has, where it runs or is read, what changed, what behavior is expected, one useful syntax/structure insight, and what remains uncertain.
 - What verification ran.
 - What was not checked.
 - Truth status, when verification or runtime claims matter.
@@ -62,9 +62,11 @@ Use this whenever implementation changed code or any project artifact changed:
 
 - What code or artifact changed.
 - What role that code or artifact plays in the project.
+- Where it runs, renders, validates, builds, publishes, or is read.
 - What was wrong, missing, unclear, or risky.
-- What changed and what behavior the change should produce.
+- What changed: before/after behavior or guidance, and what behavior the change should produce.
 - One small syntax, API, schema, or structure insight for a non-specialist.
+- Architecture hygiene when relevant: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
 - What was verified, or why verification is partial/skipped/blocked.
 - What remains uncertain.
 
@@ -87,7 +89,7 @@ Use this when the next run needs a clear starting point:
 - Avoidance note when a repeated mistake should be easy to spot; durable memory still uses explicit `yam memory add`.
 - Owner route, scope owner, and side effects when more than one person or route may continue the work.
 
-`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `covered_requirements`, `uncovered_requirements`, `blocked_kind`, `failure_cause`, `recovery_hint`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, `side_effects`, and `avoidance_note`.
+`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `covered_requirements`, `uncovered_requirements`, `touched_files`, `read_files`, `verified_files`, `skipped_checks`, `stop_condition`, `resume_hint`, `readiness_state`, `blocked_kind`, `failure_cause`, `recovery_hint`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, `side_effects`, and `avoidance_note`.
 
 ## Route Weight
 

package/references/scout-wide-scan.md

@@ -0,0 +1,150 @@
+# Scout Wide Scan
+
+Use this reference when `$scout` needs broad search, powerful outside patterns, ecosystem comparison, agent/harness discovery, or source-heavy direction setting.
+
+## Activation
+
+Use wide scan when the user asks for:
+
+- Broad search or "find powerful patterns".
+- Tool, library, agent, harness, protocol, or market landscape comparison.
+- Third-party perspective before committing to a direction.
+- Evidence from multiple source classes.
+- Ideas worth reworking into yam style.
+
+Do not use wide scan for:
+
+- Stable direct answers.
+- Small implementation tasks.
+- Local code questions that a focused file read answers.
+- Heavy verification; use `$deep`.
+- Real subagent/team execution; use `$mission` unless the user explicitly asks for parallel agent work inside the current route and the environment supports it.
+
+## Scan Lanes
+
+1. Decision frame: name the decision, audience, constraints, and what would change the recommendation.
+2. Source map: decide which source classes are needed before reading deeply.
+3. Acquisition: gather enough sources; recover blocked high-signal sources only when needed.
+4. Triage: rank sources by authority, freshness, relevance, bias, and directness.
+5. Comparison: compare by fit, risk, cost, implementation effort, durability, and evidence quality.
+6. Opposition pass: name the strongest argument against the preferred direction.
+7. Synthesis: compress into a practical recommendation and yam-style rework ideas.
+8. Evidence ledger: record the important claims, evidence, confidence, and uncertainty.
+
+## Source Map
+
+Prefer a small balanced map over a large pile:
+
+- Official or primary source: docs, specs, vendor pages, source repos, standards.
+- Implementation evidence: source code, examples, package metadata, changelogs, local files.
+- Third-party analysis: credible writeups, benchmarks, incident reports, adoption notes.
+- Community evidence: issues, forum posts, social reports, user complaints; useful but lower trust.
+- Contrarian source: the best reason the attractive option may be wrong.
+- Local evidence: project constraints, existing route boundaries, installed tools, package scripts.
+
+Default focused scout remains 3-7 high-signal sources. Wide scan may use more, but stop once the decision is supported and marginal sources repeat what is already known.
+
+## Acquisition Ladder
+
+1. Use local project context packs and relevant local files first when the decision is project-specific.
+2. Use official or primary docs for current SDK/API/cloud-service behavior.
+3. Use ordinary web search or documentation search for accessible external sources.
+4. Use platform-specific public APIs or feeds when they are cleaner than rendered pages.
+5. Use blocked-source fallback only for high-signal sources that ordinary access cannot read.
+
+Blocked-source fallback:
+
+- Treat `insane-search` as a source acquisition subroutine.
+- Use it for blocked/WAF/platform-protected sources such as X, Reddit, YouTube, Naver, LinkedIn, Medium, Substack, or similar pages when they matter to the decision.
+- Preserve provenance: original URL, access path, trace or fallback note, and whether the content came from API, cache, feed, rendered HTML, or archive.
+- Do not use it for ordinary searches that normal web search can handle.
+- Do not treat authentication, paywall, private data, or rate-limit boundaries as something to force through.
+
+## Evidence Ledger
+
+Use a compact ledger for broad scans:
+
+```text
+Claim:
+Evidence:
+Source class:
+Confidence: high / medium / low
+Uncertainty:
+Decision impact:
+```
+
+Keep the ledger short. Include only claims that materially shape the recommendation.
+
+## Parallel Research
+
+Scout stays single-agent by default.
+
+Use real subagents or parallel agent lanes only when all are true:
+
+- The user explicitly asked for subagents, delegation, or parallel agent work.
+- The available environment provides real subagent tools.
+- The questions are independent and self-contained.
+- The results can be summarized without flooding the main context.
+
+Good lanes:
+
+- Official/docs lane.
+- Implementation/source lane.
+- Community/contrarian lane.
+- Security/risk lane.
+
+Bad lanes:
+
+- Multiple agents reading the same sources.
+- Delegating the immediate blocking question.
+- Role-playing subagents when no real subagent tool is available.
+- Turning a normal scout into `$mission`.
+
+## Opposition Pass
+
+Before the recommendation, ask:
+
+- What would make the best pick fail in this project?
+- Which source is least trustworthy or most stale?
+- What is the strongest cheaper/simpler alternative?
+- What security or operational risk is easy to miss?
+- What would we need to verify before implementation?
+
+Report the opposition pass briefly. It should sharpen the recommendation, not bury it.
+
+## Output
+
+Use the normal Scout shape, adding only the sections that help:
+
+- Best pick.
+- Objective judgment.
+- Subjective judgment.
+- Macro / realistic / future view.
+- Alternatives.
+- Risks.
+- Security lens.
+- Opposition pass.
+- Evidence ledger.
+- Ideas to rework into yam style.
+- Sources or local evidence.
+- Remaining tasks.
+
+## Source Clarity
+
+When outside systems shape the answer, preserve boundaries:
+
+- Fact: what the source says or what local files show.
+- Inference: what follows from comparing sources.
+- Opinion: taste, product instinct, or likely user perception.
+- Recommendation: the action Scout would take.
+
+Useful outside patterns to rework, not copy wholesale:
+
+- Agent Skills: progressive disclosure through `SKILL.md` plus optional references/scripts/assets.
+- Deep Research: multi-step search, backtracking, citations, and synthesis.
+- Coding-agent subagents: isolated read-only research lanes for context-heavy side tasks.
+- Agents SDK-style guardrails and tracing: lightweight checks and evidence records around runs.
+- Deep Agents-style harnesses: planning, context offloading, subagents, memory, and human checkpoints.
+- MCP/ACP-style protocols: standard tool/resource discovery and agent-client boundaries.
+
+Keep yam's bias: start with momentum, deepen deliberately, stay security-first, and avoid always-on orchestration.

package/references/scout.md

@@ -14,15 +14,20 @@ Use for:
 - Macro, realistic, and future-facing direction checks.
 - Security-centered direction checks.
 - Reference scans that find useful patterns to rework into yam style.
+- Wide scans across tools, agent systems, protocols, harnesses, markets, or third-party ecosystems.
 
 Default behavior:
 
 - Define the decision clearly.
 - Prefer official or primary sources.
 - Gather 3-7 high-signal references for focused scouting, or more when the user asks for a wide scan.
+- For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community evidence, contrarian sources, and local evidence.
 - Use current docs proof only for modern SDK/API/cloud-service behavior where stale knowledge is plausible.
+- Use blocked-source fallback only when a high-signal source is blocked or platform-protected; treat `insane-search` as source acquisition, not as the default search path.
 - Summarize options and recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use a compact evidence ledger for broad recommendations.
+- Run an opposition pass when false confidence would make the recommendation brittle.
 - Keep source boundaries clear: cite what was read and do not present reference-derived judgment as direct verification.
 - Put security before convenience: auth, payment, DB, secrets, permissions, deployment, supply chain, and public release get called out early.
 - Do not change code unless the user asks.
@@ -36,9 +41,13 @@ Judgment format:
 - Future view: second-order effects, durability, and what may age well or badly.
 - Security view: sensitive surfaces, safer defaults, failure modes, and what a non-specialist might miss.
 - Rework view: what ideas should be adapted into yam style and what should be rejected.
+- Evidence view: important claim, source class, confidence, uncertainty, and decision impact.
+- Opposition view: the strongest reason the preferred direction could be wrong.
 
 Escalate:
 
 - Use `question` for direct answers that do not need sources.
 - Use `deep` only when the user asks for heavy verification.
 - Use implementation routes only after the user asks to change code.
+
+For broad scan mechanics, use `references/scout-wide-scan.md`.

package/references/study-note.md

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

package/references/ueye-proof.md

@@ -26,12 +26,13 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --acceptance-criterion "primary CTA remains visible on mobile" --design-system-evidence "uses existing button token" --implementation-evidence "browser screenshot reviewed" --state-check default:pass --state-check mobile:partial --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 - `capture` uses a project-local capture backend when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
 - `compare` is local-only and dependency-free. It records hashes, dimensions, comparison result, and visual provenance. Different screenshots stay `partial`; exact file matches can be `verified`.
 - `report` records the Ueye run as reference sources, implementation sources, comparison result, surface context, design quality, blocked reason, next action, and truth status.
+- `report` can also record a deep visual review with acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
 - `report` may include continuity fields when a previous review or screenshot is being rechecked.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
@@ -239,6 +240,46 @@ yam proof --route ueye --truth verified --visual "implementation screenshot evid
 
 The design completion gate is a completion judgment. Keep actual source-screen proof in visual evidence, visual provenance, or a Ueye run report. Do not use self-reported gate fields to pretend a missing screenshot was captured.
 
+### Deep Visual Review
+
+Purpose: let Ueye carry Deep-grade UI verification when the work is serious, without forcing a separate route.
+
+Use this when:
+
+- The user asks for strong UI/UX verification.
+- A done claim depends on multiple states, viewports, or design-system fit.
+- A previous Ueye review needs a resume-ready handoff.
+- Missing visual evidence should become an explicit residual risk instead of being hidden.
+
+Minimum useful fields:
+
+- `acceptance_criteria`
+- `touched_files`
+- `read_files`
+- `verified_files`
+- `skipped_checks`
+- `residual_risks`
+- `stop_condition`
+- `resume_hint`
+- `deep_visual_checks`
+- `design_system_evidence`
+- `state_matrix`
+- `implementation_evidence`
+- `truth_status`
+
+State matrix examples:
+
+```bash
+yam ueye report --state-check default:pass --state-check loading:pass --state-check error:partial --state-check mobile:blocked --json
+```
+
+Truth rules:
+
+- Failed or blocked state matrix rows block the deep visual review.
+- Skipped checks and residual risks keep the result honest as `partial` unless other evidence still supports a narrower claim.
+- Deep visual review evidence does not replace a real implementation screenshot when the claim needs visual proof.
+- A stop condition should explain when to stop verifying; a resume hint should explain the next safe visual action.
+
 ### Review Continuity And Comparison Report
 
 Use this when a Ueye task continues a previous visual review, rechecks a fix, or compares two review runs.