yam-flow 0.1.3 → 0.1.5

package/dist/lib/trust-kernel.d.ts

@@ -38,12 +38,36 @@ export interface UeyeVisualProvenance {
     source_hash: string;
     reference_id: string;
     screenshot_id: string;
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
     local_only: boolean;
     redacted: boolean;
     operator_provided: boolean;
     comparison_result: string;
     truth_status: TruthStatus;
 }
+export interface UeyeSurfaceContext {
+    schema: 'yam.ueye-surface-context.v1';
+    provider_context: string;
+    provider_badge: string;
+    execution_surface: string;
+    app_surface: string;
+    browser_surface: string;
+    control_mode: string;
+    route: string;
+    mode: string;
+    url: string;
+    viewport: string;
+    screenshot_id: string;
+    evidence_id: string;
+    preserved_state: boolean;
+    preserved_url: string;
+    local_only: boolean;
+    truth_status: TruthStatus;
+}
 export interface RollbackHint {
     schema: 'yam.rollback-hint.v1';
     touched_files: string[];
@@ -74,6 +98,7 @@ export interface UeyeRunReport {
     schema: 'yam.ueye-run-report.v1';
     reference_sources: UeyeVisualProvenance[];
     implementation_sources: UeyeVisualProvenance[];
+    surface_context: UeyeSurfaceContext;
     comparison_result: string;
     design_quality: string;
     blocked_reason: string;
@@ -164,6 +189,7 @@ export interface YamCompletionProof {
     runtimeTruth: RuntimeTruthMatrix;
 }
 export declare function buildUeyeVisualProvenance(input?: Partial<UeyeVisualProvenance>): UeyeVisualProvenance;
+export declare function buildUeyeSurfaceContext(input?: Partial<UeyeSurfaceContext>): UeyeSurfaceContext;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;

package/dist/lib/trust-kernel.js

@@ -19,6 +19,11 @@ export function buildUeyeVisualProvenance(input = {}) {
         source_hash: String(input.source_hash || 'unknown'),
         reference_id: String(input.reference_id || ''),
         screenshot_id: String(input.screenshot_id || ''),
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
         local_only: Boolean(input.local_only),
         redacted: Boolean(input.redacted),
         operator_provided: Boolean(input.operator_provided),
@@ -26,6 +31,27 @@ export function buildUeyeVisualProvenance(input = {}) {
         truth_status: truth
     };
 }
+export function buildUeyeSurfaceContext(input = {}) {
+    return {
+        schema: 'yam.ueye-surface-context.v1',
+        provider_context: String(input.provider_context || 'not-recorded'),
+        provider_badge: String(input.provider_badge || input.provider_context || 'not-recorded'),
+        execution_surface: String(input.execution_surface || 'not-recorded'),
+        app_surface: String(input.app_surface || 'not-recorded'),
+        browser_surface: String(input.browser_surface || 'not-recorded'),
+        control_mode: String(input.control_mode || 'not-recorded'),
+        route: String(input.route || 'ueye'),
+        mode: String(input.mode || 'report'),
+        url: String(input.url || ''),
+        viewport: String(input.viewport || ''),
+        screenshot_id: String(input.screenshot_id || ''),
+        evidence_id: String(input.evidence_id || ''),
+        preserved_state: Boolean(input.preserved_state),
+        preserved_url: String(input.preserved_url || ''),
+        local_only: input.local_only !== undefined ? Boolean(input.local_only) : true,
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
+    };
+}
 export function buildRollbackHint(input = {}) {
     return {
         schema: 'yam.rollback-hint.v1',
@@ -82,6 +108,10 @@ export function buildUeyeRunReport(input = {}) {
         schema: 'yam.ueye-run-report.v1',
         reference_sources: references,
         implementation_sources: implementations,
+        surface_context: buildUeyeSurfaceContext({
+            ...input.surface_context,
+            truth_status: isTruthStatus(input.surface_context?.truth_status) ? input.surface_context?.truth_status : derivedTruth
+        }),
         comparison_result: comparisonResult,
         design_quality: String(input.design_quality || 'not-checked'),
         blocked_reason: blockedReason,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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

@@ -26,12 +26,13 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```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 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 --browser-surface in-app-browser --preserved-state --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` records the Ueye run as reference sources, implementation sources, comparison result, surface context, 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,13 @@ Record these fields when a reference or screenshot materially affects the claim:
 - `source_hash`
 - `reference_id`
 - `screenshot_id`
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
+- `viewport`
+- `state`
 - `local_only`
 - `redacted`
 - `operator_provided`
@@ -100,6 +108,28 @@ Record these fields when a reference or screenshot materially affects the claim:
 
 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.
 
+### Surface Context
+
+Purpose: preserve where and how a visual claim was observed without turning Ueye into an always-on capture gate.
+
+Record these fields when they affect the visual claim:
+
+- `provider_context`
+- `provider_badge`
+- `execution_surface`
+- `app_surface`
+- `browser_surface`
+- `control_mode`
+- `url`
+- `viewport`
+- `screenshot_id`
+- `evidence_id`
+- `preserved_state`
+- `preserved_url`
+- `truth_status`
+
+Use `not-recorded` when the field was not observed. Prefer `partial` over `verified` when surface context exists but no actual implementation screenshot was captured or supplied.
+
 ### Reference Read Proof
 
 Purpose: separate reading the reference from judging the implementation.
@@ -160,6 +190,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,42 @@ 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 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "..." --different "..." --missing "..." --json` when you need a compact continuity record.
+
+### Surface Context
+
+Use surface context when a Ueye claim depends on preserving the current app/browser state or explaining where visual evidence came from.
+
+Fields:
+
+- provider context and badge.
+- execution surface.
+- app surface.
+- browser surface.
+- control mode.
+- preserved URL/state.
+- evidence id.
+
+Keep this metadata descriptive. It should support honest visual claims, not force a heavy browser workflow for every Ueye run.
+
 ## P0-P3 Ledger
 
 - P0: blocker, unusable, impossible to complete primary workflow, severe accessibility or responsive failure.
@@ -162,8 +199,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: