yam-flow 2.6.0 → 2.8.0

package/src/bin/yam.ts

@@ -50,6 +50,7 @@ import {
 import {
   inspectSkillInstallation,
   installSkillSetTransactional,
+  planSkillSetInstallation,
   uninstallSkillSetSafely
 } from '../lib/skill-installation.js';
 import {
@@ -66,6 +67,27 @@ 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 {
+  createScoutReceipt,
+  verifyScoutReceiptFile
+} from '../lib/scout-receipt.js';
+import {
+  buildNextStep,
+  verifyNextStep
+} from '../lib/next-step.js';
+import { releaseRegistryStatusFromChecks } from '../lib/release-registry-status.js';
+import {
+  buildReleaseAuthReadiness,
+  inspectTrustedPublisherWorkflowText
+} from '../lib/release-auth-readiness.js';
 import {
   BoundedInputError,
   GENERAL_STDIN_MAX_BYTES,
@@ -202,7 +224,9 @@ Usage:
   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 study-note check [dir] [--report file|--text text] [--json]
+  yam next-step <report|verify> [--spec file|--receipt file] [--json]
   yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
+  yam scout receipt <create|verify> [options]
   yam ueye capture --url URL --out screenshot.png [--viewport 1440x900] [--full-page] [--json]
   yam ueye compare --reference ref.png --actual screenshot.png [--json]
   yam ueye preflight [dir] [--json]
@@ -215,18 +239,19 @@ Usage:
   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 release report [--auth-mode auto|oidc|token] [--json]
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
   yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
   yam template <project|ueye|mission|proof|tuning>
   yam tune-log [dir]
-  yam install [--replace-user-skill name]
+  yam install [--dry-run] [--json] [--replace-user-skill name]
   yam uninstall
   yam doctor [--json]
   yam examples
@@ -252,10 +277,20 @@ async function rmrf(target) {
   await fsp.rm(target, { recursive: true, force: true });
 }
 
-function installReplacementSkills(args: string[] = []) {
+function installOptions(args: string[] = []) {
   const skills: string[] = [];
+  let dryRun = false;
+  let json = false;
   for (let index = 0; index < args.length; index += 1) {
     const arg = String(args[index] || '');
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
     if (arg === '--replace-user-skill') {
       const skill = String(args[index + 1] || '');
       if (!skill || skill.startsWith('--')) {
@@ -273,21 +308,31 @@ function installReplacementSkills(args: string[] = []) {
     }
     throw new Error(`unknown yam install argument: ${arg}`);
   }
-  return [...new Set(skills)];
+  if (json && !dryRun) throw new Error('yam install --json currently requires --dry-run');
+  return { replaceSkills: [...new Set(skills)], dryRun, json };
 }
 
 async function install(args: string[] = []) {
-  const replaceSkills = installReplacementSkills(args);
-  const result = await installSkillSetTransactional({
+  const options = installOptions(args);
+  const installInput = {
     sourceRoot: ROOT,
     destination: DEST,
     codexMirror: CODEX_MIRROR,
     packageName: String(PACKAGE_JSON.name || 'yam-flow'),
     version: VERSION,
     skills: SKILLS,
-    replaceSkills,
+    replaceSkills: options.replaceSkills,
     legacySkills: LEGACY_SKILLS,
     retiredSkills: RETIRED_SKILLS
+  };
+  if (options.dryRun) {
+    const plan = await planSkillSetInstallation(installInput);
+    printJsonOrHuman(plan, options.json, 'yam install dry run');
+    if (!plan.ready) process.exitCode = 1;
+    return;
+  }
+  const result = await installSkillSetTransactional({
+    ...installInput
   });
   console.log(`yam installed to ${DEST}`);
   console.log(`install receipt: ${result.receiptPath}`);
@@ -365,6 +410,92 @@ async function readJson(file): Promise<AnyRecord> {
   return JSON.parse(await fsp.readFile(file, 'utf8'));
 }
 
+async function readBoundedRegularJson(file, label = 'JSON input', maxBytes = GENERAL_STDIN_MAX_BYTES): Promise<AnyRecord> {
+  const requested = path.resolve(expandHome(String(file || '')));
+  const physicalParent = await fsp.realpath(path.dirname(requested));
+  const target = path.join(physicalParent, path.basename(requested));
+  const parents = await captureAbsoluteRegularDirectoryPath(physicalParent, label);
+  const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+    ? fs.constants.O_NOFOLLOW
+    : 0;
+  const before = await fsp.lstat(target);
+  if (!before.isFile() || before.isSymbolicLink()) {
+    throw new Error(`${label} must be a regular JSON file no larger than ${maxBytes} bytes`);
+  }
+  const handle = await fsp.open(target, fs.constants.O_RDONLY | noFollow);
+  try {
+    const opened = await handle.stat();
+    await revalidateAbsoluteRegularDirectoryPath(parents, label);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > maxBytes) {
+      throw new Error(`${label} must be a stable regular JSON file no larger than ${maxBytes} bytes`);
+    }
+    const bytes = await readBoundedFileHandle(handle, maxBytes);
+    const afterOpened = await handle.stat();
+    const after = await fsp.lstat(target);
+    await revalidateAbsoluteRegularDirectoryPath(parents, label);
+    if (
+      bytes.length > maxBytes
+      || after.isSymbolicLink()
+      || !after.isFile()
+      || after.dev !== opened.dev
+      || after.ino !== opened.ino
+      || afterOpened.dev !== opened.dev
+      || afterOpened.ino !== opened.ino
+      || afterOpened.size !== bytes.length
+    ) {
+      throw new Error(`${label} changed identity or size while being read`);
+    }
+    return JSON.parse(bytes.toString('utf8'));
+  } finally {
+    await handle.close();
+  }
+}
+
+type CliPathIdentity = { path: string; dev: number; ino: number };
+
+async function captureAbsoluteRegularDirectoryPath(target: string, label: string) {
+  const absolute = path.resolve(target);
+  const filesystemRoot = path.parse(absolute).root;
+  const relative = path.relative(filesystemRoot, absolute);
+  const identities: CliPathIdentity[] = [];
+  let current = filesystemRoot;
+  for (const segment of relative ? ['', ...relative.split(path.sep)] : ['']) {
+    if (segment) current = path.join(current, segment);
+    const stat = await fsp.lstat(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`${label} parent must be a regular physical directory: ${current}`);
+    }
+    identities.push({ path: current, dev: stat.dev, ino: stat.ino });
+  }
+  return identities;
+}
+
+async function revalidateAbsoluteRegularDirectoryPath(identities: CliPathIdentity[], label: string) {
+  for (const identity of identities) {
+    const stat = await fsp.lstat(identity.path);
+    if (
+      stat.isSymbolicLink()
+      || !stat.isDirectory()
+      || stat.dev !== identity.dev
+      || stat.ino !== identity.ino
+    ) {
+      throw new Error(`${label} parent changed identity while being read: ${identity.path}`);
+    }
+  }
+}
+
+async function readBoundedFileHandle(handle: fsp.FileHandle, maxBytes: number) {
+  const buffer = Buffer.alloc(maxBytes + 1);
+  let total = 0;
+  while (total < buffer.length) {
+    const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+    if (bytesRead === 0) break;
+    total += bytesRead;
+  }
+  if (total > maxBytes) throw new Error(`JSON input exceeds ${maxBytes} bytes while being read`);
+  return buffer.subarray(0, total);
+}
+
 async function readJsonOrDefault(file, fallback: AnyRecord = {}): Promise<AnyRecord> {
   try {
     return JSON.parse(await fsp.readFile(file, 'utf8'));
@@ -836,8 +967,9 @@ Usage:
   yam study-note check [dir] [--report file|--text text] [--json]
 
 Notes:
-  Read-only guard. It checks whether changed work has a Study Note and whether relevant UI/CSS/DB hygiene was reported.
-  It does not generate, edit, or infer the Study Note for you.
+  Read-only guard. It checks whether changed work has a complete Study Note followed immediately by Next step,
+  including relevant UI/CSS/DB hygiene and the ordered fix-first/planned handoff contract.
+  It does not generate, edit, or infer either section for you.
 `);
 }
 
@@ -858,6 +990,7 @@ async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'n
   const needsStudyNote = changeScopeAvailable && changedFiles.length > 0;
   const scopeAwareStatus = (passes) => changeScopeAvailable ? (!needsStudyNote || passes ? 'pass' : 'fail') : 'partial';
   const hygieneRequirements = studyNoteHygieneRequirements(changedFiles);
+  const studyNoteText = studyNoteSectionText(reportText);
   const checks = [
     studyNoteGuardCheck(
       'changed_files',
@@ -867,16 +1000,24 @@ async function buildStudyNoteGuardResult(dir, reportText = '', reportSource = 'n
         : 'Git changed-file scope is unavailable; do not treat this project as clean and determine Study Note need manually'
     ),
     studyNoteGuardCheck('study_note_present', scopeAwareStatus(hasStudyNoteMarker(reportText)), 'final report should include a Study Note when project artifacts changed'),
-    studyNoteGuardCheck('role_or_responsibility', scopeAwareStatus(/(\brole\b|\bresponsib|\bdoes\b|역할|기능)/i.test(reportText)), 'Study Note should explain what the touched code/artifact does'),
-    studyNoteGuardCheck('execution_point', scopeAwareStatus(/(execution|\bruns?\b|\bloads?\b|\brenders?\b|validates?|builds?|publishes?|read by|실행|로드|렌더|검사|검증|빌드|게시|배포|읽)/i.test(reportText)), 'Study Note should explain where or when the touched code/artifact runs or is read'),
-    studyNoteGuardCheck('before_after_or_change', scopeAwareStatus(/(\bbefore\b|\bafter\b|before\/after|changed|change meaning|바뀌|변경|수정)/i.test(reportText)), 'Study Note should explain what changed from before to after'),
-    studyNoteGuardCheck('expected_behavior', scopeAwareStatus(/(expected|should|will|result|behavior|예상|기대|결과|동작|되어야|하게 됨)/i.test(reportText)), 'Study Note should describe the expected behavior or result'),
-    studyNoteGuardCheck('syntax_or_structure', scopeAwareStatus(/(syntax|structure|schema|\bapi\b|function|array|field|type|condition|문법|구조|스키마|함수|배열|필드|타입|조건)/i.test(reportText)), 'Study Note should include one useful syntax or structure insight'),
-    studyNoteGuardCheck('verification', scopeAwareStatus(/(verification|verified|checked|tested|검증|확인|테스트)/i.test(reportText)), 'Study Note should say what was checked'),
-    studyNoteGuardCheck('limits_or_uncertainty', scopeAwareStatus(/(limits?|uncertain|unknown|not checked|remaining|한계|불확실|모르는|미확인|남은)/i.test(reportText)), 'Study Note should say what remains uncertain or explicitly state that no meaningful uncertainty remains')
+    studyNoteGuardCheck('role_or_responsibility', scopeAwareStatus(/(\brole\b|\bresponsib|\bdoes\b|역할|기능)/i.test(studyNoteText)), 'Study Note should explain what the touched code/artifact does'),
+    studyNoteGuardCheck('execution_point', scopeAwareStatus(/(execution|\bruns?\b|\bloads?\b|\brenders?\b|validates?|builds?|publishes?|read by|실행|로드|렌더|검사|검증|빌드|게시|배포|읽)/i.test(studyNoteText)), 'Study Note should explain where or when the touched code/artifact runs or is read'),
+    studyNoteGuardCheck('before_after_or_change', scopeAwareStatus(/(\bbefore\b|\bafter\b|before\/after|changed|change meaning|바뀌|변경|수정)/i.test(studyNoteText)), 'Study Note should explain what changed from before to after'),
+    studyNoteGuardCheck('expected_behavior', scopeAwareStatus(/(expected|should|will|result|behavior|예상|기대|결과|동작|되어야|하게 됨)/i.test(studyNoteText)), 'Study Note should describe the expected behavior or result'),
+    studyNoteGuardCheck('syntax_or_structure', scopeAwareStatus(/(syntax|structure|schema|\bapi\b|function|array|field|type|condition|문법|구조|스키마|함수|배열|필드|타입|조건)/i.test(studyNoteText)), 'Study Note should include one useful syntax or structure insight'),
+    studyNoteGuardCheck('verification', scopeAwareStatus(/(verification|verified|checked|tested|검증|확인|테스트)/i.test(studyNoteText)), 'Study Note should say what was checked'),
+    studyNoteGuardCheck('limits_or_uncertainty', scopeAwareStatus(/(limits?|uncertain|unknown|not checked|remaining|한계|불확실|모르는|미확인|남은)/i.test(studyNoteText)), 'Study Note should say what remains uncertain or explicitly state that no meaningful uncertainty remains'),
+    studyNoteGuardCheck('next_step_present', scopeAwareStatus(hasNextStepMarker(reportText)), 'changed-artifact reports should include a Next step section'),
+    studyNoteGuardCheck('single_study_note_next_step_pair', scopeAwareStatus(hasSingleStudyNoteNextStepPair(reportText)), 'changed-artifact reports should contain one unambiguous Study Note followed by one Next step section'),
+    studyNoteGuardCheck('study_note_then_next_step', scopeAwareStatus(hasStudyNoteThenNextStepOrder(reportText)), 'Next step should be the next report section immediately after Study Note'),
+    studyNoteGuardCheck('next_step_whole_process_scan', scopeAwareStatus(hasNextStepWholeProcessScan(reportText)), 'Next step should include current situation, forward outlook, a critical opinion, and an improvement recommendation'),
+    studyNoteGuardCheck('next_step_ordered_actions', scopeAwareStatus(hasNextStepOrderedActions(reportText)), 'Next step should include an ordered action sequence with fix-first work before planned work'),
+    studyNoteGuardCheck('next_step_evidence_and_ownership', scopeAwareStatus(hasNextStepEvidenceAndOwnership(reportText)), 'Next step should name evidence level or stamp plus the owner route or scope'),
+    studyNoteGuardCheck('next_step_safety_context', scopeAwareStatus(hasNextStepSafetyContext(reportText)), 'Next step should state blocker status, safe retry guidance, and side effects'),
+    studyNoteGuardCheck('next_step_truth_status', scopeAwareStatus(hasNextStepTruthStatus(reportText)), 'Next step should state its evidence-bounded truth status')
   ];
   for (const requirement of hygieneRequirements) {
-    checks.push(studyNoteGuardCheck(requirement.id, requirementSatisfied(reportText, requirement), requirement.note));
+    checks.push(studyNoteGuardCheck(requirement.id, requirementSatisfied(studyNoteText, requirement), requirement.note));
   }
   const blockers = checks.filter((check) => check.status === 'fail').map((check) => `${check.id}: ${check.next_action}`);
   const result = {
@@ -958,6 +1099,121 @@ function hasStudyNoteMarker(text = '') {
   return /(study note|study-note|학습\s*노트|스터디\s*노트)/i.test(text);
 }
 
+function hasNextStepMarker(text = '') {
+  return /(next step|next-step|다음\s*(?:단계|할\s*일|작업))/i.test(text);
+}
+
+function reportSectionMarkers(text = '') {
+  return String(text || '').split(/\r?\n/).map((line, index) => {
+    const trimmed = line.trim();
+    const heading = trimmed.match(/^#{1,6}\s+(.+?)\s*#*\s*$/);
+    const named = trimmed.match(/^(study note|study-note|학습\s*노트|스터디\s*노트|next step|next-step|다음\s*(?:단계|할\s*일|작업))\s*:?[ \t]*$/i);
+    const rawLabel = heading?.[1] || named?.[1] || '';
+    if (!rawLabel) return null;
+    const label = rawLabel.toLowerCase().replace(/[-\s]+/g, ' ').trim();
+    const kind = /(study note|학습 노트|스터디 노트)/i.test(label)
+      ? 'study_note'
+      : /(next step|다음 단계|다음 할 일|다음 작업)/i.test(label)
+        ? 'next_step'
+        : 'other';
+    return { index, kind, level: heading?.[0].match(/^#+/)?.[0].length || 0 };
+  }).filter((item): item is { index: number; kind: string; level: number } => Boolean(item));
+}
+
+function hasStudyNoteThenNextStepOrder(text = '') {
+  const markers = reportSectionMarkers(text);
+  const studyIndex = markers.findIndex((item) => item.kind === 'study_note');
+  if (studyIndex < 0) return false;
+  return nextPeerSection(markers, studyIndex)?.kind === 'next_step';
+}
+
+function hasSingleStudyNoteNextStepPair(text = '') {
+  const markers = reportSectionMarkers(text);
+  return markers.filter((item) => item.kind === 'study_note').length === 1
+    && markers.filter((item) => item.kind === 'next_step').length === 1;
+}
+
+function hasNextStepWholeProcessScan(text = '') {
+  const value = nextStepSectionText(text);
+  const situation = /(situation|current state|현재\s*(?:상황|상태))/i.test(value);
+  const outlook = /(outlook|forward|앞으로|향후|전망)/i.test(value);
+  const critical = /(critical opinion|critique|비판적|비판\s*의견|tradeoff|약점)/i.test(value);
+  const recommendation = /(recommendation|recommend|개선\s*추천|추천\s*의견|권장)/i.test(value);
+  return situation && outlook && critical && recommendation;
+}
+
+function hasNextStepOrderedActions(text = '') {
+  const value = nextStepSectionText(text);
+  const lines = value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const actionLines = lines.filter((line) => /^\d+[.)]\s+/.test(line));
+  const labeledLines = lines.filter((line) => /\[(fix[- ]first|우선\s*(?:수정|해결|처리)|planned|계획(?:된|한)?\s*(?:작업|단계)?)\]/i.test(line));
+  if (!actionLines.length || !/^1[.)]\s+/.test(actionLines[0])) return false;
+  if (labeledLines.length !== actionLines.length || labeledLines.some((line) => !/^\d+[.)]\s+/.test(line))) return false;
+  let plannedSeen = false;
+  for (const [index, line] of actionLines.entries()) {
+    const number = Number(line.match(/^(\d+)[.)]/)?.[1] || 0);
+    if (number !== index + 1) return false;
+    const kind = line.match(/\[(fix[- ]first|우선\s*(?:수정|해결|처리)|planned|계획(?:된|한)?\s*(?:작업|단계)?)\]/i)?.[1] || '';
+    if (!kind) return false;
+    const planned = /planned|계획/i.test(kind);
+    if (planned) plannedSeen = true;
+    else if (plannedSeen) return false;
+  }
+  return true;
+}
+
+function hasNextStepEvidenceAndOwnership(text = '') {
+  const value = nextStepSectionText(text);
+  const evidence = /(evidence(?:[_ -](?:level|stamp))?|\bL[0-5]\b|근거|증거|검증\s*(?:수준|스탬프))/i.test(value);
+  const ownership = /(owner(?:[_ -](?:route|scope))?|담당|소유|책임\s*(?:경로|범위|주체))/i.test(value);
+  return evidence && ownership;
+}
+
+function hasNextStepSafetyContext(text = '') {
+  const value = nextStepSectionText(text);
+  const blocker = /(blocker|blocked(?:[_ -]by)?|차단|막힘|방해)/i.test(value);
+  const safeRetry = /(safe[_ -]retry|안전[^\n]{0,20}재시도|재시도[^\n]{0,20}안전)/i.test(value);
+  const sideEffects = /(side[_ -]effects?|부작용|영향)/i.test(value);
+  return blocker && safeRetry && sideEffects;
+}
+
+function hasNextStepTruthStatus(text = '') {
+  return /(truth[_ -]status|진실\s*상태|검증\s*상태)/i.test(nextStepSectionText(text));
+}
+
+function nextStepSectionText(text = '') {
+  const value = String(text || '');
+  const lines = value.split(/\r?\n/);
+  const markers = reportSectionMarkers(value);
+  const study = markers.findIndex((item) => item.kind === 'study_note');
+  if (study < 0) return '';
+  const adjacent = nextPeerSectionIndex(markers, study);
+  if (adjacent < 0 || markers[adjacent].kind !== 'next_step') return '';
+  const end = nextPeerSection(markers, adjacent);
+  return lines.slice(markers[adjacent].index + 1, end?.index ?? lines.length).join('\n');
+}
+
+function studyNoteSectionText(text = '') {
+  const value = String(text || '');
+  const lines = value.split(/\r?\n/);
+  const markers = reportSectionMarkers(value);
+  const study = markers.findIndex((item) => item.kind === 'study_note');
+  if (study < 0) return '';
+  const end = nextPeerSection(markers, study);
+  return lines.slice(markers[study].index + 1, end?.index ?? lines.length).join('\n');
+}
+
+function nextPeerSection(markers: Array<{ index: number; kind: string; level: number }>, start: number) {
+  const nextIndex = nextPeerSectionIndex(markers, start);
+  return nextIndex < 0 ? undefined : markers[nextIndex];
+}
+
+function nextPeerSectionIndex(markers: Array<{ index: number; kind: string; level: number }>, start: number) {
+  const current = markers[start];
+  const relative = markers.slice(start + 1).findIndex((item) => current.level === 0 || item.level === 0 || item.level <= current.level);
+  return relative < 0 ? -1 : start + 1 + relative;
+}
+
 function studyNoteGuardCheck(id, status, nextAction) {
   return {
     id,
@@ -1412,6 +1668,8 @@ function buildCapabilityMatrix(readinessRows = [], liteHook: AnyRecord = {}, stu
     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')
   ];
@@ -2171,26 +2429,27 @@ async function buildStudyNoteHookContext({ cwd }) {
   const changedFileDetection = gitChangedFileSnapshot(dir);
   const changedFiles = changedFileDetection.files;
   const lines = [
-    'yam Study Note guard active: if this turn changes code, config, release metadata, docs, or project artifacts, include a Study Note in the final response.'
+    'yam Study Note guard active: if this turn changes code, config, release metadata, docs, or project artifacts, include a Study Note followed immediately by Next step in the final response.'
   ];
   if (!changedFileDetection.available) {
     lines.push('Git changed-file scope is unavailable at prompt time; do not treat this as a clean project.');
-    lines.push('Determine manually whether artifacts changed and include the Study Note when they did; the Stop hook will keep this uncertainty visible.');
+    lines.push('Determine manually whether artifacts changed and include Study Note followed by Next step when they did; the Stop hook will keep this uncertainty visible.');
     return lines.join('\n');
   }
   if (!changedFiles.length) {
-    lines.push('No changed files were detected at prompt time; if you change artifacts during this turn, add the Study Note before final.');
+    lines.push('No changed files were detected at prompt time; if you change artifacts during this turn, add Study Note followed immediately by Next step before final.');
     lines.push('The Study Note Stop hook will check the final response if artifacts are changed later in the turn.');
     return lines.join('\n');
   }
   lines.push(`Changed files detected (${Math.min(changedFiles.length, 8)} shown): ${changedFiles.slice(0, 8).join(', ')}`);
   lines.push('Study Note minimum: touched code/artifact, role, execution point, before/after change, expected behavior, one syntax/structure insight, verification, and limits.');
+  lines.push('Next step minimum: quick whole-process scan, current situation, forward outlook, critical opinion, improvement recommendation, ordered fix-first then planned actions, evidence, ownership, blocker status, safe retry, side effects, and truth status.');
   const hygiene = studyNoteHygieneRequirements(changedFiles);
   if (hygiene.length) {
     lines.push(`Architecture hygiene required: ${hygiene.map((item) => item.id).join(', ')}.`);
     lines.push('Report whether the change avoided dumping unrelated logic into page.tsx, one-off CSS into global.css, or structured product data into broad DB jsonb.');
   }
-  lines.push('This prompt reminder does not generate or edit the Study Note; the paired Stop hook requests one correction pass if the final response is incomplete.');
+  lines.push('This prompt reminder does not generate or edit either section; the paired Stop hook requests one correction pass if the final response is incomplete or ordered incorrectly.');
   return lines.join('\n');
 }
 
@@ -2268,12 +2527,15 @@ async function safety(args = []) {
 async function release(args = []) {
   const subcommand = args[0] || 'help';
   if (subcommand !== 'report') {
-    console.error('usage: yam release report [--json]');
+    console.error('usage: yam release report [--auth-mode auto|oidc|token] [--json]');
     process.exitCode = 1;
     return;
   }
-  const asJson = args.includes('--json');
-  const report = runReleaseReport();
+  const flags = parseSimpleFlags(args.slice(1), new Set(['auth-mode', 'json']));
+  const authMode = String(flags.auth_mode || 'auto');
+  if (!['auto', 'oidc', 'token'].includes(authMode)) throw new Error('--auth-mode must be auto, oidc, or token');
+  const asJson = Boolean(flags.json);
+  const report = runReleaseReport(authMode);
   if (asJson) {
     console.log(JSON.stringify(report, null, 2));
     if (!report.ok) process.exitCode = 1;
@@ -2298,7 +2560,7 @@ async function release(args = []) {
   if (report.publish_readiness) {
     console.log(`- Publish readiness: ${report.publish_readiness.status}`);
     console.log(`- Registry: ${report.publish_readiness.registry.url || 'not-verified'}`);
-    console.log(`- npm auth: ${report.publish_readiness.auth.status}`);
+    console.log(`- Publish auth: ${report.publish_readiness.auth.mode} (${report.publish_readiness.auth.status})`);
   }
   if (report.failed.length) {
     console.log('- Failed:');
@@ -2321,7 +2583,7 @@ async function release(args = []) {
   if (!report.ok) process.exitCode = 1;
 }
 
-function runReleaseReport() {
+function runReleaseReport(authMode = 'auto') {
   const startedAt = new Date().toISOString();
   const checks = [
     ['typecheck', ['npm', ['run', 'typecheck']]],
@@ -2336,7 +2598,7 @@ function runReleaseReport() {
   const tarball = releaseTarballProvenance();
   const freshness = releaseFreshness(checks, provenance, tarball);
   const publishBlockerEvidence = publishBlockerEvidenceFromRelease(checks, tarball);
-  const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
+  const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence, authMode);
   const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
   const preliminaryOk = failed.length === 0 && publishReadiness.status === 'ready';
   const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, preliminaryOk);
@@ -2402,9 +2664,14 @@ function releaseReadinessReceipt(provenance: AnyRecord = {}, freshness: AnyRecor
       truth_status: publishReadiness.registry?.truth_status || 'partial'
     },
     auth: {
-      command: 'npm whoami',
+      requested_mode: String(publishReadiness.auth?.requested_mode || 'auto'),
+      mode: String(publishReadiness.auth?.mode || 'manual_token'),
+      command: String(publishReadiness.auth?.command || 'npm whoami'),
+      required_for_selected_mode: Boolean(publishReadiness.auth?.required_for_selected_mode),
       status: String(publishReadiness.auth?.status || 'not_verified'),
-      account: publishReadiness.auth?.status === 'authenticated' ? 'observed_redacted' : '',
+      account: String(publishReadiness.auth?.account || ''),
+      local_token: publishReadiness.auth?.local_token || null,
+      trusted_publisher: publishReadiness.auth?.trusted_publisher || null,
       truth_status: publishReadiness.auth?.truth_status || 'partial'
     },
     git: {
@@ -2506,14 +2773,36 @@ function releaseFreshness(checks = [], provenance: AnyRecord = {}, tarball: AnyR
   };
 }
 
-function releasePublishReadiness(checks = [], provenance: AnyRecord = {}, tarball: AnyRecord = {}, publishBlockers = []) {
+function releasePublishReadiness(checks = [], provenance: AnyRecord = {}, tarball: AnyRecord = {}, publishBlockers = [], authMode = 'auto') {
   const failedChecks = checks.filter((check) => check.status !== 'passed');
   const registryProbe = runReadOnlyCommandResult('npm', ['config', 'get', 'registry']);
   const registryUrl = registryProbe.stdout.trim() || String(PACKAGE_JSON.publishConfig?.registry || 'https://registry.npmjs.org/');
   const whoamiProbe = runReadOnlyCommandResult('npm', ['whoami', '--registry', registryUrl]);
-  const registryStatus = releaseRegistryStatusFromChecks(checks);
+  const trustedPublisherWorkflowPath = '.github/workflows/release.yml';
+  const trustedPublisherWorkflowFile = path.join(ROOT, trustedPublisherWorkflowPath);
+  const trustedPublisherWorkflowExists = fs.existsSync(trustedPublisherWorkflowFile);
+  const trustedPublisherWorkflow = inspectTrustedPublisherWorkflowText(
+    trustedPublisherWorkflowExists ? fs.readFileSync(trustedPublisherWorkflowFile, 'utf8') : '',
+    trustedPublisherWorkflowPath,
+    trustedPublisherWorkflowExists
+  );
+  const authReadiness = buildReleaseAuthReadiness({
+    workflow: trustedPublisherWorkflow,
+    local_token: {
+      command: 'npm whoami',
+      ok: whoamiProbe.ok,
+      note: whoamiProbe.note
+    },
+    requested_mode: authMode as 'auto' | 'oidc' | 'token'
+  });
+  const registryStatus = releaseRegistryStatusFromChecks(checks, {
+    package_name: PACKAGE_JSON.name,
+    version: VERSION
+  });
   const latestProbe = registryStatus.checked
     ? { ok: true, stdout: registryStatus.latest_version, note: registryStatus.note }
+    : registryStatus.parse_failed
+      ? { ok: false, stdout: '', note: `registry check output did not prove ${PACKAGE_JSON.name}@${VERSION} is unpublished: ${registryStatus.note}` }
     : runReadOnlyCommandResult('npm', ['view', PACKAGE_JSON.name, 'version', '--registry', registryUrl]);
   const latestVersion = latestProbe.ok ? String(latestProbe.stdout || '').trim() : '';
   const blockers = [];
@@ -2524,8 +2813,8 @@ function releasePublishReadiness(checks = [], provenance: AnyRecord = {}, tarbal
   if (!registryProbe.ok) {
     blockers.push(readinessBlocker('registry_not_verified', 'npm registry could not be read from this shell', 'run `npm config get registry` and confirm it points to the intended public registry', 'npm config get registry', 'error'));
   }
-  if (!whoamiProbe.ok) {
-    blockers.push(readinessBlocker('auth_not_verified', whoamiProbe.note || 'npm whoami did not confirm an authenticated publisher in this shell', 'refresh npm login/token, then rerun `npm whoami` before publishing', 'npm whoami', 'error'));
+  for (const blocker of authReadiness.blockers) {
+    blockers.push(readinessBlocker(blocker.kind, blocker.reason, blocker.safe_next_action, blocker.command, blocker.severity));
   }
   if (!latestProbe.ok) {
     const blocker = classifyPublishBlockerText(latestProbe.note);
@@ -2565,11 +2854,16 @@ function releasePublishReadiness(checks = [], provenance: AnyRecord = {}, tarbal
       truth_status: latestProbe.ok ? 'verified' : 'blocked'
     },
     auth: {
-      command: 'npm whoami',
-      status: whoamiProbe.ok ? 'authenticated' : 'not_authenticated',
-      account: whoamiProbe.ok ? 'observed_redacted' : '',
-      note: whoamiProbe.ok ? 'npm account observed; username intentionally redacted' : whoamiProbe.note,
-      truth_status: whoamiProbe.ok ? 'verified' : 'blocked'
+      requested_mode: authReadiness.requested_mode,
+      mode: authReadiness.mode,
+      command: authReadiness.local_token.command,
+      required_for_selected_mode: authReadiness.local_token.required_for_selected_mode,
+      status: authReadiness.status,
+      account: authReadiness.local_token.account,
+      note: authReadiness.next_action,
+      local_token: authReadiness.local_token,
+      trusted_publisher: authReadiness.trusted_publisher,
+      truth_status: authReadiness.truth_status
     },
     blockers: uniqueBlockers,
     next_action: uniqueBlockers[0]?.safe_next_action || 'publish readiness is complete; run publish only when the user explicitly intends it',
@@ -2577,19 +2871,6 @@ function releasePublishReadiness(checks = [], provenance: AnyRecord = {}, tarbal
   };
 }
 
-function releaseRegistryStatusFromChecks(checks = []) {
-  const registryCheck = checks.find((check) => check.id === 'registry_status');
-  const note = String(registryCheck?.note || '');
-  if (registryCheck?.status !== 'passed') return { checked: false, latest_version: '', not_published: false, note };
-  const latest = note.match(/\blatest\s+([^,\s)]+)/i)?.[1] || '';
-  return {
-    checked: true,
-    latest_version: latest,
-    not_published: /not published yet/i.test(note),
-    note
-  };
-}
-
 function readinessBlocker(kind, reason, safeNextAction, command = '', severity = 'warning') {
   return {
     kind,
@@ -2625,13 +2906,13 @@ function releaseStudyNote(publishReadiness: AnyRecord = {}, publishBlockers = []
   }
   return buildStudyNote({
     issue_code: 'npm publish readiness',
-    issue_role: 'This part checks registry, version, auth, tarball, and local release checks before any public publish.',
+    issue_role: 'This part checks registry, version, the selected OIDC or manual-token authentication path, tarball, and local release checks before any public publish.',
     issue_symptom: firstBlocker.reason || firstBlocker.likely_cause || 'Publish readiness is blocked.',
     changed_code: 'yam release report',
     changed_role: 'It now explains the likely publish blocker instead of only showing a raw npm failure.',
-    change_summary: 'The report adds auth-safe readiness, safe next action, and beginner-readable blocker evidence.',
-    why_important: 'A bad token or wrong npm account can make publish fail or target the wrong package context.',
-    learning_note: 'When release readiness is blocked, fix the first blocker before trying a publish command.'
+    change_summary: 'The report separates Trusted Publisher OIDC evidence from optional local-token evidence and gives a path-specific safe next action.',
+    why_important: 'npm whoami cannot prove OIDC readiness; treating its E401 as an OIDC blocker would recommend the wrong credential model.',
+    learning_note: 'For Trusted Publisher releases, verify the hosted workflow and npmjs package binding; use npm whoami only for an explicitly selected manual-token path.'
   });
 }
 
@@ -2806,20 +3087,117 @@ async function loop(args = []) {
   return loopUsage();
 }
 
+async function scout(args = []) {
+  const subcommand = args[0] || 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return scoutUsage();
+  if (subcommand === 'receipt') return scoutReceipt(args.slice(1));
+  console.error(`unknown scout command: ${subcommand}`);
+  process.exitCode = 1;
+  return scoutUsage();
+}
+
+function scoutUsage() {
+  console.log(`yam scout
+
+Immutable, operator-supplied research evidence helpers. These commands do not browse, fetch, or trust external content as instructions.
+
+Usage:
+  yam scout receipt create [--root dir] --receipt-path .yam/scout/run.json --spec scout-spec.json [--json]
+  yam scout receipt verify [--root dir] --receipt-path .yam/scout/run.json [--json]
+`);
+}
+
+async function scoutReceipt(args = []) {
+  const action = args[0] || 'help';
+  if (action === 'help' || action === '--help' || action === '-h') return scoutUsage();
+  const flags = parseSimpleFlags(args.slice(1), new Set(['root', 'receipt-path', 'spec', 'json']));
+  const root = path.resolve(expandHome(String(flags.root || process.cwd())));
+  try {
+    let result;
+    if (action === 'create') {
+      if (!flags.receipt_path || !flags.spec) throw new Error('create requires --receipt-path and --spec');
+      result = await createScoutReceipt({
+        root,
+        receipt_path: String(flags.receipt_path),
+        spec: await readBoundedRegularJson(flags.spec, 'Scout spec') as any
+      });
+    } else if (action === 'verify') {
+      if (!flags.receipt_path) throw new Error('verify requires --receipt-path');
+      result = await verifyScoutReceiptFile({ root, receipt_path: String(flags.receipt_path) });
+    } else {
+      throw new Error(`unknown Scout receipt action: ${action}`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Scout receipt');
+    if (result.truth_status === 'blocked') process.exitCode = 1;
+  } catch (error) {
+    const result = {
+      schema: 'yam.scout-receipt-error.v1',
+      truth_status: 'blocked',
+      error: errorMessage(error),
+      next_action: 'repair the confined receipt path, canonical entity, version clocks, source digests, claim links, or failure taxonomy before retrying'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Scout receipt');
+    process.exitCode = 1;
+  }
+}
+
+async function nextStepCommand(args = []) {
+  const subcommand = args[0] || 'help';
+  if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') return nextStepUsage();
+  const flags = parseSimpleFlags(args.slice(1), new Set(['spec', 'receipt', 'json']));
+  try {
+    let result;
+    if (subcommand === 'report') {
+      if (!flags.spec) throw new Error('report requires --spec');
+      result = buildNextStep(await readBoundedRegularJson(flags.spec, 'Next step spec') as any);
+    } else if (subcommand === 'verify') {
+      if (!flags.receipt) throw new Error('verify requires --receipt');
+      result = verifyNextStep(await readBoundedRegularJson(flags.receipt, 'Next step receipt') as any);
+    } else {
+      throw new Error(`unknown Next step command: ${subcommand}`);
+    }
+    printJsonOrHuman(result, Boolean(flags.json), 'Next step');
+    if (result.truth_status === 'blocked') process.exitCode = 1;
+  } catch (error) {
+    const result = {
+      schema: 'yam.next-step-error.v1',
+      truth_status: 'blocked',
+      error: errorMessage(error),
+      next_action: 'repair the whole-process scan, ordered steps, evidence level/stamp, owner scope, blockers, or safe retry before retrying'
+    };
+    printJsonOrHuman(result, Boolean(flags.json), 'Next step');
+    process.exitCode = 1;
+  }
+}
+
+function nextStepUsage() {
+  console.log(`yam next-step
+
+Build or verify an evidence-bound ordered handoff after a quick whole-process scan.
+
+Usage:
+  yam next-step report --spec next-step-spec.json [--json]
+  yam next-step verify --receipt next-step-receipt.json [--json]
+`);
+}
+
 function loopUsage() {
   console.log(`yam loop
 
-Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, next action, handoff fields, and a short study note. It does not run agents, start processes, publish packages, or write files.
+Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, a short Study Note, and an evidence-bound Next step receipt. It does not run agents, start processes, publish packages, or write files.
 
 Usage:
-  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--touched-file file] [--read-file file] [--verified-file file] [--skipped-check text] [--stop-condition text] [--resume-hint text] [--readiness-state usable|degraded|blocked|unknown] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
+  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--touched-file file] [--read-file file] [--verified-file file] [--skipped-check text] [--stop-condition text] [--resume-hint text] [--readiness-state usable|degraded|blocked|unknown] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--next-step-spec file] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
 `);
 }
 
 async function loopReport(args = []) {
   if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return loopUsage();
-  const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'touched-file', 'read-file', 'verified-file', 'skipped-check', 'stop-condition', 'resume-hint', 'readiness-state', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
+  const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'touched-file', 'read-file', 'verified-file', 'skipped-check', 'stop-condition', 'resume-hint', 'readiness-state', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'next-step-spec', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
   const blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
+  const nextStepSpec = flags.next_step_spec
+    ? await readBoundedRegularJson(flags.next_step_spec, 'Next step spec')
+    : undefined;
   const report = buildLoopReport({
     route: normalizeRoute(flags.route) || String(flags.route || ''),
     intent: String(flags.intent || ''),
@@ -2858,6 +3236,7 @@ async function loopReport(args = []) {
     scope_owner: String(flags.scope_owner || flags.owner || ''),
     side_effects: arrayFlag(flags.side_effect),
     avoidance_note: String(flags.avoidance_note || ''),
+    next_step: nextStepSpec as any,
     issue_code: String(flags.issue_code || ''),
     issue_role: String(flags.issue_role || ''),
     issue_symptom: String(flags.issue_symptom || ''),
@@ -3158,15 +3537,60 @@ async function readProductionSpecs(value: unknown, label: string) {
   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 stat = await fsp.stat(file);
-  if (!stat.isFile()) throw new Error(`${label} must be a regular file: ${file}`);
-  if (stat.size > 256 * 1024) throw new Error(`${label} exceeds the 256 KiB limit: ${file}`);
-  const value = JSON.parse(await fsp.readFile(file, 'utf8'));
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must contain one JSON object: ${file}`);
+  const physicalParent = await fsp.realpath(path.dirname(file));
+  const target = path.join(physicalParent, path.basename(file));
+  const parents = await captureAbsoluteRegularDirectoryPath(physicalParent, label);
+  const before = await fsp.lstat(target);
+  if (before.isSymbolicLink() || !before.isFile()) throw new Error(`${label} must be a regular non-symlink file: ${target}`);
+  if (before.size > 256 * 1024) throw new Error(`${label} exceeds the 256 KiB limit: ${target}`);
+  const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+    ? fs.constants.O_NOFOLLOW
+    : 0;
+  const handle = await fsp.open(target, fs.constants.O_RDONLY | noFollow);
+  let text = '';
+  try {
+    const opened = await handle.stat();
+    await revalidateAbsoluteRegularDirectoryPath(parents, label);
+    if (!opened.isFile() || !sameSpecFileIdentity(before, opened)) throw new Error(`${label} identity changed before open: ${target}`);
+    if (opened.size > 256 * 1024) throw new Error(`${label} exceeds the 256 KiB limit: ${target}`);
+    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: ${target}`);
+      offset += bytesRead;
+    }
+    const openedAfter = await handle.stat();
+    const after = await fsp.lstat(target);
+    await revalidateAbsoluteRegularDirectoryPath(parents, label);
+    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: ${target}`);
+    }
+    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: ${target}`);
   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);
@@ -3738,10 +4162,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();
 }
@@ -3753,9 +4244,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']));
@@ -4257,7 +4802,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;
     }
@@ -5807,11 +6352,14 @@ function showRequestedHelp(args: string[]) {
     context: contextUsage,
     cleanup: cleanupUsage,
     'study-note': studyNoteUsage,
+    'next-step': nextStepUsage,
+    scout: scoutUsage,
     tools: toolsUsage,
     hook: hookUsage,
     loop: loopUsage,
     ueye: ueyeUsage,
     media: mediaUsage,
+    verification: verificationUsage,
     runtime: runtimeUsage,
     mission: missionUsage,
     update: updateUsage,
@@ -5839,9 +6387,12 @@ async function main() {
   if (command === 'tools') return tools(process.argv.slice(3));
   if (command === 'proof') return proof(process.argv.slice(3));
   if (command === 'study-note') return studyNote(process.argv.slice(3));
+  if (command === 'next-step') return nextStepCommand(process.argv.slice(3));
   if (command === 'loop') return loop(process.argv.slice(3));
+  if (command === 'scout') return scout(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));