yam-flow 0.1.0

package/references/token-budget-reporter.md

@@ -0,0 +1,44 @@
+# Token Budget Reporter
+
+`yam` tracks token pressure without hooks or automatic surveillance.
+
+Use the CLI after a run when you want a quick budget check:
+
+```bash
+yam measure quick --files 3 --commands 1 --report-lines 5 --seconds 40
+yam measure ueye --files 7 --commands 2 --report-lines 18 --seconds 260
+```
+
+## Metrics
+
+- `files`: files or large snippets intentionally read.
+- `commands`: verification or inspection commands that materially shaped the answer.
+- `report-lines`: approximate final answer length in rendered lines.
+- `seconds`: rough elapsed working time.
+
+## Meaning
+
+`ok` means the run fit the route's intended weight.
+
+`over budget` means the route may still be valid, but the next run should either narrow scope or intentionally choose a heavier route.
+
+`no measurements` means no actuals were provided; use `yam budget <route>` for static limits.
+
+## Route Policy
+
+- `$quick`: should stay small. If it repeatedly exceeds budget, the request is probably `$deep` or `$mission`.
+- `$ueye`: may use visual/browser checks and nearby design context, but should avoid broad design archaeology unless the user asked for design-heavy work.
+- `$question`: should answer directly. If it needs sources or comparison, switch to `$scout`.
+- `$scout`: may gather a bounded set of high-signal sources and should separate evidence from judgment.
+- `$deep`: can exceed ordinary budgets, but the reason must be risk-tied; single-agent runtime/tmux/browser checks belong here when verification needs them.
+- `$mission`: can spend more context on real subagent/team lanes, cross-verification, doctor scan, and runtime evidence, but only for approved plans where real subagents are used or explicitly unavailable/partial.
+
+## Design Baseline
+
+Strict proof would favor stronger automatic evidence collection.
+
+Modular skill workflows favor selective, low-context reporting.
+
+Minimal-core design removes the measurement unless it changes behavior.
+
+`yam` keeps manual measurement because it helps reduce over-reading without installing hooks.

package/references/token-economy.md

@@ -0,0 +1,61 @@
+# Token Economy
+
+Token economy is part of quality.
+
+Default behavior:
+
+- Read `yam.project.md` first when present.
+- Start with the narrowest likely file set.
+- Prefer `rg`, file names, and local snippets over broad reading.
+- Read nearby patterns before reading whole modules.
+- Summarize large files instead of loading full context when possible.
+- Stop searching once the edit surface is clear.
+- Do not open long docs or generated files unless they are directly needed.
+- Treat `yam.project.md` as the reusable context source; inspect it with `yam pack` when it seems stale.
+- Do not produce long reports for small work.
+- Use `yam measure <route>` after real runs when budget drift needs tuning.
+
+Suggested read budgets:
+
+```text
+quick
+- Start with 1 to 3 files for patch work.
+- Allow a small module or error surface only when the first hypothesis fails or the scan points wider.
+- Prefer one focused command, two at most.
+
+ueye
+- Project direction, source screen, target component, nearby styles/tokens.
+- Avoid full design-system archaeology for simple tweaks.
+- Visual claims require source-screen evidence or a partial truth cap.
+
+question
+- 0 to 2 files.
+- Prefer current conversation context and stable knowledge.
+- Switch to scout when evidence, source freshness, or comparison matters.
+
+scout
+- 3 to 7 high-signal sources.
+- Prefer official docs and primary sources.
+
+deep
+- Wider single-agent reading is allowed, but explain why.
+- Runtime/tmux/browser context should be tied to verification evidence.
+
+mission
+- Wider reading is allowed only for approved real subagent/team execution.
+- Runtime/tmux/browser context should be tied to mission evidence.
+```
+
+Measured budgets:
+
+```bash
+yam measure quick --files 3 --commands 1 --report-lines 5 --seconds 40
+yam measure deep --files 18 --commands 4 --report-lines 32 --seconds 900
+```
+
+Escalate reading only when:
+
+- The first edit surface is wrong.
+- Tests or runtime output contradict the hypothesis.
+- Risk surface is broader than expected.
+- The user asks for deeper analysis.

package/references/tool-trust-layer.md

@@ -0,0 +1,115 @@
+# Tool Trust Layer
+
+`yam` should grow a proof-first trust layer, but not a proof-first cage.
+
+The goal is to help a beginner start small and then move toward professional implementation with evidence, without making every step feel like a release gate.
+This is not a lightweight-only direction. `yam-lite` is light; `yam` is progressive.
+
+## Depth Ladder
+
+Every route carries a basic contract:
+
+- respect project direction before changing code
+- use context packs or memory before broad re-reading
+- verify only what was actually checked
+- report remaining tasks and fix-first issues when useful
+
+Then depth increases by route:
+
+- `$question`: answer without unnecessary research.
+- `$scout`: investigate and judge without implementation by default.
+- `$quick`: implement quickly with focused verification.
+- `$ueye`: implement/review UI with real visual evidence when feasible.
+- `$deep`: prove risky single-agent work with stronger runtime/tool evidence.
+- `$mission`: coordinate real subagents/team lanes with cross-verification.
+
+## Surfaces To Wrap
+
+- Codex CLI/App readiness.
+- Browser and Computer Use availability.
+- tmux and long-running process lifecycle.
+- Subagent/team availability for `$mission`.
+- imagegen or screenshot evidence for `$ueye`.
+- Context7 or official docs for current package/API questions.
+- codex-lb or provider routing health when configured.
+- DB/Supabase safety for destructive or migration work.
+- Research, QA, wiki/context, proof, and release-gate workflows.
+
+## yam Policy
+
+Default:
+
+- No automatic trust gate.
+- No automatic proof loop.
+- No automatic tmux.
+- No automatic subagents.
+- No automatic external provider setup.
+- Basic direction fit and honest verification boundaries still apply.
+
+Advisory:
+
+- `yam-lite` hook may suggest routes and warn about overclaiming.
+- `yam pack` may warn about stale project direction, command drift, active hooks, or legacy proof surfaces.
+
+On demand:
+
+- `$quick`: smallest honest local verification.
+- `$ueye`: visual evidence and truth caps.
+- `$deep`: single-agent heavy proof, runtime/tmux/browser/process cleanup.
+- `$mission`: real subagent/team execution with cross-verification.
+- `yam tools doctor`: inspect tool readiness without changing project state.
+- `yam proof`: summarize actual evidence without running verification.
+- `src/lib/trust-kernel.ts`: classify evidence, cap truth claims, distinguish fake/real proof, and summarize runtime truth.
+
+## Strict Proof Inputs
+
+- Tool readiness checks.
+- Hook status and trust reporting.
+- DB/Supabase destructive-operation gate thinking.
+- Computer Use and screenshot evidence caps.
+- tmux/process cleanup truth.
+- Source-intelligence proof for current docs.
+- Destructive DB/Supabase command detection and production-write caution.
+- Fake-vs-real and runtime truth matrix checks, reduced to local route-scoped helpers.
+- Feature/release inventory as an optional doctor, not a default gate.
+
+## Modular Skill Inputs
+
+- Selective install and profiles.
+- Evidence boundaries.
+- Low-context command detection.
+- Optional orchestration instead of always-on orchestration.
+
+## Design Quality Inputs
+
+- Real preview/screenshot evidence.
+- Compact design direction.
+- P0 visual gates for design-heavy work.
+
+## Reject
+
+- Always-on Team route.
+- Always-on hook enforcement.
+- Release gates for normal coding.
+- Mandatory generated image review for every UI task.
+- Broad MCP/tool scans before small work.
+- Provider config mutation without explicit user approval.
+
+## Implemented Shape
+
+`yam tools doctor` should be read-only by default:
+
+- report installed/available tools
+- report package scripts
+- report hook conflicts
+- report known high-risk surfaces
+- suggest route and proof level
+- do not install, configure, or mutate
+
+`yam proof` should summarize what actually ran:
+
+- command evidence
+- browser/screenshot evidence
+- runtime/tmux/process cleanup evidence
+- truth status
+- skipped/blocked/assumed items

package/references/trust-kernel.md

@@ -0,0 +1,55 @@
+# Trust Kernel
+
+This is the small trust kernel that keeps `yam` honest without turning every task into a release gate.
+
+`yam` implements these ideas as small local functions. It does not install always-on gates, external runtimes, or hidden orchestration.
+
+## Included
+
+- completion proof shape
+- route/truth status separation
+- fake versus real evidence distinction
+- runtime truth matrix idea
+- visual evidence caps
+- DB/Supabase destructive-signal detection
+
+## Rejected
+
+- always-on release gates
+- mandatory team/subagent evidence for normal work
+- mandatory tmux lifecycle proof for small work
+- image voxel ledger as a default requirement
+- broad source/tool scans before ordinary changes
+
+## yam Shape
+
+Implemented as:
+
+```text
+src/lib/trust-kernel.ts
+```
+
+The module provides:
+
+- `TRUTH_STATUSES`
+- DB/Supabase safety detection
+- evidence classification
+- truth cap application
+- fake/real policy
+- runtime truth matrix
+- completion proof object creation
+
+## Policy
+
+Use the kernel to prevent overclaiming.
+
+Do not use it to slow every task down.
+
+For example:
+
+- Reference image only cannot become full visual `verified`.
+- Mock/fixture evidence cannot become real runtime `proven`.
+- Required runtime evidence that is missing becomes `real_required_missing`.
+- Cleanup claims require cleanup evidence.
+
+This keeps the trust layer progressive and route-scoped.

package/references/truth-matrix.md

@@ -0,0 +1,47 @@
+# Truth Matrix
+
+Use precise verification language.
+
+```text
+verified
+Actual command, browser check, screenshot, or test passed.
+
+proven
+Runtime-specific: physical or process evidence supports the claim, such as a live server response, browser check, tmux pane evidence, or verified process exit.
+
+partial
+Some meaningful checks passed, but not the full surface.
+
+fixture_only
+Fixture or mock evidence exists, but it cannot support a real runtime claim.
+
+fixture_instrumented_real
+A real backend or process was involved, but the run was shaped by fixture instrumentation. Do not report it as fully proven.
+
+integration_optional
+A live integration/runtime check was optional and not requested. This is not a failure, but it is not verified.
+
+real_required_missing
+The user or route required live runtime evidence, but that evidence was unavailable.
+
+skipped
+Verification intentionally skipped because the change is tiny or not runnable.
+
+blocked
+Verification could not run because of environment, tool, auth, network, or time limits.
+
+assumed
+Reasonable inference from code reading, but no execution evidence.
+```
+
+Never say `verified` when the correct status is `partial`, `skipped`, `blocked`, or `assumed`.
+
+Never say `proven` for runtime work unless the runtime evidence exists.
+
+Never say full visual `verified` when the only evidence is a reference image, generated image, code reading, or text-only critique.
+
+For ordinary routes, prefer `verified`, `partial`, `skipped`, `blocked`, or `assumed`.
+For `$deep` runtime verification and `$mission`, use the more precise runtime statuses when they prevent overclaiming.
+
+`yam` implements a small truth cap in `src/lib/trust-kernel.ts`.
+If requested truth is stronger than evidence, cap it downward and report the cap.

package/references/ueye-proof.md

@@ -0,0 +1,109 @@
+# Ueye Proof
+
+Ueye proof keeps visual claims honest without turning design review into a heavy release gate.
+
+## When To Use
+
+Use Ueye proof artifacts when:
+
+- The user asks for UI/UX/design review.
+- A reference image, screenshot, or target design is part of the task.
+- The final answer needs to claim visual quality, visual parity, or responsive correctness.
+- A screenshot or browser check exists and should be tied to the conclusion.
+
+Skip or compress them when:
+
+- The change is text-only or documentation-only.
+- The user asks for a quick opinion and no visual source exists.
+- The only possible evidence is code reading; mark the result `assumed` or `partial`.
+
+## Artifact Set
+
+### Visual Evidence Inventory
+
+Purpose: identify what visual sources were inspected.
+
+Minimum useful fields:
+
+- Label:
+- Type:
+- Path/URL:
+- Dimensions:
+- sha256:
+- Viewport:
+- State:
+- Role:
+
+Bounds:
+
+- Default to 1-3 primary visual sources.
+- Cap ordinary inventories at 5 rows.
+- Record missing dimensions or hashes as `unknown`, not as failure.
+- Use generated annotations only as derivative aids.
+
+### Reference Read Proof
+
+Purpose: separate reading the reference from judging the implementation.
+
+Capture:
+
+- Layout:
+- Hierarchy:
+- Typography:
+- Color/contrast:
+- Component detail:
+- Interaction/motion:
+- Responsiveness:
+- Brand/mood:
+
+Keep this concise. It should explain what the reference asks for, not become a full design essay.
+
+### Reference vs Implementation Matrix
+
+Purpose: compare reference direction against the actual implementation evidence.
+
+Status values:
+
+- `matched`
+- `similar`
+- `different`
+- `not-verified`
+- `not-applicable`
+
+Rows to use only when relevant:
+
+- Layout and spacing.
+- Visual hierarchy.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility-relevant visuals.
+- Brand and mood fit.
+
+### Design Quality Review
+
+Purpose: judge the implemented UI on design quality after evidence is established.
+
+Dimensions:
+
+- Visual hierarchy.
+- Layout and spacing.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility.
+- Brand and mood fit.
+
+Report findings as P0-P3. Keep P2/P3 short unless the user requested a full polish pass.
+For each relevant design dimension, use `pass`, `needs-polish`, or `fails`.
+
+## Truth Caps
+
+- Full visual verification requires real implementation evidence and relevant recheck.
+- Reference-only evidence can support direction, not implementation proof.
+- Generated-only evidence can support ideation or annotation, not implemented-screen verification.
+- Missing screenshots, unavailable browser, or text-only review should cap the result at `partial`, `blocked`, or `assumed`.

package/references/ueye.md

@@ -0,0 +1,174 @@
+# Ueye
+
+`ueye` is the merged UI/design route: design-heavy implementation, screenshot-led UX review, and visual QA.
+
+## Selected Principles
+
+Visual proof:
+
+- Source-screen inventory before visual claims.
+- P0-P3 issue ledger.
+- Fix P0/P1 first, then cheap local P2 issues.
+- Recheck changed or high-risk screens after fixes when feasible.
+- Cap text-only or missing-screenshot reviews as partial instead of fully verified.
+
+Kept out by design:
+
+- Mandatory generated annotated images.
+- Image voxel ledgers.
+- Release gates for every UI change.
+- Always-on proof loops.
+
+Design quality:
+
+- Real examples and previews matter more than abstract prose.
+- Design direction should be compact and searchable.
+- P0 gates should reject placeholder visuals, generic UI, and broken responsive states.
+- UI work should be self-contained enough to inspect.
+
+Evidence boundaries:
+
+- Separate evidence from judgment.
+- Keep review output compact.
+- Escalate only when the risk justifies it.
+
+## Source-Screen Inventory
+
+Acceptable sources:
+
+- User-provided screenshot.
+- Browser screenshot from a local or remote URL.
+- Exported static artifact image.
+- Current screen when the browser tool can inspect it.
+- Reference image, as direction evidence only.
+- Generated annotated image, as derivative review aid only.
+
+Record:
+
+- Source type.
+- Screen or URL.
+- State: default, loading, error, empty, disabled, hover/focus, mobile, or unknown.
+- Whether visual verification is full, partial, skipped, or blocked.
+
+Bound:
+
+- Inspect 1-3 primary images by default.
+- Keep the source-screen inventory to the 5 most important rows by default.
+- Generated callout images are optional and should usually be at most one per review pass.
+- P0/P1 issues can expand the review; P2/P3 should stay top-few unless the user asks for a full polish pass.
+
+## Ueye Proof Artifacts
+
+Use these when the task depends on visual truth, reference matching, or design quality judgment. They are proof aids, not a separate lite/deep split.
+
+1. Visual Evidence Inventory.
+2. Reference Read Proof.
+3. Reference vs Implementation Matrix.
+4. Design Quality Review.
+
+Default bound:
+
+- Use only the artifacts that support the claim being made.
+- Keep evidence to the smallest set of screenshots, references, or URLs that can honestly support the result.
+- Prefer paths, URLs, dimensions, and hashes for images when available.
+- Do not require voxel grids, exhaustive callouts, or generated annotations.
+- Do not let proof artifacts turn Ueye into always-on heavy orchestration.
+
+### Visual Evidence Inventory
+
+Record the real screens and image sources behind the review.
+
+Include when known:
+
+- Label.
+- Type: implementation screenshot, browser URL, user screenshot, reference image, artifact export, generated annotation.
+- Path or URL.
+- Dimensions.
+- sha256.
+- Viewport or device.
+- State: default, loading, error, empty, disabled, hover/focus, mobile, or unknown.
+- Role: proof, reference direction, annotation, or partial evidence.
+
+Images without hashes or dimensions can still be useful, but mark the missing fields plainly.
+
+### Reference Read Proof
+
+Before judging a reference match, state what was actually read from the reference.
+
+Keep it visual and bounded:
+
+- Layout structure.
+- Hierarchy and emphasis.
+- Typography feel.
+- Color and contrast.
+- Component shapes and details.
+- Interaction or motion cues when visible.
+- Responsive implication if the reference includes multiple sizes.
+- Brand or mood fit.
+
+Reference read proof describes the direction. It is not proof that the implementation matches.
+
+### Reference vs Implementation Matrix
+
+Use when a user supplies, names, or implies a reference visual.
+
+Compare only meaningful dimensions:
+
+- Layout and spacing.
+- Visual hierarchy.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility-relevant visual behavior.
+- Brand or mood fit.
+
+For each row, record `matched`, `similar`, `different`, `not-verified`, or `not-applicable`, plus the smallest evidence note.
+
+### Design Quality Review
+
+Use as the judgment layer after evidence is separated and reference comparison is complete.
+
+Review dimensions:
+
+- Visual hierarchy.
+- Layout and spacing.
+- Typography.
+- Color and contrast.
+- Component detail.
+- Interaction and motion.
+- Responsiveness.
+- Accessibility.
+- Brand and mood fit.
+
+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.
+
+## P0-P3 Ledger
+
+- P0: blocker, unusable, impossible to complete primary workflow, severe accessibility or responsive failure.
+- P1: major issue that strongly harms conversion, comprehension, trust, or task completion.
+- P2: noticeable quality issue: spacing, alignment, hierarchy, contrast, density, state polish.
+- P3: optional polish.
+
+## Implementation Loop
+
+1. Direction fit.
+2. Visual Evidence Inventory.
+3. Reference Read Proof when a reference is used.
+4. Nearby pattern and token scan.
+5. Implementation.
+6. Screenshot/browser recheck when feasible.
+7. Reference vs Implementation Matrix when reference fidelity matters.
+8. Design Quality Review.
+9. P0/P1 closeout.
+10. Truth status.
+
+## Truth Caps
+
+- Full visual verification: real source-screen evidence and relevant recheck.
+- Partial: text-only review, no screenshot, browser unavailable, or source-state gaps.
+- 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.

package/references/ui-quality.md

@@ -0,0 +1,23 @@
+# UI Quality
+
+Direction comes before decoration.
+
+Check:
+
+- What real source-screen evidence supports the visual claim?
+- Does the change match the product domain?
+- Does it fit existing components, tokens, spacing, typography, and interaction patterns?
+- Is the primary workflow easier to scan or complete?
+- Does text fit on mobile and desktop?
+- Are states covered when relevant: default, loading, error, empty, disabled, hover/focus, mobile?
+- Is color contrast sufficient?
+- Is the UI less generic after the change?
+
+Avoid:
+
+- Generic purple gradients.
+- Decorative blobs.
+- Cards inside cards.
+- Marketing layouts for operational tools.
+- New dependencies for small visual flourishes.
+- Treating reference/generated images as proof of the implemented screen.

package/references/verification-levels.md

@@ -0,0 +1,53 @@
+# Verification Levels
+
+## Level 0: Read/Inspect
+
+For copy, spacing, small CSS, docs, or no-runtime changes.
+
+Expected:
+
+- Re-read the changed file or relevant snippet.
+- Check local project fit.
+- Report that no command was run.
+
+## Level 1: One Relevant Check
+
+For small JS/TS/component changes.
+
+Examples:
+
+- One focused test.
+- Typecheck.
+- Lint for touched area.
+
+## Level 2: Focused Confidence
+
+For feature-sized work.
+
+Examples:
+
+- Typecheck plus related test.
+- Build if no narrower test exists.
+
+## Level 3: UI Confidence
+
+For visible UI changes.
+
+Expected when feasible:
+
+- Desktop screenshot or browser check.
+- Mobile viewport check.
+- Check overflow, alignment, contrast, density, and core states.
+
+## Level 4: Deep Confidence
+
+For auth, payment, DB, migration, release, broad refactor, or user-requested deep verification.
+
+Examples:
+
+- Build.
+- Test suite or relevant suites.
+- Browser QA.
+- Security check.
+- Proof summary.
+