yam-flow 0.1.0 → 0.1.2

package/COMMANDS.md

@@ -39,6 +39,14 @@ $ueye
 yam template ueye-comparison
 ```
 
+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 proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
+```
+
 ## Review-Only
 
 ```text
@@ -135,12 +143,22 @@ yam tools doctor /path/to/project --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"
+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 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"
 yam proof write /path/to/project --format md --truth assumed --assumption "No runtime was started"
 yam safety "supabase db reset --linked"
 ```
 
+Release reporting intentionally runs the release checks and returns a machine-readable summary.
+
+```bash
+yam release report --json
+```
+
 ## Lite Hook
 
 Advisory-only hook. It does not run checks or force routes.

package/README.md

@@ -126,6 +126,11 @@ yam tools doctor /path/to/project --json
 yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 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 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
 yam safety "supabase db reset"
 yam detect /path/to/project
 yam pack /path/to/project
@@ -172,3 +177,18 @@ Publishing still requires confirming the final npm package name and account acce
 - 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.
+
+## 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.
+
+```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
+```
+
+`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.
+
+For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.

package/ROADMAP.md

@@ -311,3 +311,113 @@ Tasks:
 - Add `yam proof write`. Done.
 - Prepare npm/npx package metadata and dry-run packaging. Done.
 - Add small route-scoped trust kernel: truth caps, fake/real policy, runtime truth matrix, and completion proof object. Done.
+
+### 16. Deferred Triggers
+
+Goal: keep useful future trust-layer ideas visible without turning them into always-on gates too early.
+
+Rules:
+
+- Do not implement deferred items just because they are listed here.
+- Mention an item again when its trigger appears in real use.
+- Prefer lite metadata before runtime systems.
+- Keep ordinary `$quick`, `$question`, and `$scout` flows free of these gates.
+
+#### Mission Patch Queue Lite
+
+Status: next candidate for `$mission` only.
+
+Trigger:
+
+- A mission uses two or more real subagent/lane outputs.
+- Multiple lanes touch nearby files or the same subsystem.
+- It becomes hard to tell who changed what, why, and how to revert it.
+- Mission rollback or apply order starts to matter.
+
+First shape:
+
+- pending / applied / verified / reverted / blocked state.
+- lane id and assigned scope.
+- changed files.
+- verification hint.
+- rollback hint.
+- truth status.
+
+Keep out for now:
+
+- automatic merge engine.
+- persistent locks.
+- parallel apply worker.
+- broad runtime orchestration.
+
+#### Tool Intent Label / Tool Trust Metadata
+
+Status: near-term lightweight metadata.
+
+Trigger:
+
+- A route uses several tool classes together, such as browser, package manager, GitHub, filesystem, database, or deployment tools.
+- Read-only and write actions need to be distinguished in proof.
+- Destructive actions need a visible route recommendation before execution.
+- Release or mission reports need clearer evidence about what kind of tool ran.
+
+First shape:
+
+- tool intent: read_only / write / destructive / runtime / visual.
+- parallel safe: true / false / unknown.
+- approval required: true / false / unknown.
+- evidence kind and truth status.
+
+Keep out for now:
+
+- automatic scheduling.
+- automatic permission mutation.
+- mandatory tool graph.
+
+#### MCP Scheduler Runtime
+
+Status: later.
+
+Trigger:
+
+- Tool intent labels are no longer enough.
+- The harness 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.
+
+First shape:
+
+- scheduler proof object.
+- read-only overlap allowed.
+- write/destructive serialization.
+- blocked/approved/skipped status.
+
+Keep out for now:
+
+- default scheduler for normal work.
+- route-wide mandatory scheduler.
+- background runtime service.
+
+#### Appshots Attachment Gate
+
+Status: deferred.
+
+Trigger:
+
+- Ueye visual provenance cannot answer which exact visual source was used.
+- A team workflow needs thread-level or attachment-level audit trails.
+- Reference and implementation screenshots are easy to confuse.
+- External review requires source image lineage beyond path/hash/id.
+
+First shape:
+
+- optional attachment source fields.
+- no mandatory gate.
+- preserve Ueye visual provenance as the default.
+
+Keep out for now:
+
+- required thread attachment ids.
+- app-specific visual gates.
+- blocking ordinary Ueye work when attachment metadata is absent.