yam-flow 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to yam-flow are documented here.
 
+## 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" --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 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, stage outcomes, evidence, blockers, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route, 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" --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 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: 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.
 - 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

@@ -1970,16 +1970,16 @@ 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] [--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]
 `);
 }
 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', '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 blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
     const report = buildLoopReport({
         route: normalizeRoute(flags.route) || String(flags.route || ''),
@@ -1991,7 +1991,13 @@ async function loopReport(args = []) {
         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 || ''),
+        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 || ''),
         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,7 +161,13 @@ export interface LoopReport {
     intent_label: ToolIntent;
     tool_intent: ToolIntent;
     next_action: string;
+    fix_first_items: string[];
     remaining_tasks: string[];
+    recommended_direction: string;
+    implementation_notes: string[];
+    why_this_next: string;
+    blocked_by: string[];
+    owner_route: string;
     study_note: StudyNote;
 }
 export interface UeyeRunReport {

package/dist/lib/trust-kernel.js

@@ -259,7 +259,13 @@ export function buildLoopReport(input = {}) {
         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')),
+        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),
+        owner_route: normalizeOwnerRoute(input.owner_route || input.route),
         study_note: studyNote
     };
 }
@@ -388,6 +394,12 @@ 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 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": "0.1.9",
   "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,30 @@ 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.
+
+`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`.
+
 ## 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, and why that next step matters.

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, and why that next step matters.

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, and why that next step matters.

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, and why that next step matters.

package/src/bin/yam.ts

@@ -1968,16 +1968,16 @@ 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] [--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]
 `);
 }
 
 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', '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 blockers = [...arrayFlag(flags.blocked), ...arrayFlag(flags.blocker)];
   const report = buildLoopReport({
     route: normalizeRoute(flags.route) || String(flags.route || ''),
@@ -1989,7 +1989,13 @@ async function loopReport(args = []) {
     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 || ''),
+    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 || ''),
     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,7 +189,13 @@ export interface LoopReport {
   intent_label: ToolIntent;
   tool_intent: ToolIntent;
   next_action: string;
+  fix_first_items: string[];
   remaining_tasks: string[];
+  recommended_direction: string;
+  implementation_notes: string[];
+  why_this_next: string;
+  blocked_by: string[];
+  owner_route: string;
   study_note: StudyNote;
 }
 
@@ -557,7 +563,13 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     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')),
+    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),
+    owner_route: normalizeOwnerRoute(input.owner_route || input.route),
     study_note: studyNote
   };
 }
@@ -676,6 +688,12 @@ 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 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": "0.1.9",
   "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, and recommended next direction when useful."
   ],
   "defaultHooks": false,
   "routes": [