yam-flow 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to yam-flow are documented here.
+
+## v0.1.5 - 2026-06-04
+
+### Added
+
+- Added Ueye surface context metadata for provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL, preserved state, and evidence id.
+- Added surface context output to `yam ueye capture`, `yam ueye compare`, and `yam ueye report` so visual evidence can say where and how it was observed.
+- Added provider and execution surface fields to Ueye visual provenance records.
+
+### Improved
+
+- Strengthened `yam ueye report` for fast UI state preservation without making capture or compare an always-on gate.
+- Updated Ueye docs and templates so visual proof can distinguish source files, local screenshots, in-app browser checks, and other execution surfaces.
+
+## v0.1.4 - 2026-06-03
+
+### Added
+
+- Added `yam runtime evidence` details for pid, port, URL, exit code, screenshot id, and runtime timing metadata.
+- Added `yam mission queue` patch queue items with lane id, status, dependencies, tool intent, patch envelope, rollback hint, optional JSON output, and queue depth.
+- Added Ueye review continuity fields for resolved findings, new findings, still-open items, regressions, viewport, state, previous screenshot id, and current screenshot id.
+- Added release tarball provenance and release freshness summaries to `yam release report`.
+- Added structured diagnostic next-action metadata with priority, owner route, tool intent, fix-first, and release-blocking signals.
+- Added `yam benchmark report` for compact before/after performance notes.
+
+### Improved
+
+- Expanded CLI smoke coverage for Ueye report continuity, runtime evidence, mission queue, and benchmark report commands.
+- Strengthened docs, skill guidance, and templates for visual provenance, mission lane handoff, runtime proof, and final report evidence.
+- Kept advanced scheduler, persistent queue, and attachment-gate ideas deferred so the default flow stays fast.
+
+## v0.1.3 - 2026-05-31
+
+### Added
+
+- Added `yam ueye report` for compact visual run reports with reference sources, implementation screenshots, comparison result, design quality, next action, and truth status.
+- Added `yam media proof` to record media generation attempts, outputs, blocked states, and proof caps without treating generated media as implemented UI evidence.
+- Added runtime backend evidence fields to `yam proof`, including backend, claim, evidence id, command, cleanup check, and truth status.
+- Added `yam doctor --json` with machine-readable issues and next-action hints.
+- Added framework mini checklist output to `yam detect` and `yam tools doctor`.
+
+### Improved
+
+- Expanded Ueye proof guidance for reference evidence, implementation screenshots, comparison reports, and generated media limits.
+- Extended CLI smoke checks to cover the new Ueye report and media proof commands.
+- Kept visual and media proof helpers opt-in so fast routes remain lightweight.

package/COMMANDS.md

@@ -44,7 +44,7 @@ Opt-in visual evidence helpers:
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
 ```
@@ -133,6 +133,7 @@ yam memory summary /path/to/project
 ```bash
 yam budget quick
 yam measure quick --files 3 --commands 1 --report-lines 5 --seconds 40
+yam template tuning
 ```
 
 ## Tool Doctor / Proof / Safety
@@ -148,8 +149,11 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
+yam runtime evidence --backend terminal --claim observed --evidence-id dev-server-1 --command "npm run dev" --json
+yam mission queue --agent-id implementer --scope "checkout form" --changed src/checkout.tsx --verification-hint "npm run typecheck" --rollback-hint "revert checkout form patch if typecheck or smoke fails" --json
+yam benchmark report --label "render time" --baseline 100 --current 86 --unit ms --target lower --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 proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
 yam proof write /path/to/project --route deep --truth partial --command "npm run build: pass"
@@ -163,6 +167,29 @@ Release reporting intentionally runs the release checks and returns a machine-re
 yam release report --json
 ```
 
+## Flow Artifact Shapes
+
+Use existing templates and JSON outputs for compact support records:
+
+```bash
+yam template proof
+yam template mission
+yam template tuning
+yam tools doctor /path/to/project --json
+yam release report --json
+yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-checked --json
+yam mission queue --agent-id reviewer --scope "changed files review" --changed src/bin/yam.ts --verification-hint "npm run typecheck" --json
+yam benchmark report --label "bundle size" --baseline 120 --current 118 --unit kB --target lower --json
+```
+
+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.
+- 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.
+
 ## Lite Hook
 
 Advisory-only hook. It does not run checks or force routes.

package/README.md

@@ -19,7 +19,7 @@ End with remaining tasks and fix-first items.
 - `$quick`: fast scoped implementation, small fixes, and quick error scans.
 - `$ueye`: tight UI/UX/design implementation and visual review with reference-read proof, comparison, and quality judgment.
 - `$question`: direct Q&A without turning simple questions into research projects.
-- `$scout`: bounded investigation and recommendation.
+- `$scout`: conduct broad investigations, gather evidence, analyze options, and provide recommendations.
 - `$deep`: single-agent heavy verification by request, including runtime/tmux/browser/process proof when needed.
 - `$mission`: approved-plan execution with real subagent/team lanes, cross-verification, doctor scan, and final proof.
 
@@ -129,7 +129,7 @@ yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
 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 release report --json
@@ -177,12 +177,29 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime truth matrix
 - visual evidence caps
 - Ueye visual run reports
+- Ueye surface context metadata
 - runtime backend evidence
+- runtime evidence mini summaries
+- mission patch queue lite records
+- release report JSON
+- structured diagnostic next actions
 - media generation proof caps
 - DB/Supabase safety signals
 
 It is implemented locally in `src/lib/trust-kernel.ts` and kept route-scoped. It is not an always-on release gate.
 
+## Flow Artifact Shapes
+
+These shapes keep reports machine-readable without turning normal work into a heavy gate.
+
+- 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.
+- 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.
+- Structured diagnostic next action: every doctor/release diagnostic should say what was observed, what evidence supports it, what to do next, owner route, severity, and truth status.
+- Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.
+- Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
+
 ## Ueye Capture And Compare
 
 `$ueye` stays one skill. It starts fast by default, then uses capture/compare only when a visual claim needs real evidence.
@@ -190,14 +207,14 @@ It is implemented locally in `src/lib/trust-kernel.ts` and kept route-scoped. It
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 `capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
 
 `compare` is local-only and dependency-free. It records file hashes, dimensions, comparison result, and proof-ready visual provenance. Exact image matches can be `verified`; different screenshots stay `partial` so visual parity is not overclaimed.
 
-`report` gathers reference sources, implementation screenshots, comparison result, design quality judgment, and next action into one compact proof-ready JSON object.
+`report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, surface context, and next action into one compact proof-ready JSON object.
 
 Generated media can guide visual direction, but it cannot prove the implemented UI by itself:
 

package/ROADMAP.md

@@ -4,7 +4,7 @@
 
 Implemented:
 
-- Skills-first harness.
+- Skills-first workflow.
 - Six routes: quick, ueye, question, scout, deep, mission.
 - Shared references.
 - Local CLI: list, status, verify, doctor, examples, path, install, uninstall.
@@ -54,7 +54,7 @@ Tasks:
 
 ### 4. Token Budget Reporter
 
-Goal: keep the harness honest about context usage.
+Goal: keep the workflow honest about context usage.
 
 Tasks:
 
@@ -275,7 +275,7 @@ Tasks:
 ### 15. Lite Hook / Progressive Tool Trust Layer
 
 Goal: keep beginner momentum while creating a path toward professional proof-first work.
-The hook stays light, but the harness direction does not. `yam` should support a depth ladder: direction fit first, focused proof for ordinary work, strong proof for risky work, and real team proof for `$mission`.
+The hook stays light, but the `yam` direction does not. `yam` should support a depth ladder: direction fit first, focused proof for ordinary work, strong proof for risky work, and real team proof for `$mission`.
 
 Kept:
 
@@ -325,7 +325,7 @@ Rules:
 
 #### Mission Patch Queue Lite
 
-Status: next candidate for `$mission` only.
+Status: documented lite shape for `$mission` only; implementation remains route-scoped.
 
 Trigger:
 
@@ -381,7 +381,7 @@ Status: later.
 Trigger:
 
 - Tool intent labels are no longer enough.
-- The harness starts coordinating multiple external tools inside one route.
+- The workflow starts coordinating multiple external tools inside one route.
 - Write or destructive actions could run near read-only checks.
 - Parallel tool execution becomes common and needs ordering.
 - A mission needs deterministic tool sequence proof.