yam-flow 2.5.1 → 2.7.0

package/src/bin/yam.ts

@@ -34,6 +34,19 @@ import {
   verifyUeyeAssetManifest,
   verifyUeyeRevisionHistory
 } from '../lib/ueye-artifacts.js';
+import {
+  addPlanReviewComment,
+  closePlanReviewCanvas,
+  createDesignRevisionState,
+  createPlanReviewCanvas,
+  finalizeDesignProductionPhase,
+  readCanonicalDesignRevisionState,
+  readPlanReviewSession,
+  recordDesignRevisionRound,
+  verifyFinalGalleryManifest,
+  verifyDesignProductionPhaseReceipt,
+  writeFinalGalleryManifest
+} from '../lib/design-production.js';
 import {
   inspectSkillInstallation,
   installSkillSetTransactional,
@@ -45,6 +58,22 @@ import {
   checkExternalUpdates
 } from '../lib/external-updates.js';
 import type { ExternalUpdateComponent } from '../lib/external-updates.js';
+import {
+  buildBoundedPromotionReport,
+  parsePromotionSample
+} from '../lib/benchmark-promotion.js';
+import {
+  buildStrictGateResult,
+  verifyStrictGateResult
+} from '../lib/gate-result.js';
+import {
+  createVerificationClosureReceipt,
+  verifyVerificationClosureReceiptFile
+} from '../lib/verification-closure.js';
+import {
+  createMediaProviderReceipt,
+  verifyMediaProviderReceipt
+} from '../lib/media-provider-receipt.js';
 import {
   BoundedInputError,
   GENERAL_STDIN_MAX_BYTES,
@@ -188,15 +217,18 @@ Usage:
   yam ueye report [--reference ref.png] [--actual screenshot.png] [--provider-context local] [--execution-surface in-app-browser] [--json]
   yam ueye asset <add|verify> [options]
   yam ueye revision <archive|verify> [options]
+  yam ueye production <canvas|revision|gallery|finalize|phase> [options]
   yam media proof [--requested] [--attempted] [--output file] [--json]
   yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--json]
   yam mission queue [--agent-id id] [--scope text] [--changed file] [--verification-hint text] [--json]
   yam mission receipt [--thread-id id] [--role reviewer] [--lifecycle stopped] [--outcome passed] [--evidence text] [--json]
   yam mission gate [--expected-thread id] [--receipt file] [--json]
+  yam verification closure <create|verify> [options]
   yam update check [--json]
   yam update apply --component yam|scrapling|insane-search [--json]
   yam update apply --all [--json]
   yam benchmark report [--baseline n] [--current n] [--unit ms] [--target lower|higher] [--json]
+  yam benchmark report --candidate-digest sha256 --baseline-digest sha256 --sample seed:candidate:baseline --unit score --evidence-source text [--min-samples n] [--min-mean-delta n] [--min-win-rate n] [--json]
   yam release report [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
@@ -1335,6 +1367,7 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
     readinessRow('Supabase plugin', await pluginCacheHas('openai-curated/supabase') ? 'ready' : 'unknown', 'plugin cache only; no DB query performed'),
     readinessRow('Vercel plugin', await pluginCacheHas('openai-curated/vercel') ? 'ready' : 'unknown', 'plugin cache only; no deployment/API call performed')
   ];
+  const capabilityMatrix = buildCapabilityMatrix(rows, globalLiteHookHealth, globalStudyNoteHookHealth);
   const riskNotes = [
     ...instructionSurfaces.issues.map((message) => ({ level: 'issue', reason: message })),
     ...instructionSurfaces.warnings.map((message) => ({ level: 'warning', reason: message })),
@@ -1361,6 +1394,7 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
     frameworkChecklist,
     contextPressure,
     realProbe,
+    capabilityMatrix,
     sqlScan,
     riskNotes,
     nextActions: nextActionDetails.map((action) => action.next_action),
@@ -1374,6 +1408,45 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
   };
 }
 
+function buildCapabilityMatrix(readinessRows = [], liteHook: AnyRecord = {}, studyNoteHook: AnyRecord = {}) {
+  const readiness = new Map(readinessRows.map((row) => [row.name, row.status]));
+  const capabilities = [
+    capabilityRow('skill_installation', 'stable', readiness.get('Yam skills') || 'unknown', 'yam status plus the transactional installation receipt', 'proves managed skill bytes only; it does not prove a route ran'),
+    capabilityRow('external_update_check', 'stable', 'unknown', 'packaged `yam update check` command', 'this inventory does not contact registries or prove Codex/plugin/network availability'),
+    capabilityRow('external_update_apply', 'beta', 'unknown', 'transactional component updater with rollback receipts', 'runtime readiness is checked only during an explicit run; effective yam identity currently supports POSIX symlinks while Windows npm .cmd shims fail closed as unverified'),
+    capabilityRow('mission_receipt_gate', 'stable', 'ready', 'packaged mission receipt and aggregate gate commands', 'validates supplied real-thread evidence; it does not spawn agents'),
+    capabilityRow('mission_real_subagents', 'instruction-only', 'unknown', 'Mission skill delegates through environment-owned subagent tools', 'CLI cannot prove host slot availability or a real thread outcome'),
+    capabilityRow('ueye_asset_revision_integrity', 'stable', 'ready', 'hash-verified Ueye asset and revision manifests', 'integrity does not prove design quality, licensing, or browser state'),
+    capabilityRow('plan_review_canvas_lite', 'beta', 'ready', 'local static review session artifacts', 'no remote hosting, background service, or automatic implementation start'),
+    capabilityRow('bounded_design_revisions', 'beta', 'ready', 'maximum two reviewer-finding-backed revision rounds', 'round state does not replace Ueye artifact hash verification'),
+    capabilityRow('final_gallery_manifest', 'beta', 'ready', 'path-confined hash-verified packaging manifest', 'gallery completeness does not prove visual or license correctness'),
+    capabilityRow('demand_gated_design_production', 'beta', 'ready', 'pre-recorded operator trigger, Canvas, chronological bounded revisions, gallery, and digest-verifiable phase receipt', 'demand evidence is operator-asserted and overall phase truth remains partial'),
+    capabilityRow('final_scope_verification_closure', 'beta', 'ready', 'explicit Git-scope and selected/executed command receipt with digest verification', 'does not execute checks; unavailable or unplanned Git scope blocks and successful operator evidence remains partial'),
+    capabilityRow('media_provider_execution_receipt', 'beta', 'ready', 'optional demand-gated exact execution boundary plus identity-bound local assets', 'never contacts providers and does not prove visual or implementation correctness'),
+    capabilityRow('yam_lite_hook', 'beta', String(liteHook.state || readiness.get('yam-lite hook') || 'unknown'), 'optional hook health inspection', 'advisory only; disabled unless explicitly enabled'),
+    capabilityRow('study_note_hook', 'beta', String(studyNoteHook.state || readiness.get('yam-study-note hook') || 'unknown'), 'optional prompt and bounded Stop check', 'does not generate the Study Note or run verification')
+  ];
+  return {
+    schema: 'yam.capability-matrix.v1',
+    generated_at: new Date().toISOString(),
+    capabilities,
+    maturity_vocabulary: ['stable', 'beta', 'experimental', 'instruction-only'],
+    truth_status: 'partial',
+    note: 'support maturity and current runtime state are separate; this read-only inventory does not execute capabilities'
+  };
+}
+
+function capabilityRow(id, maturity, runtimeState, evidence, limit) {
+  return {
+    id,
+    maturity,
+    runtime_state: runtimeState,
+    evidence,
+    limit,
+    truth_status: runtimeState === 'ready' ? 'partial' : 'assumed'
+  };
+}
+
 function printToolsDoctorReport(data) {
   console.log('yam tools doctor');
   console.log(`Project: ${data.project}`);
@@ -1390,6 +1463,14 @@ function printToolsDoctorReport(data) {
     }
   }
 
+  if (data.capabilityMatrix?.capabilities?.length) {
+    console.log('');
+    console.log('Capability matrix:');
+    for (const capability of data.capabilityMatrix.capabilities) {
+      console.log(`- ${capability.id}: ${capability.maturity} / ${capability.runtime_state} (${capability.limit})`);
+    }
+  }
+
   if (data.instructionSurfaces.found.length || data.projectSurfaces.length) {
     console.log('');
     console.log('Project surfaces:');
@@ -2268,8 +2349,35 @@ function runReleaseReport() {
   const publishBlockerEvidence = publishBlockerEvidenceFromRelease(checks, tarball);
   const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
   const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
-  const ok = failed.length === 0 && publishReadiness.status === 'ready';
-  const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, ok);
+  const preliminaryOk = failed.length === 0 && publishReadiness.status === 'ready';
+  const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, preliminaryOk);
+  const gateResult = buildStrictGateResult({
+    gate_id: 'release-readiness',
+    boundary: 'release',
+    checks: [
+      ...checks.map((check) => ({
+        id: `release-${String(check.id || 'unnamed').replace(/[^a-z0-9._-]/gi, '-')}`,
+        status: check.status === 'passed' ? 'passed' as const : 'failed' as const,
+        note: check.note || check.command || check.id,
+        required: true
+      })),
+      {
+        id: 'publish-readiness',
+        status: publishReadiness.status === 'ready' ? 'passed' as const : 'failed' as const,
+        note: publishReadiness.next_action,
+        required: true
+      }
+    ],
+    blockers: publishReadiness.blockers?.map((blocker) => `${blocker.kind}: ${blocker.reason}`) || [],
+    evidence: [
+      `${readinessReceipt.schema}:${readinessReceipt.local_version}`,
+      tarball.integrity ? `tarball-integrity:${tarball.integrity}` : 'tarball-integrity:not-observed',
+      provenance.git_commit ? `git-commit:${provenance.git_commit}` : 'git-commit:not-observed'
+    ],
+    next_action: publishReadiness.next_action
+  });
+  const gateContract = verifyStrictGateResult(gateResult);
+  const ok = preliminaryOk && gateResult.status === 'passed' && gateContract.valid;
   return {
     schema: 'yam.release-report.v1',
     generated_at: startedAt,
@@ -2284,6 +2392,8 @@ function runReleaseReport() {
     freshness,
     publish_readiness: publishReadiness,
     readiness_receipt: readinessReceipt,
+    gate_result: gateResult,
+    gate_contract: gateContract,
     study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
     publishBlockerEvidence,
     next_actions: nextActions
@@ -2781,6 +2891,7 @@ async function ueye(args = []) {
   if (subcommand === 'report') return ueyeReport(args.slice(1));
   if (subcommand === 'asset') return ueyeAsset(args.slice(1));
   if (subcommand === 'revision') return ueyeRevision(args.slice(1));
+  if (subcommand === 'production') return ueyeProduction(args.slice(1));
   console.error(`unknown ueye command: ${subcommand}`);
   return ueyeUsage();
 }
@@ -2799,6 +2910,11 @@ Usage:
   yam ueye asset verify [--manifest file] [--json]
   yam ueye revision archive --file image --round n [--artifact-id id] [--root dir] [--manifest file] [--json]
   yam ueye revision verify [--root dir] [--manifest file] [--json]
+  yam ueye production canvas <create|comment|close|show> [options]
+  yam ueye production revision <init|record|show> [options]
+  yam ueye production gallery <write|verify> [options]
+  yam ueye production finalize [options]
+  yam ueye production phase verify [options]
 
 Notes:
   capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
@@ -2806,6 +2922,7 @@ Notes:
   report produces a proof-ready Ueye visual run report, design completion gate, and continuity/comparison record without requiring a new capture.
   asset records local reference provenance and protection flags; it never downloads remote content.
   revision copies the current local artifact into a non-overwriting round archive before the live file is edited.
+  production is demand-gated: it writes local-only review artifacts, permits at most two finding-backed revision rounds, and keeps gallery correctness claims explicitly unverified.
 `);
 }
 
@@ -2880,6 +2997,236 @@ async function ueyeRevision(args = []) {
   }
 }
 
+async function ueyeProduction(args = []) {
+  const surface = String(args[0] || 'help');
+  const isFinalize = surface === 'finalize';
+  const action = isFinalize ? 'run' : String(args[1] || 'help');
+  const flagArgs = isFinalize ? args.slice(1) : args.slice(2);
+  if (surface === 'help' || action === 'help' || surface === '--help' || surface === '-h' || flagArgs.includes('--help') || flagArgs.includes('-h')) return ueyeProductionUsage();
+  const flags = parseSimpleFlags(flagArgs, new Set([
+    'root', 'session-id', 'title', 'artifact-spec', 'session-path', 'render-path',
+    'comment-id', 'artifact-id', 'anchor-kind', 'locator', 'finding', 'requested-change', 'verdict',
+    'state-path', 'finding-id', 'source-comment-id', 'finding-summary', 'finding-evidence', 'planned-change', 'outcome', 'revision-ref',
+    'manifest-path', 'completion-state', 'demand-kind', 'demand-evidence', 'canvas-session-path',
+    'revision-state-path', 'gallery-manifest-path', 'receipt-path', 'json'
+  ]));
+  const root = path.resolve(expandHome(flags.root || process.cwd()));
+  try {
+    let result: AnyRecord;
+    if (surface === 'canvas' && action === 'create') {
+      requireProductionFlags(flags, ['session_id', 'title', 'demand_kind', 'demand_evidence', 'artifact_spec']);
+      result = await createPlanReviewCanvas({
+        root,
+        session_id: String(flags.session_id),
+        title: String(flags.title),
+        demand_trigger: {
+          kind: String(flags.demand_kind) as 'repeated_plan_review' | 'multi_asset_production',
+          evidence: String(flags.demand_evidence)
+        },
+        artifacts: await readProductionSpecs(flags.artifact_spec, 'canvas artifact spec') as any,
+        ...(flags.session_path ? { session_path: String(flags.session_path) } : {}),
+        ...(flags.render_path ? { render_path: String(flags.render_path) } : {})
+      });
+    } else if (surface === 'canvas' && action === 'comment') {
+      requireProductionFlags(flags, ['session_path', 'render_path', 'comment_id', 'artifact_id', 'anchor_kind', 'locator', 'finding', 'requested_change']);
+      result = await addPlanReviewComment({
+        root,
+        session_path: String(flags.session_path),
+        render_path: String(flags.render_path),
+        comment: {
+          id: String(flags.comment_id),
+          anchor: {
+            artifact_id: String(flags.artifact_id),
+            kind: String(flags.anchor_kind) as 'line' | 'region' | 'text',
+            locator: String(flags.locator)
+          },
+          finding: String(flags.finding),
+          requested_change: String(flags.requested_change)
+        }
+      });
+    } else if (surface === 'canvas' && action === 'close') {
+      requireProductionFlags(flags, ['session_path', 'render_path', 'verdict']);
+      result = await closePlanReviewCanvas({
+        root,
+        session_path: String(flags.session_path),
+        render_path: String(flags.render_path),
+        verdict: String(flags.verdict) as 'approve' | 'request_changes'
+      });
+    } else if (surface === 'canvas' && action === 'show') {
+      requireProductionFlags(flags, ['session_path']);
+      const sessionPath = await existingProductionPath(root, String(flags.session_path), 'session_path');
+      result = await readPlanReviewSession(sessionPath);
+    } else if (surface === 'revision' && action === 'init') {
+      requireProductionFlags(flags, ['session_id']);
+      result = await createDesignRevisionState({
+        root,
+        session_id: String(flags.session_id),
+        ...(flags.state_path ? { state_path: String(flags.state_path) } : {})
+      });
+    } else if (surface === 'revision' && action === 'record') {
+      requireProductionFlags(flags, ['state_path', 'finding_id', 'source_comment_id', 'finding_summary', 'finding_evidence', 'planned_change', 'outcome', 'revision_ref']);
+      result = await recordDesignRevisionRound({
+        root,
+        state_path: String(flags.state_path),
+        reviewer_finding: {
+          id: String(flags.finding_id),
+          source_comment_id: String(flags.source_comment_id),
+          summary: String(flags.finding_summary),
+          evidence: String(flags.finding_evidence)
+        },
+        planned_change: String(flags.planned_change),
+        outcome: String(flags.outcome) as 'accepted' | 'changes_requested',
+        revision_refs: await readProductionSpecs(flags.revision_ref, 'Ueye revision reference') as any
+      });
+    } else if (surface === 'revision' && action === 'show') {
+      requireProductionFlags(flags, ['state_path']);
+      result = await readCanonicalDesignRevisionState({ root, state_path: String(flags.state_path) });
+    } else if (surface === 'gallery' && action === 'write') {
+      requireProductionFlags(flags, ['manifest_path', 'session_id', 'completion_state', 'artifact_spec']);
+      result = await writeFinalGalleryManifest({
+        root,
+        manifest_path: String(flags.manifest_path),
+        session_id: String(flags.session_id),
+        completion_state: String(flags.completion_state) as 'draft' | 'ready_for_inspection' | 'packaged',
+        artifacts: await readProductionSpecs(flags.artifact_spec, 'gallery artifact spec') as any
+      });
+    } else if (surface === 'gallery' && action === 'verify') {
+      requireProductionFlags(flags, ['manifest_path']);
+      result = await verifyFinalGalleryManifest({ root, manifest_path: String(flags.manifest_path) });
+    } else if (surface === 'finalize' && action === 'run') {
+      requireProductionFlags(flags, ['demand_kind', 'demand_evidence', 'canvas_session_path', 'gallery_manifest_path', 'receipt_path']);
+      result = await finalizeDesignProductionPhase({
+        root,
+        demand_trigger: {
+          kind: String(flags.demand_kind) as 'repeated_plan_review' | 'multi_asset_production',
+          evidence: String(flags.demand_evidence)
+        },
+        canvas_session_path: String(flags.canvas_session_path),
+        revision_state_path: flags.revision_state_path ? String(flags.revision_state_path) : null,
+        gallery_manifest_path: String(flags.gallery_manifest_path),
+        receipt_path: String(flags.receipt_path)
+      });
+    } else if (surface === 'phase' && action === 'verify') {
+      requireProductionFlags(flags, ['receipt_path']);
+      result = await verifyDesignProductionPhaseReceipt({ root, receipt_path: String(flags.receipt_path) });
+    } else {
+      throw new Error(`unknown Ueye production command: ${surface} ${action}`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye design production');
+    if (result.truth_status === 'blocked') process.exitCode = 1;
+  } catch (error) {
+    const reason = summarizeCheckOutput(errorMessage(error));
+    const result = {
+      schema: 'yam.design-production-error.v1',
+      surface,
+      action,
+      status: 'blocked',
+      reason,
+      next_action: /two_round_limit|maximum (?:is )?2|maximum two/i.test(reason)
+        ? 'stop this phase at two rounds and keep unresolved gallery work draft; start a new phase only after new explicit demand authorization'
+        : /stopped with status accepted/i.test(reason)
+          ? 'stop revising because the reviewer already accepted this phase'
+          : 'repair the local spec, path, integrity evidence, or phase state before retrying',
+      truth_status: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Ueye design production');
+    process.exitCode = 1;
+  }
+}
+
+function ueyeProductionUsage() {
+  console.log(`yam ueye production
+
+Demand-gated local design production helpers. Spec files are bounded JSON objects; repeat --artifact-spec or --revision-ref for multiple entries.
+
+Usage:
+  yam ueye production canvas create [--root dir] --session-id id --title text --demand-kind repeated_plan_review|multi_asset_production --demand-evidence text --artifact-spec file [--json]
+  yam ueye production canvas comment [--root dir] --session-path relative --render-path relative --comment-id id --artifact-id id --anchor-kind line|region|text --locator text --finding text --requested-change text [--json]
+  yam ueye production canvas close [--root dir] --session-path relative --render-path relative --verdict approve|request_changes [--json]
+  yam ueye production canvas show [--root dir] --session-path relative [--json]
+  yam ueye production revision init [--root dir] --session-id id [--state-path .yam/ueye/design-production/<session-id>/revision-state.json] [--json]
+  yam ueye production revision record [--root dir] --state-path relative --finding-id id --source-comment-id id --finding-summary text --finding-evidence text --planned-change text --outcome accepted|changes_requested --revision-ref file [--json]
+  yam ueye production revision show [--root dir] --state-path relative [--json]
+  yam ueye production gallery write [--root dir] --manifest-path relative --session-id id --completion-state draft|ready_for_inspection|packaged --artifact-spec file [--json]
+  yam ueye production gallery verify [--root dir] --manifest-path relative [--json]
+  yam ueye production finalize [--root dir] --demand-kind repeated_plan_review|multi_asset_production --demand-evidence text --canvas-session-path relative [--revision-state-path relative] --gallery-manifest-path relative --receipt-path relative [--json]
+  yam ueye production phase verify [--root dir] --receipt-path relative [--json]
+
+Use this phase only when repeated plan review or large multi-asset production creates real coordination demand. Canvas artifacts stay static and local. Revision init requires the session's closed request_changes Canvas and fixes state to .yam/ueye/design-production/<session-id>/revision-state.json; --state-path is accepted only when it names that exact path. Record/show/finalize reject alternate state files. Gallery verification covers paths, hashes, dimensions, and revision references only. Finalize binds the explicit demand evidence, closed Canvas, terminal revision state when needed, and verified gallery into one immutable receipt.
+`);
+}
+
+function requireProductionFlags(flags: AnyRecord, names: string[]) {
+  const missing = names.filter((name) => flags[name] === undefined || flags[name] === '');
+  if (missing.length) throw new Error(`missing required option(s): ${missing.map((name) => `--${name.replace(/_/g, '-')}`).join(', ')}`);
+}
+
+async function readProductionSpecs(value: unknown, label: string) {
+  const files = arrayFlag(value);
+  if (!files.length) throw new Error(`${label} requires at least one JSON spec file`);
+  const specs: AnyRecord[] = [];
+  for (const file of files) specs.push(await readBoundedJsonSpec(path.resolve(expandHome(file)), label));
+  return specs;
+}
+
+async function readOptionalSpecs(value: unknown, label: string) {
+  const files = arrayFlag(value);
+  const specs: AnyRecord[] = [];
+  for (const file of files) specs.push(await readBoundedJsonSpec(path.resolve(expandHome(file)), label));
+  return specs;
+}
+
+async function readBoundedJsonSpec(file: string, label: string) {
+  const before = await fsp.lstat(file);
+  if (before.isSymbolicLink() || !before.isFile()) throw new Error(`${label} must be a regular non-symlink file: ${file}`);
+  if (before.size > 256 * 1024) throw new Error(`${label} exceeds the 256 KiB limit: ${file}`);
+  const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+    ? fs.constants.O_NOFOLLOW
+    : 0;
+  const handle = await fsp.open(file, fs.constants.O_RDONLY | noFollow);
+  let text = '';
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || !sameSpecFileIdentity(before, opened)) throw new Error(`${label} identity changed before open: ${file}`);
+    if (opened.size > 256 * 1024) throw new Error(`${label} exceeds the 256 KiB limit: ${file}`);
+    const bytes = Buffer.alloc(opened.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+      if (!bytesRead) throw new Error(`${label} became shorter while reading: ${file}`);
+      offset += bytesRead;
+    }
+    const openedAfter = await handle.stat();
+    const after = await fsp.lstat(file);
+    if (!sameSpecFileIdentity(opened, openedAfter) || openedAfter.size !== opened.size
+      || after.isSymbolicLink() || !after.isFile() || !sameSpecFileIdentity(opened, after)) {
+      throw new Error(`${label} changed size or identity while reading: ${file}`);
+    }
+    text = bytes.toString('utf8');
+  } finally {
+    await handle.close();
+  }
+  const value = JSON.parse(text);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must contain one JSON object: ${file}`);
+  return value;
+}
+
+function sameSpecFileIdentity(
+  left: { dev: number | bigint; ino: number | bigint },
+  right: { dev: number | bigint; ino: number | bigint }
+) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function existingProductionPath(root: string, value: string, label: string) {
+  if (!value || path.isAbsolute(value) || value.includes('\0')) throw new Error(`${label} must be a non-empty project-relative path`);
+  const realRoot = await fsp.realpath(root);
+  const candidate = await fsp.realpath(path.resolve(realRoot, value));
+  const relative = path.relative(realRoot, candidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`${label} escapes the project root`);
+  return candidate;
+}
+
 async function ueyePreflight(args = []) {
   if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return ueyeUsage();
   const parsed = parseDirJsonArgs(args);
@@ -3442,10 +3789,77 @@ function normalizeUeyeComparisonResult(value = '') {
   return 'not-verified';
 }
 
+async function verification(args = []) {
+  const surface = String(args[0] || 'help');
+  const action = String(args[1] || 'help');
+  if (surface === 'help' || action === 'help' || surface === '--help' || surface === '-h') return verificationUsage();
+  if (surface !== 'closure') {
+    console.error(`unknown verification command: ${surface}`);
+    return verificationUsage();
+  }
+  const flags = parseSimpleFlags(args.slice(2), new Set([
+    'root', 'receipt-path', 'planned-scope', 'changed-file', 'selected-spec',
+    'executed-spec', 'skipped-spec', 'truncated-spec', 'json'
+  ]));
+  const root = path.resolve(expandHome(flags.root || process.cwd()));
+  try {
+    let result: AnyRecord;
+    if (action === 'create') {
+      requireProductionFlags(flags, ['receipt_path', 'planned_scope', 'changed_file', 'selected_spec']);
+      result = await createVerificationClosureReceipt({
+        root,
+        receipt_path: String(flags.receipt_path),
+        planned_scope: String(flags.planned_scope) as 'affected' | 'release',
+        changed_files: arrayFlag(flags.changed_file),
+        selected_commands: await readProductionSpecs(flags.selected_spec, 'selected command spec') as any,
+        executed_commands: await readOptionalSpecs(flags.executed_spec, 'executed command spec') as any,
+        skipped: await readOptionalSpecs(flags.skipped_spec, 'skipped command spec') as any,
+        truncated: await readOptionalSpecs(flags.truncated_spec, 'truncated output spec') as any
+      });
+    } else if (action === 'verify') {
+      requireProductionFlags(flags, ['receipt_path']);
+      result = await verifyVerificationClosureReceiptFile({ root, receipt_path: String(flags.receipt_path) });
+    } else {
+      throw new Error(`unknown verification closure command: ${action}`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Verification closure');
+    if (result.truth_status === 'blocked') process.exitCode = 1;
+  } catch (error) {
+    const result = {
+      schema: 'yam.verification-closure-error.v1',
+      action,
+      status: 'blocked',
+      reason: summarizeCheckOutput(errorMessage(error)),
+      next_action: 'repair changed-file scope, selected/executed command evidence, skipped/truncated reasons, or receipt integrity before retrying',
+      truth_status: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Verification closure');
+    process.exitCode = 1;
+  }
+}
+
+function verificationUsage() {
+  console.log(`yam verification closure
+
+Explicit, immutable completion receipts. Create records operator-supplied results; it does not execute commands or replace advisory yam detect output.
+
+Usage:
+  yam verification closure create [--root dir] --receipt-path .yam/verification/closure.json --planned-scope affected|release --changed-file file --selected-spec file [--executed-spec file] [--skipped-spec file] [--truncated-spec file] [--json]
+  yam verification closure verify [--root dir] --receipt-path .yam/verification/closure.json [--json]
+
+Selected spec: {"id":"typecheck","command":"npm run typecheck","scope":"affected","required":true}
+Executed spec: {"id":"typecheck","command":"npm run typecheck","exit_code":0,"evidence":"exit 0 observed"}
+Skipped/truncated spec: {"check_id":"browser","reason":"no UI surface changed"}
+
+Repeat spec and changed-file flags as needed. Release-sensitive paths promote affected to release and require an executed required release-scope command. Required selected commands cannot be skipped. Digest verification does not upgrade operator-declared execution results beyond partial truth.
+`);
+}
+
 async function media(args = []) {
   const subcommand = args[0] || 'help';
   if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return mediaUsage();
   if (subcommand === 'proof') return mediaProof(args.slice(1));
+  if (subcommand === 'provider') return mediaProvider(args.slice(1));
   console.error(`unknown media command: ${subcommand}`);
   return mediaUsage();
 }
@@ -3457,9 +3871,63 @@ Opt-in media generation proof helpers. Generated media can support visual direct
 
 Usage:
   yam media proof [--tool name] [--requested] [--attempted] [--output file] [--wait-loop] [--blocked-reason text] [--json]
+  yam media provider create [--root dir] --receipt-path .yam/media/run.json --demand-kind media_generation|media_transformation --demand-evidence text --provider name --model name --provider-calls n [--provider-execution] [--dry-run] [--submit] --asset-spec file [--json]
+  yam media provider verify [--root dir] --receipt-path .yam/media/run.json [--json]
+
+Provider receipts are optional and demand-gated. This command hashes local assets and records an operator-asserted boundary; it never contacts a provider. Dry runs require zero calls and no submit. Explicit execution requires at least one call, submit, and a provider-provenance output asset.
 `);
 }
 
+async function mediaProvider(args = []) {
+  const action = String(args[0] || 'help');
+  if (action === 'help' || action === '--help' || action === '-h') return mediaUsage();
+  const flags = parseSimpleFlags(args.slice(1), new Set([
+    'root', 'receipt-path', 'demand-kind', 'demand-evidence', 'provider', 'model',
+    'provider-calls', 'provider-execution', 'dry-run', 'submit', 'asset-spec', 'json'
+  ]));
+  const root = path.resolve(expandHome(flags.root || process.cwd()));
+  try {
+    let result: AnyRecord;
+    if (action === 'create') {
+      requireProductionFlags(flags, [
+        'receipt_path', 'demand_kind', 'demand_evidence', 'provider', 'model', 'provider_calls', 'asset_spec'
+      ]);
+      result = await createMediaProviderReceipt({
+        root,
+        receipt_path: String(flags.receipt_path),
+        demand_trigger: {
+          kind: String(flags.demand_kind) as 'media_generation' | 'media_transformation',
+          evidence: String(flags.demand_evidence)
+        },
+        provider: { name: String(flags.provider), model: String(flags.model) },
+        provider_calls: Number(flags.provider_calls),
+        provider_execution: Boolean(flags.provider_execution),
+        dry_run: Boolean(flags.dry_run),
+        submit: Boolean(flags.submit),
+        assets: await readProductionSpecs(flags.asset_spec, 'media asset spec') as any
+      });
+    } else if (action === 'verify') {
+      requireProductionFlags(flags, ['receipt_path']);
+      result = await verifyMediaProviderReceipt({ root, receipt_path: String(flags.receipt_path) });
+    } else {
+      throw new Error(`unknown media provider command: ${action}`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Media provider receipt');
+    if (result.truth_status === 'blocked') process.exitCode = 1;
+  } catch (error) {
+    const result = {
+      schema: 'yam.media-provider-receipt-error.v1',
+      action,
+      status: 'blocked',
+      reason: summarizeCheckOutput(errorMessage(error)),
+      next_action: 'repair the demand, exact execution fields, confined asset provenance, or receipt integrity before retrying',
+      truth_status: 'blocked'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Media provider receipt');
+    process.exitCode = 1;
+  }
+}
+
 async function mediaProof(args = []) {
   if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return mediaUsage();
   const flags = parseSimpleFlags(args, new Set(['tool', 'requested', 'attempted', 'output', 'wait-loop', 'blocked-reason', 'next-action', 'json']));
@@ -3719,12 +4187,37 @@ async function missionGate(args = []) {
     receipts
   });
   const blockers = [...gate.blockers, ...loadErrors.map((error) => `receipt_load_failed: ${error}`)];
+  const gateResult = buildStrictGateResult({
+    gate_id: 'mission-completion',
+    boundary: 'mission',
+    checks: [
+      {
+        id: 'receipt-inventory',
+        status: gate.ready_to_claim_complete && loadErrors.length === 0 ? 'passed' : 'failed',
+        note: blockers[0] || 'all expected Mission receipts are present and eligible',
+        required: true
+      },
+      {
+        id: 'read-only-boundary',
+        status: gate.read_only_violations.length === 0 ? 'passed' : 'failed',
+        note: gate.read_only_violations.length ? `violations: ${gate.read_only_violations.join(', ')}` : 'reviewer and doctor receipts preserve read-only access',
+        required: true
+      }
+    ],
+    blockers,
+    evidence: gate.receipts.map((receipt) => `${receipt.thread_id}:${receipt.receipt_id}:${receipt.outcome}`),
+    next_action: blockers[0] || gate.next_action
+  });
+  const gateContract = verifyStrictGateResult(gateResult);
+  const strictReady = gate.ready_to_claim_complete && loadErrors.length === 0 && gateResult.status === 'passed' && gateContract.valid;
   const result = {
     ...gate,
     blockers,
-    ready_to_claim_complete: gate.ready_to_claim_complete && loadErrors.length === 0,
+    ready_to_claim_complete: strictReady,
     next_action: blockers[0] || gate.next_action,
-    truth_status: blockers.length ? 'blocked' : gate.truth_status,
+    truth_status: strictReady ? gate.truth_status : 'blocked',
+    gate_result: gateResult,
+    gate_contract: gateContract,
     persistence: flags.out ? 'written' : 'not-persisted',
     out: flags.out ? path.resolve(expandHome(flags.out)) : ''
   };
@@ -3810,15 +4303,72 @@ function benchmarkUsage() {
 
 Usage:
   yam benchmark report [--label text] [--baseline n] [--current n] [--unit ms] [--target lower|higher] [--next-action text] [--json]
+  yam benchmark report --candidate-digest sha256 --baseline-digest sha256 --sample seed:candidate:baseline --unit score --evidence-source text [--sample ...] [--min-samples n] [--min-mean-delta n] [--min-win-rate n] [--json]
 
 Notes:
   Records a small optimization loop result. It does not run benchmarks by itself.
+  Promotion mode verifies deterministic paired-sample arithmetic but treats supplied scores as operator assertions, not statistical significance.
 `);
 }
 
 async function benchmarkReport(args = []) {
   if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return benchmarkUsage();
-  const flags = parseSimpleFlags(args, new Set(['label', 'baseline', 'current', 'unit', 'target', 'next-action', 'rollback-hint', 'intent', 'json']));
+  const flags = parseSimpleFlags(args, new Set(['label', 'baseline', 'current', 'unit', 'target', 'next-action', 'rollback-hint', 'intent', 'candidate-digest', 'baseline-digest', 'sample', 'min-samples', 'min-mean-delta', 'min-win-rate', 'evidence-source', 'json']));
+  const promotionRequested = Boolean(
+    flags.candidate_digest
+    || flags.baseline_digest
+    || flags.sample
+    || flags.min_samples
+    || flags.min_mean_delta
+    || flags.min_win_rate
+    || flags.evidence_source
+  );
+  if (promotionRequested) {
+    try {
+      const promotion = buildBoundedPromotionReport({
+        label: String(flags.label || 'unnamed'),
+        candidate_digest: String(flags.candidate_digest || ''),
+        baseline_digest: String(flags.baseline_digest || ''),
+        samples: arrayFlag(flags.sample).map((sample) => parsePromotionSample(sample)),
+        min_samples: flags.min_samples === undefined ? undefined : Number(flags.min_samples),
+        min_mean_delta: flags.min_mean_delta === undefined ? undefined : Number(flags.min_mean_delta),
+        min_win_rate: flags.min_win_rate === undefined ? undefined : Number(flags.min_win_rate),
+        target: String(flags.target || 'higher').toLowerCase() as 'lower' | 'higher',
+        unit: String(flags.unit || ''),
+        evidence_source: String(flags.evidence_source || '')
+      });
+      const gateResult = buildStrictGateResult({
+        gate_id: 'benchmark-promotion',
+        boundary: 'generic',
+        checks: [
+          {
+            id: 'promotion-decision',
+            status: promotion.decision === 'keep' ? 'passed' : 'failed',
+            note: promotion.next_action,
+            required: true
+          }
+        ],
+        blockers: promotion.blockers,
+        evidence: [promotion.evidence_digest, promotion.evidence_source || 'operator-supplied paired measurements'],
+        next_action: promotion.next_action
+      });
+      const result = { ...promotion, gate_result: gateResult };
+      printJsonOrHuman(result, Boolean(flags.json), 'Bounded promotion report');
+      if (promotion.decision !== 'keep' || gateResult.status !== 'passed') process.exitCode = 1;
+      return;
+    } catch (error) {
+      const result = {
+        schema: 'yam.bounded-promotion-error.v1',
+        decision: 'blocked',
+        blockers: [errorMessage(error)],
+        next_action: 'repair the malformed paired-sample input before making a promotion decision',
+        truth_status: 'blocked'
+      };
+      printJsonOrHuman(result, Boolean(flags.json), 'Bounded promotion report');
+      process.exitCode = 1;
+      return;
+    }
+  }
   const baseline = numberOrNull(flags.baseline);
   const current = numberOrNull(flags.current);
   const target = String(flags.target || 'lower').toLowerCase() === 'higher' ? 'higher' : 'lower';
@@ -3879,7 +4429,7 @@ function parseSimpleFlags(args = [], allowed = new Set<string>()) {
     const key = rawKey.slice(2);
     if (allowed.size && !allowed.has(key)) continue;
     const normalizedKey = key.replace(/-/g, '_');
-    if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'cleanup-observed', 'left-running-intentionally', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'invented-metric', 'placeholder-copy', 'generic-visual', 'operator-provided', 'do-not-replace', 'allowed-for-edit', 'replace'].includes(key)) {
+    if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'cleanup-observed', 'left-running-intentionally', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'invented-metric', 'placeholder-copy', 'generic-visual', 'operator-provided', 'do-not-replace', 'allowed-for-edit', 'replace', 'provider-execution', 'dry-run', 'submit'].includes(key)) {
       flags[normalizedKey] = true;
       continue;
     }
@@ -4413,7 +4963,12 @@ function formatStructuredEvidence(value) {
       return JSON.stringify(buildMissionSubagentReceipt(data));
     }
     if (data.schema === 'yam.mission-completion-gate.v1' || data.expected_thread_ids || data.ready_to_claim_complete !== undefined) {
-      return JSON.stringify(buildMissionCompletionGate(data));
+      const completion = buildMissionCompletionGate(data);
+      return JSON.stringify({
+        ...completion,
+        ...(data.gate_result && typeof data.gate_result === 'object' ? { gate_result: data.gate_result } : {}),
+        ...(data.gate_contract && typeof data.gate_contract === 'object' ? { gate_contract: data.gate_contract } : {})
+      });
     }
     if (data.schema === 'yam.mission-patch-envelope.v1' || data.agent_id || data.assigned_scope) {
       return JSON.stringify(buildMissionPatchEnvelope(data));
@@ -5415,6 +5970,11 @@ function showPath() {
 function showRequestedHelp(args: string[]) {
   if (!args.some((arg) => arg === '--help' || arg === '-h')) return false;
 
+  if (args[0] === 'ueye' && args[1] === 'production') {
+    ueyeProductionUsage();
+    return true;
+  }
+
   const commandUsage: Record<string, () => void> = {
     context: contextUsage,
     cleanup: cleanupUsage,
@@ -5424,6 +5984,7 @@ function showRequestedHelp(args: string[]) {
     loop: loopUsage,
     ueye: ueyeUsage,
     media: mediaUsage,
+    verification: verificationUsage,
     runtime: runtimeUsage,
     mission: missionUsage,
     update: updateUsage,
@@ -5454,6 +6015,7 @@ async function main() {
   if (command === 'loop') return loop(process.argv.slice(3));
   if (command === 'ueye') return ueye(process.argv.slice(3));
   if (command === 'media') return media(process.argv.slice(3));
+  if (command === 'verification') return verification(process.argv.slice(3));
   if (command === 'runtime') return runtime(process.argv.slice(3));
   if (command === 'mission') return mission(process.argv.slice(3));
   if (command === 'update') return updateCommand(process.argv.slice(3));