yam-flow 0.1.5 → 0.1.7

package/references/ueye.md

@@ -66,6 +66,7 @@ Use these when the task depends on visual truth, reference matching, or design q
 3. Reference vs Implementation Matrix.
 4. Design Quality Review.
 5. Review Continuity and Comparison Report.
+6. Design Completion Gate.
 
 Default bound:
 
@@ -146,6 +147,27 @@ Review dimensions:
 For each relevant dimension, record `pass`, `needs-polish`, or `fails`.
 Keep actionable findings in P0-P3 order. Prefer fixing P0/P1 and cheap local P2 issues before broad polish.
 
+### Design Completion Gate
+
+Use before claiming a Ueye implementation or serious review is done. This is the design-side completion check, not a separate route.
+
+Record:
+
+- `completion_claim`: draft, needs-polish, or done.
+- `mode`: fast or strict.
+- `design_score`, when score-based completion is useful.
+- P0 and P1 open findings.
+- Whether direction, reference read proof, implementation evidence, comparison, design quality, CTA affordance, state coverage, mobile/responsive behavior, and contrast/accessibility visuals were checked.
+- blockers, warnings, next action, and truth status.
+
+Gate behavior:
+
+- Draft and needs-polish can stay fast.
+- `done` automatically behaves as strict.
+- P0 or blocked reason should return blocked.
+- Missing required checks for a done claim should cap truth at partial.
+- Only claim done when the gate says `ready_to_claim_done: true`.
+
 ### Review Continuity and Comparison Report
 
 Use when a screen has more than one visual pass, a reference needs follow-up, or a previous Ueye report should stay connected to the next one.
@@ -199,9 +221,10 @@ Keep this metadata descriptive. It should support honest visual claims, not forc
 6. Screenshot/browser recheck when feasible.
 7. Reference vs Implementation Matrix when reference fidelity matters.
 8. Design Quality Review.
-9. Review Continuity and Comparison Report when the work spans multiple passes.
-10. P0/P1 closeout.
-11. Truth status.
+9. Design Completion Gate before any done claim.
+10. Review Continuity and Comparison Report when the work spans multiple passes.
+11. P0/P1 closeout.
+12. Truth status.
 
 ## Truth Caps
 
@@ -210,3 +233,4 @@ Keep this metadata descriptive. It should support honest visual claims, not forc
 - Blocked: requested visual claim cannot be inspected.
 - Assumed: implementation follows code patterns but visual result was not observed.
 - Reference-only or generated-only evidence cannot upgrade a result to full visual verification.
+- A done claim without a passing design completion gate cannot upgrade beyond partial or blocked.

package/skills/scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scout
-description: Lightweight investigation and judgment route. Use when the user invokes $scout or asks to find options, references, docs, tools, product direction, or third-party perspective before implementation.
+description: Broad investigation and judgment route. Use when the user invokes $scout or asks to find options, references, docs, tools, product direction, security implications, or third-party perspective before implementation.
 ---
 
 # yam Scout
@@ -15,21 +15,27 @@ Use for:
 - Third-party judgment before committing to a direction.
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing judgment.
+- Broad reference scans when the user needs wider perspective.
+- Security-centered direction checks before implementation.
+- Finding patterns worth reworking into yam style.
 
 ## Principles
 
-- Scout, do not sprawl.
+- Scout broadly enough to see the field, then compress the judgment.
 - Token economy is part of quality.
 - Reuse `yam.project.md` before broad context reading when present.
 - Prefer official and primary sources.
+- Keep source boundaries clear: cite what was read, separate fact from inference, and do not blur reference material into yam claims.
 - Use current docs proof only when SDK/API/cloud-service freshness matters.
-- Keep the question narrow.
+- Keep the decision clear, but do not make the field of view artificially narrow when the user asks for a broad scan.
 - Do not change code unless the user asks.
 - Return a practical recommendation.
 - Separate fact, inference, opinion, and recommendation.
 - Treat "objective" as evidence plus constraints, not certainty theater.
 - Treat "subjective" as named taste, product instinct, and likely user perception.
-- Keep source count bounded by default; use `$deep` only when the user asks for heavy verification.
+- Security is the first lens: call out auth, payment, DB, secrets, permission, deployment, supply-chain, and public-release risks early.
+- Source count should match the decision: 3-7 high-signal sources for focused scouting, more when the user explicitly asks for wide research.
+- Use `$deep` when the user asks for heavy verification or when false confidence would be costly.
 
 ## Workflow
 
@@ -41,11 +47,12 @@ Use for:
    - product/technical direction memo
    - risk discovery
 3. Read `yam.project.md` first when project direction matters.
-4. Gather 3-7 high-signal sources by default.
+4. Gather enough high-signal sources to support the decision; keep source quality higher than source volume.
 5. Compare options by fit, risk, cost, implementation effort, and durability.
-6. Give both objective and subjective judgment when useful.
-7. Recommend a direction.
-8. State uncertainty and what would change the recommendation.
+6. Identify security and trust implications before convenience or aesthetics.
+7. Give both objective and subjective judgment when useful.
+8. Recommend a direction and which ideas are worth reworking into yam style.
+9. State uncertainty and what would change the recommendation.
 
 ## Output
 
@@ -57,9 +64,12 @@ Use concise sections:
 - Macro / realistic / future view when the decision benefits from it.
 - Alternatives.
 - Risks.
+- Security lens.
+- Ideas to rework into yam style.
 - Sources or local evidence.
+- Remaining tasks or useful next improvements.
 
-Use `references/token-economy.md`; default to 3-7 high-signal sources.
+Use `references/token-economy.md`; default to 3-7 high-signal sources unless the user asks for a broad research scan.
 Use `references/current-docs.md` for current SDK/API/cloud-service questions.
 Use `references/context-reuse.md`; do not rescout known decisions unless they may be stale.
 Use `references/markdown-management.md` before creating or updating project packs.

package/skills/ueye/SKILL.md

@@ -41,6 +41,9 @@ Do not use for:
 - Record surface context when it matters: provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Generated media can guide direction, but it cannot verify the implemented screen without implementation screenshot evidence.
 - 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.
+- 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
 
@@ -78,8 +81,17 @@ Do not use for:
    - accessibility
    - brand or mood fit
    - mark each relevant dimension as pass, needs-polish, or fails.
-11. Produce a P0-P3 visual issue ledger and fix path.
-12. Recheck changed/high-risk screens after fixes when feasible.
+11. Run the Design Completion Gate before any "done" claim:
+   - direction locked
+   - reference read proof exists when reference-led
+   - implementation screenshot or source-screen evidence exists
+   - reference comparison is recorded when reference-led
+   - design quality is pass
+   - P0 is empty
+   - P1 is fixed or explicitly deferred
+   - CTA, states, mobile/responsive behavior, and contrast/accessibility visuals were checked
+12. Produce a P0-P3 visual issue ledger and fix path.
+13. Recheck changed/high-risk screens after fixes when feasible.
 
 ## Required Ueye Artifacts
 
@@ -106,7 +118,11 @@ Use these artifacts for reference-led implementation or serious visual review. K
    - use pass, needs-polish, or fails for each relevant design dimension.
 7. Review Continuity and Comparison Report, when this is a follow-up review:
    - record previous source/report, current source/report, comparison delta, resolved findings, new findings, still-open findings, truth status, and next action.
-8. Media Generation Proof, when generated images are part of the task:
+8. Design Completion Gate, when implementation or review is claimed done:
+   - record completion claim, design score when used, P0/P1 status, gate checks, blockers, warnings, next action, and truth status.
+   - use `yam ueye report --completion-claim done --design-quality pass --direction-locked --states-checked --mobile-checked --contrast-checked --cta-checked --json` when a compact proof-ready gate is needed.
+   - if the gate is partial or blocked, report the Ueye result as partial or blocked instead of complete.
+9. Media Generation Proof, when generated images are part of the task:
    - record whether generation was requested, attempted, blocked, or produced an output.
    - use `yam media proof --requested --attempted --output path.png --wait-loop --json` when a generated image materially affects the design direction.
    - never use generated media proof as a substitute for implemented screen evidence.
@@ -120,6 +136,7 @@ Use these artifacts for reference-led implementation or serious visual review. K
 - Inspect 1-3 primary images by default; expand only for P0/P1 risk, responsive breakage, or user-requested deep visual QA.
 - Keep source-screen inventory to the 5 most important rows by default.
 - Screenshot unavailable: cap the result at `partial` or `blocked`.
+- Completion gate missing for a `done` claim: cap the result at `partial` or `blocked`.
 - Text-only review: cap the result at `partial`.
 - Mock or invented screenshots: cap the result at `partial` and mark the source.
 - Browser unavailable but source files reviewed: report implementation verification separately from visual verification.