yam-flow 0.1.2 → 0.1.4

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.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

@@ -26,18 +26,39 @@ 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.
+- `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
+
+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.
-- 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
 
@@ -72,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`
@@ -140,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.