yam-flow 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",
@@ -16,7 +16,7 @@
     "node": ">=18"
   },
   "bin": {
-    "yam": "dist/bin/yam.js"
+    "yam": "./dist/bin/yam.js"
   },
   "types": "dist/lib/trust-kernel.d.ts",
   "exports": {
@@ -27,6 +27,7 @@
   },
   "files": [
     "AGENTS.md",
+    "CHANGELOG.md",
     "COMMANDS.md",
     "DECISIONS.md",
     "LICENSE",

package/references/current-docs.md

@@ -4,10 +4,10 @@ Use current docs proof only when stale knowledge is a realistic risk.
 
 ## Require Current Docs Proof
 
-Use Context7, official docs, or primary sources when the task depends on current behavior for:
+Use official docs or primary sources when the task depends on current behavior for:
 
 - modern SDK/API syntax
-- cloud services such as Supabase, Vercel, OpenAI, Stripe, or auth providers
+- cloud services, model APIs, payment providers, or auth providers
 - framework version behavior, migration, deprecation, or breaking changes
 - CLI flags, deployment behavior, pricing/limits, security rules, or platform integrations
 - user wording such as latest, current, recently changed, new version, official docs, migration, or upgrade
@@ -27,7 +27,7 @@ Do not force current-docs proof for:
 Use one concise line:
 
 ```text
-Current-docs proof: Context7/official docs checked for <SDK/service>; result applied to <decision>.
+Current-docs proof: official docs checked for <SDK/service>; result applied to <decision>.
 ```
 
 Or:

package/references/doctor-scan.md

@@ -53,4 +53,23 @@ Doctor scan:
 - Runtime/cleanup:
 - Truth status:
 - Fix-first:
+- Diagnostic next action:
 ```
+
+## Structured Diagnostic Next Action
+
+Use this shape for doctor or release diagnostics that need a concrete follow-up:
+
+- `status`: pass / needs_action / blocked / skipped
+- `severity`: P0 / P1 / P2 / P3
+- `owner_route`: quick / ueye / question / scout / deep / mission
+- `priority`: fix_first / next / later / none
+- `fix_first`: true / false
+- `blocks_release`: true / false
+- `observation`
+- `evidence`
+- `next_action.kind`: read_file / run_command / inspect_ui / update_docs / ask_user / none
+- `next_action.command` or `next_action.files`, when relevant
+- `truth_status`
+
+Keep it singular. If there are several issues, list the fix-first item that most affects the next run.

package/references/final-report.md

@@ -10,6 +10,7 @@ Include these when they are useful and keep them short:
 - What verification ran.
 - What was not checked.
 - Truth status, when verification or runtime claims matter.
+- Structured diagnostic next action, when a check found a concrete next step.
 - Remaining tasks.
 - Fix-first items before planned tasks.
 
@@ -59,3 +60,23 @@ For `$deep` and `$mission`, include evidence, remaining risks, remaining tasks,
 Do not pad the final answer when there are no meaningful remaining tasks or fix-first items.
 
 When budget drift matters, include or run `yam measure <route>` with approximate files, commands, report lines, and seconds.
+
+## Diagnostic Next Action
+
+When a report says something needs attention, include one concrete next action instead of a vague warning.
+
+Compact shape:
+
+```text
+Diagnostic next action:
+- severity:
+- owner route:
+- priority:
+- fix first:
+- blocks release:
+- evidence:
+- next action:
+- truth status:
+```
+
+Use `none` when there is no meaningful next action.

package/references/hook-lite.md

@@ -14,7 +14,7 @@ Allowed:
 - Remind the agent not to overclaim verification, cleanup, or visual evidence.
 - Suggest `$quick`, `$ueye`, `$question`, `$scout`, `$deep`, or `$mission` based on obvious prompt signals.
 - Mention a project pack or memory summary when present.
-- Warn when conflicting proof-harness surfaces are active in the current project.
+- Warn when conflicting proof surfaces are active in the current project.
 
 Not allowed:
 

package/references/memory.md

@@ -2,7 +2,7 @@
 
 `yam memory` is an opt-in, project-local memory layer.
 
-It keeps only the lightest useful parts from heavier harness patterns:
+It keeps only the lightest useful parts from heavier workflow patterns:
 
 - Sparse records, one file per durable claim, and deliberate forgetting instead of injecting every old claim.
 - Wrongness memory for repeated mistakes, wrong decisions, stale assumptions, and overconfident claims.

package/references/mission.md

@@ -49,6 +49,31 @@ Use a small envelope when a real mission lane changes code:
 
 This is only a record shape. It is not a queue, lock manager, or parallel apply engine.
 
+Patch queue lite:
+
+Use this only when two or more real mission lanes produce patches, apply order matters, or rollback needs a clearer handoff.
+Persist it with `--out` only when a later run needs to resume or audit the queue. Otherwise keep it in the report.
+
+Each item records:
+
+- `status`: pending / applied / verified / reverted / blocked
+- `lane_id`
+- `depends_on`: lane ids that must land first, or empty
+- `assigned_scope`
+- `changed_files`
+- `verification_hint`
+- `rollback_hint`
+- `truth_status`
+- `next_action`
+
+Keep it lite:
+
+- No automatic merge engine.
+- No persistent locks.
+- No required queue file for single-pass missions.
+- No parallel apply worker.
+- No broad runtime orchestration unless mission evidence already needs it.
+
 Rollback hint:
 
 Record:

package/references/runtime-orchestration.md

@@ -41,11 +41,35 @@ Runtime proof should include:
 - Goal.
 - Steps run.
 - Commands/processes started.
-- PIDs, ports, sessions, or panes when available.
+- PID, port, URL, session, pane, screenshot id, started_at, stopped_at, and exit_code when available.
 - Checks before and after.
 - Cleanup result.
 - Truth status: proven, verified, partial, fixture_only, fixture_instrumented_real, integration_optional, real_required_missing, skipped, blocked, assumed.
 
+## Runtime Evidence Mini
+
+Use the mini shape when a final report, release report, or doctor scan needs runtime evidence without a full runtime proof artifact.
+
+Minimum fields:
+
+- `kind`: `runtime_evidence_mini`
+- `route`: `deep` or `mission`
+- `required`: true / false
+- `command` or check name
+- `target`: URL, port, process, or service
+- `pid`, `port`, `url`, `exit_code`, `screenshot_id`, `started_at`, `stopped_at`
+- `process`: session, pane, or `unknown` when process detail is unavailable
+- `observation`: before and after notes
+- `cleanup`: status and evidence
+- `truth_status`
+- `next_action`: one concrete follow-up when status is not fully proven
+
+Truth caps:
+
+- Missing process/target evidence cannot support `proven`.
+- Missing cleanup evidence cannot support a cleanup-complete claim.
+- Optional runtime checks may be `integration_optional`; required but unavailable runtime checks should be `real_required_missing`, `blocked`, or `partial`.
+
 ## Cleanup Rule
 
 Do not claim cleanup succeeded unless one of these is true:

package/references/tool-trust-layer.md

@@ -25,13 +25,13 @@ Then depth increases by route:
 
 ## Surfaces To Wrap
 
-- Codex CLI/App readiness.
-- Browser and Computer Use availability.
+- Local CLI/app readiness.
+- Browser and screen-control 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.
+- Current official docs for package/API questions.
+- provider routing health when configured.
 - DB/Supabase safety for destructive or migration work.
 - Research, QA, wiki/context, proof, and release-gate workflows.
 
@@ -66,7 +66,7 @@ On demand:
 - Tool readiness checks.
 - Hook status and trust reporting.
 - DB/Supabase destructive-operation gate thinking.
-- Computer Use and screenshot evidence caps.
+- Screen-control and screenshot evidence caps.
 - tmux/process cleanup truth.
 - Source-intelligence proof for current docs.
 - Destructive DB/Supabase command detection and production-write caution.
@@ -92,7 +92,7 @@ On demand:
 - Always-on hook enforcement.
 - Release gates for normal coding.
 - Mandatory generated image review for every UI task.
-- Broad MCP/tool scans before small work.
+- Broad connector/tool scans before small work.
 - Provider config mutation without explicit user approval.
 
 ## Implemented Shape
@@ -106,14 +106,26 @@ On demand:
 - suggest route and proof level
 - do not install, configure, or mutate
 
+Tool intent labels stay advisory and route-scoped:
+
+- `read_only`: inspect, list, or report.
+- `write`: edit workspace files or local generated artifacts.
+- `destructive`: delete, reset, overwrite, publish irreversible data, or mutate production-like state.
+- `runtime`: start, stop, probe, or depend on a live process.
+- `visual`: capture, compare, or inspect screen evidence.
+- `publish`: package, release, push, deploy, or expose artifacts.
+
 `yam proof` should summarize what actually ran:
 
 - command evidence
 - browser/screenshot evidence
 - visual provenance for reference-based UI work
 - mission patch envelopes for real team lanes
+- runtime evidence mini for route-level runtime claims
+- patch queue lite when mission lane apply/verify order matters
 - rollback hints for risky changes
 - runtime/tmux/process cleanup evidence
+- structured diagnostic next action
 - truth status
 - skipped/blocked/assumed items
 
@@ -125,4 +137,86 @@ On demand:
 - registry status
 - CLI smoke
 - dist freshness
+- release tarball provenance: package name/version, tarball path, sha256, generated_at, source commit/tree state, included files summary
+- diagnostics with structured next action
 - final truth status
+
+## Compact Artifact Contracts
+
+Runtime evidence mini:
+
+```json
+{
+  "kind": "runtime_evidence_mini",
+  "route": "deep",
+  "required": true,
+  "command": "npm run dev",
+  "target": "http://localhost:3000",
+  "pid": "unknown",
+  "port": "3000",
+  "url": "http://localhost:3000",
+  "exit_code": null,
+  "screenshot_id": "",
+  "started_at": "",
+  "stopped_at": "",
+  "process": {
+    "session": "",
+    "pane": ""
+  },
+  "observation": {
+    "before": "",
+    "after": ""
+  },
+  "cleanup": {
+    "status": "checked_stopped",
+    "evidence": ""
+  },
+  "truth_status": "partial",
+  "next_action": {
+    "kind": "run_check",
+    "summary": ""
+  }
+}
+```
+
+Patch queue lite:
+
+```json
+{
+  "kind": "patch_queue_lite",
+  "items": [
+    {
+      "status": "pending",
+      "lane_id": "",
+      "depends_on": [],
+      "assigned_scope": "",
+      "changed_files": [],
+      "verification_hint": "",
+      "rollback_hint": "",
+      "truth_status": "partial",
+      "next_action": ""
+    }
+  ]
+}
+```
+
+Structured diagnostic next action:
+
+```json
+{
+  "status": "needs_action",
+  "severity": "P2",
+  "owner_route": "quick",
+  "priority": "fix_first",
+  "fix_first": true,
+  "blocks_release": false,
+  "observation": "",
+  "evidence": "",
+  "next_action": {
+    "kind": "run_command",
+    "command": "",
+    "reason": ""
+  },
+  "truth_status": "partial"
+}
+```

package/references/ueye-proof.md

@@ -29,9 +29,10 @@ yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --js
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality needs-polish --json
 ```
 
-- `capture` uses a Playwright install from the current project when present, then reports `blocked` instead of installing dependencies or pretending a screenshot exists.
+- `capture` uses a project-local capture backend 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`.
 - `report` records the Ueye run as reference sources, implementation sources, comparison result, design quality, blocked reason, next action, and truth status.
+- `report` may include continuity fields when a previous review or screenshot is being rechecked.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
 ### Media Generation Proof
@@ -54,10 +55,10 @@ Record:
 
 ### 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`.
+- Prefer the in-app browser for local pages, localhost, file URLs, and ordinary visual QA.
+- Do not silently switch to a profile-dependent browser when the in-app browser cannot capture or inspect.
+- Use a profile-dependent browser only when the user explicitly asks for it, or when the task requires existing cookies, sessions, extensions, or profile state.
+- If the in-app browser is unavailable and a profile-dependent browser was not explicitly requested or required, cap the visual claim at `partial` or `blocked`.
 
 ### Visual Evidence Inventory
 
@@ -92,6 +93,8 @@ Record these fields when a reference or screenshot materially affects the claim:
 - `source_hash`
 - `reference_id`
 - `screenshot_id`
+- `viewport`
+- `state`
 - `local_only`
 - `redacted`
 - `operator_provided`
@@ -160,6 +163,32 @@ Dimensions:
 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`.
 
+### Review Continuity And Comparison Report
+
+Use this when a Ueye task continues a previous visual review, rechecks a fix, or compares two review runs.
+
+Minimum fields:
+
+- `previous_report_id` or `previous_report_path`
+- `previous_screenshot_id`, when available
+- `previous_source_hash`, when available
+- `current_report_id` or `current_source_path`
+- `current_screenshot_id`, when available
+- `current_source_hash`, when available
+- `viewport`
+- `state`
+- `changed_surface`
+- `comparison_result`: improved / regressed / unchanged / not-verified
+- `regression`: true / false / not-verified
+- `resolved_findings`
+- `new_findings`
+- `still_open_findings`
+- `design_quality`
+- `truth_status`
+- `next_action`
+
+Do not claim continuity from memory alone. Link it to a previous report, screenshot, source path/hash, or an explicit user-provided prior finding.
+
 ## Truth Caps
 
 - Full visual verification requires real implementation evidence and relevant recheck.

package/references/ueye.md

@@ -65,6 +65,7 @@ Use these when the task depends on visual truth, reference matching, or design q
 2. Reference Read Proof.
 3. Reference vs Implementation Matrix.
 4. Design Quality Review.
+5. Review Continuity and Comparison Report.
 
 Default bound:
 
@@ -145,6 +146,26 @@ 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.
 
+### 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.
+
+Record:
+
+- `review_session_id` for the current pass.
+- previous report path or previous session id when available.
+- reference sources and implementation screenshot sources.
+- comparison result.
+- previous and current screenshot ids when available.
+- viewport and state.
+- similar, different, and missing items.
+- resolved findings, new findings, still-open findings, and regression status.
+- design quality result.
+- next visual action.
+- truth status.
+
+Use `yam ueye report --previous-report previous.json --review-session-id current-pass --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+
 ## P0-P3 Ledger
 
 - P0: blocker, unusable, impossible to complete primary workflow, severe accessibility or responsive failure.
@@ -162,8 +183,9 @@ Keep actionable findings in P0-P3 order. Prefer fixing P0/P1 and cheap local P2
 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.
+9. Review Continuity and Comparison Report when the work spans multiple passes.
+10. P0/P1 closeout.
+11. Truth status.
 
 ## Truth Caps
 

package/skills/question/SKILL.md

@@ -8,7 +8,7 @@ description: Very-light Q&A route. Use when the user invokes $question or asks a
 Use for:
 - Simple conceptual explanations.
 - "What is X?" or "Can I do Y?" questions.
-- Local harness/project usage questions.
+- Local workflow/project usage questions.
 - Clarifying a decision that does not need fresh source gathering.
 
 Do not use for:

package/skills/ueye/SKILL.md

@@ -37,8 +37,9 @@ Do not use for:
 - 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.
 - Use `yam ueye report` when reference, implementation screenshot, comparison result, design quality, and next action should be recorded as one compact run report.
+- For follow-up visual reviews, keep continuity explicit: previous report/source, current report/source, comparison delta, resolved findings, new findings, and next action.
 - Generated media can guide direction, but it cannot verify the implemented screen without implementation screenshot 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.
+- 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.
 
 ## Workflow
 
@@ -56,11 +57,12 @@ 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.
+   - Prefer the in-app browser for local pages, localhost, file URLs, and ordinary visual QA.
+   - Do not silently use a profile-dependent browser 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 project-local capture backend 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.
    - Use `yam ueye report --reference ref.png --actual shot.png --design-quality needs-polish --json` to preserve the run-level visual provenance and next action.
+   - When continuing a prior review, include previous/current report or screenshot identifiers and mark the comparison as improved, regressed, unchanged, or not-verified.
 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."
@@ -98,7 +100,9 @@ Use these artifacts for reference-led implementation or serious visual review. K
 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.
-6. Media Generation Proof, when generated images are part of the task:
+6. 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.
+7. 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.
@@ -142,6 +146,7 @@ Report:
 - Source evidence used.
 - Reference Read Proof and reference comparison result when a reference was used.
 - Design Quality Review result when implementation or serious visual review was requested.
+- Review continuity/comparison result when this continues a prior Ueye run.
 - P0-P3 issues or confirmation that no blockers were found.
 - States/viewports checked.
 - Truth status and visual verification cap.