yam-flow 0.1.0 → 0.1.1

package/COMMANDS.md

@@ -135,12 +135,20 @@ yam tools doctor /path/to/project --json
 yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
+yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
+yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
 yam proof write /path/to/project --route deep --truth partial --command "npm run build: pass"
 yam proof write /path/to/project --format md --truth assumed --assumption "No runtime was started"
 yam safety "supabase db reset --linked"
 ```
 
+Release reporting intentionally runs the release checks and returns a machine-readable summary.
+
+```bash
+yam release report --json
+```
+
 ## Lite Hook
 
 Advisory-only hook. It does not run checks or force routes.

package/README.md

@@ -126,6 +126,9 @@ yam tools doctor /path/to/project --json
 yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
+yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
+yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
+yam release report --json
 yam safety "supabase db reset"
 yam detect /path/to/project
 yam pack /path/to/project

package/ROADMAP.md

@@ -311,3 +311,113 @@ Tasks:
 - Add `yam proof write`. Done.
 - Prepare npm/npx package metadata and dry-run packaging. Done.
 - Add small route-scoped trust kernel: truth caps, fake/real policy, runtime truth matrix, and completion proof object. Done.
+
+### 16. Deferred Triggers
+
+Goal: keep useful future trust-layer ideas visible without turning them into always-on gates too early.
+
+Rules:
+
+- Do not implement deferred items just because they are listed here.
+- Mention an item again when its trigger appears in real use.
+- Prefer lite metadata before runtime systems.
+- Keep ordinary `$quick`, `$question`, and `$scout` flows free of these gates.
+
+#### Mission Patch Queue Lite
+
+Status: next candidate for `$mission` only.
+
+Trigger:
+
+- A mission uses two or more real subagent/lane outputs.
+- Multiple lanes touch nearby files or the same subsystem.
+- It becomes hard to tell who changed what, why, and how to revert it.
+- Mission rollback or apply order starts to matter.
+
+First shape:
+
+- pending / applied / verified / reverted / blocked state.
+- lane id and assigned scope.
+- changed files.
+- verification hint.
+- rollback hint.
+- truth status.
+
+Keep out for now:
+
+- automatic merge engine.
+- persistent locks.
+- parallel apply worker.
+- broad runtime orchestration.
+
+#### Tool Intent Label / Tool Trust Metadata
+
+Status: near-term lightweight metadata.
+
+Trigger:
+
+- A route uses several tool classes together, such as browser, package manager, GitHub, filesystem, database, or deployment tools.
+- Read-only and write actions need to be distinguished in proof.
+- Destructive actions need a visible route recommendation before execution.
+- Release or mission reports need clearer evidence about what kind of tool ran.
+
+First shape:
+
+- tool intent: read_only / write / destructive / runtime / visual.
+- parallel safe: true / false / unknown.
+- approval required: true / false / unknown.
+- evidence kind and truth status.
+
+Keep out for now:
+
+- automatic scheduling.
+- automatic permission mutation.
+- mandatory tool graph.
+
+#### MCP Scheduler Runtime
+
+Status: later.
+
+Trigger:
+
+- Tool intent labels are no longer enough.
+- The harness starts coordinating multiple external tools inside one route.
+- Write or destructive actions could run near read-only checks.
+- Parallel tool execution becomes common and needs ordering.
+- A mission needs deterministic tool sequence proof.
+
+First shape:
+
+- scheduler proof object.
+- read-only overlap allowed.
+- write/destructive serialization.
+- blocked/approved/skipped status.
+
+Keep out for now:
+
+- default scheduler for normal work.
+- route-wide mandatory scheduler.
+- background runtime service.
+
+#### Appshots Attachment Gate
+
+Status: deferred.
+
+Trigger:
+
+- Ueye visual provenance cannot answer which exact visual source was used.
+- A team workflow needs thread-level or attachment-level audit trails.
+- Reference and implementation screenshots are easy to confuse.
+- External review requires source image lineage beyond path/hash/id.
+
+First shape:
+
+- optional attachment source fields.
+- no mandatory gate.
+- preserve Ueye visual provenance as the default.
+
+Keep out for now:
+
+- required thread attachment ids.
+- app-specific visual gates.
+- blocking ordinary Ueye work when attachment metadata is absent.

package/dist/bin/yam.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { TRUTH_STATUSES, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
+import { TRUTH_STATUSES, buildMissionPatchEnvelope, buildRollbackHint, buildUeyeVisualProvenance, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -117,6 +118,7 @@ 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 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]
@@ -927,6 +929,86 @@ async function safety(args = []) {
     const result = detectDbSafetyText(text);
     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 '';
@@ -975,6 +1057,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);
@@ -1050,6 +1135,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)],
@@ -1099,6 +1196,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),
         '',
@@ -1129,7 +1235,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
     const flags = {};
     const positionals = [];
-    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('--')) {
@@ -1145,7 +1251,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 {
@@ -1184,6 +1290,9 @@ function emptyProofArtifact() {
         evidence: [],
         visual: [],
         runtime: [],
+        visualProvenance: [],
+        missionEnvelope: [],
+        rollbackHint: [],
         cleanup: '',
         changed: [],
         skipped: [],
@@ -1205,6 +1314,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),
@@ -1230,6 +1342,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'),
@@ -1274,9 +1389,39 @@ function arrayFlag(value) {
         return [];
     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) {
     console.log(`- ${label}:`);
@@ -1967,6 +2112,8 @@ async function main() {
         return tools(process.argv.slice(3));
     if (command === 'proof')
         return proof(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')

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

@@ -29,6 +29,35 @@ export interface RuntimeTruthMatrix {
     rows: RuntimeTruthRow[];
     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;
@@ -52,6 +81,9 @@ export interface ProofSummary {
     blocked?: unknown;
     assumptions?: unknown;
     unverified?: unknown;
+    visualProvenance?: unknown;
+    missionEnvelope?: unknown;
+    rollbackHint?: unknown;
 }
 export interface ProofOptions {
     requireRealRuntime?: boolean;
@@ -79,6 +111,9 @@ export interface YamCompletionProof {
     evidence: string[];
     visual: string[];
     runtime: string[];
+    visualProvenance: string[];
+    missionEnvelope: string[];
+    rollbackHint: string[];
     cleanup: unknown;
     changed: string[];
     skipped: string[];
@@ -90,6 +125,9 @@ export interface YamCompletionProof {
     fakeReal: FakeRealPolicyResult;
     runtimeTruth: RuntimeTruthMatrix;
 }
+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 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

@@ -10,6 +10,45 @@ export const TRUTH_STATUSES = Object.freeze([
     'blocked',
     'assumed'
 ]);
+export function buildUeyeVisualProvenance(input = {}) {
+    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 = {}) {
+    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 = {}) {
+    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 = Object.freeze({
     blocked: 0,
     real_required_missing: 0,
@@ -81,6 +120,15 @@ export function classifyEvidenceTruth(summary = {}, options = {}) {
     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)));
     }
@@ -166,6 +214,9 @@ export function buildYamCompletionProof(summary = {}, options = {}) {
         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),
@@ -223,6 +274,24 @@ function classifyCleanupEvidence(value = '') {
 function commandPassed(value = '') {
     return /pass|passed|ok|success|exit\s*0|green/i.test(String(value || '')) && !/fail|failed|error|blocked/i.test(String(value || ''));
 }
+function metadataTruth(value = '', fallback = 'partial') {
+    return weakestTruth(readStructuredTruth(value, fallback), 'partial');
+}
+function readStructuredTruth(value = '', fallback = 'partial') {
+    if (typeof value === 'object' && value) {
+        const candidate = value.truth_status || value.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 = []) {
     if (rows.some((row) => row.truth === 'blocked'))
         return 'blocked';

package/package.json

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

package/references/mission.md

@@ -36,6 +36,30 @@ Subagent policy:
 - If the user explicitly insists on mission despite missing subagents, mark the result `partial` or `blocked`; do not treat self-review as team execution.
 - The final proof must record the subagent decision: `used`, `downgraded_to_deep`, `unavailable_partial`, or `blocked`, with the reason.
 
+Patch envelope:
+
+Use a small envelope when a real mission lane changes code:
+
+- `agent_id`: who or which lane made the change.
+- `assigned_scope`: the bounded work area.
+- `changed_files`: files the lane touched.
+- `verification_hint`: the smallest relevant check for the lane.
+- `rollback_hint`: what to inspect or revert if the change is wrong.
+- `truth_status`: the lane's honest status.
+
+This is only a record shape. It is not a queue, lock manager, or parallel apply engine.
+
+Rollback hint:
+
+Record:
+
+- touched files
+- generated files
+- before check
+- safe revert note
+
+Do not claim rollback safety unless the relevant check or revert path was actually inspected.
+
 Runtime use:
 
 - Mission may use deep runtime verification when needed, but runtime proof alone does not make a mission if subagents were not used.

package/references/tool-trust-layer.md

@@ -110,6 +110,19 @@ On demand:
 
 - command evidence
 - browser/screenshot evidence
+- visual provenance for reference-based UI work
+- mission patch envelopes for real team lanes
+- rollback hints for risky changes
 - runtime/tmux/process cleanup evidence
 - truth status
 - skipped/blocked/assumed items
+
+`yam release report --json` should collect release readiness into a machine-readable artifact:
+
+- typecheck
+- forbidden names
+- package boundary
+- registry status
+- CLI smoke
+- dist freshness
+- final truth status

package/references/ueye-proof.md

@@ -41,6 +41,25 @@ Bounds:
 - Record missing dimensions or hashes as `unknown`, not as failure.
 - Use generated annotations only as derivative aids.
 
+### Visual Provenance
+
+Purpose: prove the visual source path from reference reading to implementation recheck.
+
+Record these fields when a reference or screenshot materially affects the claim:
+
+- `source_kind`
+- `source_path`
+- `source_hash`
+- `reference_id`
+- `screenshot_id`
+- `local_only`
+- `redacted`
+- `operator_provided`
+- `comparison_result`
+- `truth_status`
+
+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.
+
 ### Reference Read Proof
 
 Purpose: separate reading the reference from judging the implementation.

package/skills/mission/SKILL.md

@@ -49,12 +49,14 @@ Do not use for:
    - UX/browser verifier: checks screen behavior when relevant.
    - Doctor/scanner: checks direction fit, scope control, verification, cleanup, stale context, and false-completion risk.
 5. Execute the implementation in bounded steps.
-6. Use `$deep`-style runtime verification when the mission needs dev server, tmux, test watcher, browser QA, cleanup, or before/after evidence.
-7. Cross-check findings and resolve contradictions.
-8. Run the smallest honest final verification set.
-9. Run doctor scan with `references/doctor-scan.md`.
-10. Confirm cleanup or explicitly report intentionally running processes.
-11. Produce final proof summary, truth status, remaining tasks, and fix-first items.
+6. Record a compact patch envelope for each real lane that changes code.
+7. Add rollback hints for touched files, generated files, before checks, and safe revert notes.
+8. Use `$deep`-style runtime verification when the mission needs dev server, tmux, test watcher, browser QA, cleanup, or before/after evidence.
+9. Cross-check findings and resolve contradictions.
+10. Run the smallest honest final verification set.
+11. Run doctor scan with `references/doctor-scan.md`.
+12. Confirm cleanup or explicitly report intentionally running processes.
+13. Produce final proof summary, truth status, remaining tasks, and fix-first items.
 
 ## Proof Summary
 
@@ -64,6 +66,8 @@ Include:
 - Role work completed.
 - Subagent decision: used / downgraded_to_deep / unavailable_partial / blocked, with reason.
 - Files or surfaces changed.
+- Patch envelope for each real code-changing lane.
+- Rollback hint for risky or multi-file changes.
 - Runtime/tmux/browser evidence when used.
 - Cross-verification result.
 - Doctor/scanner result.

package/skills/ueye/SKILL.md

@@ -77,13 +77,16 @@ Use these artifacts for reference-led implementation or serious visual review. K
    - reference, before, and after evidence when available.
    - path or URL, source type, state, viewport, and visual verification cap.
    - sha256 and dimensions when an image file is locally available.
-2. Reference Read Proof:
+2. Visual Provenance:
+   - source kind, path, hash, reference id, screenshot id, redaction/locality flags, operator-provided flag, comparison result, and truth status.
+   - use this to prove the route from reference reading to implementation recheck.
+3. Reference Read Proof:
    - concrete observations from the reference before implementation.
    - no implementation claim should depend on an unrecorded reference observation.
-3. Reference vs Implementation Matrix:
+4. Reference vs Implementation Matrix:
    - compare the implemented result against the reference by aspect.
    - record matched, similar, different, not-applicable, or not-verified.
-4. Design Quality Review:
+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.
 

package/src/bin/yam.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import os from 'node:os';
@@ -7,6 +8,9 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import {
   TRUTH_STATUSES,
+  buildMissionPatchEnvelope,
+  buildRollbackHint,
+  buildUeyeVisualProvenance,
   buildYamCompletionProof,
   detectDbSafetyText as detectTrustDbSafetyText,
   isTruthStatus
@@ -128,6 +132,7 @@ 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 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 +924,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 = [];
@@ -966,6 +1050,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 +1127,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 +1189,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 +1230,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 +1244,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 +1282,9 @@ function emptyProofArtifact() {
     evidence: [],
     visual: [],
     runtime: [],
+    visualProvenance: [],
+    missionEnvelope: [],
+    rollbackHint: [],
     cleanup: '',
     changed: [],
     skipped: [],
@@ -1196,6 +1307,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 +1335,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 +1384,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 +2105,7 @@ 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 === '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 사용

package/templates/ueye-comparison.md

@@ -14,6 +14,21 @@
 | implementation |  |  | unknown | unknown |  |  | proof |
 | reference |  |  | unknown | unknown |  |  | reference direction |
 
+## Visual Provenance
+
+| Field | Value |
+| --- | --- |
+| source_kind |  |
+| source_path |  |
+| source_hash | unknown |
+| reference_id |  |
+| screenshot_id |  |
+| 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 |
+
 ## Reference Read Proof
 
 - Layout:

package/templates/ueye-review.md

@@ -25,6 +25,21 @@
 - Role: proof / reference direction / annotation / partial evidence
 - Visual verification cap:
 
+## Visual Provenance
+
+| Field | Value |
+| --- | --- |
+| source_kind |  |
+| source_path |  |
+| source_hash | unknown |
+| reference_id |  |
+| screenshot_id |  |
+| 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 |
+
 ## Reference Read Proof
 
 - Layout:

package/yam.manifest.json

@@ -22,7 +22,7 @@
     {
       "id": "ueye",
       "stage": "v0.3",
-      "purpose": "Tight UI/UX/design implementation and visual review with 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, reference-read proof, visual comparison, design quality review, and P0-P3 issue tracking."
     },
     {
       "id": "question",
@@ -42,7 +42,7 @@
     {
       "id": "mission",
       "stage": "v0.2",
-      "purpose": "Explicit real-subagent/team execution route for approved plans, cross-verification, doctor scan, and final proof."
+      "purpose": "Explicit real-subagent/team execution route for approved plans, patch envelopes, rollback hints, cross-verification, doctor scan, and final proof."
     }
   ]
 }