yam-flow 0.1.2 → 0.1.3

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

@@ -3,6 +3,8 @@ export type TruthStatus = (typeof TRUTH_STATUSES)[number];
 export type SafetyLevel = 'danger' | 'warning';
 export type EvidenceKind = 'command' | 'evidence' | 'visual' | 'runtime' | 'skipped' | 'blocked' | 'assumption' | 'cleanup' | 'none';
 export type RuntimeSubsystem = 'real_runtime' | 'tmux_physical' | 'process_cleanup' | 'browser_visual' | 'db_safety';
+export type RuntimeBackend = 'none' | 'in_app_browser' | 'playwright' | 'terminal' | 'tmux' | 'zellij' | 'unknown';
+export type RuntimeClaim = 'not_started' | 'started' | 'observed' | 'stopped' | 'cleanup_verified' | 'blocked' | 'unknown';
 export interface SafetyHit {
     level: SafetyLevel;
     reason: string;
@@ -58,6 +60,38 @@ export interface MissionPatchEnvelope {
     rollback_hint: RollbackHint;
     truth_status: TruthStatus;
 }
+export interface RuntimeBackendEvidence {
+    schema: 'yam.runtime-backend-evidence.v1';
+    backend: RuntimeBackend;
+    claim: RuntimeClaim;
+    evidence_id: string;
+    command: string;
+    cleanup_checked: boolean;
+    note: string;
+    truth_status: TruthStatus;
+}
+export interface UeyeRunReport {
+    schema: 'yam.ueye-run-report.v1';
+    reference_sources: UeyeVisualProvenance[];
+    implementation_sources: UeyeVisualProvenance[];
+    comparison_result: string;
+    design_quality: string;
+    blocked_reason: string;
+    next_action: string;
+    truth_status: TruthStatus;
+}
+export interface MediaGenerationProof {
+    schema: 'yam.media-generation-proof.v1';
+    tool_name: string;
+    generation_requested: boolean;
+    generation_attempted: boolean;
+    output_path: string;
+    output_hash: string;
+    wait_loop_checked: boolean;
+    blocked_reason: string;
+    next_action: string;
+    truth_status: TruthStatus;
+}
 export interface FakeRealPolicyResult {
     schema: 'yam.fake-real-policy.v1';
     ok: boolean;
@@ -84,6 +118,8 @@ export interface ProofSummary {
     visualProvenance?: unknown;
     missionEnvelope?: unknown;
     rollbackHint?: unknown;
+    runtimeBackendEvidence?: unknown;
+    mediaProof?: unknown;
 }
 export interface ProofOptions {
     requireRealRuntime?: boolean;
@@ -114,6 +150,8 @@ export interface YamCompletionProof {
     visualProvenance: string[];
     missionEnvelope: string[];
     rollbackHint: string[];
+    runtimeBackendEvidence: string[];
+    mediaProof: string[];
     cleanup: unknown;
     changed: string[];
     skipped: string[];
@@ -128,6 +166,9 @@ export interface YamCompletionProof {
 export declare function buildUeyeVisualProvenance(input?: Partial<UeyeVisualProvenance>): UeyeVisualProvenance;
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
+export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;
+export declare function buildUeyeRunReport(input?: Partial<UeyeRunReport>): UeyeRunReport;
+export declare function buildMediaGenerationProof(input?: Partial<MediaGenerationProof>): MediaGenerationProof;
 export declare function isTruthStatus(value?: unknown): value is TruthStatus;
 export declare function weakestTruth(...statuses: unknown[]): TruthStatus;
 export declare function detectDbSafetyText(text?: unknown): DbSafetyScanResult;

package/dist/lib/trust-kernel.js

@@ -49,6 +49,70 @@ export function buildMissionPatchEnvelope(input = {}) {
         truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
     };
 }
+export function buildRuntimeBackendEvidence(input = {}) {
+    const backend = normalizeRuntimeBackend(input.backend);
+    const claim = normalizeRuntimeClaim(input.claim);
+    return {
+        schema: 'yam.runtime-backend-evidence.v1',
+        backend,
+        claim,
+        evidence_id: String(input.evidence_id || ''),
+        command: String(input.command || ''),
+        cleanup_checked: Boolean(input.cleanup_checked),
+        note: String(input.note || ''),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : runtimeBackendTruth(backend, claim, Boolean(input.cleanup_checked))
+    };
+}
+export function buildUeyeRunReport(input = {}) {
+    const references = Array.isArray(input.reference_sources)
+        ? input.reference_sources.map((item) => buildUeyeVisualProvenance(item))
+        : [];
+    const implementations = Array.isArray(input.implementation_sources)
+        ? input.implementation_sources.map((item) => buildUeyeVisualProvenance(item))
+        : [];
+    const blockedReason = String(input.blocked_reason || '');
+    const comparisonResult = String(input.comparison_result || 'not-verified');
+    const hasImplementation = implementations.length > 0;
+    const derivedTruth = blockedReason ? 'blocked'
+        : !references.length && !hasImplementation ? 'assumed'
+            : comparisonResult === 'matched' && hasImplementation ? 'verified'
+                : hasImplementation ? 'partial'
+                    : 'partial';
+    return {
+        schema: 'yam.ueye-run-report.v1',
+        reference_sources: references,
+        implementation_sources: implementations,
+        comparison_result: comparisonResult,
+        design_quality: String(input.design_quality || 'not-checked'),
+        blocked_reason: blockedReason,
+        next_action: String(input.next_action || (derivedTruth === 'verified' ? 'no action required' : 'capture or provide implementation screenshot before claiming verified visual status')),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : derivedTruth
+    };
+}
+export function buildMediaGenerationProof(input = {}) {
+    const requested = Boolean(input.generation_requested);
+    const attempted = Boolean(input.generation_attempted);
+    const outputHash = String(input.output_hash || 'unknown');
+    const blockedReason = String(input.blocked_reason || '');
+    const derivedTruth = blockedReason ? 'blocked'
+        : requested && !attempted ? 'blocked'
+            : attempted && outputHash !== 'unknown' ? 'verified'
+                : attempted ? 'partial'
+                    : requested ? 'assumed'
+                        : 'skipped';
+    return {
+        schema: 'yam.media-generation-proof.v1',
+        tool_name: String(input.tool_name || ''),
+        generation_requested: requested,
+        generation_attempted: attempted,
+        output_path: String(input.output_path || ''),
+        output_hash: outputHash,
+        wait_loop_checked: Boolean(input.wait_loop_checked),
+        blocked_reason: blockedReason,
+        next_action: String(input.next_action || (derivedTruth === 'blocked' ? 'provide a usable media tool or mark generation as skipped' : 'record output evidence before using generated media as implementation proof')),
+        truth_status: isTruthStatus(input.truth_status) ? input.truth_status : derivedTruth
+    };
+}
 const TRUTH_RANK = Object.freeze({
     blocked: 0,
     real_required_missing: 0,
@@ -129,6 +193,12 @@ export function classifyEvidenceTruth(summary = {}, options = {}) {
     for (const rollback of asList(summary.rollbackHint)) {
         rows.push(evidenceRow('evidence', rollback, metadataTruth(rollback, 'partial')));
     }
+    for (const backend of asList(summary.runtimeBackendEvidence)) {
+        rows.push(evidenceRow('runtime', backend, readStructuredTruth(backend, 'partial')));
+    }
+    for (const media of asList(summary.mediaProof)) {
+        rows.push(evidenceRow('evidence', media, readStructuredTruth(media, 'partial')));
+    }
     for (const runtime of asList(summary.runtime)) {
         rows.push(evidenceRow('runtime', runtime, classifyRuntimeEvidence(runtime, options)));
     }
@@ -217,6 +287,8 @@ export function buildYamCompletionProof(summary = {}, options = {}) {
         visualProvenance: asList(summary.visualProvenance),
         missionEnvelope: asList(summary.missionEnvelope),
         rollbackHint: asList(summary.rollbackHint),
+        runtimeBackendEvidence: asList(summary.runtimeBackendEvidence),
+        mediaProof: asList(summary.mediaProof),
         cleanup: summary.cleanup || '',
         changed: asList(summary.changed),
         skipped: asList(summary.skipped),
@@ -353,6 +425,51 @@ function runtimeRow(subsystem, proofLevel, required) {
             : 'no action required'
     };
 }
+function normalizeRuntimeBackend(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (text === 'in_app_browser' || text === 'browser')
+        return 'in_app_browser';
+    if (text === 'playwright')
+        return 'playwright';
+    if (text === 'terminal' || text === 'shell')
+        return 'terminal';
+    if (text === 'tmux')
+        return 'tmux';
+    if (text === 'zellij')
+        return 'zellij';
+    if (text === 'none' || text === 'not_started')
+        return 'none';
+    return 'unknown';
+}
+function normalizeRuntimeClaim(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (text === 'not_started' || text === 'none')
+        return 'not_started';
+    if (text === 'started')
+        return 'started';
+    if (text === 'observed' || text === 'checked')
+        return 'observed';
+    if (text === 'stopped')
+        return 'stopped';
+    if (text === 'cleanup_verified' || text === 'cleanup_checked')
+        return 'cleanup_verified';
+    if (text === 'blocked')
+        return 'blocked';
+    return 'unknown';
+}
+function runtimeBackendTruth(backend, claim, cleanupChecked = false) {
+    if (claim === 'blocked')
+        return 'blocked';
+    if (backend === 'none' || claim === 'not_started')
+        return 'skipped';
+    if (backend === 'unknown' || claim === 'unknown')
+        return 'partial';
+    if (claim === 'cleanup_verified' || cleanupChecked)
+        return 'proven';
+    if (claim === 'observed' || claim === 'stopped' || claim === 'started')
+        return 'verified';
+    return 'partial';
+}
 function evidenceRow(kind, value, truth) {
     return { kind, value: String(value || ''), truth };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/ueye-proof.md

@@ -26,12 +26,32 @@ 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
 ```
 
 - `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`.
+- `report` records the Ueye run as reference sources, implementation sources, comparison result, design quality, blocked reason, next action, and truth status.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
+### Media Generation Proof
+
+Generated media can help with direction and visual ideation, but it is derivative evidence. It cannot prove that the implemented UI was captured or compared.
+
+```bash
+yam media proof --requested --attempted --output ./generated.png --wait-loop --json
+```
+
+Record:
+
+- tool name, when relevant
+- whether generation was requested
+- whether generation was attempted
+- output path and hash, when a local image exists
+- whether the wait loop was checked
+- blocked reason and next action
+- truth status
+
 ### Browser Preference
 
 - Prefer the Codex in-app Browser plugin for local pages, localhost, file URLs, and ordinary visual QA.

package/skills/ueye/SKILL.md

@@ -36,6 +36,8 @@ Do not use for:
 - 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.
+- Use `yam ueye report` when reference, implementation screenshot, comparison result, design quality, and next action should be recorded as one compact run report.
+- 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.
 
 ## Workflow
@@ -58,6 +60,7 @@ Do not use for:
    - 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.
+   - 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.
 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."
@@ -95,6 +98,10 @@ 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:
+   - 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.
 
 ## Visual Truth Caps