yam-flow 2.0.0 → 2.2.0

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; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
@@ -65,12 +66,19 @@ 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, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Evidence gathered.
 - Truth status.
 - Blockers or remaining risk.

package/skills/mission/SKILL.md

@@ -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; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items.
 Use `references/token-budget-reporter.md` when budget drift matters.
 
@@ -102,7 +110,8 @@ 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, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Evidence gathered.
 - Truth status.
 - Cleanup status.

package/skills/quick/SKILL.md

@@ -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; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
@@ -76,7 +79,8 @@ Use `references/token-budget-reporter.md` when a run needs measured budget feedb
 Keep it compact:
 
 - What changed or what the scan found.
-- Study Note when 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, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - What was checked.
 - What was skipped, blocked, or still risky.
 - Handoff when useful: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.

package/skills/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; include role, execution point, before/after, expected behavior, one syntax/structure insight, verification, limits, and architecture hygiene when relevant.
 Always consider:
 
 - Direction fit.
@@ -170,6 +173,7 @@ Report:
 - Review continuity/comparison result when this continues a prior Ueye run.
 - P0-P3 issues or confirmation that no blockers were found.
 - States/viewports checked.
-- Study Note when UI 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, where it runs or is read, what was wrong or missing, before/after behavior, what behavior is expected, one useful syntax/structure insight, what was verified, and what remains uncertain.
+- Architecture hygiene when relevant: flag if the change risks dumping unrelated UI logic into `page.tsx`, one-off component styling into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Truth status and visual verification cap.
 - Handoff when useful: fix-first visual issues, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.