yam-flow 0.1.0 → 0.1.2

package/src/bin/yam.ts

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import {
   TRUTH_STATUSES,
+  buildMissionPatchEnvelope,
+  buildRollbackHint,
+  buildUeyeVisualProvenance,
   buildYamCompletionProof,
   detectDbSafetyText as detectTrustDbSafetyText,
   isTruthStatus
@@ -128,6 +134,9 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
+  yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
   yam hook <status|enable|disable|run> [lite] [--global|--project dir]
@@ -919,6 +928,85 @@ async function safety(args = []) {
   printSafetyResult(result);
 }
 
+async function release(args = []) {
+  const subcommand = args[0] || 'help';
+  if (subcommand !== 'report') {
+    console.error('usage: yam release report [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const asJson = args.includes('--json');
+  const report = runReleaseReport();
+  if (asJson) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+  console.log('yam release report');
+  console.log(`- Package: ${report.packageName}@${report.version}`);
+  console.log(`- Truth status: ${report.truth_status}`);
+  for (const check of report.checks) {
+    console.log(`- ${check.id}: ${check.status} (${check.duration_ms}ms)`);
+    if (check.note) console.log(`  ${check.note}`);
+  }
+  if (report.failed.length) {
+    console.log('- Failed:');
+    for (const id of report.failed) console.log(`  - ${id}`);
+  }
+  if (!report.ok) process.exitCode = 1;
+}
+
+function runReleaseReport() {
+  const startedAt = new Date().toISOString();
+  const checks = [
+    ['typecheck', ['npm', ['run', 'typecheck']]],
+    ['forbidden_names', ['npm', ['run', 'forbidden-names:check']]],
+    ['package_boundary', ['npm', ['run', 'package-boundary:check']]],
+    ['registry_status', ['npm', ['run', 'registry:check']]],
+    ['cli_smoke', ['npm', ['run', 'cli-smoke']]],
+    ['dist_freshness', ['npm', ['run', 'dist:freshness']]]
+  ].map(([id, command]) => runReleaseCheck(id, command));
+  const failed = checks.filter((check) => check.status !== 'passed').map((check) => check.id);
+  return {
+    schema: 'yam.release-report.v1',
+    generated_at: startedAt,
+    packageName: PACKAGE_JSON.name,
+    version: VERSION,
+    ok: failed.length === 0,
+    truth_status: failed.length === 0 ? 'verified' : 'blocked',
+    checks,
+    failed
+  };
+}
+
+function runReleaseCheck(id, commandSpec) {
+  const [command, args] = commandSpec;
+  const start = Date.now();
+  const result = spawnSync(command, args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    env: { ...process.env, npm_config_cache: path.join(os.tmpdir(), 'yam-npm-cache') },
+    timeout: 120000
+  });
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  const timedOut = result.error?.message?.includes('ETIMEDOUT') || result.signal === 'SIGTERM';
+  return {
+    id,
+    command: [command, ...args].join(' '),
+    status: result.status === 0 ? 'passed' : timedOut ? 'blocked' : 'failed',
+    exit_code: typeof result.status === 'number' ? result.status : null,
+    duration_ms: Date.now() - start,
+    note: summarizeCheckOutput(output || result.error?.message || '')
+  };
+}
+
+function summarizeCheckOutput(output = '') {
+  const lines = String(output || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (!lines.length) return '';
+  const highSignal = lines.filter((line) => !line.startsWith('>')).slice(-4);
+  return highSignal.join(' | ').slice(0, 600);
+}
+
 async function readStdinTextIfAvailable() {
   if (process.stdin.isTTY) return '';
   const chunks = [];
@@ -926,6 +1014,261 @@ async function readStdinTextIfAvailable() {
   return Buffer.concat(chunks).toString('utf8').trim();
 }
 
+async function ueye(args = []) {
+  const subcommand = args[0] || 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return ueyeUsage();
+  if (subcommand === 'capture') return ueyeCapture(args.slice(1));
+  if (subcommand === 'compare') return ueyeCompare(args.slice(1));
+  console.error(`unknown ueye command: ${subcommand}`);
+  return ueyeUsage();
+}
+
+function ueyeUsage() {
+  console.log(`yam ueye
+
+Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/compare only when verified visual claims need real evidence.
+
+Usage:
+  yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
+  yam ueye compare --reference ref.png --actual screenshot.png [--json]
+
+Notes:
+  capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
+  compare uses local files only and reports sha256, dimensions, comparison_result, and proof-ready visual provenance.
+`);
+}
+
+async function ueyeCapture(args = []) {
+  if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return ueyeUsage();
+  const flags = parseSimpleFlags(args, new Set(['url', 'out', 'viewport', 'wait-until', 'timeout', 'full-page', 'json']));
+  const url = String(flags.url || '');
+  const out = String(flags.out || '');
+  if (!url || !out) {
+    console.error('usage: yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = path.resolve(expandHome(out));
+  const viewport = parseViewport(String(flags.viewport || '1440x900'));
+  const timeout = Number(flags.timeout || 30000);
+  const waitUntil = String(flags.wait_until || 'networkidle');
+  let browser;
+
+  try {
+    const playwright = await loadOptionalPlaywright();
+    const chromium = playwright?.chromium;
+    if (!chromium) throw new Error('Playwright chromium launcher was not found');
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage({ viewport });
+    await page.goto(url, { waitUntil, timeout });
+    await page.screenshot({ path: target, fullPage: Boolean(flags.full_page) });
+    const info = await imageFileInfo(target);
+    const result = {
+      schema: 'yam.ueye-capture.v1',
+      status: 'verified',
+      url,
+      out: target,
+      viewport: `${viewport.width}x${viewport.height}`,
+      full_page: Boolean(flags.full_page),
+      sha256: info.sha256,
+      dimensions: info.dimensions,
+      visual_evidence: `browser screenshot captured: ${target} (${info.dimensions}, sha256:${info.sha256})`
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+  } catch (error) {
+    const result = {
+      schema: 'yam.ueye-capture.v1',
+      status: 'blocked',
+      url,
+      out: target,
+      reason: errorMessage(error),
+      next_action: 'Install Playwright in the current project or provide a user/browser screenshot, then use `yam ueye compare`.',
+      visual_cap: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye capture');
+    process.exitCode = 1;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+async function ueyeCompare(args = []) {
+  if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return ueyeUsage();
+  const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'json', 'reference-id', 'screenshot-id']));
+  const reference = String(flags.reference || flags.ref || '');
+  const actual = String(flags.actual || flags.screenshot || '');
+  if (!reference || !actual) {
+    console.error('usage: yam ueye compare --reference ref.png --actual screenshot.png [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const referencePath = path.resolve(expandHome(reference));
+  const actualPath = path.resolve(expandHome(actual));
+  try {
+    const referenceInfo = await imageFileInfo(referencePath);
+    const actualInfo = await imageFileInfo(actualPath);
+    if (referenceInfo.dimensions === 'unknown' || actualInfo.dimensions === 'unknown') {
+      throw new Error('compare requires image files with readable PNG, JPEG, or GIF dimensions');
+    }
+    const exactMatch = referenceInfo.sha256 === actualInfo.sha256;
+    const sameDimensions = referenceInfo.dimensions === actualInfo.dimensions;
+    const comparisonResult = exactMatch ? 'matched' : 'different';
+    const truthStatus = exactMatch ? 'verified' : 'partial';
+    const provenance = buildUeyeVisualProvenance({
+      source_kind: 'implementation_screenshot',
+      source_path: actualPath,
+      source_hash: actualInfo.sha256,
+      reference_id: String(flags.reference_id || path.basename(referencePath)),
+      screenshot_id: String(flags.screenshot_id || path.basename(actualPath)),
+      local_only: true,
+      redacted: false,
+      operator_provided: false,
+      comparison_result: comparisonResult,
+      truth_status: truthStatus
+    });
+    const result = {
+      schema: 'yam.ueye-compare.v1',
+      status: truthStatus,
+      comparison_result: comparisonResult,
+      exact_match: exactMatch,
+      same_dimensions: sameDimensions,
+      reference: referenceInfo,
+      actual: actualInfo,
+      visual_evidence: `browser/local screenshot comparison executed: reference=${referencePath}, actual=${actualPath}, result=${comparisonResult}`,
+      visual_provenance: provenance,
+      proof_hint: `yam proof --route ueye --truth ${truthStatus} --visual "browser/local screenshot comparison executed: ${comparisonResult}" --visual-provenance '${JSON.stringify(provenance)}' --require-visual`
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+  } catch (error) {
+    const result = {
+      schema: 'yam.ueye-compare.v1',
+      status: 'blocked',
+      comparison_result: 'not-verified',
+      reason: errorMessage(error),
+      visual_cap: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye compare');
+    process.exitCode = 1;
+  }
+}
+
+function parseSimpleFlags(args = [], allowed = new Set<string>()) {
+  const flags: AnyRecord = {};
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const [rawKey, inlineValue] = arg.includes('=') ? arg.split(/=(.*)/s, 2) : [arg, undefined];
+    const key = rawKey.slice(2);
+    if (allowed.size && !allowed.has(key)) continue;
+    const normalizedKey = key.replace(/-/g, '_');
+    if (['json', 'full-page'].includes(key)) {
+      flags[normalizedKey] = true;
+      continue;
+    }
+    const value = inlineValue ?? args[index + 1] ?? '';
+    if (inlineValue === undefined) index += 1;
+    flags[normalizedKey] = value;
+  }
+  flags._ = positionals;
+  return flags;
+}
+
+function parseViewport(value = '1440x900') {
+  const match = String(value || '').match(/^(\d{2,5})x(\d{2,5})$/i);
+  if (!match) return { width: 1440, height: 900 };
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+async function loadOptionalPlaywright() {
+  let projectError = '';
+  try {
+    const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+    return projectRequire('playwright');
+  } catch (error) {
+    projectError = errorMessage(error);
+    // Fall through to the yam package context for local development or bundled installs.
+  }
+  const dynamicImport = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<any>;
+  try {
+    return await dynamicImport('playwright');
+  } catch (error) {
+    throw new Error(`Playwright not found from current project or yam package context. Current project: ${projectError}; package context: ${errorMessage(error)}`);
+  }
+}
+
+async function imageFileInfo(file) {
+  const absolute = path.resolve(expandHome(file));
+  const buffer = await fsp.readFile(absolute);
+  const stat = await fsp.stat(absolute);
+  return {
+    path: absolute,
+    sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+    bytes: stat.size,
+    dimensions: imageDimensions(buffer)
+  };
+}
+
+function imageDimensions(buffer) {
+  const png = pngDimensions(buffer);
+  if (png) return png;
+  const jpeg = jpegDimensions(buffer);
+  if (jpeg) return jpeg;
+  const gif = gifDimensions(buffer);
+  if (gif) return gif;
+  return 'unknown';
+}
+
+function pngDimensions(buffer) {
+  if (buffer.length < 24) return '';
+  if (buffer.readUInt32BE(0) !== 0x89504e47 || buffer.readUInt32BE(4) !== 0x0d0a1a0a) return '';
+  return `${buffer.readUInt32BE(16)}x${buffer.readUInt32BE(20)}`;
+}
+
+function gifDimensions(buffer) {
+  if (buffer.length < 10) return '';
+  const signature = buffer.toString('ascii', 0, 6);
+  if (signature !== 'GIF87a' && signature !== 'GIF89a') return '';
+  return `${buffer.readUInt16LE(6)}x${buffer.readUInt16LE(8)}`;
+}
+
+function jpegDimensions(buffer) {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return '';
+  let offset = 2;
+  while (offset < buffer.length) {
+    if (buffer[offset] !== 0xff) return '';
+    const marker = buffer[offset + 1];
+    const length = buffer.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xc3 && offset + 8 < buffer.length) {
+      return `${buffer.readUInt16BE(offset + 7)}x${buffer.readUInt16BE(offset + 5)}`;
+    }
+    offset += 2 + length;
+  }
+  return '';
+}
+
+function printJsonOrHuman(result, json = false, label = 'yam') {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(label);
+  for (const [key, value] of Object.entries(result)) {
+    if (key === 'schema') continue;
+    if (typeof value === 'object' && value !== null) {
+      console.log(`- ${key}: ${JSON.stringify(value)}`);
+    } else {
+      console.log(`- ${key}: ${value}`);
+    }
+  }
+}
+
 function detectDbSafetyText(text = '') {
   return detectTrustDbSafetyText(text);
 }
@@ -966,6 +1309,9 @@ async function proof(args = []) {
   printProofList('Evidence', summary.evidence);
   printProofList('Visual evidence', summary.visual);
   printProofList('Runtime evidence', summary.runtime);
+  printProofList('Visual provenance', summary.visualProvenance || []);
+  printProofList('Mission patch envelope', summary.missionEnvelope || []);
+  printProofList('Rollback hint', summary.rollbackHint || []);
   printProofList('Changed surfaces', summary.changed);
   printProofList('Skipped', summary.skipped);
   printProofList('Blocked', summary.blocked);
@@ -1040,6 +1386,18 @@ function buildProofSummary(parsed, artifact) {
     evidence: [...artifact.evidence, ...arrayFlag(parsed.flags.evidence)],
     visual: [...artifact.visual, ...arrayFlag(parsed.flags.visual)],
     runtime: [...artifact.runtime, ...arrayFlag(parsed.flags.runtime)],
+    visualProvenance: [
+      ...structuredEvidenceList(artifact.visualProvenance),
+      ...structuredEvidenceList(parsed.flags.visual_provenance)
+    ],
+    missionEnvelope: [
+      ...structuredEvidenceList(artifact.missionEnvelope),
+      ...structuredEvidenceList(parsed.flags.mission_envelope)
+    ],
+    rollbackHint: [
+      ...structuredEvidenceList(artifact.rollbackHint),
+      ...structuredEvidenceList(parsed.flags.rollback_hint)
+    ],
     cleanup: parsed.flags.cleanup || artifact.cleanup || '',
     changed: [...artifact.changed, ...arrayFlag(parsed.flags.changed)],
     skipped: [...artifact.skipped, ...arrayFlag(parsed.flags.skipped)],
@@ -1090,6 +1448,15 @@ function renderProofMarkdown(summary) {
     '## Runtime evidence',
     ...renderProofMarkdownList(summary.runtime),
     '',
+    '## Visual provenance',
+    ...renderProofMarkdownList(summary.visualProvenance || []),
+    '',
+    '## Mission patch envelope',
+    ...renderProofMarkdownList(summary.missionEnvelope || []),
+    '',
+    '## Rollback hint',
+    ...renderProofMarkdownList(summary.rollbackHint || []),
+    '',
     '## Changed surfaces',
     ...renderProofMarkdownList(summary.changed),
     '',
@@ -1122,7 +1489,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
   const flags: AnyRecord = {};
   const positionals: string[] = [];
-  const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
+  const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg.startsWith('--')) {
@@ -1136,7 +1503,7 @@ function parseProofArgs(args = []) {
       }
       const value = inlineValue ?? args[index + 1] ?? '';
       if (inlineValue === undefined) index += 1;
-      if (['command', 'evidence', 'visual', 'runtime', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
+      if (['command', 'evidence', 'visual', 'runtime', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified'].includes(key)) {
         flags[normalizedKey] = [...arrayFlag(flags[normalizedKey]), value];
       } else {
         flags[normalizedKey] = value;
@@ -1174,6 +1541,9 @@ function emptyProofArtifact() {
     evidence: [],
     visual: [],
     runtime: [],
+    visualProvenance: [],
+    missionEnvelope: [],
+    rollbackHint: [],
     cleanup: '',
     changed: [],
     skipped: [],
@@ -1196,6 +1566,9 @@ async function parseProofJson(file, empty) {
       evidence: arrayFlag(data.evidence),
       visual: arrayFlag(data.visual || data.visualEvidence),
       runtime: arrayFlag(data.runtime || data.runtimeEvidence),
+      visualProvenance: structuredEvidenceList(data.visualProvenance || data.visual_provenance),
+      missionEnvelope: structuredEvidenceList(data.missionEnvelope || data.mission_envelope),
+      rollbackHint: structuredEvidenceList(data.rollbackHint || data.rollback_hint),
       cleanup: String(data.cleanup || data.cleanupStatus || ''),
       changed: arrayFlag(data.changed || data.files),
       skipped: arrayFlag(data.skipped),
@@ -1221,6 +1594,9 @@ async function parseProofMarkdown(file, empty) {
     evidence: readProofList(text, 'Evidence'),
     visual: readProofList(text, 'Visual evidence'),
     runtime: firstProofList(text, ['Runtime evidence', 'Processes', 'tmux']),
+    visualProvenance: readProofList(text, 'Visual provenance'),
+    missionEnvelope: readProofList(text, 'Mission patch envelope'),
+    rollbackHint: readProofList(text, 'Rollback hint'),
     cleanup: readProofField(text, 'Cleanup') || readProofField(text, 'Cleanup status'),
     changed: firstProofList(text, ['Changed surfaces', 'Files']),
     skipped: readProofList(text, 'Skipped'),
@@ -1267,9 +1643,36 @@ function arrayFlag(value) {
   return Array.isArray(value) ? value.filter(Boolean) : [value].filter(Boolean);
 }
 
+function structuredEvidenceList(value) {
+  return arrayFlag(value).map((item) => formatStructuredEvidence(item)).filter(Boolean);
+}
+
+function formatStructuredEvidence(value) {
+  if (!value) return '';
+  if (typeof value === 'object') return JSON.stringify(value);
+  const text = String(value).trim();
+  if (!text) return '';
+  if (!text.startsWith('{')) return text;
+  try {
+    const data = JSON.parse(text);
+    if (data.schema === 'yam.ueye-visual-provenance.v1' || data.source_kind || data.reference_id || data.screenshot_id) {
+      return JSON.stringify(buildUeyeVisualProvenance(data));
+    }
+    if (data.schema === 'yam.mission-patch-envelope.v1' || data.agent_id || data.assigned_scope) {
+      return JSON.stringify(buildMissionPatchEnvelope(data));
+    }
+    if (data.schema === 'yam.rollback-hint.v1' || data.touched_files || data.safe_revert_note) {
+      return JSON.stringify(buildRollbackHint(data));
+    }
+    return JSON.stringify(data);
+  } catch {
+    return text;
+  }
+}
+
 function hasProofEvidence(parsed) {
   const flags = parsed.flags || {};
-  return ['command', 'evidence', 'visual', 'runtime', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup);
+  return ['command', 'evidence', 'visual', 'runtime', 'visual_provenance', 'mission_envelope', 'rollback_hint', 'changed', 'skipped', 'blocked'].some((key) => arrayFlag(flags[key]).length > 0) || Boolean(flags.cleanup);
 }
 
 function printProofList(label, values) {
@@ -1961,6 +2364,8 @@ async function main() {
   if (command === 'measure') return measure(process.argv[3], process.argv.slice(4));
   if (command === 'tools') return tools(process.argv.slice(3));
   if (command === 'proof') return proof(process.argv.slice(3));
+  if (command === 'ueye') return ueye(process.argv.slice(3));
+  if (command === 'release') return release(process.argv.slice(3));
   if (command === 'safety') return safety(process.argv.slice(3));
   if (command === 'memory') return memory(process.argv.slice(3));
   if (command === 'hook') return hook(process.argv.slice(3));

package/src/lib/trust-kernel.ts

@@ -47,6 +47,38 @@ export interface RuntimeTruthMatrix {
   blockers: string[];
 }
 
+export interface UeyeVisualProvenance {
+  schema: 'yam.ueye-visual-provenance.v1';
+  source_kind: string;
+  source_path: string;
+  source_hash: string;
+  reference_id: string;
+  screenshot_id: string;
+  local_only: boolean;
+  redacted: boolean;
+  operator_provided: boolean;
+  comparison_result: string;
+  truth_status: TruthStatus;
+}
+
+export interface RollbackHint {
+  schema: 'yam.rollback-hint.v1';
+  touched_files: string[];
+  generated_files: string[];
+  before_check: string;
+  safe_revert_note: string;
+}
+
+export interface MissionPatchEnvelope {
+  schema: 'yam.mission-patch-envelope.v1';
+  agent_id: string;
+  assigned_scope: string;
+  changed_files: string[];
+  verification_hint: string;
+  rollback_hint: RollbackHint;
+  truth_status: TruthStatus;
+}
+
 export interface FakeRealPolicyResult {
   schema: 'yam.fake-real-policy.v1';
   ok: boolean;
@@ -71,6 +103,9 @@ export interface ProofSummary {
   blocked?: unknown;
   assumptions?: unknown;
   unverified?: unknown;
+  visualProvenance?: unknown;
+  missionEnvelope?: unknown;
+  rollbackHint?: unknown;
 }
 
 export interface ProofOptions {
@@ -101,6 +136,9 @@ export interface YamCompletionProof {
   evidence: string[];
   visual: string[];
   runtime: string[];
+  visualProvenance: string[];
+  missionEnvelope: string[];
+  rollbackHint: string[];
   cleanup: unknown;
   changed: string[];
   skipped: string[];
@@ -113,6 +151,48 @@ export interface YamCompletionProof {
   runtimeTruth: RuntimeTruthMatrix;
 }
 
+export function buildUeyeVisualProvenance(input: Partial<UeyeVisualProvenance> = {}): UeyeVisualProvenance {
+  const truth = isTruthStatus(input.truth_status) ? input.truth_status : 'partial';
+  return {
+    schema: 'yam.ueye-visual-provenance.v1',
+    source_kind: String(input.source_kind || ''),
+    source_path: String(input.source_path || ''),
+    source_hash: String(input.source_hash || 'unknown'),
+    reference_id: String(input.reference_id || ''),
+    screenshot_id: String(input.screenshot_id || ''),
+    local_only: Boolean(input.local_only),
+    redacted: Boolean(input.redacted),
+    operator_provided: Boolean(input.operator_provided),
+    comparison_result: String(input.comparison_result || 'not-verified'),
+    truth_status: truth
+  };
+}
+
+export function buildRollbackHint(input: Partial<RollbackHint> = {}): RollbackHint {
+  return {
+    schema: 'yam.rollback-hint.v1',
+    touched_files: asList(input.touched_files),
+    generated_files: asList(input.generated_files),
+    before_check: String(input.before_check || ''),
+    safe_revert_note: String(input.safe_revert_note || '')
+  };
+}
+
+export function buildMissionPatchEnvelope(input: Partial<MissionPatchEnvelope> = {}): MissionPatchEnvelope {
+  const rollback = input.rollback_hint && typeof input.rollback_hint === 'object'
+    ? buildRollbackHint(input.rollback_hint)
+    : buildRollbackHint();
+  return {
+    schema: 'yam.mission-patch-envelope.v1',
+    agent_id: String(input.agent_id || ''),
+    assigned_scope: String(input.assigned_scope || ''),
+    changed_files: asList(input.changed_files),
+    verification_hint: String(input.verification_hint || ''),
+    rollback_hint: rollback,
+    truth_status: isTruthStatus(input.truth_status) ? input.truth_status : 'partial'
+  };
+}
+
 const TRUTH_RANK: Readonly<Record<TruthStatus, number>> = Object.freeze({
   blocked: 0,
   real_required_missing: 0,
@@ -184,6 +264,15 @@ export function classifyEvidenceTruth(summary: ProofSummary = {}, options: Proof
   for (const visual of asList(summary.visual)) {
     rows.push(evidenceRow('visual', visual, classifyVisualEvidence(visual)));
   }
+  for (const provenance of asList(summary.visualProvenance)) {
+    rows.push(evidenceRow('visual', provenance, metadataTruth(provenance, 'partial')));
+  }
+  for (const envelope of asList(summary.missionEnvelope)) {
+    rows.push(evidenceRow('evidence', envelope, metadataTruth(envelope, 'partial')));
+  }
+  for (const rollback of asList(summary.rollbackHint)) {
+    rows.push(evidenceRow('evidence', rollback, metadataTruth(rollback, 'partial')));
+  }
   for (const runtime of asList(summary.runtime)) {
     rows.push(evidenceRow('runtime', runtime, classifyRuntimeEvidence(runtime, options)));
   }
@@ -267,6 +356,9 @@ export function buildYamCompletionProof(summary: ProofSummary = {}, options: Pro
     evidence: asList(summary.evidence),
     visual: asList(summary.visual),
     runtime: asList(summary.runtime),
+    visualProvenance: asList(summary.visualProvenance),
+    missionEnvelope: asList(summary.missionEnvelope),
+    rollbackHint: asList(summary.rollbackHint),
     cleanup: summary.cleanup || '',
     changed: asList(summary.changed),
     skipped: asList(summary.skipped),
@@ -317,6 +409,25 @@ function commandPassed(value: unknown = ''): boolean {
   return /pass|passed|ok|success|exit\s*0|green/i.test(String(value || '')) && !/fail|failed|error|blocked/i.test(String(value || ''));
 }
 
+function metadataTruth(value: unknown = '', fallback: TruthStatus = 'partial'): TruthStatus {
+  return weakestTruth(readStructuredTruth(value, fallback), 'partial');
+}
+
+function readStructuredTruth(value: unknown = '', fallback: TruthStatus = 'partial'): TruthStatus {
+  if (typeof value === 'object' && value) {
+    const candidate = (value as { truth_status?: unknown; truth?: unknown }).truth_status || (value as { truth?: unknown }).truth;
+    return isTruthStatus(candidate) ? candidate : fallback;
+  }
+  const text = String(value || '');
+  try {
+    const data = JSON.parse(text);
+    const candidate = data.truth_status || data.truth;
+    return isTruthStatus(candidate) ? candidate : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
 function strongestSupportedTruth(rows: EvidenceRow[] = []): TruthStatus {
   if (rows.some((row) => row.truth === 'blocked')) return 'blocked';
   if (rows.some((row) => row.truth === 'real_required_missing')) return 'real_required_missing';

package/templates/mission-plan.md

@@ -29,6 +29,19 @@ Subagent 판단:
 - 이유:
 - subagent가 불가능하거나 불필요하면 기본적으로 $deep으로 전환:
 
+Patch envelope:
+- agent_id:
+- assigned_scope:
+- changed_files:
+- verification_hint:
+- truth_status: verified / partial / skipped / blocked / assumed
+
+Rollback hint:
+- touched_files:
+- generated_files:
+- before_check:
+- safe_revert_note:
+
 검증:
 - 필요한 가장 작은 검증 명령을 우선 실행
 - 필요하면 tmux/dev server/browser QA/process cleanup proof 사용