yam-flow 0.1.8 → 1.9.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to yam-flow are documented here.
 
+## 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
+
+- Expanded `yam loop report --json` into a read-only handoff artifact with `fix_first_items`, `recommended_direction`, `implementation_notes`, `why_this_next`, `blocked_by`, and `owner_route`.
+- Added loop report smoke coverage for the new handoff fields while keeping the existing minimal and blocked report paths.
+
+### Improved
+
+- Updated `$quick`, `$deep`, `$mission`, and `$ueye` final response guidance so implementation work can include Study Note and handoff habits without forcing a CLI artifact for ordinary work.
+- Updated `references/final-report.md`, README, COMMANDS, and manifest principles to treat Study Note and handoff direction as final-report practices.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run build`
+- `node ./dist/bin/yam.js loop report --json` with handoff fields
+- `npm run cli-smoke`
+- `npm run verify:self`
+- `npm run forbidden-names:check`
+- `npm run package-boundary:check`
+- `npm run dist:freshness`
+
 ## v0.1.8 - 2026-06-16
 
 ### 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" --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" --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 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, remaining tasks, 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" --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" --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 release report --json
 yam safety "supabase db reset"
 yam detect /path/to/project
@@ -216,7 +216,7 @@ 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.
+- 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.
 - 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.

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 = [];
@@ -1970,28 +1976,43 @@ async function loop(args = []) {
 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.
+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] [--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]
+  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]
 `);
 }
 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 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 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 || ''),
         blockers,
+        blocked_kind: String(flags.blocked_kind || ''),
         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 || ''),
+        fix_first_items: arrayFlag(flags.fix_first_item),
         remaining_tasks: arrayFlag(flags.remaining_task),
+        recommended_direction: String(flags.recommended_direction || flags.direction || ''),
+        implementation_notes: arrayFlag(flags.implementation_note),
+        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),
         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,14 +155,29 @@ 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;
     blockers: string[];
+    blocked_kind: string;
     truth_status: TruthStatus;
     intent_label: ToolIntent;
     tool_intent: ToolIntent;
     next_action: string;
+    safe_retry: string;
+    fix_first_items: string[];
     remaining_tasks: string[];
+    recommended_direction: string;
+    implementation_notes: string[];
+    why_this_next: string;
+    blocked_by: string[];
+    owner_route: string;
+    owner_scope: string[];
+    scope_owner: string;
+    side_effects: string[];
     study_note: StudyNote;
 }
 export interface UeyeRunReport {

package/dist/lib/trust-kernel.js

@@ -237,9 +237,14 @@ export function buildLoopReport(input = {}) {
         : [];
     const evidence = asList(input.evidence);
     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 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 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,14 +257,31 @@ 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,
         blockers,
+        blocked_kind: blockedKind,
         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 || (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')),
+        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: 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),
         study_note: studyNote
     };
 }
@@ -388,6 +410,18 @@ function normalizeToolIntentLabel(value = '') {
         return text;
     return 'read_only';
 }
+function normalizeOwnerRoute(value = '') {
+    const text = String(value || '').trim().replace(/^\$/, '').replace(/^yam-/, '');
+    if (['quick', 'ueye', 'question', 'scout', 'deep', 'mission'].includes(text))
+        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.8",
+  "version": "1.9.1",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/final-report.md

@@ -16,8 +16,10 @@ Include these when they are useful and keep them short:
 - Context pressure or cleanup findings when they could affect the next run.
 - Publish blocker evidence when npm/release work fails.
 - Structured diagnostic next action, when a check found a concrete next step.
+- Study Note for implementation work: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
 - Remaining tasks.
 - Fix-first items before planned tasks.
+- Recommended direction and why that next step matters when the handoff would otherwise be ambiguous.
 
 ## Anti-False-Completion Check
 
@@ -54,6 +56,33 @@ Examples:
 - Active hooks or instruction files that conflict with the route.
 - Warnings that keep obscuring real problems.
 
+## Study Note
+
+Use this when implementation changed code or fixed an error and the user would benefit from learning:
+
+- What code had the issue.
+- What role that code plays.
+- How the issue showed up.
+- What changed.
+- Why the change matters.
+
+Keep it short. If the information is not known, say so instead of inventing it.
+
+## Handoff Direction
+
+Use this when the next run needs a clear starting point:
+
+- Fix-first items before planned work.
+- Remaining tasks that still belong to the request or roadmap.
+- Recommended direction.
+- Why this next step matters.
+- What is blocked, and by what.
+- 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.
+- 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`.
+
 ## Route Weight
 
 For `$quick`, one short paragraph or a compact verification matrix is enough.

package/skills/deep/SKILL.md

@@ -70,8 +70,8 @@ Deep verification may include:
 Include:
 
 - What was changed or reviewed.
+- Study Note for implementation work: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
 - Evidence gathered.
 - Truth status.
 - Blockers or remaining risk.
-- Remaining tasks.
-- Fix-first items before planned tasks.
+- 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

@@ -102,8 +102,8 @@ Report:
 
 - What the mission changed.
 - Role/cross-verification summary.
+- Study Note for implementation lanes: what code was wrong, what role it has, how the symptom showed up, what changed, and why it matters in short non-specialist language.
 - Evidence gathered.
 - Truth status.
 - Cleanup status.
-- Remaining tasks.
-- Fix-first items before planned tasks.
+- 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

@@ -76,6 +76,7 @@ Use `references/token-budget-reporter.md` when a run needs measured budget feedb
 Keep it compact:
 
 - What changed or what the scan found.
+- 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.
-- Remaining tasks and fix-first items, only when useful.
+- 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

@@ -170,5 +170,6 @@ Report:
 - Review continuity/comparison result when this continues a prior Ueye run.
 - P0-P3 issues or confirmation that no blockers were found.
 - 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.
-- Remaining tasks and fix-first items before planned tasks when useful.
+- 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 = [];
@@ -1968,28 +1974,43 @@ async function loop(args = []) {
 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.
+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] [--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]
+  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]
 `);
 }
 
 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 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 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 || ''),
     blockers,
+    blocked_kind: String(flags.blocked_kind || ''),
     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 || ''),
+    fix_first_items: arrayFlag(flags.fix_first_item),
     remaining_tasks: arrayFlag(flags.remaining_task),
+    recommended_direction: String(flags.recommended_direction || flags.direction || ''),
+    implementation_notes: arrayFlag(flags.implementation_note),
+    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),
     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,14 +183,29 @@ 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;
   blockers: string[];
+  blocked_kind: string;
   truth_status: TruthStatus;
   intent_label: ToolIntent;
   tool_intent: ToolIntent;
   next_action: string;
+  safe_retry: string;
+  fix_first_items: string[];
   remaining_tasks: string[];
+  recommended_direction: string;
+  implementation_notes: string[];
+  why_this_next: string;
+  blocked_by: string[];
+  owner_route: string;
+  owner_scope: string[];
+  scope_owner: string;
+  side_effects: string[];
   study_note: StudyNote;
 }
 
@@ -535,9 +551,14 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     : [];
   const evidence = asList(input.evidence);
   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 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 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';
@@ -550,14 +571,31 @@ 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,
     blockers,
+    blocked_kind: blockedKind,
     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 || (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')),
+    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: 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),
     study_note: studyNote
   };
 }
@@ -676,6 +714,18 @@ function normalizeToolIntentLabel(value: unknown = ''): ToolIntent {
   return 'read_only';
 }
 
+function normalizeOwnerRoute(value: unknown = ''): string {
+  const text = String(value || '').trim().replace(/^\$/, '').replace(/^yam-/, '');
+  if (['quick', 'ueye', 'question', 'scout', 'deep', 'mission'].includes(text)) return `$${text}`;
+  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.8",
+  "version": "1.9.1",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -11,7 +11,8 @@
     "Token-aware by default.",
     "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."
+    "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."
   ],
   "defaultHooks": false,
   "routes": [