yam-flow 0.1.9 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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
+
+- Extended `yam loop report --json` with guided stage conventions, `evidence_level`, `evidence_stamp`/`source_digest`, `blocked_kind`, `safe_retry`, `owner_scope`, `scope_owner`, and `side_effects` so the report can act as a clearer handoff artifact without adding a new command.
+- Updated loop report smoke coverage to assert the new handoff fields.
+
+### Improved
+
+- Updated README, COMMANDS, final-report guidance, implementation skill final-response rules, and manifest principles to prefer fix-first handoff with evidence level, blocker kind, safe retry, and owner/scope clarity.
+
 ## v0.1.9 - 2026-06-18
 
 ### 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" --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 --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"
@@ -195,7 +195,7 @@ 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, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route, and study note.
+- Loop report: intent, guided stage outcomes, evidence level/stamp, blockers, blocker kind, safe retry, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route/scope, side effects, 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.

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" --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 --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: intent, stages, evidence, blockers, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, owner route, 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

@@ -524,6 +524,12 @@ function normalizeToolIntent(value = '') {
         return text;
     return 'read_only';
 }
+function normalizeLoopEvidenceLevelFlag(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['fixture', 'smoke', 'local', 'real'].includes(text))
+        return text;
+    return 'none';
+}
 function uniqueNextActionDetails(actions = []) {
     const seen = new Set();
     const unique = [];
@@ -1580,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,
@@ -1593,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']);
@@ -1973,24 +2022,34 @@ 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] [--blocked text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--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', 'evidence', 'blocked', 'blocker', 'next-action', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', '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 || ''),
         intent: String(flags.intent || ''),
         loop_kind: String(flags.loop_kind || flags.route || 'harness'),
+        stage_conventions: arrayFlag(flags.stage_convention),
         stages: arrayFlag(flags.stage),
         evidence: arrayFlag(flags.evidence),
+        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 || ''),
@@ -1998,6 +2057,10 @@ async function loopReport(args = []) {
         why_this_next: String(flags.why_this_next || ''),
         blocked_by: arrayFlag(flags.blocked_by),
         owner_route: String(flags.owner_route || flags.route || ''),
+        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

@@ -6,6 +6,7 @@ export type RuntimeSubsystem = 'real_runtime' | 'tmux_physical' | 'process_clean
 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 LoopEvidenceLevel = 'none' | 'fixture' | 'smoke' | 'local' | 'real';
 export type ToolIntent = 'read_only' | 'write' | 'destructive' | 'runtime' | 'visual' | 'publish';
 export interface SafetyHit {
     level: SafetyLevel;
@@ -154,13 +155,23 @@ export interface LoopReport {
     route: string;
     intent: string;
     loop_kind: string;
+    stage_conventions: string[];
     stages: LoopStage[];
     evidence: string[];
+    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;
@@ -168,6 +179,10 @@ export interface LoopReport {
     why_this_next: string;
     blocked_by: string[];
     owner_route: string;
+    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,10 +236,20 @@ 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 || (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 || uncoveredRequirements.length);
     const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
-    const derivedTruth = blockers.length || hasBlockedStage ? 'blocked'
+    const derivedTruth = hasBlockerSignal || hasBlockedStage ? 'blocked'
         : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
             : evidence.length || stages.length ? 'partial'
                 : 'assumed';
@@ -252,20 +262,36 @@ export function buildLoopReport(input = {}) {
         route: String(input.route || ''),
         intent: shortText(input.intent),
         loop_kind: String(input.loop_kind || 'harness'),
+        stage_conventions: asList(input.stage_conventions || input.stage_convention).length
+            ? asList(input.stage_conventions || input.stage_convention)
+            : ['brief', 'plan', 'implement', 'critique', 'verify', 'handoff'],
         stages,
         evidence,
+        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 || (blockers[0] ? '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),
         implementation_notes: asList(input.implementation_notes || input.implementation_note),
         why_this_next: shortText(input.why_this_next),
-        blocked_by: asList(input.blocked_by),
+        blocked_by: blockedBy,
         owner_route: normalizeOwnerRoute(input.owner_route || input.route),
+        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
     };
 }
@@ -400,6 +426,12 @@ function normalizeOwnerRoute(value = '') {
         return `$${text}`;
     return text ? shortText(text, 80) : '';
 }
+function normalizeLoopEvidenceLevel(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['fixture', 'smoke', 'local', 'real'].includes(text))
+        return text;
+    return 'none';
+}
 function shortText(value = '', limit = 240) {
     const text = String(value || '').trim().replace(/\s+/g, ' ');
     if (text.length <= limit)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.9",
+  "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,8 +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, 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`, and `owner_route`.
+`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/skills/deep/SKILL.md

@@ -74,4 +74,4 @@ Include:
 - Evidence gathered.
 - Truth status.
 - Blockers or remaining risk.
-- Handoff: fix-first items, remaining tasks, recommended direction, and why that next step matters.
+- Handoff: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, side effects, and owner scope when another route or person may continue.

package/skills/mission/SKILL.md

@@ -106,4 +106,4 @@ Report:
 - Evidence gathered.
 - Truth status.
 - Cleanup status.
-- Handoff: fix-first items, remaining tasks, recommended direction, and why that next step matters.
+- Handoff: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, side effects, and owner scope when another route or person may continue.

package/skills/quick/SKILL.md

@@ -79,4 +79,4 @@ Keep it compact:
 - Study Note when useful: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
 - What was checked.
 - What was skipped, blocked, or still risky.
-- Handoff when useful: fix-first items, remaining tasks, recommended direction, and why that next step matters.
+- Handoff when useful: fix-first items, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.

package/skills/ueye/SKILL.md

@@ -172,4 +172,4 @@ Report:
 - States/viewports checked.
 - Study Note when UI implementation changed code: what UI code changed, what role it has, how the visible symptom appeared, and why the change matters in short non-specialist language.
 - Truth status and visual verification cap.
-- Handoff when useful: fix-first visual issues, remaining tasks, recommended direction, and why that next step matters.
+- Handoff when useful: fix-first visual issues, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.

package/src/bin/yam.ts

@@ -24,7 +24,7 @@ import {
   detectDbSafetyText as detectTrustDbSafetyText,
   isTruthStatus
 } from '../lib/trust-kernel.js';
-import type { ToolIntent } from '../lib/trust-kernel.js';
+import type { LoopEvidenceLevel, ToolIntent } from '../lib/trust-kernel.js';
 
 type AnyRecord = Record<string, any>;
 
@@ -525,6 +525,12 @@ function normalizeToolIntent(value = ''): ToolIntent {
   return 'read_only';
 }
 
+function normalizeLoopEvidenceLevelFlag(value = ''): LoopEvidenceLevel {
+  const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+  if (['fixture', 'smoke', 'local', 'real'].includes(text)) return text as LoopEvidenceLevel;
+  return 'none';
+}
+
 function uniqueNextActionDetails(actions = []) {
   const seen = new Set<string>();
   const unique = [];
@@ -1569,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,
@@ -1582,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']);
@@ -1971,24 +2021,34 @@ 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] [--blocked text] [--fix-first-item text] [--remaining-task text] [--recommended-direction text] [--implementation-note text] [--why-this-next text] [--blocked-by text] [--owner-route route] [--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', 'evidence', 'blocked', 'blocker', 'next-action', 'fix-first-item', 'remaining-task', 'recommended-direction', 'direction', 'implementation-note', 'why-this-next', 'blocked-by', 'owner-route', '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 || ''),
     intent: String(flags.intent || ''),
     loop_kind: String(flags.loop_kind || flags.route || 'harness'),
+    stage_conventions: arrayFlag(flags.stage_convention),
     stages: arrayFlag(flags.stage),
     evidence: arrayFlag(flags.evidence),
+    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 || ''),
@@ -1996,6 +2056,10 @@ async function loopReport(args = []) {
     why_this_next: String(flags.why_this_next || ''),
     blocked_by: arrayFlag(flags.blocked_by),
     owner_route: String(flags.owner_route || flags.route || ''),
+    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

@@ -18,6 +18,7 @@ export type RuntimeSubsystem = 'real_runtime' | 'tmux_physical' | 'process_clean
 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 LoopEvidenceLevel = 'none' | 'fixture' | 'smoke' | 'local' | 'real';
 export type ToolIntent = 'read_only' | 'write' | 'destructive' | 'runtime' | 'visual' | 'publish';
 
 export interface SafetyHit {
@@ -182,13 +183,23 @@ export interface LoopReport {
   route: string;
   intent: string;
   loop_kind: string;
+  stage_conventions: string[];
   stages: LoopStage[];
   evidence: string[];
+  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;
@@ -196,6 +207,10 @@ export interface LoopReport {
   why_this_next: string;
   blocked_by: string[];
   owner_route: string;
+  owner_scope: string[];
+  scope_owner: string;
+  side_effects: string[];
+  avoidance_note: string;
   study_note: StudyNote;
 }
 
@@ -540,10 +555,20 @@ 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 || (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 || uncoveredRequirements.length);
   const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
-  const derivedTruth: TruthStatus = blockers.length || hasBlockedStage ? 'blocked'
+  const derivedTruth: TruthStatus = hasBlockerSignal || hasBlockedStage ? 'blocked'
     : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
       : evidence.length || stages.length ? 'partial'
         : 'assumed';
@@ -556,20 +581,36 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     route: String(input.route || ''),
     intent: shortText(input.intent),
     loop_kind: String(input.loop_kind || 'harness'),
+    stage_conventions: asList(input.stage_conventions || input.stage_convention).length
+      ? asList(input.stage_conventions || input.stage_convention)
+      : ['brief', 'plan', 'implement', 'critique', 'verify', 'handoff'],
     stages,
     evidence,
+    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 || (blockers[0] ? '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),
     implementation_notes: asList(input.implementation_notes || input.implementation_note),
     why_this_next: shortText(input.why_this_next),
-    blocked_by: asList(input.blocked_by),
+    blocked_by: blockedBy,
     owner_route: normalizeOwnerRoute(input.owner_route || input.route),
+    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
   };
 }
@@ -694,6 +735,12 @@ function normalizeOwnerRoute(value: unknown = ''): string {
   return text ? shortText(text, 80) : '';
 }
 
+function normalizeLoopEvidenceLevel(value: unknown = ''): LoopEvidenceLevel {
+  const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+  if (['fixture', 'smoke', 'local', 'real'].includes(text)) return text as LoopEvidenceLevel;
+  return 'none';
+}
+
 function shortText(value: unknown = '', limit = 240): string {
   const text = String(value || '').trim().replace(/\s+/g, ' ');
   if (text.length <= limit) return text;

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "0.1.9",
+  "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, and recommended next direction 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": [