yam-flow 0.1.6 → 0.1.8

package/dist/bin/yam.js

@@ -8,7 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { TRUTH_STATUSES, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildUeyeDesignCompletionGate, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
+import { TRUTH_STATUSES, buildLoopReport, buildMediaGenerationProof, buildMissionPatchEnvelope, buildRollbackHint, buildRuntimeBackendEvidence, buildStudyNote, buildUeyeDesignCompletionGate, buildUeyeVisualProvenance, buildUeyeRunReport, buildUeyeSurfaceContext, buildYamCompletionProof, detectDbSafetyText as detectTrustDbSafetyText, isTruthStatus } from '../lib/trust-kernel.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -115,13 +115,17 @@ Usage:
   yam verify
   yam detect [dir]
   yam pack [dir]
+  yam context pressure [dir] [--json]
+  yam cleanup scan [dir] [--json]
   yam budget [route]
   yam measure <route> [--files n] [--commands n] [--report-lines n] [--seconds n]
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
   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]
   yam ueye report [--reference ref.png] [--actual screenshot.png] [--provider-context local] [--execution-surface in-app-browser] [--json]
   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]
@@ -302,6 +306,7 @@ async function verify({ quiet = false } = {}) {
         'ui-quality.md',
         'question.md',
         'mission.md',
+        'cleanup-scan.md',
         'doctor-scan.md',
         'scout.md',
         'runtime-orchestration.md',
@@ -499,6 +504,8 @@ function toolIntentForCommand(command = '') {
     const text = String(command || '').toLowerCase();
     if (!text)
         return 'read_only';
+    if (/(npm\s+(view|whoami|config\s+get|owner\s+ls)|registry:check)/i.test(text))
+        return 'read_only';
     if (/(publish|registry|release|npm pack|npm publish)/i.test(text))
         return 'publish';
     if (/(rm |delete|drop|truncate|reset|migrate|push|deploy|write|commit|add |install)/i.test(text))
@@ -529,6 +536,297 @@ function uniqueNextActionDetails(actions = []) {
     }
     return unique;
 }
+async function context(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return contextUsage();
+    if (subcommand === 'pressure')
+        return contextPressure(args.slice(1));
+    console.error(`unknown context command: ${subcommand}`);
+    return contextUsage();
+}
+function contextUsage() {
+    console.log(`yam context
+
+Usage:
+  yam context pressure [dir] [--json]
+
+Notes:
+  Read-only context pressure scan. It explains when to summarize, refresh the project pack, narrow scope, or deepen the route.
+`);
+}
+async function contextPressure(args = []) {
+    const parsed = parseDirJsonArgs(args);
+    const report = await buildContextPressureReport(parsed.dir);
+    if (parsed.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    printContextPressureReport(report);
+}
+async function buildContextPressureReport(targetDir = process.cwd()) {
+    const dir = path.resolve(expandHome(targetDir || process.cwd()));
+    const pack = await findProjectPack(dir);
+    const memorySummary = path.join(dir, '.yam', 'memory', 'summary.md');
+    const instructionSurfaces = await findInstructionSurfaces(dir);
+    const detection = await detectProject(dir, { quiet: true });
+    const gitStatus = runReadOnlyCommandIn(dir, 'git', ['status', '--short']);
+    const dirtyFiles = gitStatus.trim().split(/\r?\n/).filter(Boolean);
+    const signals = {
+        project_pack: await projectPackPressureSignal(pack),
+        memory_summary: {
+            present: await exists(memorySummary),
+            path: memorySummary
+        },
+        git: {
+            dirty_file_count: dirtyFiles.length,
+            dirty_files_sample: dirtyFiles.slice(0, 12)
+        },
+        package_scripts: detection.packageJson ? detection.commands : {},
+        instruction_surfaces: instructionSurfaces
+    };
+    const reasons = [];
+    let score = 0;
+    if (!signals.project_pack.present) {
+        score += 3;
+        reasons.push('project pack is missing, so direction may need rediscovery');
+    }
+    else {
+        if (signals.project_pack.age_days > PACK_STALE_DAYS) {
+            score += 2;
+            reasons.push(`project pack is ${signals.project_pack.age_days} days old`);
+        }
+        if (signals.project_pack.words < 80) {
+            score += 1;
+            reasons.push('project pack is very short, so local direction may be thin');
+        }
+        if (signals.project_pack.words > 1200) {
+            score += 2;
+            reasons.push('project pack is long, so reuse may become expensive');
+        }
+        if (signals.project_pack.missing_sections?.length) {
+            score += 2;
+            reasons.push(`project pack is missing sections: ${signals.project_pack.missing_sections.join(', ')}`);
+        }
+    }
+    if (!signals.memory_summary.present) {
+        score += 1;
+        reasons.push('project memory summary is missing');
+    }
+    if (dirtyFiles.length >= 12) {
+        score += 3;
+        reasons.push(`${dirtyFiles.length} dirty files increase review and reporting pressure`);
+    }
+    else if (dirtyFiles.length >= 4) {
+        score += 2;
+        reasons.push(`${dirtyFiles.length} dirty files suggest the scope is widening`);
+    }
+    else if (dirtyFiles.length > 0) {
+        score += 1;
+        reasons.push(`${dirtyFiles.length} dirty file(s) should be kept in the final handoff`);
+    }
+    if (instructionSurfaces.issues.length) {
+        score += 3;
+        reasons.push('active hook or instruction issue can change route behavior');
+    }
+    if (instructionSurfaces.warnings.length >= 2) {
+        score += 1;
+        reasons.push('multiple instruction surfaces can make guidance harder to predict');
+    }
+    if (detection.packageJson && !detection.commands.build && !detection.commands.typecheck) {
+        score += 1;
+        reasons.push('no build/typecheck script was detected for quick implementation verification');
+    }
+    const pressure = score >= 7 ? 'high' : score >= 3 ? 'medium' : 'low';
+    return {
+        schema: 'yam.context-pressure.v1',
+        generated_at: new Date().toISOString(),
+        project: dir,
+        pressure,
+        score,
+        why_pressure_is_rising: reasons,
+        signals,
+        beginner_insight: contextPressureInsight(pressure),
+        recommended_next_action: pressure === 'high'
+            ? 'pause and narrow scope, refresh yam.project.md or memory summary, then choose the route deliberately'
+            : pressure === 'medium'
+                ? 'keep the task scoped and summarize important changes before expanding'
+                : 'continue with the current route and the smallest honest verification',
+        route_hint: pressure === 'high' ? '$deep or $mission when risk is real; otherwise split the task' : pressure === 'medium' ? '$quick with explicit boundaries, or $deep if verification claims grow' : '$quick or current route',
+        truth_status: 'partial'
+    };
+}
+async function projectPackPressureSignal(pack) {
+    if (!pack)
+        return { present: false, path: '', age_days: null, words: 0, size_bytes: 0, missing_sections: REQUIRED_PACK_SECTIONS };
+    const text = await readText(pack).catch(() => '');
+    const stat = await fsp.stat(pack).catch(() => null);
+    return {
+        present: true,
+        path: pack,
+        age_days: stat ? Math.floor((Date.now() - stat.mtimeMs) / 86400000) : null,
+        words: countWords(text),
+        size_bytes: stat?.size || 0,
+        missing_sections: REQUIRED_PACK_SECTIONS.filter((section) => !hasHeading(text, section))
+    };
+}
+function contextPressureInsight(pressure) {
+    if (pressure === 'high')
+        return 'The project has enough moving pieces that a non-specialist may lose track of what changed, what was checked, or which instruction surface is steering the agent.';
+    if (pressure === 'medium')
+        return 'The task is still manageable, but scope or stale context may start causing repeated reading and weaker final explanations.';
+    return 'The current context looks small enough to keep momentum without heavy proof, as long as claims stay modest.';
+}
+function printContextPressureReport(report) {
+    console.log('yam context pressure');
+    console.log(`Project: ${report.project}`);
+    console.log(`Pressure: ${report.pressure} (score ${report.score})`);
+    console.log(`Insight: ${report.beginner_insight}`);
+    if (report.why_pressure_is_rising.length) {
+        console.log('');
+        console.log('Why pressure is rising:');
+        for (const reason of report.why_pressure_is_rising)
+            console.log(`- ${reason}`);
+    }
+    console.log('');
+    console.log(`Next: ${report.recommended_next_action}`);
+    console.log(`Route hint: ${report.route_hint}`);
+}
+async function cleanup(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return cleanupUsage();
+    if (subcommand === 'scan')
+        return cleanupScan(args.slice(1));
+    console.error(`unknown cleanup command: ${subcommand}`);
+    return cleanupUsage();
+}
+function cleanupUsage() {
+    console.log(`yam cleanup
+
+Usage:
+  yam cleanup scan [dir] [--json]
+
+Notes:
+  Read-only cleanup scan. It never deletes files; it only reports confusing surfaces and safe next actions.
+`);
+}
+async function cleanupScan(args = []) {
+    const parsed = parseDirJsonArgs(args);
+    const report = await buildCleanupScanReport(parsed.dir);
+    if (parsed.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    printCleanupScanReport(report);
+}
+async function buildCleanupScanReport(targetDir = process.cwd()) {
+    const dir = path.resolve(expandHome(targetDir || process.cwd()));
+    const findings = [];
+    const instructionSurfaces = await findInstructionSurfaces(dir);
+    for (const found of instructionSurfaces.found) {
+        const issue = instructionSurfaces.issues.find((item) => item.startsWith(`${found}:`));
+        const warning = instructionSurfaces.warnings.find((item) => item.startsWith(`${found}:`));
+        findings.push(cleanupFinding(issue ? 'high' : 'medium', found, issue || warning || 'instruction surface detected', 'inspect the file and keep only the instruction surface you intend to use'));
+    }
+    const projectAgents = path.join(dir, '.agents');
+    if (await exists(projectAgents)) {
+        findings.push(cleanupFinding('medium', '.agents', 'project-local skills can override or duplicate user-level skills', 'review project-local skills before assuming global yam-flow behavior'));
+    }
+    for (const hook of [path.join(dir, '.codex', 'hooks.json'), path.join(os.homedir(), '.codex', 'hooks.json')]) {
+        if (await exists(hook))
+            findings.push(cleanupFinding('high', hook, 'active hooks can add hidden latency or route pressure', 'disable or edit only after user approval and backup'));
+    }
+    for (const skill of [...LEGACY_SKILLS, ...RETIRED_SKILLS]) {
+        if (await exists(path.join(DEST, skill, 'SKILL.md')))
+            findings.push(cleanupFinding('medium', `installed skill: ${skill}`, 'old skill names can confuse route selection', 'run the explicit current installer or remove only with user approval'));
+    }
+    const legacyPackageHits = await scanLimitedTextFiles(dir, ['package.json', 'README.md', 'COMMANDS.md', 'CHANGELOG.md'], /\b(yam-harness|yam-codex)\b/i);
+    for (const hit of legacyPackageHits) {
+        findings.push(cleanupFinding('low', hit.file, `legacy package name mention: ${hit.match}`, 'update public text only if it confuses install guidance'));
+    }
+    for (const artifact of await staleYamArtifacts(dir)) {
+        findings.push(cleanupFinding('low', artifact.file, artifact.reason, 'archive or refresh only if it misleads the current work'));
+    }
+    return {
+        schema: 'yam.cleanup-scan.v1',
+        generated_at: new Date().toISOString(),
+        project: dir,
+        destructive: false,
+        findings,
+        risk_level: overallCleanupRisk(findings),
+        safe_next_action: findings.length ? 'review findings and make explicit user-approved cleanup decisions' : 'no cleanup action needed',
+        truth_status: 'partial'
+    };
+}
+function cleanupFinding(riskLevel, surface, whyItMatters, safeNextAction) {
+    return {
+        risk_level: riskLevel,
+        surface,
+        why_it_matters: whyItMatters,
+        safe_next_action: safeNextAction,
+        destructive: false,
+        truth_status: 'partial'
+    };
+}
+function overallCleanupRisk(findings = []) {
+    if (findings.some((item) => item.risk_level === 'high'))
+        return 'high';
+    if (findings.some((item) => item.risk_level === 'medium'))
+        return 'medium';
+    return 'low';
+}
+async function scanLimitedTextFiles(dir, relativeFiles = [], pattern = /$^/) {
+    const hits = [];
+    for (const relative of relativeFiles) {
+        const file = path.join(dir, relative);
+        if (!await exists(file))
+            continue;
+        const text = await readText(file).catch(() => '');
+        const match = text.match(pattern);
+        if (match)
+            hits.push({ file: relative, match: match[0] });
+    }
+    return hits;
+}
+async function staleYamArtifacts(dir) {
+    const candidates = [
+        path.join(dir, '.yam', 'proof.json'),
+        path.join(dir, '.yam', 'proof.md'),
+        path.join(dir, '.yam', 'runtime-proof.md'),
+        path.join(dir, '.yam', 'ueye-report.json')
+    ];
+    const artifacts = [];
+    for (const file of candidates) {
+        if (!await exists(file))
+            continue;
+        const stat = await fsp.stat(file).catch(() => null);
+        if (stat && Date.now() - stat.mtimeMs > 14 * 86400000) {
+            artifacts.push({ file: path.relative(dir, file), reason: 'old proof/runtime artifact may be mistaken for current evidence' });
+        }
+    }
+    return artifacts;
+}
+function printCleanupScanReport(report) {
+    console.log('yam cleanup scan');
+    console.log(`Project: ${report.project}`);
+    console.log(`Risk level: ${report.risk_level}`);
+    console.log('Destructive: false');
+    if (!report.findings.length) {
+        console.log('No confusing cleanup surfaces found.');
+        return;
+    }
+    for (const finding of report.findings) {
+        console.log(`- ${finding.risk_level}: ${finding.surface}`);
+        console.log(`  why: ${finding.why_it_matters}`);
+        console.log(`  next: ${finding.safe_next_action}`);
+    }
+}
+function parseDirJsonArgs(args = []) {
+    const flags = parseSimpleFlags(args, new Set(['json']));
+    const dir = flags._?.find(looksLikeDirectoryArg) || process.cwd();
+    return { dir, json: Boolean(flags.json) };
+}
 async function tools(args = []) {
     const subcommand = args[0] || 'doctor';
     if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
@@ -588,6 +886,8 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
     const projectSurfaces = await detectProjectToolSurfaces(dir, packageInfo.pkg);
     const frameworkChecklist = await detectFrameworkChecklist(dir, packageInfo.pkg);
     const sqlScan = await scanSqlFiles(dir);
+    const contextPressure = await buildContextPressureReport(dir);
+    const realProbe = await buildRealProbeReport(dir, packageInfo.pkg, detection);
     const rows = [
         readinessRow('Codex home', await exists(codexHome) ? 'ready' : 'missing', codexHome),
         readinessRow('Yam skills', await status({ quiet: true }) === 0 ? 'ready' : 'missing', DEST),
@@ -624,6 +924,8 @@ async function buildToolsDoctorReport(targetDir = process.cwd()) {
         instructionSurfaces,
         projectSurfaces,
         frameworkChecklist,
+        contextPressure,
+        realProbe,
         sqlScan,
         riskNotes,
         nextActions: nextActionDetails.map((action) => action.next_action),
@@ -666,6 +968,16 @@ function printToolsDoctorReport(data) {
             console.log(`- ${check.id}: ${check.label} (${check.route})`);
         }
     }
+    if (data.contextPressure) {
+        console.log('');
+        console.log(`Context pressure: ${data.contextPressure.pressure} (${data.contextPressure.recommended_next_action})`);
+    }
+    if (data.realProbe?.probes?.length) {
+        console.log('');
+        console.log(`Real probe: ${data.realProbe.readiness_truth_status}`);
+        for (const probe of data.realProbe.probes)
+            console.log(`- ${probe.id}: ${probe.status} (${probe.truth_status})`);
+    }
     if (data.sqlScan.filesScanned > 0) {
         console.log('');
         console.log(`SQL scan: ${data.sqlScan.filesScanned} file(s), ${data.sqlScan.findings.length} risk finding(s)`);
@@ -794,6 +1106,62 @@ async function detectFrameworkChecklist(dir, pkg = null) {
 function checklistRow(id, label, route) {
     return { id, label, route };
 }
+async function buildRealProbeReport(dir = process.cwd(), pkg = null, detection = {}) {
+    const probes = [];
+    probes.push(realProbeRow('node_version', 'observed', process.version, 'verified'));
+    const npmVersion = runReadOnlyCommandIn(dir, 'npm', ['--version']).trim();
+    probes.push(realProbeRow('npm_version', npmVersion ? 'observed' : 'not_found', npmVersion || 'npm not found or not runnable', npmVersion ? 'verified' : 'partial'));
+    probes.push(realProbeRow('yam_binary', 'observed', `${process.argv[1] || 'unknown'} @ ${VERSION}`, 'verified'));
+    const scripts = detection.packageJson ? detection.commands : {};
+    probes.push(realProbeRow('package_scripts', Object.values(scripts).some(Boolean) ? 'observed' : 'not_found', scripts, Object.values(scripts).some(Boolean) ? 'verified' : 'partial'));
+    const playwrightPath = await localPackagePath(dir, 'playwright');
+    probes.push(realProbeRow('playwright_package', playwrightPath ? 'observed' : 'not_found', playwrightPath || 'playwright package not found in project or yam package context', playwrightPath ? 'verified' : 'partial'));
+    const browserCache = await pluginCacheHas('openai-bundled/browser');
+    probes.push(realProbeRow('in_app_browser_plugin_cache', browserCache ? 'observed' : 'not_found', browserCache ? 'plugin cache present' : 'plugin cache not found locally', browserCache ? 'partial' : 'partial'));
+    const tmux = await findExecutable('tmux');
+    const zellij = await findExecutable('zellij');
+    probes.push(realProbeRow('tmux', tmux ? 'observed' : 'not_found', tmux || 'not found on PATH', tmux ? 'verified' : 'partial'));
+    probes.push(realProbeRow('zellij', zellij ? 'observed' : 'not_found', zellij || 'not found on PATH', zellij ? 'verified' : 'partial'));
+    const gitInside = runReadOnlyCommandIn(dir, 'git', ['rev-parse', '--is-inside-work-tree']).trim();
+    const gitDirty = runReadOnlyCommandIn(dir, 'git', ['status', '--short']).trim();
+    probes.push(realProbeRow('git_state', gitInside === 'true' ? 'observed' : 'not_found', {
+        inside_work_tree: gitInside === 'true',
+        dirty_file_count: gitDirty ? gitDirty.split(/\r?\n/).length : 0
+    }, gitInside === 'true' ? 'verified' : 'partial'));
+    return {
+        schema: 'yam.real-probe.v1',
+        generated_at: new Date().toISOString(),
+        project: path.resolve(dir),
+        probes,
+        readiness_truth_status: probes.some((probe) => probe.status === 'blocked') ? 'blocked' : 'partial',
+        note: 'read-only local availability probe; no browser, server, database, or process was started'
+    };
+}
+function realProbeRow(id, status, evidence, truthStatus = 'partial') {
+    return {
+        id,
+        status,
+        evidence,
+        truth_status: truthStatus
+    };
+}
+async function localPackagePath(dir, packageName) {
+    const candidates = [
+        path.join(dir, 'node_modules', packageName, 'package.json'),
+        path.join(ROOT, 'node_modules', packageName, 'package.json')
+    ];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            return candidate;
+    }
+    try {
+        const projectRequire = createRequire(path.join(dir, 'package.json'));
+        return projectRequire.resolve(`${packageName}/package.json`);
+    }
+    catch {
+        return '';
+    }
+}
 function toolsDoctorNextActions(input) {
     return toolsDoctorNextActionDetails(input).map((action) => action.next_action);
 }
@@ -1166,16 +1534,31 @@ async function release(args = []) {
         if (report.tarball.file_count !== undefined)
             console.log(`- Tarball files: ${report.tarball.file_count}`);
     }
+    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}`);
+    }
     if (report.failed.length) {
         console.log('- Failed:');
         for (const id of report.failed)
             console.log(`  - ${id}`);
     }
+    if (report.publishBlockerEvidence?.length) {
+        console.log('- Publish blockers:');
+        for (const blocker of report.publishBlockerEvidence) {
+            console.log(`  - ${blocker.blocker_kind}: ${blocker.likely_cause}`);
+            console.log(`    next: ${blocker.safe_next_action}`);
+        }
+    }
     if (report.next_actions?.length) {
         console.log('- Next actions:');
         for (const action of report.next_actions)
             console.log(`  - ${action.next_action}`);
     }
+    if (report.study_note?.problem?.summary || report.study_note?.problem?.symptom) {
+        console.log(`- Study note: ${report.study_note.problem.summary || report.study_note.problem.symptom}`);
+    }
     if (!report.ok)
         process.exitCode = 1;
 }
@@ -1193,19 +1576,25 @@ function runReleaseReport() {
     const provenance = releaseProvenance(checks);
     const tarball = releaseTarballProvenance();
     const freshness = releaseFreshness(checks, provenance, tarball);
-    const nextActions = releaseNextActions(checks, provenance, tarball);
+    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';
     return {
         schema: 'yam.release-report.v1',
         generated_at: startedAt,
         packageName: PACKAGE_JSON.name,
         version: VERSION,
-        ok: failed.length === 0,
-        truth_status: failed.length === 0 ? 'verified' : 'blocked',
+        ok,
+        truth_status: ok ? 'verified' : 'blocked',
         checks,
         failed,
         provenance,
         tarball,
         freshness,
+        publish_readiness: publishReadiness,
+        study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
+        publishBlockerEvidence,
         next_actions: nextActions
     };
 }
@@ -1282,7 +1671,131 @@ function releaseFreshness(checks = [], provenance = {}, tarball = {}) {
         truth_status: [dist, registry, boundary, smoke, tarballStatus].every((value) => !/not-verified|needs-check/.test(value)) ? 'verified' : 'partial'
     };
 }
-function releaseNextActions(checks = [], provenance = {}, tarball = {}) {
+function releasePublishReadiness(checks = [], provenance = {}, tarball = {}, publishBlockers = []) {
+    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 latestProbe = registryStatus.checked
+        ? { ok: true, stdout: registryStatus.latest_version, note: registryStatus.note }
+        : runReadOnlyCommandResult('npm', ['view', PACKAGE_JSON.name, 'version', '--registry', registryUrl]);
+    const latestVersion = latestProbe.ok ? String(latestProbe.stdout || '').trim() : '';
+    const blockers = [];
+    const versionStatus = latestProbe.ok
+        ? registryStatus.not_published ? 'package_not_published' : latestVersion === VERSION ? 'already_published' : 'new_version'
+        : 'not_verified';
+    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'));
+    }
+    if (!latestProbe.ok) {
+        const blocker = classifyPublishBlockerText(latestProbe.note);
+        blockers.push(readinessBlocker(blocker?.blocker_kind || 'latest_version_not_verified', blocker?.likely_cause || 'npm latest version could not be read', blocker?.safe_next_action || 'rerun the read-only registry check before publishing', 'npm view', 'error'));
+    }
+    if (versionStatus === 'already_published') {
+        blockers.push(readinessBlocker('version_already_published', `${PACKAGE_JSON.name}@${VERSION} is already present on the registry`, 'bump package.json to the next patch version before publishing', 'npm view', 'error'));
+    }
+    if (failedChecks.length) {
+        blockers.push(readinessBlocker('release_checks_failed', `${failedChecks.length} release check(s) did not pass`, 'fix failing release checks before publishing', 'npm run release:check', 'error'));
+    }
+    if (provenance.git_dirty) {
+        blockers.push(readinessBlocker('git_dirty', 'working tree has uncommitted changes', 'commit intended changes or keep them explicitly local before tagging/publishing', 'git status --short'));
+    }
+    if (provenance.dist_changed_files?.length) {
+        blockers.push(readinessBlocker('dist_not_fresh', 'dist has changed files after freshness check', 'run build and commit dist only if this package publishes dist', 'npm run build'));
+    }
+    if (tarball.status !== 'checked') {
+        blockers.push(readinessBlocker('tarball_not_verified', tarball.reason || 'npm pack dry-run did not produce tarball provenance', 'fix tarball/package-boundary issues before publishing', 'npm pack --dry-run', 'error'));
+    }
+    for (const blocker of publishBlockers) {
+        blockers.push(readinessBlocker(blocker.blocker_kind, blocker.likely_cause, blocker.safe_next_action, 'npm publish', 'error'));
+    }
+    const uniqueBlockers = uniqueReadinessBlockers(blockers);
+    const status = uniqueBlockers.length ? 'blocked' : 'ready';
+    return {
+        schema: 'yam.release-publish-readiness.v1',
+        generated_at: new Date().toISOString(),
+        package_name: PACKAGE_JSON.name,
+        local_version: VERSION,
+        status,
+        registry: {
+            url: registryUrl,
+            latest_version: latestVersion,
+            version_status: versionStatus,
+            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'
+        },
+        blockers: uniqueBlockers,
+        next_action: uniqueBlockers[0]?.safe_next_action || 'publish readiness is complete; run publish only when the user explicitly intends it',
+        truth_status: status === 'ready' ? 'verified' : 'blocked'
+    };
+}
+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,
+        severity,
+        reason: summarizeCheckOutput(redactSensitiveText(reason)),
+        safe_next_action: safeNextAction,
+        command,
+        truth_status: 'partial'
+    };
+}
+function uniqueReadinessBlockers(blockers = []) {
+    const seen = new Set();
+    return blockers.filter((blocker) => {
+        const key = `${blocker.kind}:${blocker.safe_next_action}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function releaseStudyNote(publishReadiness = {}, publishBlockers = []) {
+    const authBlocked = publishReadiness.blockers?.find((blocker) => /auth|otp|permission|forbidden|not_found/i.test(`${blocker.kind} ${blocker.reason}`));
+    const firstBlocker = authBlocked || publishReadiness.blockers?.[0] || publishBlockers[0];
+    if (!firstBlocker) {
+        return buildStudyNote({
+            changed_code: 'yam release report',
+            changed_role: 'It checks whether the package looks ready to publish without running npm publish.',
+            change_summary: 'Release readiness passed the read-only checks that were available.',
+            why_important: 'A publish command changes public package state, so yam keeps the readiness proof separate from the publish action.',
+            learning_note: 'Readiness means the checks looked good; publishing still requires an explicit user action.'
+        });
+    }
+    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_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.'
+    });
+}
+function releaseNextActions(checks = [], provenance = {}, tarball = {}, publishBlockers = [], publishReadiness = {}) {
     const actions = [];
     for (const check of checks) {
         if (check.status === 'passed')
@@ -1298,8 +1811,73 @@ function releaseNextActions(checks = [], provenance = {}, tarball = {}) {
     if (tarball.status !== 'checked') {
         actions.push(nextActionDetail('release-tarball-provenance', 'error', tarball.reason || 'tarball provenance was not produced', 'run npm pack dry-run before publishing', 'npm pack --dry-run'));
     }
+    for (const blocker of publishBlockers) {
+        actions.push(nextActionDetail(`publish-${blocker.blocker_kind}`, blocker.truth_status === 'blocked' ? 'error' : 'warning', blocker.likely_cause, blocker.safe_next_action, 'npm publish'));
+    }
+    for (const blocker of publishReadiness.blockers || []) {
+        actions.push(nextActionDetail(`publish-readiness-${blocker.kind}`, blocker.severity || 'warning', blocker.reason, blocker.safe_next_action, blocker.command || 'npm publish'));
+    }
     return uniqueNextActionDetails(actions);
 }
+function publishBlockerEvidenceFromRelease(checks = [], tarball = {}) {
+    const texts = [
+        ...checks.map((check) => `${check.id}\n${check.note || ''}`),
+        tarball.reason || ''
+    ].filter(Boolean);
+    const blockers = [];
+    for (const text of texts) {
+        const blocker = classifyPublishBlockerText(text);
+        if (blocker)
+            blockers.push(blocker);
+    }
+    const seen = new Set();
+    return blockers.filter((blocker) => {
+        if (seen.has(blocker.blocker_kind))
+            return false;
+        seen.add(blocker.blocker_kind);
+        return true;
+    });
+}
+function classifyPublishBlockerText(text = '') {
+    const value = String(text || '');
+    if (!value.trim())
+        return null;
+    const excerpt = summarizeCheckOutput(value);
+    if (/\b(ENEEDAUTH|E401|Unauthorized|whoami)\b/i.test(value)) {
+        return publishBlocker('auth_required', excerpt, 'npm is not logged in for this shell or token', 'run `npm login` or refresh the npm token, then rerun `npm whoami`');
+    }
+    if (/\b(OTP|one-time password|two-factor|2FA)\b/i.test(value)) {
+        return publishBlocker('otp_required', excerpt, 'npm publish requires a current two-factor authentication code', 'rerun publish with `npm publish --otp=123456` using the current authenticator code');
+    }
+    if (/\bE403\b|403\s+Forbidden|Forbidden\s+-\s+PUT|npm ERR!.*Forbidden/i.test(value)) {
+        return publishBlocker('permission_forbidden', excerpt, 'the npm account lacks publish permission or the package policy rejected the request', 'confirm package ownership with `npm owner ls <package>` and publish with the owning account');
+    }
+    if (/\bE404\b|Not Found - PUT/i.test(value)) {
+        return publishBlocker('package_or_permission_not_found', excerpt, 'npm could not publish this package name from the current account or registry context', 'check `npm config get registry`, `npm owner ls <package>`, and package name access');
+    }
+    if (/previously published|cannot publish over|already exists|You cannot publish over/i.test(value)) {
+        return publishBlocker('version_already_published', excerpt, 'npm versions are immutable once published', 'bump package.json to the next patch version before publishing');
+    }
+    if (/(EACCES|EPERM|permission denied|cache|_cacache)/i.test(value)) {
+        return publishBlocker('npm_cache_permission', excerpt, 'npm cache or filesystem permissions are blocking the command', 'retry with a user-owned cache such as `npm_config_cache=/private/tmp/yam-npm-cache npm publish`');
+    }
+    if (/(ENOTFOUND|ECONNRESET|ETIMEDOUT|EAI_AGAIN|registry unreachable|network timeout)/i.test(value)) {
+        return publishBlocker('registry_unreachable', excerpt, 'the npm registry or network path was unreachable', 'wait, check network/VPN, then retry the read-only registry check first');
+    }
+    if (/(tarball|package boundary|files list|npm pack)/i.test(value)) {
+        return publishBlocker('tarball_or_boundary_failure', excerpt, 'the package contents or dry-run tarball check failed', 'run `npm run package-boundary:check` and `npm pack --dry-run` before publishing');
+    }
+    return null;
+}
+function publishBlocker(kind, excerpt, likelyCause, safeNextAction) {
+    return {
+        blocker_kind: kind,
+        native_error_excerpt: excerpt,
+        likely_cause: likelyCause,
+        safe_next_action: safeNextAction,
+        truth_status: 'partial'
+    };
+}
 function runReadOnlyCommand(command, args = []) {
     const result = spawnSync(command, args, {
         cwd: ROOT,
@@ -1310,6 +1888,33 @@ function runReadOnlyCommand(command, args = []) {
         return '';
     return String(result.stdout || '');
 }
+function runReadOnlyCommandResult(command, args = []) {
+    const result = spawnSync(command, args, {
+        cwd: ROOT,
+        encoding: 'utf8',
+        env: { ...process.env, npm_config_cache: path.join(os.tmpdir(), 'yam-npm-cache') },
+        timeout: 30000
+    });
+    const stdout = redactSensitiveText(String(result.stdout || ''));
+    const stderr = redactSensitiveText(String(result.stderr || result.error?.message || ''));
+    return {
+        ok: result.status === 0,
+        status: typeof result.status === 'number' ? result.status : null,
+        stdout,
+        stderr,
+        note: summarizeCheckOutput([stdout, stderr].filter(Boolean).join('\n'))
+    };
+}
+function runReadOnlyCommandIn(cwd, command, args = []) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: 30000
+    });
+    if (result.status !== 0)
+        return '';
+    return String(result.stdout || '');
+}
 function runReleaseCheck(id, commandSpec) {
     const [command, args] = commandSpec;
     const start = Date.now();
@@ -1331,12 +1936,19 @@ function runReleaseCheck(id, commandSpec) {
     };
 }
 function summarizeCheckOutput(output = '') {
-    const lines = String(output || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const lines = redactSensitiveText(String(output || '')).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (!lines.length)
         return '';
     const highSignal = lines.filter((line) => !line.startsWith('>')).slice(-4);
     return highSignal.join(' | ').slice(0, 600);
 }
+function redactSensitiveText(text = '') {
+    return String(text || '')
+        .replace(/(_authToken\s*=\s*)[^\s]+/gi, '$1[redacted]')
+        .replace(/\b(password|passwd|api[_-]?key|secret|token)\s*[:=]\s*\S+/gi, '$1=[redacted]')
+        .replace(/\/\/([^:\s]+):([^@\s]+)@/g, '//[redacted]@')
+        .replace(/\b(npm_[A-Za-z0-9]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,})\b/g, '[redacted-token]');
+}
 async function readStdinTextIfAvailable() {
     if (process.stdin.isTTY)
         return '';
@@ -1345,6 +1957,54 @@ async function readStdinTextIfAvailable() {
         chunks.push(Buffer.from(chunk));
     return Buffer.concat(chunks).toString('utf8').trim();
 }
+async function loop(args = []) {
+    const subcommand = args[0] || 'help';
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
+        return loopUsage();
+    if (subcommand === 'report')
+        return loopReport(args.slice(1));
+    console.error(`unknown loop command: ${subcommand}`);
+    process.exitCode = 1;
+    return loopUsage();
+}
+function loopUsage() {
+    console.log(`yam loop
+
+Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, next action, and a short study note. 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] [--blocked text] [--remaining-task 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]
+`);
+}
+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', 'evidence', 'blocked', 'blocker', 'next-action', 'remaining-task', '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 report = buildLoopReport({
+        route: normalizeRoute(flags.route) || String(flags.route || ''),
+        intent: String(flags.intent || ''),
+        loop_kind: String(flags.loop_kind || flags.route || 'harness'),
+        stages: arrayFlag(flags.stage),
+        evidence: arrayFlag(flags.evidence),
+        blockers,
+        truth_status: isTruthStatus(flags.truth) ? flags.truth : undefined,
+        intent_label: normalizeToolIntent(flags.intent_label || flags.tool_intent || 'read_only'),
+        next_action: String(flags.next_action || ''),
+        remaining_tasks: arrayFlag(flags.remaining_task),
+        issue_code: String(flags.issue_code || ''),
+        issue_role: String(flags.issue_role || ''),
+        issue_symptom: String(flags.issue_symptom || ''),
+        changed_code: String(flags.changed_code || ''),
+        changed_role: String(flags.changed_role || ''),
+        change_summary: String(flags.change_summary || ''),
+        why_important: String(flags.why_important || ''),
+        learning_note: String(flags.learning_note || '')
+    });
+    printJsonOrHuman(report, Boolean(flags.json), 'Loop report');
+    if (report.truth_status === 'blocked')
+        process.exitCode = 1;
+}
 async function ueye(args = []) {
     const subcommand = args[0] || 'help';
     if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
@@ -1353,6 +2013,8 @@ async function ueye(args = []) {
         return ueyeCapture(args.slice(1));
     if (subcommand === 'compare')
         return ueyeCompare(args.slice(1));
+    if (subcommand === 'preflight')
+        return ueyePreflight(args.slice(1));
     if (subcommand === 'report')
         return ueyeReport(args.slice(1));
     console.error(`unknown ueye command: ${subcommand}`);
@@ -1366,7 +2028,8 @@ Opt-in visual evidence helpers. Ueye stays one skill: fast by default, capture/c
 Usage:
   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 report [--reference ref.png] [--actual screenshot.png] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--completion-claim draft|needs-polish|done] [--strict] [--design-score n] [--p0 text] [--p1 text] [--states-checked] [--mobile-checked] [--contrast-checked] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
+  yam ueye preflight [dir] [--json]
+  yam ueye report [--reference ref.png] [--actual screenshot.png] [--preflight-id id] [--p0-risk text] [--quality-gate-note text] [--brief-dimension text] [--constraint text] [--anti-slop text] [--invented-metric] [--placeholder-copy] [--generic-visual] [--review-session-id id] [--provider-context local] [--execution-surface in-app-browser] [--app-surface codex-app] [--browser-surface in-app-browser] [--control-mode manual|automated] [--preserved-state] [--preserved-url URL] [--completion-claim draft|needs-polish|done] [--strict] [--design-score n] [--p0 text] [--p1 text] [--states-checked] [--mobile-checked] [--contrast-checked] [--similar text] [--different text] [--missing text] [--resolved text] [--new-finding text] [--still-open text] [--regression text] [--viewport 1440x900] [--state default] [--design-quality pass|needs-polish|fails|not-checked] [--json]
 
 Notes:
   capture uses a locally available Playwright install when present. It does not download browsers or install dependencies.
@@ -1374,6 +2037,74 @@ Notes:
   report produces a proof-ready Ueye visual run report, design completion gate, and continuity/comparison record without requiring a new capture.
 `);
 }
+async function ueyePreflight(args = []) {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
+        return ueyeUsage();
+    const parsed = parseDirJsonArgs(args);
+    const report = await buildUeyePreflightReport(parsed.dir);
+    if (parsed.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log('Ueye preflight');
+    console.log(`Project: ${report.project}`);
+    console.log(`Preflight id: ${report.preflight_id}`);
+    console.log(`Truth status: ${report.truth_status}`);
+    for (const item of report.checklist)
+        console.log(`- ${item.status}: ${item.item} (${item.next_action})`);
+}
+async function buildUeyePreflightReport(targetDir = process.cwd()) {
+    const dir = path.resolve(expandHome(targetDir || process.cwd()));
+    const packageInfo = await projectPackageInfo(dir);
+    const frameworkChecklist = await detectFrameworkChecklist(dir, packageInfo.pkg);
+    const pack = await findProjectPack(dir);
+    const playwrightPath = await localPackagePath(dir, 'playwright');
+    const browserCache = await pluginCacheHas('openai-bundled/browser');
+    const uiPaths = await existingRelativePaths(dir, ['app', 'src/app', 'pages', 'src/pages', 'components', 'src/components', 'styles', 'src/styles']);
+    const screenshotAvailability = playwrightPath ? 'automated_capture_possible' : browserCache ? 'in_app_or_user_screenshot_needed' : 'user_screenshot_needed';
+    const p0p1Risks = [];
+    if (!frameworkChecklist.uiLike)
+        p0p1Risks.push('target UI surface is not detected yet');
+    if (!browserCache && !playwrightPath)
+        p0p1Risks.push('no local capture surface was observed');
+    if (!pack)
+        p0p1Risks.push('project direction pack is missing');
+    return {
+        schema: 'yam.ueye-preflight.v1',
+        preflight_id: `ueye-preflight-${timestampId()}`,
+        generated_at: new Date().toISOString(),
+        project: dir,
+        detected_framework: frameworkChecklist.framework,
+        ui_paths: uiPaths,
+        reference_source_needed: true,
+        target_states_needed: ['default', 'loading', 'error', 'empty', 'mobile'],
+        mobile_responsive_check_needed: true,
+        contrast_cta_accessibility_risk: frameworkChecklist.uiLike ? 'check before done claim' : 'unknown until UI target is identified',
+        p0_p1_risk_candidates: p0p1Risks,
+        screenshot_capture_availability: screenshotAvailability,
+        preferred_surface: 'in-app-browser',
+        checklist: [
+            preflightItem('reference', 'reference source selected or user confirms no reference', 'needed', 'record reference path, screenshot, or text target before claiming design fidelity'),
+            preflightItem('states', 'primary states are listed', 'needed', 'prepare default/loading/error/empty/mobile states when the UI supports them'),
+            preflightItem('mobile', 'mobile/responsive pass planned', 'needed', 'capture or inspect a narrow viewport before verified visual claims'),
+            preflightItem('contrast_cta_accessibility', 'CTA, contrast, and accessible labels reviewed', 'needed', 'mark P0/P1 risks before saying done'),
+            preflightItem('capture', 'screenshot/capture surface available', screenshotAvailability === 'automated_capture_possible' ? 'observed' : 'partial', 'use in-app browser or user-provided screenshot if automation is unavailable')
+        ],
+        completion_cap: 'preflight cannot prove visual quality without implementation screenshot and comparison evidence',
+        truth_status: 'partial'
+    };
+}
+function preflightItem(id, item, status, nextAction) {
+    return { id, item, status, next_action: nextAction, truth_status: status === 'observed' ? 'verified' : 'partial' };
+}
+async function existingRelativePaths(dir, relativePaths = []) {
+    const found = [];
+    for (const relative of relativePaths) {
+        if (await exists(path.join(dir, relative)))
+            found.push(relative);
+    }
+    return found;
+}
 async function ueyeCapture(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
@@ -1539,7 +2270,7 @@ async function ueyeCompare(args = []) {
 async function ueyeReport(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return ueyeUsage();
-    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'completion-claim', 'completion-status', 'gate-mode', 'strict', 'design-score', 'min-design-score', 'p0', 'p1', 'open-p0', 'open-p1', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'comparison-result', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['reference', 'ref', 'actual', 'screenshot', 'capture-backend', 'compare-backend', 'design-quality', 'blocked-reason', 'next-action', 'next-visual-action', 'review-session-id', 'preflight-id', 'p0-risk', 'quality-gate-note', 'brief-dimension', 'constraint', 'anti-slop', 'invented-metric', 'placeholder-copy', 'generic-visual', 'reference-id', 'screenshot-id', 'previous-screenshot-id', 'current-screenshot-id', 'previous-report', 'comparison-notes', 'similar', 'different', 'missing', 'resolved', 'new-finding', 'still-open', 'regression', 'viewport', 'state', 'provider-context', 'provider-badge', 'execution-surface', 'app-surface', 'browser-surface', 'control-mode', 'preserved-state', 'preserved-url', 'url', 'evidence-id', 'completion-claim', 'completion-status', 'gate-mode', 'strict', 'design-score', 'min-design-score', 'p0', 'p1', 'open-p0', 'open-p1', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'comparison-result', 'json']));
     const reference = String(flags.reference || flags.ref || '');
     const actual = String(flags.actual || flags.screenshot || '');
     const referenceSources = [];
@@ -1548,6 +2279,8 @@ async function ueyeReport(args = []) {
     let blockedReason = String(flags.blocked_reason || '');
     const reviewSessionId = String(flags.review_session_id || `ueye-${timestampId()}`);
     const previousReport = await readPreviousUeyeReport(flags.previous_report);
+    const designBrief = buildUeyeDesignBrief(flags);
+    const antiSlopReview = buildUeyeAntiSlopReview(flags);
     const surfaceContext = buildUeyeSurfaceContext({
         provider_context: String(flags.provider_context || 'not-recorded'),
         provider_badge: String(flags.provider_badge || flags.provider_context || 'not-recorded'),
@@ -1632,7 +2365,7 @@ async function ueyeReport(args = []) {
             completion_claim: flags.completion_claim || flags.completion_status || 'draft',
             design_score: numberOrNull(flags.design_score),
             min_design_score: numberOrNull(flags.min_design_score) ?? 8,
-            p0: [...arrayFlag(flags.p0), ...arrayFlag(flags.open_p0)],
+            p0: [...arrayFlag(flags.p0), ...arrayFlag(flags.open_p0), ...arrayFlag(flags.p0_risk), ...antiSlopReview.blockers],
             p1: [...arrayFlag(flags.p1), ...arrayFlag(flags.open_p1)],
             states_checked: Boolean(flags.states_checked),
             mobile_checked: Boolean(flags.mobile_checked),
@@ -1673,6 +2406,14 @@ async function ueyeReport(args = []) {
     const result = {
         ...report,
         review_session_id: reviewSessionId,
+        design_brief: designBrief,
+        anti_slop_review: antiSlopReview,
+        preflight: {
+            preflight_id: String(flags.preflight_id || ''),
+            p0_risks: arrayFlag(flags.p0_risk),
+            quality_gate_notes: arrayFlag(flags.quality_gate_note),
+            truth_status: flags.preflight_id || flags.p0_risk || flags.quality_gate_note ? 'partial' : 'assumed'
+        },
         tool_intent: 'visual',
         capture_backend: String(flags.capture_backend || 'not-recorded'),
         compare_backend: String(flags.compare_backend || 'local-file-hash'),
@@ -1683,6 +2424,48 @@ async function ueyeReport(args = []) {
     if (report.truth_status === 'blocked')
         process.exitCode = 1;
 }
+function buildUeyeDesignBrief(flags = {}) {
+    const dimensions = arrayFlag(flags.brief_dimension);
+    const constraints = arrayFlag(flags.constraint);
+    const hasBrief = dimensions.length || constraints.length;
+    return {
+        schema: 'yam.ueye-design-brief.v1',
+        dimensions,
+        constraints,
+        source_boundary: hasBrief ? 'operator_provided_cli_flags' : 'not_provided',
+        next_action: hasBrief ? 'use this brief as context, not as visual proof' : 'add --brief-dimension and --constraint when design direction matters',
+        truth_status: hasBrief ? 'partial' : 'assumed'
+    };
+}
+function buildUeyeAntiSlopReview(flags = {}) {
+    const explicit = arrayFlag(flags.anti_slop);
+    const checks = [
+        antiSlopCheck('invented_metric', 'Invented metrics or unsupported numeric claims', Boolean(flags.invented_metric), 'replace invented metrics with measured values or remove the claim'),
+        antiSlopCheck('placeholder_copy', 'Placeholder copy remains in the UI', Boolean(flags.placeholder_copy), 'replace placeholder copy with product-specific text before claiming done'),
+        antiSlopCheck('generic_visual', 'Generic visual treatment does not fit the product context', Boolean(flags.generic_visual), 'tie visuals to the product, state, or reference before claiming design quality')
+    ];
+    const blockers = [
+        ...explicit,
+        ...checks.filter((check) => check.status === 'fail').map((check) => `${check.id}: ${check.next_action}`)
+    ];
+    return {
+        schema: 'yam.ueye-anti-slop-review.v1',
+        checks,
+        blockers,
+        next_action: blockers[0] || (checks.some((check) => check.status === 'pass') || explicit.length ? 'anti-slop risks are recorded; keep visual proof separate' : 'record anti-slop risks when they matter before claiming done'),
+        truth_status: blockers.length ? 'blocked' : checks.some((check) => check.status === 'pass') || explicit.length ? 'partial' : 'assumed'
+    };
+}
+function antiSlopCheck(id, label, failed = false, nextAction = '') {
+    return {
+        id,
+        label,
+        status: failed ? 'fail' : 'not_checked',
+        severity: failed ? 'P0' : 'P2',
+        next_action: nextAction,
+        truth_status: failed ? 'blocked' : 'assumed'
+    };
+}
 async function readPreviousUeyeReport(file = '') {
     const target = String(file || '');
     if (!target)
@@ -1820,7 +2603,7 @@ function runtimeUsage() {
     console.log(`yam runtime
 
 Usage:
-  yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--evidence-id id] [--command text] [--pid n] [--port n] [--url URL] [--exit-code n] [--screenshot-id id] [--cleanup-checked] [--note text] [--json]
+  yam runtime evidence [--backend terminal|in-app-browser|playwright|tmux|zellij] [--claim observed|started|stopped|cleanup-verified] [--evidence-id id] [--command text] [--pid n] [--port n] [--url URL] [--exit-code n] [--screenshot-id id] [--started-at time] [--stopped-at time] [--cleanup-method text] [--cleanup-observed] [--left-running-intentionally] [--cleanup-checked] [--note text] [--json]
 
 Notes:
   Records a small runtime evidence shape. It does not start, stop, or inspect processes by itself.
@@ -1829,13 +2612,21 @@ Notes:
 async function runtimeEvidence(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return runtimeUsage();
-    const flags = parseSimpleFlags(args, new Set(['backend', 'claim', 'evidence-id', 'command', 'pid', 'port', 'url', 'exit-code', 'screenshot-id', 'started-at', 'stopped-at', 'cleanup-checked', 'note', 'truth', 'intent', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['backend', 'claim', 'evidence-id', 'command', 'pid', 'port', 'url', 'exit-code', 'screenshot-id', 'started-at', 'stopped-at', 'cleanup-method', 'cleanup-observed', 'left-running-intentionally', 'cleanup-checked', 'note', 'truth', 'intent', 'json']));
     const evidence = buildRuntimeBackendEvidence({
         backend: flags.backend,
         claim: flags.claim,
         evidence_id: String(flags.evidence_id || `runtime-${timestampId()}`),
         command: String(flags.command || ''),
         cleanup_checked: Boolean(flags.cleanup_checked),
+        started_at: String(flags.started_at || ''),
+        stopped_at: String(flags.stopped_at || ''),
+        exit_code: numberOrNull(flags.exit_code),
+        pid: numberOrNull(flags.pid),
+        port: numberOrNull(flags.port),
+        cleanup_method: String(flags.cleanup_method || ''),
+        cleanup_observed: Boolean(flags.cleanup_observed),
+        left_running_intentionally: Boolean(flags.left_running_intentionally),
         note: String(flags.note || ''),
         truth_status: isTruthStatus(flags.truth) ? flags.truth : undefined
     });
@@ -1862,17 +2653,20 @@ function runtimeEvidenceDetails(flags = {}) {
         exit_code: numberOrNull(flags.exit_code),
         screenshot_id: String(flags.screenshot_id || ''),
         started_at: String(flags.started_at || ''),
-        stopped_at: String(flags.stopped_at || '')
+        stopped_at: String(flags.stopped_at || ''),
+        cleanup_method: String(flags.cleanup_method || ''),
+        cleanup_observed: Boolean(flags.cleanup_observed),
+        left_running_intentionally: Boolean(flags.left_running_intentionally)
     };
 }
 function runtimeDetailsHasVerification(details = {}) {
-    return Boolean(details.url || details.screenshot_id || details.pid !== null || details.port !== null || details.exit_code !== null || details.started_at || details.stopped_at);
+    return Boolean(details.url || details.screenshot_id || details.pid !== null || details.port !== null || details.exit_code !== null || details.started_at || details.stopped_at || details.cleanup_method || details.cleanup_observed || details.left_running_intentionally);
 }
 function runtimeEvidenceNextAction(evidence) {
     if (evidence.truth_status === 'proven' || evidence.truth_status === 'verified')
         return 'attach this evidence to `yam proof` when making a runtime claim';
-    if (evidence.claim === 'cleanup_verified' && !evidence.cleanup_checked)
-        return 'rerun with --cleanup-checked only after process exit or intentional persistence is confirmed';
+    if (evidence.claim === 'cleanup_verified' && !evidence.cleanup_observed && !evidence.left_running_intentionally)
+        return 'rerun with --cleanup-observed plus exit/closure evidence, or record --left-running-intentionally';
     if (evidence.backend === 'none' || evidence.backend === 'unknown')
         return 'record the actual runtime backend before claiming runtime verification';
     return 'add command output, screenshot id, pid/session id, or cleanup proof before upgrading the claim';
@@ -2053,7 +2847,7 @@ function parseSimpleFlags(args = [], allowed = new Set()) {
         if (allowed.size && !allowed.has(key))
             continue;
         const normalizedKey = key.replace(/-/g, '_');
-        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read'].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'].includes(key)) {
             flags[normalizedKey] = true;
             continue;
         }
@@ -2408,7 +3202,7 @@ function renderProofMarkdownList(values) {
 function parseProofArgs(args = []) {
     const flags = {};
     const positionals = [];
-    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'runtime-backend', 'runtime-claim', 'runtime-evidence-id', 'runtime-command', 'cleanup-checked', 'runtime-note', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'design-completion', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
+    const aliases = new Set(['goal', 'route', 'truth', 'command', 'evidence', 'visual', 'runtime', 'runtime-backend', 'runtime-claim', 'runtime-evidence-id', 'runtime-command', 'runtime-pid', 'runtime-port', 'runtime-exit-code', 'runtime-started-at', 'runtime-stopped-at', 'runtime-cleanup-method', 'cleanup-observed', 'left-running-intentionally', 'cleanup-checked', 'runtime-note', 'runtime-backend-evidence', 'visual-provenance', 'mission-envelope', 'rollback-hint', 'media-proof', 'design-completion', 'cleanup', 'changed', 'skipped', 'blocked', 'assumed', 'assumption', 'unverified', 'from', 'format', 'out', 'file', 'json', 'require-runtime', 'require-real-runtime', 'require-tmux', 'require-visual']);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg.startsWith('--')) {
@@ -2417,7 +3211,7 @@ function parseProofArgs(args = []) {
             if (!aliases.has(key))
                 continue;
             const normalizedKey = key.replace(/-/g, '_');
-            if (key === 'json' || key.startsWith('require-') || key === 'cleanup-checked') {
+            if (key === 'json' || key.startsWith('require-') || key === 'cleanup-checked' || key === 'cleanup-observed' || key === 'left-running-intentionally') {
                 flags[normalizedKey] = true;
                 continue;
             }
@@ -2575,13 +3369,21 @@ function structuredEvidenceList(value) {
     return arrayFlag(value).map((item) => formatStructuredEvidence(item)).filter(Boolean);
 }
 function directRuntimeBackendEvidence(flags) {
-    if (!flags.runtime_backend && !flags.runtime_claim && !flags.runtime_evidence_id && !flags.runtime_command && !flags.runtime_note && !flags.cleanup_checked)
+    if (!flags.runtime_backend && !flags.runtime_claim && !flags.runtime_evidence_id && !flags.runtime_command && !flags.runtime_note && !flags.cleanup_checked && !flags.cleanup_observed && !flags.left_running_intentionally)
         return [];
     return [JSON.stringify(buildRuntimeBackendEvidence({
             backend: flags.runtime_backend,
             claim: flags.runtime_claim,
             evidence_id: flags.runtime_evidence_id,
             command: flags.runtime_command,
+            pid: numberOrNull(flags.runtime_pid),
+            port: numberOrNull(flags.runtime_port),
+            exit_code: numberOrNull(flags.runtime_exit_code),
+            started_at: String(flags.runtime_started_at || ''),
+            stopped_at: String(flags.runtime_stopped_at || ''),
+            cleanup_method: String(flags.runtime_cleanup_method || ''),
+            cleanup_observed: Boolean(flags.cleanup_observed),
+            left_running_intentionally: Boolean(flags.left_running_intentionally),
             cleanup_checked: Boolean(flags.cleanup_checked),
             note: flags.runtime_note
         }))];
@@ -3316,6 +4118,10 @@ async function main() {
         return detectProject(process.argv[3]);
     if (command === 'pack')
         return inspectProjectPack(process.argv[3]);
+    if (command === 'context')
+        return context(process.argv.slice(3));
+    if (command === 'cleanup')
+        return cleanup(process.argv.slice(3));
     if (command === 'budget')
         return budget(process.argv[3]);
     if (command === 'measure')
@@ -3324,6 +4130,8 @@ async function main() {
         return tools(process.argv.slice(3));
     if (command === 'proof')
         return proof(process.argv.slice(3));
+    if (command === 'loop')
+        return loop(process.argv.slice(3));
     if (command === 'ueye')
         return ueye(process.argv.slice(3));
     if (command === 'media')