yam-flow 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to yam-flow are documented here.
 
+## v0.1.8 - 2026-06-16
+
+### Added
+
+- Added `yam loop report [--json]` as a read-only loop artifact for intent, stages, evidence, blockers, next action, remaining tasks, tool intent, truth status, and study note.
+- Added `yam.study-note.v1` so reports can carry short non-specialist explanations of the failing code, its role, observed symptom, changed code, why it matters, and learning note without guessing missing details.
+- Added `publish_readiness` and `study_note` to `yam release report --json` with read-only npm registry/auth/version probes and redacted account/token details.
+- Added Ueye `design_brief` and `anti_slop_review` fields with `--brief-dimension`, `--constraint`, `--anti-slop`, `--invented-metric`, `--placeholder-copy`, and `--generic-visual`.
+
+### Improved
+
+- Ueye anti-slop P0 findings now feed the design completion gate so `done` claims are blocked until fix-first issues are resolved.
+- Release reports now separate publish readiness evidence from the publish action; `npm publish` remains outside the report.
+- CLI smoke coverage now asserts loop report, study note limits, and Ueye design brief/anti-slop blocked paths.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run cli-smoke`
+- `npm run verify:self`
+- `npm run forbidden-names:check`
+- `npm run package-boundary:check`
+- `npm run dist:freshness`
+- `node ./dist/bin/yam.js release report --json` (blocked as expected by npm auth readiness and dirty git)
+- `npm whoami --registry https://registry.npmjs.org/` (E401, confirms auth/token blocker)
+
 ## v0.1.7 - 2026-06-12
 
 ### Added

package/COMMANDS.md

@@ -45,7 +45,7 @@ Opt-in visual evidence helpers:
 yam ueye preflight /path/to/project --json
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --brief-dimension "primary CTA clarity" --constraint "mobile first" --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
@@ -148,6 +148,7 @@ yam tools doctor /path/to/project
 yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
@@ -187,15 +188,19 @@ yam release report --json
 yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-observed --exit-code 0 --cleanup-method "exit observed" --json
 yam mission queue --agent-id reviewer --scope "changed files review" --changed src/bin/yam.ts --verification-hint "npm run typecheck" --json
 yam benchmark report --label "bundle size" --baseline 120 --current 118 --unit kB --target lower --json
+yam loop report --route deep --intent "verify release readiness" --blocked "npm auth not verified" --next-action "refresh npm token, then rerun npm whoami" --json
 ```
 
 Supported report shapes:
 
 - Runtime evidence mini: command/process, observation, cleanup, truth status, next action.
 - Patch queue lite: mission lane status, changed files, verification hint, rollback hint, truth status.
+- Loop report: intent, stage outcomes, evidence, blockers, next action, remaining tasks, and study note.
+- Study note: short non-specialist explanation of the failing code, its role, observed symptom, changed code, and why it matters.
 - Benchmark optimization loop lite: baseline, one change, rerun, keep/revert decision.
 - Structured diagnostic next action: severity, evidence, owner route, next action, truth status.
 - Ueye continuity/comparison: previous report, current report, comparison delta, design quality, next action.
+- Ueye design brief/anti-slop: brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom P0 blockers.
 - Context pressure: project pack age/size, memory summary, dirty scope, scripts, instruction surfaces, and route hint.
 - Cleanup scan: advisory-only list of confusing surfaces with destructive=false.
 

package/README.md

@@ -142,6 +142,7 @@ yam ueye report --reference ./reference.png --actual .yam/screens/home.png --pre
 yam proof --route ueye --truth verified --visual "implementation screenshot evidence recorded" --design-completion '{"completion_claim":"done","has_implementation_screenshot":true,"design_quality":"pass","states_checked":true,"mobile_checked":true,"contrast_checked":true,"cta_checked":true,"direction_locked":true,"truth_status":"verified"}'
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam release report --json
 yam safety "supabase db reset"
 yam detect /path/to/project
@@ -194,10 +195,13 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime evidence mini summaries
 - mission patch queue lite records
 - release report JSON
+- loop report JSON
+- study note JSON
 - structured diagnostic next actions
 - context pressure summaries
 - advisory cleanup scans
 - publish blocker evidence
+- publish readiness evidence
 - change insight reporting
 - reference source boundary notes
 - media generation proof caps
@@ -212,7 +216,10 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Runtime evidence mini: compact route, command/process, observation, cleanup, truth status, and next action fields for `$deep` or `$mission` runtime claims.
 - Patch queue lite: `$mission` lane records with pending/applied/verified/reverted/blocked state, changed files, verification hint, rollback hint, truth status, and next action.
 - Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, and final truth status.
+- Loop report JSON: `yam loop report --json` records a read-only loop artifact: intent, stages, evidence, blockers, next action, remaining tasks, tool intent, truth status, and study note.
+- Study note: `yam.study-note.v1` keeps short non-specialist explanations for what code was failing, what role it plays, how the symptom showed up, what changed, and why it matters. Missing details stay in `limits` instead of being guessed.
 - Publish blocker evidence: release reports classify common npm auth, permission, OTP, immutable-version, cache, registry, and tarball failures into safe next actions.
+- Publish readiness evidence: release reports run read-only registry/auth/version probes, redact account/token details, and keep npm publish outside the report.
 - Context pressure: `yam context pressure` explains when project context is getting stale, broad, or confusing enough to summarize, refresh, narrow scope, or deepen route.
 - Cleanup scan: `yam cleanup scan` is read-only and advisory; it reports confusing hooks, local skill folders, stale traces, or old proof artifacts without deleting anything.
 - Benchmark optimization loop lite: use `yam measure <route>` and `yam template tuning` to record baseline, one route wording change, rerun result, keep/revert decision, and stop condition.
@@ -220,6 +227,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.
 - Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Ueye design completion gate: `$ueye` can stay fast for draft work, but a `done` claim is capped until implementation evidence, comparison/design-quality status, P0/P1 status, key states, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, and direction/reference-read proof are recorded when relevant.
+- Ueye design brief and anti-slop review: `$ueye` reports can record operator-provided brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom anti-slop blockers. P0 anti-slop findings block `done` claims.
 
 ## Ueye Capture And Compare
 
@@ -229,7 +237,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
 yam ueye preflight . --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --brief-dimension "primary CTA clarity" --constraint "mobile first" --anti-slop "placeholder copy remains" --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 `capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.

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);
 }
@@ -122,6 +122,7 @@ Usage:
   yam tools doctor [dir]
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
+  yam 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]
@@ -503,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))
@@ -1531,6 +1534,11 @@ 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)
@@ -1548,6 +1556,9 @@ async function release(args = []) {
         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;
 }
@@ -1566,19 +1577,23 @@ function runReleaseReport() {
     const tarball = releaseTarballProvenance();
     const freshness = releaseFreshness(checks, provenance, tarball);
     const publishBlockerEvidence = publishBlockerEvidenceFromRelease(checks, tarball);
-    const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence);
+    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
     };
@@ -1656,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 = {}, publishBlockers = []) {
+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')
@@ -1675,6 +1814,9 @@ function releaseNextActions(checks = [], provenance = {}, tarball = {}, publishB
     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 = {}) {
@@ -1746,6 +1888,23 @@ 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,
@@ -1777,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 '';
@@ -1791,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')
@@ -1815,7 +2029,7 @@ 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 preflight [dir] [--json]
-  yam ueye report [--reference ref.png] [--actual screenshot.png] [--preflight-id id] [--p0-risk text] [--quality-gate-note text] [--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 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.
@@ -2056,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', 'preflight-id', 'p0-risk', 'quality-gate-note', '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 = [];
@@ -2065,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'),
@@ -2149,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), ...arrayFlag(flags.p0_risk)],
+            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),
@@ -2190,6 +2406,8 @@ 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),
@@ -2206,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)
@@ -2587,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', 'cleanup-observed', 'left-running-intentionally', '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;
         }
@@ -3870,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')

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

@@ -5,6 +5,8 @@ export type EvidenceKind = 'command' | 'evidence' | 'visual' | 'runtime' | 'skip
 export type RuntimeSubsystem = 'real_runtime' | 'tmux_physical' | 'process_cleanup' | 'browser_visual' | 'db_safety';
 export type RuntimeBackend = 'none' | 'in_app_browser' | 'playwright' | 'terminal' | 'tmux' | 'zellij' | 'unknown';
 export type RuntimeClaim = 'not_started' | 'started' | 'observed' | 'stopped' | 'cleanup_verified' | 'blocked' | 'unknown';
+export type LoopStageStatus = 'passed' | 'failed' | 'blocked' | 'skipped' | 'partial' | 'pending' | 'recorded';
+export type ToolIntent = 'read_only' | 'write' | 'destructive' | 'runtime' | 'visual' | 'publish';
 export interface SafetyHit {
     level: SafetyLevel;
     reason: string;
@@ -124,6 +126,44 @@ export interface RuntimeBackendEvidence {
     note: string;
     truth_status: TruthStatus;
 }
+export interface StudyNoteSection {
+    code: string;
+    role: string;
+    symptom?: string;
+    summary?: string;
+    truth_status: TruthStatus;
+}
+export interface StudyNote {
+    schema: 'yam.study-note.v1';
+    problem: StudyNoteSection;
+    change: StudyNoteSection;
+    why_it_matters: string;
+    learning_note: string;
+    limits: string[];
+    truth_status: TruthStatus;
+}
+export interface LoopStage {
+    id: string;
+    status: LoopStageStatus;
+    note: string;
+    truth_status: TruthStatus;
+}
+export interface LoopReport {
+    schema: 'yam.loop-report.v1';
+    generated_at: string;
+    route: string;
+    intent: string;
+    loop_kind: string;
+    stages: LoopStage[];
+    evidence: string[];
+    blockers: string[];
+    truth_status: TruthStatus;
+    intent_label: ToolIntent;
+    tool_intent: ToolIntent;
+    next_action: string;
+    remaining_tasks: string[];
+    study_note: StudyNote;
+}
 export interface UeyeRunReport {
     schema: 'yam.ueye-run-report.v1';
     reference_sources: UeyeVisualProvenance[];
@@ -230,6 +270,8 @@ export declare function buildUeyeDesignCompletionGate(input?: Partial<UeyeDesign
 export declare function buildRollbackHint(input?: Partial<RollbackHint>): RollbackHint;
 export declare function buildMissionPatchEnvelope(input?: Partial<MissionPatchEnvelope>): MissionPatchEnvelope;
 export declare function buildRuntimeBackendEvidence(input?: Partial<RuntimeBackendEvidence>): RuntimeBackendEvidence;
+export declare function buildStudyNote(input?: Partial<StudyNote> & Record<string, unknown>): StudyNote;
+export declare function buildLoopReport(input?: Partial<LoopReport> & Record<string, unknown>): LoopReport;
 export declare function buildUeyeRunReport(input?: UeyeRunReportInput): UeyeRunReport;
 export declare function buildMediaGenerationProof(input?: Partial<MediaGenerationProof>): MediaGenerationProof;
 export declare function isTruthStatus(value?: unknown): value is TruthStatus;