yam-flow 0.1.7 → 0.1.9

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

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

package/dist/lib/trust-kernel.js

@@ -199,6 +199,76 @@ export function buildRuntimeBackendEvidence(input = {}) {
         })
     };
 }
+export function buildStudyNote(input = {}) {
+    const problem = buildStudyNoteSection(input.problem, {
+        code: input.issue_code,
+        role: input.issue_role,
+        symptom: input.issue_symptom
+    }, 'problem');
+    const change = buildStudyNoteSection(input.change, {
+        code: input.changed_code,
+        role: input.changed_role,
+        summary: input.change_summary
+    }, 'change');
+    const whyItMatters = shortText(input.why_it_matters || input.why_important);
+    const learningNote = shortText(input.learning_note);
+    const limits = [
+        ...asList(input.limits),
+        ...missingStudyNoteLimits(problem, change, whyItMatters, learningNote)
+    ];
+    const hasProblem = Boolean(problem.code || problem.role || problem.symptom);
+    const hasChange = Boolean(change.code || change.role || change.summary);
+    const truth = isTruthStatus(input.truth_status) ? input.truth_status
+        : hasProblem || hasChange || whyItMatters || learningNote ? 'partial'
+            : 'assumed';
+    return {
+        schema: 'yam.study-note.v1',
+        problem,
+        change,
+        why_it_matters: whyItMatters,
+        learning_note: learningNote,
+        limits: [...new Set(limits)],
+        truth_status: truth
+    };
+}
+export function buildLoopReport(input = {}) {
+    const stages = Array.isArray(input.stages)
+        ? input.stages.map((stage) => buildLoopStage(stage))
+        : [];
+    const evidence = asList(input.evidence);
+    const blockers = asList(input.blockers || input.blocked);
+    const hasBlockedStage = stages.some((stage) => stage.status === 'blocked' || stage.status === 'failed');
+    const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
+    const derivedTruth = blockers.length || hasBlockedStage ? 'blocked'
+        : evidence.length && stages.some((stage) => stage.status === 'passed') ? 'verified'
+            : evidence.length || stages.length ? 'partial'
+                : 'assumed';
+    const truth = requestedTruth ? weakestTruth(requestedTruth, derivedTruth) : derivedTruth;
+    const studyNote = buildStudyNote(input.study_note && typeof input.study_note === 'object' ? input.study_note : input);
+    const intentLabel = normalizeToolIntentLabel(input.intent_label || input.tool_intent);
+    return {
+        schema: 'yam.loop-report.v1',
+        generated_at: String(input.generated_at || new Date().toISOString()),
+        route: String(input.route || ''),
+        intent: shortText(input.intent),
+        loop_kind: String(input.loop_kind || 'harness'),
+        stages,
+        evidence,
+        blockers,
+        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')),
+        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
+    };
+}
 export function buildUeyeRunReport(input = {}) {
     const references = Array.isArray(input.reference_sources)
         ? input.reference_sources.map((item) => buildUeyeVisualProvenance(item))
@@ -240,6 +310,102 @@ export function buildUeyeRunReport(input = {}) {
         truth_status: isTruthStatus(input.truth_status) ? input.truth_status : finalTruth
     };
 }
+function buildStudyNoteSection(section, fallback, kind) {
+    const source = section && typeof section === 'object' ? section : fallback;
+    const code = shortText(source.code);
+    const role = shortText(source.role);
+    const symptom = kind === 'problem' ? shortText(source.symptom) : undefined;
+    const summary = kind === 'change' ? shortText(source.summary) : undefined;
+    return {
+        code,
+        role,
+        ...(symptom !== undefined ? { symptom } : {}),
+        ...(summary !== undefined ? { summary } : {}),
+        truth_status: code || role || symptom || summary ? 'partial' : 'assumed'
+    };
+}
+function missingStudyNoteLimits(problem, change, whyItMatters = '', learningNote = '') {
+    const limits = [];
+    if (!problem.code)
+        limits.push('issue_code not provided');
+    if (!problem.role)
+        limits.push('issue_role not provided');
+    if (!problem.symptom)
+        limits.push('issue_symptom not provided');
+    if (!change.code)
+        limits.push('changed_code not provided');
+    if (!change.role)
+        limits.push('changed_role not provided');
+    if (!change.summary)
+        limits.push('change_summary not provided');
+    if (!whyItMatters)
+        limits.push('why_it_matters not provided');
+    if (!learningNote)
+        limits.push('learning_note not provided');
+    return limits;
+}
+function buildLoopStage(value = '') {
+    if (value && typeof value === 'object') {
+        const item = value;
+        return loopStage(String(item.id || ''), item.status, String(item.note || ''));
+    }
+    const [id = '', rawStatus = '', ...noteParts] = String(value || '').split(':');
+    return loopStage(id, rawStatus, noteParts.join(':'));
+}
+function loopStage(id = '', rawStatus = '', note = '') {
+    const status = normalizeLoopStageStatus(rawStatus);
+    return {
+        id: shortText(id || 'stage'),
+        status,
+        note: shortText(note),
+        truth_status: stageTruth(status)
+    };
+}
+function normalizeLoopStageStatus(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (text === 'pass' || text === 'passed' || text === 'ok')
+        return 'passed';
+    if (text === 'fail' || text === 'failed' || text === 'error')
+        return 'failed';
+    if (text === 'block' || text === 'blocked')
+        return 'blocked';
+    if (text === 'skip' || text === 'skipped')
+        return 'skipped';
+    if (text === 'partial')
+        return 'partial';
+    if (text === 'pending')
+        return 'pending';
+    return 'recorded';
+}
+function stageTruth(status) {
+    if (status === 'passed')
+        return 'verified';
+    if (status === 'failed' || status === 'blocked')
+        return 'blocked';
+    if (status === 'skipped')
+        return 'skipped';
+    if (status === 'pending')
+        return 'assumed';
+    return 'partial';
+}
+function normalizeToolIntentLabel(value = '') {
+    const text = String(value || '').toLowerCase().replace(/[-\s]/g, '_');
+    if (['read_only', 'write', 'destructive', 'runtime', 'visual', 'publish'].includes(text))
+        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)
+        return text;
+    return `${text.slice(0, limit - 3)}...`;
+}
 export function buildMediaGenerationProof(input = {}) {
     const requested = Boolean(input.generation_requested);
     const attempted = Boolean(input.generation_attempted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "0.1.7",
+  "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.