yam-flow 1.9.1 → 2.1.0

package/AGENTS.md

@@ -8,14 +8,15 @@
 6. Check local project fit before changing code, even for small work.
 7. Prefer existing project patterns over new abstractions.
 8. Make the smallest useful change.
-9. Verify at the lightest level that honestly supports the claim, then escalate verification when the claim is larger.
+9. Verify at the lightest level that honestly supports the claim, then escalate verification with the L0-L5 Verification Ladder when the claim, scope, risk, public release, runtime, UI completion, auth, DB, broad refactor, learning value, or user intent is larger.
 10. Report skipped, partial, blocked, or assumed verification plainly.
 11. Do not run broad tests for tiny changes, but do not under-verify risky, security-sensitive, or public work.
 12. Do not use teams, orchestration, structured proof, or tmux unless risk, user intent, learning value, or an approved route justifies it.
 13. Escalate risky work by asking or recommending, not by silently switching modes.
 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. Explain useful change insight for non-specialists: what the touched code does, what changed, and why it matters.
-17. Use external references deliberately, preserve source clarity in research/proof notes, and rework good ideas into yam style.
-18. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
-19. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
+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.
+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.

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.1.0 - 2026-06-30
+
+### Added
+
+- Added `references/study-note.md` with required Study Note guidance for any changed code, config, release metadata, documentation, or project artifact.
+- Reworked `references/verification-levels.md` into an L0-L5 Verification Ladder covering stated, inspected, local check, integrated, release/runtime/visual proof, and bounded deep verification.
+
+### Improved
+
+- Updated core, final-report, route skill, project-pack, and trust-layer guidance so serious claims can require heavier evidence while bounded stop conditions prevent endless proof loops.
+- Strengthened `$quick`, `$deep`, `$mission`, and `$ueye` final report rules so changed artifacts include code/artifact role, expected behavior, syntax or structure insight, verification note, and uncertainty.
+
+## v2.0.0 - 2026-06-24
+
+### Added
+
+- Extended `yam loop report --json` with lightweight requirement coverage, `failure_cause`, `recovery_hint`, and `avoidance_note` so handoff artifacts can show what must still be covered before a completion claim.
+- Added `readiness_receipt` to `yam release report --json` to summarize the read-only evidence basis for package/version, registry, auth, git, dist, tarball, and release-check readiness.
+
+### Improved
+
+- Uncovered loop requirements now block verified truth, default `blocked_kind` to `requirement_uncovered`, and point the default next action at the first uncovered requirement.
+- Documented that loop avoidance notes are report-only; durable learning remains explicit through `yam memory add`.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run cli-smoke`
+- `npm run verify:self`
+- `node ./dist/bin/yam.js loop report --json` with uncovered requirement truth blocking
+- `node ./dist/bin/yam.js release report --json` (blocked as expected by npm auth readiness and dirty git, with `readiness_receipt`)
+
 ## v1.9.1 - 2026-06-19
 
 ### Added

package/COMMANDS.md

@@ -148,7 +148,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 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" --blocked-kind auth_blocked --safe-retry "retry after npm whoami succeeds" --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" --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" --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"
@@ -195,8 +195,9 @@ 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 failing code, its role, observed symptom, changed code, and why it matters.
+- 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.
 - 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.

package/DECISIONS.md

@@ -38,11 +38,14 @@ Every `yam` change is evaluated against honest proof, progressive depth, securit
 - Rules the model can actually follow.
 - Fast momentum without pretending simple work is always enough.
 - Depth growth when the user's understanding, project risk, or product quality benefits from it.
+- L0-L5 verification ladder with bounded heavy verification and explicit stop conditions.
 
 ### Beginner Insight
 
 - Explain changed behavior in plain language.
 - Name the code area touched and what it is responsible for.
+- Include Study Note whenever code, config, release metadata, documentation, or project artifacts changed.
+- Teach one useful syntax, schema, or structure insight without turning the final report into a long tutorial.
 - Separate implementation facts from judgment.
 - Always close with remaining tasks or useful improvements.
 

package/README.md

@@ -14,6 +14,8 @@ Context-reuse first.
 End with remaining tasks and fix-first items.
 Security-first project guidance.
 Useful change insight for non-specialists.
+Study Note for changed artifacts.
+Verification Ladder for larger claims.
 Reference-led judgment with clear source boundaries.
 ```
 
@@ -31,17 +33,18 @@ See `ROADMAP.md` for remaining implementation stages.
 
 ## Defaults
 
-- No hooks.
+- No required hooks.
 - Optional `yam-lite` hook is advisory-only and off by default.
 - No automatic Team routing.
 - No automatic proof loops.
 - No automatic tmux.
 - No false completion claims: verification, cleanup, and visual checks must match actual evidence.
 - `yam` is not lightweight-only; it is progressive: fast direction, broader judgment when useful, stronger proof as scope/risk grows.
-- Every route should check project direction and use an honest verification level.
+- Every route should check project direction and use the L0-L5 Verification Ladder honestly.
 - Small work stays small, but serious work is allowed to become serious.
 - Security-sensitive work is never treated as ordinary polish.
-- Useful reports explain what the changed code does, how it changed, and why the change matters.
+- When code, config, release metadata, documentation, or project artifacts changed, final reports include a Study Note even if no yam skill was invoked.
+- Useful Study Notes explain what the changed code or artifact does, what role it has, what was wrong or missing, what changed, what behavior is expected, one small syntax/structure insight, what was verified, and what remains uncertain.
 - Research and reference scans should keep source boundaries clear, then rework good ideas into yam style.
 - Token economy is part of quality.
 - Project packs prevent re-reading and re-planning from scratch.
@@ -142,7 +145,7 @@ yam ueye report --reference ./reference.png --actual .yam/screens/home.png --pre
 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" --blocked-kind auth_blocked --safe-retry "retry after npm whoami succeeds" --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" --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" --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
@@ -215,11 +218,13 @@ These shapes keep reports machine-readable without turning normal work into a he
 
 - Runtime evidence mini: compact route, command/process, observation, cleanup, truth status, and next action fields for `$deep` or `$mission` runtime claims.
 - Patch queue lite: `$mission` lane records with pending/applied/verified/reverted/blocked state, changed files, verification hint, rollback hint, truth status, and next action.
-- Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, and final truth status.
-- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, evidence level/stamp, blocker kind, safe retry, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, tool intent, truth status, and study note.
-- Study note: `yam.study-note.v1` keeps short non-specialist explanations for what code was failing, what role it plays, how the symptom showed up, what changed, and why it matters. Missing details stay in `limits` instead of being guessed.
+- 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.
+- 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, and keep npm publish outside the report.
+- 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.
 - Context pressure: `yam context pressure` explains when project context is getting stale, broad, or confusing enough to summarize, refresh, narrow scope, or deepen route.
 - Cleanup scan: `yam cleanup scan` is read-only and advisory; it reports confusing hooks, local skill folders, stale traces, or old proof artifacts without deleting anything.
 - Benchmark optimization loop lite: use `yam measure <route>` and `yam template tuning` to record baseline, one route wording change, rerun result, keep/revert decision, and stop condition.

package/dist/bin/yam.js

@@ -318,6 +318,7 @@ async function verify({ quiet = false } = {}) {
         'token-economy.md',
         'context-reuse.md',
         'markdown-management.md',
+        'study-note.md',
         'final-report.md',
         'token-budget-reporter.md',
         'memory.md'
@@ -1586,6 +1587,7 @@ function runReleaseReport() {
     const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
     const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
     const ok = failed.length === 0 && publishReadiness.status === 'ready';
+    const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, ok);
     return {
         schema: 'yam.release-report.v1',
         generated_at: startedAt,
@@ -1599,11 +1601,53 @@ function runReleaseReport() {
         tarball,
         freshness,
         publish_readiness: publishReadiness,
+        readiness_receipt: readinessReceipt,
         study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
         publishBlockerEvidence,
         next_actions: nextActions
     };
 }
+function releaseReadinessReceipt(provenance = {}, freshness = {}, tarball = {}, publishReadiness = {}, ok = false) {
+    return {
+        schema: 'yam.release-readiness-receipt.v1',
+        generated_at: new Date().toISOString(),
+        package_name: PACKAGE_JSON.name,
+        local_version: VERSION,
+        registry: {
+            url: String(publishReadiness.registry?.url || ''),
+            latest_version: String(publishReadiness.registry?.latest_version || ''),
+            version_status: String(publishReadiness.registry?.version_status || 'not_verified'),
+            truth_status: publishReadiness.registry?.truth_status || 'partial'
+        },
+        auth: {
+            command: 'npm whoami',
+            status: String(publishReadiness.auth?.status || 'not_verified'),
+            account: publishReadiness.auth?.status === 'authenticated' ? 'observed_redacted' : '',
+            truth_status: publishReadiness.auth?.truth_status || 'partial'
+        },
+        git: {
+            commit: String(provenance.git_commit || ''),
+            dirty: Boolean(provenance.git_dirty),
+            dirty_lines_observed: Array.isArray(provenance.git_status_lines) ? provenance.git_status_lines.length : 0,
+            truth_status: provenance.truth_status || 'partial'
+        },
+        checks: {
+            dist: freshness.dist || 'not-verified',
+            package_boundary: freshness.package_boundary || 'not-verified',
+            cli_smoke: freshness.cli_smoke || 'not-verified',
+            tarball: tarball.status === 'checked' ? 'checked' : 'not-verified'
+        },
+        tarball: {
+            status: String(tarball.status || 'not-verified'),
+            name: String(tarball.tarball_name || ''),
+            integrity_present: Boolean(tarball.integrity),
+            shasum_present: Boolean(tarball.shasum),
+            truth_status: tarball.truth_status || 'partial'
+        },
+        publish_attempted: false,
+        truth_status: ok ? 'verified' : 'blocked'
+    };
+}
 function releaseProvenance(checks = []) {
     const gitCommit = runReadOnlyCommand('git', ['rev-parse', '--short', 'HEAD']);
     const gitStatus = runReadOnlyCommand('git', ['status', '--short']);
@@ -1979,13 +2023,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] [--blocked text] [--blocked-kind text] [--safe-retry 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] [--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] [--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', 'blocked', 'blocker', 'blocked-kind', 'next-action', 'safe-retry', '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', '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', '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 || ''),
@@ -1997,12 +2041,16 @@ async function loopReport(args = []) {
         evidence_level: normalizeLoopEvidenceLevelFlag(flags.evidence_level),
         evidence_stamp: String(flags.evidence_stamp || ''),
         source_digest: String(flags.source_digest || ''),
+        covered_requirements: arrayFlag(flags.covered_requirement),
+        uncovered_requirements: arrayFlag(flags.uncovered_requirement),
         blockers,
         blocked_kind: String(flags.blocked_kind || ''),
+        failure_cause: String(flags.failure_cause || ''),
         truth_status: isTruthStatus(flags.truth) ? flags.truth : undefined,
         intent_label: normalizeToolIntent(flags.intent_label || flags.tool_intent || 'read_only'),
         next_action: String(flags.next_action || ''),
         safe_retry: String(flags.safe_retry || ''),
+        recovery_hint: String(flags.recovery_hint || ''),
         fix_first_items: arrayFlag(flags.fix_first_item),
         remaining_tasks: arrayFlag(flags.remaining_task),
         recommended_direction: String(flags.recommended_direction || flags.direction || ''),
@@ -2013,6 +2061,7 @@ async function loopReport(args = []) {
         owner_scope: [...arrayFlag(flags.owner_scope), ...arrayFlag(flags.scope)],
         scope_owner: String(flags.scope_owner || flags.owner || ''),
         side_effects: arrayFlag(flags.side_effect),
+        avoidance_note: String(flags.avoidance_note || ''),
         issue_code: String(flags.issue_code || ''),
         issue_role: String(flags.issue_role || ''),
         issue_symptom: String(flags.issue_symptom || ''),
@@ -3734,7 +3783,7 @@ function printDetection(result) {
     }
     console.log('');
     console.log('Smallest useful checks:');
-    console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'Level 0 read/inspect; no command detected'}`);
+    console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'L1 inspected; no command detected'}`);
     console.log(`- $ueye: ${result.commands.typecheck || result.commands.build || 'Browser/screenshot check; no command detected'}`);
     console.log(`- $deep: ${[result.commands.typecheck, result.commands.lint, result.commands.test, result.commands.build].filter(Boolean).join(' && ') || `No command detected; define in ${PROJECT_PACK}`}`);
     if (result.frameworkChecklist?.detected) {

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

@@ -161,13 +161,17 @@ export interface LoopReport {
     evidence_level: LoopEvidenceLevel;
     evidence_stamp: string;
     source_digest: string;
+    covered_requirements: string[];
+    uncovered_requirements: string[];
     blockers: string[];
     blocked_kind: string;
+    failure_cause: string;
     truth_status: TruthStatus;
     intent_label: ToolIntent;
     tool_intent: ToolIntent;
     next_action: string;
     safe_retry: string;
+    recovery_hint: string;
     fix_first_items: string[];
     remaining_tasks: string[];
     recommended_direction: string;
@@ -178,6 +182,7 @@ export interface LoopReport {
     owner_scope: string[];
     scope_owner: string;
     side_effects: string[];
+    avoidance_note: string;
     study_note: StudyNote;
 }
 export interface UeyeRunReport {

package/dist/lib/trust-kernel.js

@@ -236,13 +236,18 @@ export function buildLoopReport(input = {}) {
         ? input.stages.map((stage) => buildLoopStage(stage))
         : [];
     const evidence = asList(input.evidence);
+    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 || (blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+    const blockedKind = shortText(input.blocked_kind || (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);
+    const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length);
     const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
     const derivedTruth = hasBlockerSignal || hasBlockedStage ? 'blocked'
         : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
@@ -265,13 +270,17 @@ export function buildLoopReport(input = {}) {
         evidence_level: normalizeLoopEvidenceLevel(input.evidence_level),
         evidence_stamp: evidenceStamp,
         source_digest: sourceDigest,
+        covered_requirements: coveredRequirements,
+        uncovered_requirements: uncoveredRequirements,
         blockers,
         blocked_kind: blockedKind,
+        failure_cause: failureCause,
         truth_status: truth,
         intent_label: intentLabel,
         tool_intent: intentLabel,
-        next_action: shortText(input.next_action || (hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
+        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')),
         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),
         remaining_tasks: asList(input.remaining_tasks || input.remaining_task),
         recommended_direction: shortText(input.recommended_direction || input.direction),
@@ -282,6 +291,7 @@ export function buildLoopReport(input = {}) {
         owner_scope: asList(input.owner_scope || input.scope),
         scope_owner: normalizeOwnerRoute(input.scope_owner || input.owner),
         side_effects: asList(input.side_effects || input.side_effect),
+        avoidance_note: avoidanceNote,
         study_note: studyNote
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "1.9.1",
+  "version": "2.1.0",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/final-report.md

@@ -4,10 +4,10 @@ Every `yam` route should end with a compact handoff that helps the next run avoi
 
 ## Required Closing Check
 
-Include these when they are useful and keep them short:
+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 does, how it changed, and why it matters.
+- 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.
 - What verification ran.
 - What was not checked.
 - Truth status, when verification or runtime claims matter.
@@ -16,7 +16,7 @@ Include these when they are useful and keep them short:
 - Context pressure or cleanup findings when they could affect the next run.
 - Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.
-- Study Note for implementation work: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
+- Study Note whenever code, config, release metadata, documentation, or project artifacts changed, even if no yam skill was explicitly invoked. This item is required for changed artifacts, not optional.
 - Remaining tasks.
 - Fix-first items before planned tasks.
 - Recommended direction and why that next step matters when the handoff would otherwise be ambiguous.
@@ -58,15 +58,19 @@ Examples:
 
 ## Study Note
 
-Use this when implementation changed code or fixed an error and the user would benefit from learning:
+Use this whenever implementation changed code or any project artifact changed:
 
-- What code had the issue.
-- What role that code plays.
-- How the issue showed up.
-- What changed.
-- Why the change matters.
+- What code or artifact changed.
+- What role that code or artifact plays in the project.
+- What was wrong, missing, unclear, or risky.
+- What changed and what behavior the change should produce.
+- One small syntax, API, schema, or structure insight for a non-specialist.
+- What was verified, or why verification is partial/skipped/blocked.
+- What remains uncertain.
 
-Keep it short. If the information is not known, say so instead of inventing it.
+Keep it short: 4-7 lines for ordinary work, longer only when risk, learning value, `$deep`, `$mission`, release, runtime, or DB work justifies it. If the information is not known, say so instead of inventing it.
+
+Use `references/study-note.md`.
 
 ## Handoff Direction
 
@@ -77,11 +81,13 @@ Use this when the next run needs a clear starting point:
 - Recommended direction.
 - Why this next step matters.
 - What is blocked, and by what.
+- Covered and uncovered requirements when the next run could otherwise overclaim completion.
 - Evidence level or stamp when the handoff relies on a specific command, file, or report.
-- Blocker kind and safe retry when the next run should not blindly repeat the same action.
+- Blocker kind, failure cause, recovery hint, and safe retry when the next run should not blindly repeat the same action.
+- 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`, `blocked_kind`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, and `side_effects`.
+`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`.
 
 ## Route Weight
 

package/references/honest-completion.md

@@ -35,6 +35,19 @@ Verification: not run; change was limited to copy/CSS and inspected locally.
 
 For larger work, include proof summary and residual risk.
 
+Use the L0-L5 Verification Ladder:
+
+- L0 stated.
+- L1 inspected.
+- L2 local check.
+- L3 integrated.
+- L4 release/runtime/visual proof.
+- L5 bounded deep.
+
+Escalate when the claim touches public release, UI done, auth, payment, DB, runtime, deployment, broad refactor, security, high learning value, or explicit user intent.
+
+Bounded heavy verification must stop after the smallest meaningful proof set passes, or after three relevant checks have run and remaining uncertainty is listed as blocked, skipped, or remaining work.
+
 ## Runtime Guard
 
 Runtime work needs stronger evidence because long-running processes can create false success:

package/references/study-note.md

@@ -0,0 +1,53 @@
+# Study Note
+
+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.
+
+## Final Report Shape
+
+This is final-report writing guidance, not a new CLI JSON schema. The current CLI artifact remains `yam.study-note.v1` with `problem`, `change`, `why_it_matters`, `learning_note`, `limits`, and `truth_status`. When using `yam loop report`, map the guidance below into the existing fields and put unknowns in `limits`.
+
+Keep the default note short: 4-7 lines for ordinary work, longer only for `$deep`, `$mission`, release, DB, runtime, or learning-heavy work.
+
+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.
+- 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.
+- 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.
+
+## 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.
+- 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.
+```
+
+## When Nothing Changed
+
+For pure Q&A, planning, scouting, or review with no changed artifact, do not force a Study Note. Say `No code or project artifact changed` when that prevents ambiguity.
+
+## Tone
+
+- Use plain language before implementation jargon.
+- Explain the code's responsibility before explaining the patch.
+- 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.
+
+## What To Avoid
+
+- Do not guess root cause when it was not verified.
+- 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.

package/references/tool-trust-layer.md

@@ -13,7 +13,8 @@ Every route carries a basic contract:
 - use context packs or memory before broad re-reading
 - verify only what was actually checked
 - report remaining tasks and fix-first issues when useful
-- explain what changed in plain language when code or behavior changes
+- include a Study Note when code, config, release metadata, documentation, or project artifacts changed
+- explain what changed, what role it has, what behavior is expected, and one useful syntax or structure insight in plain language
 - treat security as the first project lens
 - preserve source boundaries when outside references shaped the judgment
 
@@ -26,6 +27,8 @@ Then depth increases by route:
 - `$deep`: prove risky single-agent work with stronger runtime/tool evidence.
 - `$mission`: coordinate real subagents/team lanes with cross-verification.
 
+Verification should follow the L0-L5 ladder: stated, inspected, local check, integrated, release/runtime/visual proof, bounded deep. Serious claims can require serious evidence, but stop after the smallest meaningful proof set passes or after remaining uncertainty is clearly handed off.
+
 ## Surfaces To Wrap
 
 - Local CLI/app readiness.
@@ -94,6 +97,8 @@ On demand:
 
 - What the touched code or artifact is responsible for.
 - What changed in behavior, contract, UI, or safety posture.
+- What syntax, schema, or structure insight helps a non-specialist understand the change.
+- What verification level supports the claim.
 - Why the change matters to the product or user.
 - What remains uncertain or unverified.
 - What should be fixed first before the next planned task.

package/references/verification-levels.md

@@ -1,53 +1,158 @@
-# Verification Levels
+# Verification Ladder
 
-## Level 0: Read/Inspect
+`yam` starts with momentum, but it is not lightweight-only. Verification should become heavier when scope, risk, public release, runtime state, UI completion, auth, DB, broad refactor, or user intent makes false completion costly.
 
-For copy, spacing, small CSS, docs, or no-runtime changes.
+Use the smallest level that honestly supports the claim, then escalate deliberately.
+
+## L0: Stated
+
+Explanation only. No code or artifact was inspected deeply enough to support an implementation claim.
+
+Use for:
+
+- Pure Q&A.
+- Early plan or hypothesis.
+- Scout recommendation before implementation.
+
+Report:
+
+- Truth status: `assumed` or `skipped`.
+- Say no verification ran.
+
+## L1: Inspected
+
+Relevant file, snippet, error, screenshot, or project context was read.
+
+Use for:
+
+- Tiny docs/copy/config edits.
+- Local explanation based on source reading.
+- First pass on a small bug.
 
 Expected:
 
-- Re-read the changed file or relevant snippet.
+- Re-read the changed snippet.
 - Check local project fit.
-- Report that no command was run.
+- Report that no command ran if none did.
 
-## Level 1: One Relevant Check
+Truth cap:
 
-For small JS/TS/component changes.
+- Usually `partial` or `assumed`, not `verified`.
+
+## L2: Local Check
+
+One focused local check supports the claim.
+
+Use for:
+
+- Small TS/JS/app logic changes.
+- Narrow bug fixes.
+- Focused build/type/lint/test failures.
 
 Examples:
 
-- One focused test.
 - Typecheck.
 - Lint for touched area.
+- One focused test.
+- Small CLI smoke for the touched command.
+
+Truth cap:
+
+- `verified` only for the checked surface.
+
+## L3: Integrated
 
-## Level 2: Focused Confidence
+The change was checked through a broader local workflow or user-facing path.
 
-For feature-sized work.
+Use for:
+
+- Feature-sized work.
+- Package-facing CLI changes.
+- UI changes with visible behavior.
+- Changes that affect multiple files or flows.
 
 Examples:
 
-- Typecheck plus related test.
-- Build if no narrower test exists.
+- Build.
+- CLI smoke.
+- Relevant workflow command.
+- Browser check or screenshot.
+- UI state/responsive check.
 
-## Level 3: UI Confidence
+Truth cap:
 
-For visible UI changes.
+- `verified` for the exercised workflow.
+- `partial` when important states, devices, or integrations remain untested.
 
-Expected when feasible:
+## L4: Release / Runtime / Visual Proof
 
-- Desktop screenshot or browser check.
-- Mobile viewport check.
-- Check overflow, alignment, contrast, density, and core states.
+Proof artifact or runtime/visual/release evidence supports the claim.
 
-## Level 4: Deep Confidence
+Use for:
 
-For auth, payment, DB, migration, release, broad refactor, or user-requested deep verification.
+- Public release readiness.
+- Runtime process claims.
+- Cleanup claims.
+- Browser or screenshot visual verification.
+- Auth/payment/DB/deployment/security-sensitive changes.
 
 Examples:
 
-- Build.
-- Test suite or relevant suites.
-- Browser QA.
-- Security check.
-- Proof summary.
+- `yam release report --json`.
+- Runtime evidence with process, port, URL, or cleanup observation.
+- Ueye visual report with screenshot/provenance.
+- DB/security readiness report.
+- Readiness receipt or proof bundle.
+
+Truth cap:
+
+- `proven` only when runtime/process evidence exists.
+- `verified` only when the relevant check actually passed.
+- `blocked` when auth/tool/runtime evidence is required but unavailable.
+
+## L5: Bounded Deep
+
+Multiple relevant checks are combined, with a stop condition, skipped checks, residual risk, and handoff.
+
+Use for:
+
+- Broad refactors.
+- Release candidates.
+- Risky auth/payment/DB/runtime/deployment work.
+- User-requested deep verification.
+- Work with high learning value or high false-completion cost.
+
+Expected:
+
+- Define acceptance criteria.
+- Run the relevant set of checks, not every possible check.
+- Record proof summary or proof bundle lite.
+- List skipped checks and why.
+- List residual risks and remaining tasks.
+
+Stop condition:
+
+- Stop after the smallest meaningful verification set has passed, or after three relevant checks have run and any remaining uncertainty is clearly listed as blocked/remaining work.
+- Stop earlier when the same blocker repeats, a required tool/auth/runtime is unavailable, or a user decision is needed.
+- Do not keep retrying the same failure. Classify `failure_cause`, give `recovery_hint`, and hand off.
+
+## Route Defaults
+
+- `$question`: L0-L1.
+- `$scout`: L0-L1 for judgment; source-backed but not implementation verification.
+- `$quick`: L1-L2 by default; L3 only when the claim needs it.
+- `$ueye`: L1-L3 for ordinary UI work; L4 when claiming visual done.
+- `$deep`: L3-L5 when risk or user intent calls for strong verification.
+- `$mission`: L4-L5 when real subagents/team lanes are used, with cross-verification.
+
+## Completion Claim Rule
+
+Completion claims require evidence at or above the level implied by the claim:
+
+- Code changed: at least L1, preferably L2.
+- User-facing behavior changed: L2-L3.
+- UI done claim: L3-L4 with visual evidence when feasible.
+- Runtime/cleanup claim: L4.
+- Release/auth/DB/security claim: L4-L5.
 
+If the evidence level is lower than the claim, lower the truth status and report the gap.

package/skills/deep/SKILL.md

@@ -43,7 +43,7 @@ Use for:
 
 ## Verification
 
-Use Level 4 from `references/verification-levels.md`.
+Use L3-L5 from `references/verification-levels.md`; pick the smallest bounded set that honestly supports the claim.
 Use `references/token-economy.md`; wider context is allowed only when tied to the risk surface.
 Use `references/context-reuse.md`; update stale project packs narrowly when needed.
 Use `references/markdown-management.md` before writing broad proof or direction markdown.
@@ -52,6 +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/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.
 
@@ -65,12 +66,18 @@ Deep verification may include:
 - Before/after screenshot.
 - Risk-specific manual inspection.
 
+Stop condition:
+
+- Stop after the smallest meaningful verification set has passed, or after three relevant checks have run and the remaining uncertainty is clearly listed as blocked/remaining work.
+- Stop earlier when the same blocker repeats, a required tool/auth/runtime is unavailable, or a user decision is needed.
+- Do not keep retrying the same failure; classify the cause, give a recovery hint, and hand off.
+
 ## Final Response
 
 Include:
 
 - What was changed or reviewed.
-- Study Note for implementation work: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
+- 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.
 - Evidence gathered.
 - Truth status.
 - Blockers or remaining risk.

package/skills/mission/SKILL.md

@@ -58,6 +58,12 @@ Do not use for:
 12. Confirm cleanup or explicitly report intentionally running processes.
 13. Produce final proof summary, truth status, remaining tasks, and fix-first items.
 
+Mission stop condition:
+
+- Stop after cross-verification and the smallest meaningful L4-L5 proof set have passed, or after three relevant checks have run and remaining uncertainty is recorded as blocked/remaining work.
+- Stop earlier when the same blocker repeats, a required tool/auth/runtime is unavailable, or a user decision is needed.
+- Do not keep retrying the same failure; classify the cause, give a recovery hint, and hand off.
+
 ## Proof Summary
 
 Include:
@@ -79,7 +85,9 @@ Use `references/runtime-orchestration.md` only when runtime evidence is needed.
 Use `references/doctor-scan.md` before final mission completion.
 Use `references/db-supabase-safety-lite.md` for destructive DB/Supabase, migration, production-write, or RLS/policy lanes.
 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/final-report.md` to close with remaining tasks and fix-first items.
 Use `references/token-budget-reporter.md` when budget drift matters.
 
@@ -102,7 +110,7 @@ Report:
 
 - What the mission changed.
 - Role/cross-verification summary.
-- Study Note for implementation lanes: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
+- 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.
 - Evidence gathered.
 - Truth status.
 - Cleanup status.

package/skills/quick/SKILL.md

@@ -58,16 +58,19 @@ Scan lane:
 
 ## Verification
 
-- Copy/CSS/docs: Level 0 is often enough after re-reading the changed snippet.
+- Copy/CSS/docs: L1 is often enough after re-reading the changed snippet.
 - TS/JS or app logic: prefer typecheck, related test, lint, or build in that order when available.
 - Build-fix: use a compact PASS/FAIL matrix for command results.
 - If verification is skipped, partial, blocked, or assumed, say that plainly.
+- Escalate beyond L2 only when the changed behavior, user-facing impact, or risk surface needs it.
 
 Use `references/quick.md` for the merged fast/build rules.
+Use `references/verification-levels.md` for the L0-L5 ladder.
 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/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.
 
@@ -76,7 +79,7 @@ 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 useful: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
+- 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.
 - What was checked.
 - What was skipped, blocked, or still risky.
 - Handoff when useful: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.

package/skills/ueye/SKILL.md

@@ -43,6 +43,7 @@ Do not use for:
 - Prefer the in-app browser for interactive visual checks. Do not switch to a profile-dependent browser unless the user explicitly asks or the task requires existing cookies, sessions, extensions, or profile state.
 - Ueye owns the design completion gate. Do not rely on a separate code-risk route to catch sloppy visual completion.
 - Draft or needs-polish work may stay fast; a `done` claim requires recorded design gate evidence.
+- Use the Verification Ladder: ordinary UI implementation can stay L1-L3, but a visual `done` claim needs L3-L4 evidence when feasible.
 - Do not claim a Ueye result is done when implementation evidence, design quality, P0/P1 status, state coverage, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, or reference-read/comparison evidence is missing where relevant.
 
 ## Workflow
@@ -145,6 +146,8 @@ Use these artifacts for reference-led implementation or serious visual review. K
 ## Design Checks
 
 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.
 Always consider:
 
 - Direction fit.
@@ -170,6 +173,6 @@ 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 implementation changed code: what UI code changed, what role it has, how the visible symptom appeared, and why the change matters in short non-specialist language.
+- 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.
 - 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

@@ -346,6 +346,7 @@ async function verify({ quiet = false } = {}) {
     'token-economy.md',
     'context-reuse.md',
     'markdown-management.md',
+    'study-note.md',
     'final-report.md',
     'token-budget-reporter.md',
     'memory.md'
@@ -1575,6 +1576,7 @@ function runReleaseReport() {
   const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
   const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
   const ok = failed.length === 0 && publishReadiness.status === 'ready';
+  const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, ok);
   return {
     schema: 'yam.release-report.v1',
     generated_at: startedAt,
@@ -1588,12 +1590,55 @@ function runReleaseReport() {
     tarball,
     freshness,
     publish_readiness: publishReadiness,
+    readiness_receipt: readinessReceipt,
     study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
     publishBlockerEvidence,
     next_actions: nextActions
   };
 }
 
+function releaseReadinessReceipt(provenance: AnyRecord = {}, freshness: AnyRecord = {}, tarball: AnyRecord = {}, publishReadiness: AnyRecord = {}, ok = false) {
+  return {
+    schema: 'yam.release-readiness-receipt.v1',
+    generated_at: new Date().toISOString(),
+    package_name: PACKAGE_JSON.name,
+    local_version: VERSION,
+    registry: {
+      url: String(publishReadiness.registry?.url || ''),
+      latest_version: String(publishReadiness.registry?.latest_version || ''),
+      version_status: String(publishReadiness.registry?.version_status || 'not_verified'),
+      truth_status: publishReadiness.registry?.truth_status || 'partial'
+    },
+    auth: {
+      command: 'npm whoami',
+      status: String(publishReadiness.auth?.status || 'not_verified'),
+      account: publishReadiness.auth?.status === 'authenticated' ? 'observed_redacted' : '',
+      truth_status: publishReadiness.auth?.truth_status || 'partial'
+    },
+    git: {
+      commit: String(provenance.git_commit || ''),
+      dirty: Boolean(provenance.git_dirty),
+      dirty_lines_observed: Array.isArray(provenance.git_status_lines) ? provenance.git_status_lines.length : 0,
+      truth_status: provenance.truth_status || 'partial'
+    },
+    checks: {
+      dist: freshness.dist || 'not-verified',
+      package_boundary: freshness.package_boundary || 'not-verified',
+      cli_smoke: freshness.cli_smoke || 'not-verified',
+      tarball: tarball.status === 'checked' ? 'checked' : 'not-verified'
+    },
+    tarball: {
+      status: String(tarball.status || 'not-verified'),
+      name: String(tarball.tarball_name || ''),
+      integrity_present: Boolean(tarball.integrity),
+      shasum_present: Boolean(tarball.shasum),
+      truth_status: tarball.truth_status || 'partial'
+    },
+    publish_attempted: false,
+    truth_status: ok ? 'verified' : 'blocked'
+  };
+}
+
 function releaseProvenance(checks = []) {
   const gitCommit = runReadOnlyCommand('git', ['rev-parse', '--short', 'HEAD']);
   const gitStatus = runReadOnlyCommand('git', ['status', '--short']);
@@ -1977,13 +2022,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] [--blocked text] [--blocked-kind text] [--safe-retry 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] [--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] [--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', 'blocked', 'blocker', 'blocked-kind', 'next-action', 'safe-retry', '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', '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', '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 || ''),
@@ -1995,12 +2040,16 @@ async function loopReport(args = []) {
     evidence_level: normalizeLoopEvidenceLevelFlag(flags.evidence_level),
     evidence_stamp: String(flags.evidence_stamp || ''),
     source_digest: String(flags.source_digest || ''),
+    covered_requirements: arrayFlag(flags.covered_requirement),
+    uncovered_requirements: arrayFlag(flags.uncovered_requirement),
     blockers,
     blocked_kind: String(flags.blocked_kind || ''),
+    failure_cause: String(flags.failure_cause || ''),
     truth_status: isTruthStatus(flags.truth) ? flags.truth : undefined,
     intent_label: normalizeToolIntent(flags.intent_label || flags.tool_intent || 'read_only'),
     next_action: String(flags.next_action || ''),
     safe_retry: String(flags.safe_retry || ''),
+    recovery_hint: String(flags.recovery_hint || ''),
     fix_first_items: arrayFlag(flags.fix_first_item),
     remaining_tasks: arrayFlag(flags.remaining_task),
     recommended_direction: String(flags.recommended_direction || flags.direction || ''),
@@ -2011,6 +2060,7 @@ async function loopReport(args = []) {
     owner_scope: [...arrayFlag(flags.owner_scope), ...arrayFlag(flags.scope)],
     scope_owner: String(flags.scope_owner || flags.owner || ''),
     side_effects: arrayFlag(flags.side_effect),
+    avoidance_note: String(flags.avoidance_note || ''),
     issue_code: String(flags.issue_code || ''),
     issue_role: String(flags.issue_role || ''),
     issue_symptom: String(flags.issue_symptom || ''),
@@ -3727,7 +3777,7 @@ function printDetection(result) {
   }
   console.log('');
   console.log('Smallest useful checks:');
-  console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'Level 0 read/inspect; no command detected'}`);
+  console.log(`- $quick: ${result.commands.typecheck || result.commands.lint || result.commands.test || result.commands.build || 'L1 inspected; no command detected'}`);
   console.log(`- $ueye: ${result.commands.typecheck || result.commands.build || 'Browser/screenshot check; no command detected'}`);
   console.log(`- $deep: ${[result.commands.typecheck, result.commands.lint, result.commands.test, result.commands.build].filter(Boolean).join(' && ') || `No command detected; define in ${PROJECT_PACK}`}`);
   if (result.frameworkChecklist?.detected) {

package/src/lib/trust-kernel.ts

@@ -189,13 +189,17 @@ export interface LoopReport {
   evidence_level: LoopEvidenceLevel;
   evidence_stamp: string;
   source_digest: string;
+  covered_requirements: string[];
+  uncovered_requirements: string[];
   blockers: string[];
   blocked_kind: string;
+  failure_cause: string;
   truth_status: TruthStatus;
   intent_label: ToolIntent;
   tool_intent: ToolIntent;
   next_action: string;
   safe_retry: string;
+  recovery_hint: string;
   fix_first_items: string[];
   remaining_tasks: string[];
   recommended_direction: string;
@@ -206,6 +210,7 @@ export interface LoopReport {
   owner_scope: string[];
   scope_owner: string;
   side_effects: string[];
+  avoidance_note: string;
   study_note: StudyNote;
 }
 
@@ -550,13 +555,18 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     ? input.stages.map((stage) => buildLoopStage(stage))
     : [];
   const evidence = asList(input.evidence);
+  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 || (blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+  const blockedKind = shortText(input.blocked_kind || (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);
+  const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length);
   const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
   const derivedTruth: TruthStatus = hasBlockerSignal || hasBlockedStage ? 'blocked'
     : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
@@ -579,13 +589,17 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     evidence_level: normalizeLoopEvidenceLevel(input.evidence_level),
     evidence_stamp: evidenceStamp,
     source_digest: sourceDigest,
+    covered_requirements: coveredRequirements,
+    uncovered_requirements: uncoveredRequirements,
     blockers,
     blocked_kind: blockedKind,
+    failure_cause: failureCause,
     truth_status: truth,
     intent_label: intentLabel,
     tool_intent: intentLabel,
-    next_action: shortText(input.next_action || (hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
+    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')),
     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),
     remaining_tasks: asList(input.remaining_tasks || input.remaining_task),
     recommended_direction: shortText(input.recommended_direction || input.direction),
@@ -596,6 +610,7 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     owner_scope: asList(input.owner_scope || input.scope),
     scope_owner: normalizeOwnerRoute(input.scope_owner || input.owner),
     side_effects: asList(input.side_effects || input.side_effect),
+    avoidance_note: avoidanceNote,
     study_note: studyNote
   };
 }

package/templates/yam.project.md

@@ -44,6 +44,8 @@
 - UI changes:
 - Feature changes:
 - Risky changes:
+- Verification ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, L5 bounded deep.
+- Stop condition for heavy verification:
 - Public/release changes: scan for external tool names, comparison wording, and attribution wording; remove those hits unless the user explicitly approves keeping them.
 
 ## Security Policy
@@ -56,7 +58,8 @@
 
 ## Report Policy
 
-- Explain changed code in plain language:
+- Study Note requirement for changed code/config/release metadata/docs/artifacts:
+- Explain touched code or artifact role, changed behavior, one syntax/structure insight, verification, and uncertainty:
 - Always include remaining tasks or useful improvements:
 - Preserve source boundaries for research/proof notes:
 

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "1.9.1",
+  "version": "2.1.0",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -11,8 +11,10 @@
     "Token-aware by default.",
     "Context-reuse first.",
     "End with remaining tasks and fix-first items.",
-    "Explain what failed, what changed, and why it matters in short non-specialist language when useful.",
-    "Use handoff notes for fix-first items, remaining tasks, recommended next direction, blocker kind, safe retry, evidence level, and owner scope when useful."
+    "When code, config, release metadata, documentation, or project artifacts changed, include a Study Note even if no yam skill was explicitly invoked.",
+    "Explain what changed, what role it has, what was wrong or missing when relevant, what behavior is expected, and one useful syntax or structure insight in short non-specialist language.",
+    "Use handoff notes for fix-first items, remaining tasks, recommended next direction, requirement coverage, blocker kind, failure cause, recovery hint, safe retry, evidence level, and owner scope when useful.",
+    "Use bounded heavy verification for serious claims, with explicit stop conditions instead of endless proof loops."
   ],
   "defaultHooks": false,
   "routes": [