yam-flow 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -96,6 +96,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "playwright": "^1.60.0",
     "typescript": "^6.0.3"
   }
 }

package/references/mission.md

@@ -36,6 +36,30 @@ Subagent policy:
 - If the user explicitly insists on mission despite missing subagents, mark the result `partial` or `blocked`; do not treat self-review as team execution.
 - The final proof must record the subagent decision: `used`, `downgraded_to_deep`, `unavailable_partial`, or `blocked`, with the reason.
 
+Patch envelope:
+
+Use a small envelope when a real mission lane changes code:
+
+- `agent_id`: who or which lane made the change.
+- `assigned_scope`: the bounded work area.
+- `changed_files`: files the lane touched.
+- `verification_hint`: the smallest relevant check for the lane.
+- `rollback_hint`: what to inspect or revert if the change is wrong.
+- `truth_status`: the lane's honest status.
+
+This is only a record shape. It is not a queue, lock manager, or parallel apply engine.
+
+Rollback hint:
+
+Record:
+
+- touched files
+- generated files
+- before check
+- safe revert note
+
+Do not claim rollback safety unless the relevant check or revert path was actually inspected.
+
 Runtime use:
 
 - Mission may use deep runtime verification when needed, but runtime proof alone does not make a mission if subagents were not used.

package/references/tool-trust-layer.md

@@ -110,6 +110,19 @@ On demand:
 
 - command evidence
 - browser/screenshot evidence
+- visual provenance for reference-based UI work
+- mission patch envelopes for real team lanes
+- rollback hints for risky changes
 - runtime/tmux/process cleanup evidence
 - truth status
 - skipped/blocked/assumed items
+
+`yam release report --json` should collect release readiness into a machine-readable artifact:
+
+- typecheck
+- forbidden names
+- package boundary
+- registry status
+- CLI smoke
+- dist freshness
+- final truth status

package/references/ueye-proof.md

@@ -19,6 +19,26 @@ Skip or compress them when:
 
 ## Artifact Set
 
+### Opt-In CLI Helpers
+
+Ueye is one route. It should not split into separate lite/deep skills. Use these helpers only when the current 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 reports `blocked` instead of installing dependencies or pretending a screenshot exists.
+- `compare` is local-only and dependency-free. It records hashes, dimensions, comparison result, and visual provenance. Different screenshots stay `partial`; exact file matches can be `verified`.
+- Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
+
+### Browser Preference
+
+- Prefer the Codex in-app Browser plugin for local pages, localhost, file URLs, and ordinary visual QA.
+- Do not silently switch to the user's Chrome browser when the in-app Browser cannot capture or inspect.
+- Use Chrome only when the user explicitly asks for it, or when the task requires existing Chrome cookies, sessions, extensions, or profile state.
+- If the in-app Browser is unavailable and Chrome was not explicitly requested or required, cap the visual claim at `partial` or `blocked`.
+
 ### Visual Evidence Inventory
 
 Purpose: identify what visual sources were inspected.
@@ -41,6 +61,25 @@ Bounds:
 - Record missing dimensions or hashes as `unknown`, not as failure.
 - Use generated annotations only as derivative aids.
 
+### Visual Provenance
+
+Purpose: prove the visual source path from reference reading to implementation recheck.
+
+Record these fields when a reference or screenshot materially affects the claim:
+
+- `source_kind`
+- `source_path`
+- `source_hash`
+- `reference_id`
+- `screenshot_id`
+- `local_only`
+- `redacted`
+- `operator_provided`
+- `comparison_result`
+- `truth_status`
+
+Use `unknown` for missing hashes and `not-verified` for comparisons that were not actually rechecked. Do not upgrade a visual claim only because a reference was supplied.
+
 ### Reference Read Proof
 
 Purpose: separate reading the reference from judging the implementation.

package/skills/mission/SKILL.md

@@ -49,12 +49,14 @@ Do not use for:
    - UX/browser verifier: checks screen behavior when relevant.
    - Doctor/scanner: checks direction fit, scope control, verification, cleanup, stale context, and false-completion risk.
 5. Execute the implementation in bounded steps.
-6. Use `$deep`-style runtime verification when the mission needs dev server, tmux, test watcher, browser QA, cleanup, or before/after evidence.
-7. Cross-check findings and resolve contradictions.
-8. Run the smallest honest final verification set.
-9. Run doctor scan with `references/doctor-scan.md`.
-10. Confirm cleanup or explicitly report intentionally running processes.
-11. Produce final proof summary, truth status, remaining tasks, and fix-first items.
+6. Record a compact patch envelope for each real lane that changes code.
+7. Add rollback hints for touched files, generated files, before checks, and safe revert notes.
+8. Use `$deep`-style runtime verification when the mission needs dev server, tmux, test watcher, browser QA, cleanup, or before/after evidence.
+9. Cross-check findings and resolve contradictions.
+10. Run the smallest honest final verification set.
+11. Run doctor scan with `references/doctor-scan.md`.
+12. Confirm cleanup or explicitly report intentionally running processes.
+13. Produce final proof summary, truth status, remaining tasks, and fix-first items.
 
 ## Proof Summary
 
@@ -64,6 +66,8 @@ Include:
 - Role work completed.
 - Subagent decision: used / downgraded_to_deep / unavailable_partial / blocked, with reason.
 - Files or surfaces changed.
+- Patch envelope for each real code-changing lane.
+- Rollback hint for risky or multi-file changes.
 - Runtime/tmux/browser evidence when used.
 - Cross-verification result.
 - Doctor/scanner result.

package/skills/ueye/SKILL.md

@@ -35,6 +35,8 @@ Do not use for:
 - Generated annotated images are optional, not a default gate.
 - Image evidence should stay bounded: inspect the primary screen first, then only the states/images needed to support the claim.
 - Design quality judgment belongs after implementation/review: compare to the reference first, then judge whether the result is good design.
+- Keep Ueye as one route: start fast, then opt into `yam ueye capture` and `yam ueye compare` only when a `verified` visual claim needs real screen evidence.
+- Prefer the Codex in-app Browser plugin for interactive visual checks. Do not switch to the user's Chrome browser unless the user explicitly asks for Chrome or the task requires existing Chrome cookies, sessions, extensions, or profile state.
 
 ## Workflow
 
@@ -52,6 +54,10 @@ Do not use for:
 6. Implement the smallest coherent design improvement when implementation is requested.
 7. Check default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
 8. Run browser/screenshot verification when feasible.
+   - Prefer the Codex in-app Browser plugin for local pages, localhost, file URLs, and ordinary visual QA.
+   - Do not silently use Chrome as a fallback. If the in-app Browser cannot capture or inspect, report the visual cap as `partial` or `blocked`.
+   - Use `yam ueye capture --url URL --out path.png` when a local Playwright install is available and the claim needs real browser evidence.
+   - Use `yam ueye compare --reference ref.png --actual shot.png` when reference fidelity needs a proof-ready local comparison record.
 9. Compare reference and implementation when reference fidelity was requested:
    - matched, similar, different, not-applicable, or not-verified.
    - Separate "faithful to reference" from "good design."
@@ -77,13 +83,16 @@ Use these artifacts for reference-led implementation or serious visual review. K
    - reference, before, and after evidence when available.
    - path or URL, source type, state, viewport, and visual verification cap.
    - sha256 and dimensions when an image file is locally available.
-2. Reference Read Proof:
+2. Visual Provenance:
+   - source kind, path, hash, reference id, screenshot id, redaction/locality flags, operator-provided flag, comparison result, and truth status.
+   - use this to prove the route from reference reading to implementation recheck.
+3. Reference Read Proof:
    - concrete observations from the reference before implementation.
    - no implementation claim should depend on an unrecorded reference observation.
-3. Reference vs Implementation Matrix:
+4. Reference vs Implementation Matrix:
    - compare the implemented result against the reference by aspect.
    - record matched, similar, different, not-applicable, or not-verified.
-4. Design Quality Review:
+5. Design Quality Review:
    - judge whether the result is good UI/UX/design after reference comparison.
    - use pass, needs-polish, or fails for each relevant design dimension.