yam-flow 0.1.3 → 0.1.5

package/src/lib/trust-kernel.ts

@@ -56,6 +56,11 @@ 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;
@@ -63,6 +68,26 @@ export interface UeyeVisualProvenance {
   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[];
@@ -96,6 +121,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;
@@ -201,6 +227,11 @@ export function buildUeyeVisualProvenance(input: Partial<UeyeVisualProvenance> =
     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),
@@ -209,6 +240,28 @@ export function buildUeyeVisualProvenance(input: Partial<UeyeVisualProvenance> =
   };
 }
 
+export function buildUeyeSurfaceContext(input: Partial<UeyeSurfaceContext> = {}): UeyeSurfaceContext {
+  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: Partial<RollbackHint> = {}): RollbackHint {
   return {
     schema: 'yam.rollback-hint.v1',
@@ -268,6 +321,10 @@ export function buildUeyeRunReport(input: Partial<UeyeRunReport> = {}): UeyeRunR
     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/templates/mission-plan.md

@@ -36,6 +36,18 @@ Patch envelope:
 - verification_hint:
 - truth_status: verified / partial / skipped / blocked / assumed
 
+Patch queue lite:
+- status: pending / applied / verified / reverted / blocked
+- lane_id:
+- depends_on:
+- assigned_scope:
+- changed_files:
+- verification_hint:
+- rollback_hint:
+- truth_status:
+- next_action:
+- --out optional persistence path:
+
 Rollback hint:
 - touched_files:
 - generated_files:

package/templates/runtime-proof.md

@@ -13,8 +13,11 @@
 - Command:
 - PID/session/pane:
 - Port:
-- Started:
-- Stopped:
+- URL:
+- Screenshot id:
+- Started at:
+- Stopped at:
+- Exit code:
 - Exit/closure verified:
 
 ## tmux
@@ -32,6 +35,42 @@
 - During:
 - After:
 
+## Runtime Evidence Mini
+
+```json
+{
+  "kind": "runtime_evidence_mini",
+  "route": "deep",
+  "required": true,
+  "command": "",
+  "target": "",
+  "pid": "unknown",
+  "port": "",
+  "url": "",
+  "exit_code": null,
+  "screenshot_id": "",
+  "started_at": "",
+  "stopped_at": "",
+  "process": {
+    "session": "",
+    "pane": ""
+  },
+  "observation": {
+    "before": "",
+    "after": ""
+  },
+  "cleanup": {
+    "status": "not-checked",
+    "evidence": ""
+  },
+  "truth_status": "partial",
+  "next_action": {
+    "kind": "",
+    "summary": ""
+  }
+}
+```
+
 ## Verification
 
 - Command/check:

package/templates/tuning-log.md

@@ -25,7 +25,17 @@ Use this to tune route wording from real use.
 - Seconds:
 - Budget result:
 
-## Fix To Harness
+## Benchmark Optimization Loop Lite
+
+- Baseline command: yam measure <route> --files  --commands  --report-lines  --seconds
+- Baseline result:
+- One route wording or doc change:
+- Rerun command:
+- Rerun result:
+- Decision: keep / revert / retry once / stop
+- Stop condition:
+
+## Fix To yam
 
 - Skill to edit:
 - Proposed wording:

package/templates/ueye-comparison.md

@@ -23,12 +23,32 @@
 | source_hash | unknown |
 | reference_id |  |
 | screenshot_id |  |
+| viewport |  |
+| state |  |
 | local_only | true / false |
 | redacted | true / false |
 | operator_provided | true / false |
 | comparison_result | matched / similar / different / not-verified / not-applicable |
 | truth_status | verified / partial / skipped / blocked / assumed |
 
+## Surface Context
+
+| Field | Value |
+| --- | --- |
+| provider_context | not-recorded |
+| provider_badge | not-recorded |
+| execution_surface | not-recorded |
+| app_surface | not-recorded |
+| browser_surface | not-recorded |
+| control_mode | not-recorded |
+| url |  |
+| viewport |  |
+| screenshot_id |  |
+| evidence_id |  |
+| preserved_state | true / false |
+| preserved_url |  |
+| truth_status | verified / partial / skipped / blocked / assumed |
+
 ## Reference Read Proof
 
 - Layout:
@@ -56,6 +76,26 @@ Use `matched`, `similar`, `different`, `not-verified`, or `not-applicable`.
 | Accessibility visuals | not-verified |  |  |
 | Brand and mood fit | not-verified |  |  |
 
+## Review Continuity
+
+| Field | Value |
+| --- | --- |
+| previous_report_id/path |  |
+| previous_screenshot_id |  |
+| previous_source_hash | unknown |
+| current_report_id/path |  |
+| current_screenshot_id |  |
+| current_source_hash | unknown |
+| viewport |  |
+| state |  |
+| changed_surface |  |
+| continuity_result | improved / regressed / unchanged / not-verified |
+| regression | true / false / not-verified |
+| resolved_findings |  |
+| new_findings |  |
+| still_open_findings |  |
+| next_action |  |
+
 ## Design Quality Review
 
 Use `pass`, `needs-polish`, or `fails` for each relevant design dimension before listing actionable issues.
@@ -91,3 +131,36 @@ Use `pass`, `needs-polish`, or `fails` for each relevant design dimension before
 ## Truth Status
 
 - verified / partial / skipped / blocked / assumed:
+
+## Comparison Report JSON
+
+```json
+{
+  "kind": "ueye_comparison_report",
+  "previous_report_id": "",
+  "previous_screenshot_id": "",
+  "current_report_id": "",
+  "current_screenshot_id": "",
+  "surface_context": {
+    "provider_context": "not-recorded",
+    "provider_badge": "not-recorded",
+    "execution_surface": "not-recorded",
+    "app_surface": "not-recorded",
+    "browser_surface": "not-recorded",
+    "control_mode": "not-recorded",
+    "preserved_state": false,
+    "preserved_url": "",
+    "truth_status": "partial"
+  },
+  "viewport": "",
+  "state": "",
+  "comparison_result": "not-verified",
+  "regression": "not-verified",
+  "resolved_findings": [],
+  "new_findings": [],
+  "still_open": [],
+  "design_quality": "needs-polish",
+  "truth_status": "partial",
+  "next_action": ""
+}
+```

package/templates/ueye-review.md

@@ -34,12 +34,32 @@
 | source_hash | unknown |
 | reference_id |  |
 | screenshot_id |  |
+| viewport |  |
+| state |  |
 | local_only | true / false |
 | redacted | true / false |
 | operator_provided | true / false |
 | comparison_result | matched / similar / different / not-verified / not-applicable |
 | truth_status | verified / partial / skipped / blocked / assumed |
 
+## Surface Context
+
+| Field | Value |
+| --- | --- |
+| provider_context | not-recorded |
+| provider_badge | not-recorded |
+| execution_surface | not-recorded |
+| app_surface | not-recorded |
+| browser_surface | not-recorded |
+| control_mode | not-recorded |
+| url |  |
+| viewport |  |
+| screenshot_id |  |
+| evidence_id |  |
+| preserved_state | true / false |
+| preserved_url |  |
+| truth_status | verified / partial / skipped / blocked / assumed |
+
 ## Reference Read Proof
 
 - Layout:
@@ -67,6 +87,26 @@
 
 Status values: matched / similar / different / not-verified / not-applicable.
 
+## Review Continuity
+
+| Field | Value |
+| --- | --- |
+| previous_report_id/path |  |
+| previous_screenshot_id |  |
+| previous_source_hash | unknown |
+| current_report_id/path |  |
+| current_screenshot_id |  |
+| current_source_hash | unknown |
+| viewport |  |
+| state |  |
+| changed_surface |  |
+| continuity_result | improved / regressed / unchanged / not-verified |
+| regression | true / false / not-verified |
+| resolved_findings |  |
+| new_findings |  |
+| still_open_findings |  |
+| next_action |  |
+
 ## Design Quality Review
 
 | Dimension | Result | Evidence |
@@ -123,3 +163,36 @@ Result values: pass / needs-polish / fails.
 ## Truth Status
 
 - verified / partial / skipped / blocked / assumed:
+
+## Review Report JSON
+
+```json
+{
+  "kind": "ueye_review_report",
+  "previous_report_id": "",
+  "previous_screenshot_id": "",
+  "current_report_id": "",
+  "current_screenshot_id": "",
+  "surface_context": {
+    "provider_context": "not-recorded",
+    "provider_badge": "not-recorded",
+    "execution_surface": "not-recorded",
+    "app_surface": "not-recorded",
+    "browser_surface": "not-recorded",
+    "control_mode": "not-recorded",
+    "preserved_state": false,
+    "preserved_url": "",
+    "truth_status": "partial"
+  },
+  "viewport": "",
+  "state": "",
+  "comparison_result": "not-verified",
+  "regression": "not-verified",
+  "resolved_findings": [],
+  "new_findings": [],
+  "still_open": [],
+  "design_quality": "needs-polish",
+  "truth_status": "partial",
+  "next_action": ""
+}
+```

package/templates/yam.project.md

@@ -44,7 +44,7 @@
 - UI changes:
 - Feature changes:
 - Risky changes:
-- Public/release changes: scan for external harness/tool names, comparison wording, and origin-credit wording; remove those hits unless the user explicitly approves keeping them.
+- Public/release changes: scan for external tool names, comparison wording, and attribution wording; remove those hits unless the user explicitly approves keeping them.
 
 ## Known Risks
 
@@ -62,7 +62,7 @@
 
 - Do not:
 - Avoid:
-- Do not leave external harness/tool/project comparison, attribution, or origin-credit language in public-facing source, docs, npm metadata, release notes, or GitHub repository text.
+- Do not leave external tool/project comparison or attribution language in public-facing source, docs, npm metadata, release notes, or GitHub repository text.
 
 ## MD Management
 

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -22,7 +22,7 @@
     {
       "id": "ueye",
       "stage": "v0.3",
-      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
+      "purpose": "Tight UI/UX/design implementation and visual review with visual provenance, surface context, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
     },
     {
       "id": "question",