yam-flow 1.9.1 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.0.0 - 2026-06-24
+
+### Added
+
+- Extended `yam loop report --json` with lightweight requirement coverage, `failure_cause`, `recovery_hint`, and `avoidance_note` so handoff artifacts can show what must still be covered before a completion claim.
+- Added `readiness_receipt` to `yam release report --json` to summarize the read-only evidence basis for package/version, registry, auth, git, dist, tarball, and release-check readiness.
+
+### Improved
+
+- Uncovered loop requirements now block verified truth, default `blocked_kind` to `requirement_uncovered`, and point the default next action at the first uncovered requirement.
+- Documented that loop avoidance notes are report-only; durable learning remains explicit through `yam memory add`.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run cli-smoke`
+- `npm run verify:self`
+- `node ./dist/bin/yam.js loop report --json` with uncovered requirement truth blocking
+- `node ./dist/bin/yam.js release report --json` (blocked as expected by npm auth readiness and dirty git, with `readiness_receipt`)
+
 ## v1.9.1 - 2026-06-19
 
 ### Added

package/COMMANDS.md

@@ -148,7 +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" --evidence-level local --evidence-stamp "sha256:release-report" --blocked-kind auth_blocked --safe-retry "retry after npm whoami succeeds" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --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 loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --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"

package/README.md

@@ -142,7 +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" --evidence-level local --evidence-stamp "sha256:release-report" --blocked-kind auth_blocked --safe-retry "retry after npm whoami succeeds" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --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 loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --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
@@ -215,11 +215,12 @@ 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 handoff artifact: guided stages, evidence level/stamp, blocker kind, safe retry, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, tool intent, truth status, and study note.
+- Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, readiness receipt, and final truth status.
+- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, 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.
+- Avoidance note: loop reports may include one short mistake-to-avoid note, but durable memory stays explicit through `yam memory add`; `yam loop report` does not write `.yam/memory`.
 - 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.
+- Publish readiness evidence: release reports run read-only registry/auth/version probes, redact account/token details, keep npm publish outside the report, and include a `yam.release-readiness-receipt.v1` basis for the readiness judgment.
 - 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.

package/dist/bin/yam.js

@@ -1586,6 +1586,7 @@ function runReleaseReport() {
     const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
     const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
     const ok = failed.length === 0 && publishReadiness.status === 'ready';
+    const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, ok);
     return {
         schema: 'yam.release-report.v1',
         generated_at: startedAt,
@@ -1599,11 +1600,53 @@ function runReleaseReport() {
         tarball,
         freshness,
         publish_readiness: publishReadiness,
+        readiness_receipt: readinessReceipt,
         study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
         publishBlockerEvidence,
         next_actions: nextActions
     };
 }
+function releaseReadinessReceipt(provenance = {}, freshness = {}, tarball = {}, publishReadiness = {}, ok = false) {
+    return {
+        schema: 'yam.release-readiness-receipt.v1',
+        generated_at: new Date().toISOString(),
+        package_name: PACKAGE_JSON.name,
+        local_version: VERSION,
+        registry: {
+            url: String(publishReadiness.registry?.url || ''),
+            latest_version: String(publishReadiness.registry?.latest_version || ''),
+            version_status: String(publishReadiness.registry?.version_status || 'not_verified'),
+            truth_status: publishReadiness.registry?.truth_status || 'partial'
+        },
+        auth: {
+            command: 'npm whoami',
+            status: String(publishReadiness.auth?.status || 'not_verified'),
+            account: publishReadiness.auth?.status === 'authenticated' ? 'observed_redacted' : '',
+            truth_status: publishReadiness.auth?.truth_status || 'partial'
+        },
+        git: {
+            commit: String(provenance.git_commit || ''),
+            dirty: Boolean(provenance.git_dirty),
+            dirty_lines_observed: Array.isArray(provenance.git_status_lines) ? provenance.git_status_lines.length : 0,
+            truth_status: provenance.truth_status || 'partial'
+        },
+        checks: {
+            dist: freshness.dist || 'not-verified',
+            package_boundary: freshness.package_boundary || 'not-verified',
+            cli_smoke: freshness.cli_smoke || 'not-verified',
+            tarball: tarball.status === 'checked' ? 'checked' : 'not-verified'
+        },
+        tarball: {
+            status: String(tarball.status || 'not-verified'),
+            name: String(tarball.tarball_name || ''),
+            integrity_present: Boolean(tarball.integrity),
+            shasum_present: Boolean(tarball.shasum),
+            truth_status: tarball.truth_status || 'partial'
+        },
+        publish_attempted: false,
+        truth_status: ok ? 'verified' : 'blocked'
+    };
+}
 function releaseProvenance(checks = []) {
     const gitCommit = runReadOnlyCommand('git', ['rev-parse', '--short', 'HEAD']);
     const gitStatus = runReadOnlyCommand('git', ['status', '--short']);
@@ -1979,13 +2022,13 @@ function loopUsage() {
 Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, next action, handoff fields, and a short study note. It does not run agents, start processes, publish packages, or write files.
 
 Usage:
-  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--blocked text] [--blocked-kind text] [--safe-retry text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
+  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
 `);
 }
 async function loopReport(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return loopUsage();
-    const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'blocked', 'blocker', 'blocked-kind', 'next-action', 'safe-retry', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
+    const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
     const blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
     const report = buildLoopReport({
         route: normalizeRoute(flags.route) || String(flags.route || ''),
@@ -1997,12 +2040,16 @@ async function loopReport(args = []) {
         evidence_level: normalizeLoopEvidenceLevelFlag(flags.evidence_level),
         evidence_stamp: String(flags.evidence_stamp || ''),
         source_digest: String(flags.source_digest || ''),
+        covered_requirements: arrayFlag(flags.covered_requirement),
+        uncovered_requirements: arrayFlag(flags.uncovered_requirement),
         blockers,
         blocked_kind: String(flags.blocked_kind || ''),
+        failure_cause: String(flags.failure_cause || ''),
         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 || ''),
         safe_retry: String(flags.safe_retry || ''),
+        recovery_hint: String(flags.recovery_hint || ''),
         fix_first_items: arrayFlag(flags.fix_first_item),
         remaining_tasks: arrayFlag(flags.remaining_task),
         recommended_direction: String(flags.recommended_direction || flags.direction || ''),
@@ -2013,6 +2060,7 @@ async function loopReport(args = []) {
         owner_scope: [...arrayFlag(flags.owner_scope), ...arrayFlag(flags.scope)],
         scope_owner: String(flags.scope_owner || flags.owner || ''),
         side_effects: arrayFlag(flags.side_effect),
+        avoidance_note: String(flags.avoidance_note || ''),
         issue_code: String(flags.issue_code || ''),
         issue_role: String(flags.issue_role || ''),
         issue_symptom: String(flags.issue_symptom || ''),

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

@@ -161,13 +161,17 @@ export interface LoopReport {
     evidence_level: LoopEvidenceLevel;
     evidence_stamp: string;
     source_digest: string;
+    covered_requirements: string[];
+    uncovered_requirements: string[];
     blockers: string[];
     blocked_kind: string;
+    failure_cause: string;
     truth_status: TruthStatus;
     intent_label: ToolIntent;
     tool_intent: ToolIntent;
     next_action: string;
     safe_retry: string;
+    recovery_hint: string;
     fix_first_items: string[];
     remaining_tasks: string[];
     recommended_direction: string;
@@ -178,6 +182,7 @@ export interface LoopReport {
     owner_scope: string[];
     scope_owner: string;
     side_effects: string[];
+    avoidance_note: string;
     study_note: StudyNote;
 }
 export interface UeyeRunReport {

package/dist/lib/trust-kernel.js

@@ -236,13 +236,18 @@ export function buildLoopReport(input = {}) {
         ? input.stages.map((stage) => buildLoopStage(stage))
         : [];
     const evidence = asList(input.evidence);
+    const coveredRequirements = asList(input.covered_requirements || input.covered_requirement);
+    const uncoveredRequirements = asList(input.uncovered_requirements || input.uncovered_requirement);
     const blockers = asList(input.blockers || input.blocked);
     const blockedBy = asList(input.blocked_by);
-    const blockedKind = shortText(input.blocked_kind || (blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+    const blockedKind = shortText(input.blocked_kind || (uncoveredRequirements.length ? 'requirement_uncovered' : blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+    const failureCause = shortText(input.failure_cause);
+    const recoveryHint = shortText(input.recovery_hint);
+    const avoidanceNote = shortText(input.avoidance_note);
     const evidenceStamp = shortText(input.evidence_stamp || input.source_digest, 320);
     const sourceDigest = shortText(input.source_digest || input.evidence_stamp, 320);
     const hasBlockedStage = stages.some((stage) => stage.status === 'blocked' || stage.status === 'failed');
-    const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind);
+    const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length);
     const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
     const derivedTruth = hasBlockerSignal || hasBlockedStage ? 'blocked'
         : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
@@ -265,13 +270,17 @@ export function buildLoopReport(input = {}) {
         evidence_level: normalizeLoopEvidenceLevel(input.evidence_level),
         evidence_stamp: evidenceStamp,
         source_digest: sourceDigest,
+        covered_requirements: coveredRequirements,
+        uncovered_requirements: uncoveredRequirements,
         blockers,
         blocked_kind: blockedKind,
+        failure_cause: failureCause,
         truth_status: truth,
         intent_label: intentLabel,
         tool_intent: intentLabel,
-        next_action: shortText(input.next_action || (hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
+        next_action: shortText(input.next_action || (uncoveredRequirements.length ? `cover requirement before claiming complete: ${uncoveredRequirements[0]}` : hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
         safe_retry: shortText(input.safe_retry || (hasBlockerSignal ? 'retry only after the blocker is resolved and new evidence is recorded' : 'not required')),
+        recovery_hint: recoveryHint,
         fix_first_items: asList(input.fix_first_items || input.fix_first_item),
         remaining_tasks: asList(input.remaining_tasks || input.remaining_task),
         recommended_direction: shortText(input.recommended_direction || input.direction),
@@ -282,6 +291,7 @@ export function buildLoopReport(input = {}) {
         owner_scope: asList(input.owner_scope || input.scope),
         scope_owner: normalizeOwnerRoute(input.scope_owner || input.owner),
         side_effects: asList(input.side_effects || input.side_effect),
+        avoidance_note: avoidanceNote,
         study_note: studyNote
     };
 }

package/package.json

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

package/references/final-report.md

@@ -77,11 +77,13 @@ Use this when the next run needs a clear starting point:
 - Recommended direction.
 - Why this next step matters.
 - What is blocked, and by what.
+- Covered and uncovered requirements when the next run could otherwise overclaim completion.
 - Evidence level or stamp when the handoff relies on a specific command, file, or report.
-- Blocker kind and safe retry when the next run should not blindly repeat the same action.
+- Blocker kind, failure cause, recovery hint, and safe retry when the next run should not blindly repeat the same action.
+- Avoidance note when a repeated mistake should be easy to spot; durable memory still uses explicit `yam memory add`.
 - Owner route, scope owner, and side effects when more than one person or route may continue the work.
 
-`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `blocked_kind`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, and `side_effects`.
+`yam loop report` can record this as a handoff artifact with `fix_first_items`, `remaining_tasks`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, `covered_requirements`, `uncovered_requirements`, `blocked_kind`, `failure_cause`, `recovery_hint`, `safe_retry`, `evidence_level`, `evidence_stamp`, `owner_route`, `owner_scope`, `scope_owner`, `side_effects`, and `avoidance_note`.
 
 ## Route Weight
 

package/src/bin/yam.ts

@@ -1575,6 +1575,7 @@ function runReleaseReport() {
   const publishReadiness = releasePublishReadiness(checks, provenance, tarball, publishBlockerEvidence);
   const nextActions = releaseNextActions(checks, provenance, tarball, publishBlockerEvidence, publishReadiness);
   const ok = failed.length === 0 && publishReadiness.status === 'ready';
+  const readinessReceipt = releaseReadinessReceipt(provenance, freshness, tarball, publishReadiness, ok);
   return {
     schema: 'yam.release-report.v1',
     generated_at: startedAt,
@@ -1588,12 +1589,55 @@ function runReleaseReport() {
     tarball,
     freshness,
     publish_readiness: publishReadiness,
+    readiness_receipt: readinessReceipt,
     study_note: releaseStudyNote(publishReadiness, publishBlockerEvidence),
     publishBlockerEvidence,
     next_actions: nextActions
   };
 }
 
+function releaseReadinessReceipt(provenance: AnyRecord = {}, freshness: AnyRecord = {}, tarball: AnyRecord = {}, publishReadiness: AnyRecord = {}, ok = false) {
+  return {
+    schema: 'yam.release-readiness-receipt.v1',
+    generated_at: new Date().toISOString(),
+    package_name: PACKAGE_JSON.name,
+    local_version: VERSION,
+    registry: {
+      url: String(publishReadiness.registry?.url || ''),
+      latest_version: String(publishReadiness.registry?.latest_version || ''),
+      version_status: String(publishReadiness.registry?.version_status || 'not_verified'),
+      truth_status: publishReadiness.registry?.truth_status || 'partial'
+    },
+    auth: {
+      command: 'npm whoami',
+      status: String(publishReadiness.auth?.status || 'not_verified'),
+      account: publishReadiness.auth?.status === 'authenticated' ? 'observed_redacted' : '',
+      truth_status: publishReadiness.auth?.truth_status || 'partial'
+    },
+    git: {
+      commit: String(provenance.git_commit || ''),
+      dirty: Boolean(provenance.git_dirty),
+      dirty_lines_observed: Array.isArray(provenance.git_status_lines) ? provenance.git_status_lines.length : 0,
+      truth_status: provenance.truth_status || 'partial'
+    },
+    checks: {
+      dist: freshness.dist || 'not-verified',
+      package_boundary: freshness.package_boundary || 'not-verified',
+      cli_smoke: freshness.cli_smoke || 'not-verified',
+      tarball: tarball.status === 'checked' ? 'checked' : 'not-verified'
+    },
+    tarball: {
+      status: String(tarball.status || 'not-verified'),
+      name: String(tarball.tarball_name || ''),
+      integrity_present: Boolean(tarball.integrity),
+      shasum_present: Boolean(tarball.shasum),
+      truth_status: tarball.truth_status || 'partial'
+    },
+    publish_attempted: false,
+    truth_status: ok ? 'verified' : 'blocked'
+  };
+}
+
 function releaseProvenance(checks = []) {
   const gitCommit = runReadOnlyCommand('git', ['rev-parse', '--short', 'HEAD']);
   const gitStatus = runReadOnlyCommand('git', ['status', '--short']);
@@ -1977,13 +2021,13 @@ function loopUsage() {
 Read-only loop artifact helpers. A loop report records intent, stages, evidence, blockers, next action, handoff fields, and a short study note. It does not run agents, start processes, publish packages, or write files.
 
 Usage:
-  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--blocked text] [--blocked-kind text] [--safe-retry text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
+  yam loop report [--route route] [--intent text] [--loop-kind harness|release|ueye|scout|deep|mission] [--stage id:status:note] [--evidence text] [--evidence-level none|fixture|smoke|local|real] [--evidence-stamp text] [--source-digest text] [--covered-requirement text] [--uncovered-requirement text] [--blocked text] [--blocked-kind text] [--failure-cause text] [--safe-retry text] [--recovery-hint text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--owner-scope text] [--scope-owner text] [--side-effect text] [--avoidance-note text] [--truth status] [--intent-label read_only|write|destructive|runtime|visual|publish] [--issue-code text] [--issue-role text] [--issue-symptom text] [--changed-code text] [--changed-role text] [--change-summary text] [--why-important text] [--learning-note text] [--json]
 `);
 }
 
 async function loopReport(args = []) {
   if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') return loopUsage();
-  const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'blocked', 'blocker', 'blocked-kind', 'next-action', 'safe-retry', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
+  const flags = parseSimpleFlags(args, new Set(['route', 'intent', 'loop-kind', 'stage', 'stage-convention', 'evidence', 'evidence-level', 'evidence-stamp', 'source-digest', 'covered-requirement', 'uncovered-requirement', 'blocked', 'blocker', 'blocked-kind', 'failure-cause', 'next-action', 'safe-retry', 'recovery-hint', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', 'owner-scope', 'scope-owner', 'owner', 'scope', 'side-effect', 'avoidance-note', 'truth', 'intent-label', 'tool-intent', 'issue-code', 'issue-role', 'issue-symptom', 'changed-code', 'changed-role', 'change-summary', 'why-important', 'learning-note', 'json']));
   const blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
   const report = buildLoopReport({
     route: normalizeRoute(flags.route) || String(flags.route || ''),
@@ -1995,12 +2039,16 @@ async function loopReport(args = []) {
     evidence_level: normalizeLoopEvidenceLevelFlag(flags.evidence_level),
     evidence_stamp: String(flags.evidence_stamp || ''),
     source_digest: String(flags.source_digest || ''),
+    covered_requirements: arrayFlag(flags.covered_requirement),
+    uncovered_requirements: arrayFlag(flags.uncovered_requirement),
     blockers,
     blocked_kind: String(flags.blocked_kind || ''),
+    failure_cause: String(flags.failure_cause || ''),
     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 || ''),
     safe_retry: String(flags.safe_retry || ''),
+    recovery_hint: String(flags.recovery_hint || ''),
     fix_first_items: arrayFlag(flags.fix_first_item),
     remaining_tasks: arrayFlag(flags.remaining_task),
     recommended_direction: String(flags.recommended_direction || flags.direction || ''),
@@ -2011,6 +2059,7 @@ async function loopReport(args = []) {
     owner_scope: [...arrayFlag(flags.owner_scope), ...arrayFlag(flags.scope)],
     scope_owner: String(flags.scope_owner || flags.owner || ''),
     side_effects: arrayFlag(flags.side_effect),
+    avoidance_note: String(flags.avoidance_note || ''),
     issue_code: String(flags.issue_code || ''),
     issue_role: String(flags.issue_role || ''),
     issue_symptom: String(flags.issue_symptom || ''),

package/src/lib/trust-kernel.ts

@@ -189,13 +189,17 @@ export interface LoopReport {
   evidence_level: LoopEvidenceLevel;
   evidence_stamp: string;
   source_digest: string;
+  covered_requirements: string[];
+  uncovered_requirements: string[];
   blockers: string[];
   blocked_kind: string;
+  failure_cause: string;
   truth_status: TruthStatus;
   intent_label: ToolIntent;
   tool_intent: ToolIntent;
   next_action: string;
   safe_retry: string;
+  recovery_hint: string;
   fix_first_items: string[];
   remaining_tasks: string[];
   recommended_direction: string;
@@ -206,6 +210,7 @@ export interface LoopReport {
   owner_scope: string[];
   scope_owner: string;
   side_effects: string[];
+  avoidance_note: string;
   study_note: StudyNote;
 }
 
@@ -550,13 +555,18 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     ? input.stages.map((stage) => buildLoopStage(stage))
     : [];
   const evidence = asList(input.evidence);
+  const coveredRequirements = asList(input.covered_requirements || input.covered_requirement);
+  const uncoveredRequirements = asList(input.uncovered_requirements || input.uncovered_requirement);
   const blockers = asList(input.blockers || input.blocked);
   const blockedBy = asList(input.blocked_by);
-  const blockedKind = shortText(input.blocked_kind || (blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+  const blockedKind = shortText(input.blocked_kind || (uncoveredRequirements.length ? 'requirement_uncovered' : blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+  const failureCause = shortText(input.failure_cause);
+  const recoveryHint = shortText(input.recovery_hint);
+  const avoidanceNote = shortText(input.avoidance_note);
   const evidenceStamp = shortText(input.evidence_stamp || input.source_digest, 320);
   const sourceDigest = shortText(input.source_digest || input.evidence_stamp, 320);
   const hasBlockedStage = stages.some((stage) => stage.status === 'blocked' || stage.status === 'failed');
-  const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind);
+  const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length);
   const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
   const derivedTruth: TruthStatus = hasBlockerSignal || hasBlockedStage ? 'blocked'
     : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
@@ -579,13 +589,17 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     evidence_level: normalizeLoopEvidenceLevel(input.evidence_level),
     evidence_stamp: evidenceStamp,
     source_digest: sourceDigest,
+    covered_requirements: coveredRequirements,
+    uncovered_requirements: uncoveredRequirements,
     blockers,
     blocked_kind: blockedKind,
+    failure_cause: failureCause,
     truth_status: truth,
     intent_label: intentLabel,
     tool_intent: intentLabel,
-    next_action: shortText(input.next_action || (hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
+    next_action: shortText(input.next_action || (uncoveredRequirements.length ? `cover requirement before claiming complete: ${uncoveredRequirements[0]}` : hasBlockerSignal ? 'resolve the blocker before claiming this loop complete' : 'record the next smallest useful action')),
     safe_retry: shortText(input.safe_retry || (hasBlockerSignal ? 'retry only after the blocker is resolved and new evidence is recorded' : 'not required')),
+    recovery_hint: recoveryHint,
     fix_first_items: asList(input.fix_first_items || input.fix_first_item),
     remaining_tasks: asList(input.remaining_tasks || input.remaining_task),
     recommended_direction: shortText(input.recommended_direction || input.direction),
@@ -596,6 +610,7 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     owner_scope: asList(input.owner_scope || input.scope),
     scope_owner: normalizeOwnerRoute(input.scope_owner || input.owner),
     side_effects: asList(input.side_effects || input.side_effect),
+    avoidance_note: avoidanceNote,
     study_note: studyNote
   };
 }

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "1.9.1",
+  "version": "2.0.0",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -12,7 +12,7 @@
     "Context-reuse first.",
     "End with remaining tasks and fix-first items.",
     "Explain what failed, what changed, and why it matters in short non-specialist language when useful.",
-    "Use handoff notes for fix-first items, remaining tasks, recommended next direction, blocker kind, safe retry, evidence level, and owner scope when useful."
+    "Use handoff notes for fix-first items, remaining tasks, recommended next direction, requirement coverage, blocker kind, failure cause, recovery hint, safe retry, evidence level, and owner scope when useful."
   ],
   "defaultHooks": false,
   "routes": [