yam-flow 0.1.6 → 0.1.8

package/AGENTS.md

@@ -1,7 +1,7 @@
 # yam Core Rules
 
 1. Direction before execution.
-2. Start fast, then deepen deliberately when scope, risk, or user intent calls for it.
+2. Start with clear momentum, then deepen deliberately when scope, risk, learning value, or user intent calls for it.
 3. Treat token economy as part of quality.
 4. Reuse project context packs before broad reading.
 5. Read only the context needed for the requested change.
@@ -10,9 +10,12 @@
 8. Make the smallest useful change.
 9. Verify at the lightest level that honestly supports the claim, then escalate verification when the claim is larger.
 10. Report skipped, partial, blocked, or assumed verification plainly.
-11. Do not run broad tests for tiny changes, but do not under-verify risky changes.
-12. Do not use teams, orchestration, structured proof, or tmux unless risk, user intent, or an approved route justifies it.
+11. Do not run broad tests for tiny changes, but do not under-verify risky, security-sensitive, or public work.
+12. Do not use teams, orchestration, structured proof, or tmux unless risk, user intent, learning value, or an approved route justifies it.
 13. Escalate risky work by asking or recommending, not by silently switching modes.
 14. For UI work, inspect real states and responsive behavior when feasible.
 15. For long-running processes, do not claim cleanup unless process exit is checked.
-16. Keep final reports short and concrete.
+16. Explain useful change insight for non-specialists: what the touched code does, what changed, and why it matters.
+17. Use external references deliberately, preserve source clarity in research/proof notes, and rework good ideas into yam style.
+18. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
+19. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to yam-flow are documented here.
 
+## v0.1.8 - 2026-06-16
+
+### Added
+
+- Added `yam loop report [--json]` as a read-only loop artifact for intent, stages, evidence, blockers, next action, remaining tasks, tool intent, truth status, and study note.
+- Added `yam.study-note.v1` so reports can carry short non-specialist explanations of the failing code, its role, observed symptom, changed code, why it matters, and learning note without guessing missing details.
+- Added `publish_readiness` and `study_note` to `yam release report --json` with read-only npm registry/auth/version probes and redacted account/token details.
+- Added Ueye `design_brief` and `anti_slop_review` fields with `--brief-dimension`, `--constraint`, `--anti-slop`, `--invented-metric`, `--placeholder-copy`, and `--generic-visual`.
+
+### Improved
+
+- Ueye anti-slop P0 findings now feed the design completion gate so `done` claims are blocked until fix-first issues are resolved.
+- Release reports now separate publish readiness evidence from the publish action; `npm publish` remains outside the report.
+- CLI smoke coverage now asserts loop report, study note limits, and Ueye design brief/anti-slop blocked paths.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run cli-smoke`
+- `npm run verify:self`
+- `npm run forbidden-names:check`
+- `npm run package-boundary:check`
+- `npm run dist:freshness`
+- `node ./dist/bin/yam.js release report --json` (blocked as expected by npm auth readiness and dirty git)
+- `npm whoami --registry https://registry.npmjs.org/` (E401, confirms auth/token blocker)
+
+## v0.1.7 - 2026-06-12
+
+### Added
+
+- Added `yam context pressure [dir] [--json]` to explain when project context is becoming stale, broad, or confusing enough to summarize, refresh the project pack, narrow scope, or deepen the route.
+- Added `yam cleanup scan [dir] [--json]` as a read-only advisory cleanup report for active hooks, project-local skill folders, competing instruction surfaces, old install traces, and stale proof/runtime artifacts.
+- Added `contextPressure` and `realProbe` sections to `yam tools doctor --json` so readiness reports show local availability without starting browsers, servers, databases, or long-running processes.
+- Added `publishBlockerEvidence` to `yam release report --json` to classify common npm auth, permission, OTP, immutable-version, cache, registry, and tarball/package-boundary failures into beginner-readable next actions.
+- Added `yam ueye preflight [dir] [--json]` for pre-work UI/design quality checks before screenshots are available.
+- Added optional Ueye report fields: `--preflight-id`, `--p0-risk`, and `--quality-gate-note`.
+- Added stronger runtime cleanup evidence fields for `started_at`, `stopped_at`, `exit_code`, `pid`, `port`, `cleanup_method`, `cleanup_observed`, and `left_running_intentionally`.
+
+### Improved
+
+- Runtime cleanup claims no longer become `proven` from `--cleanup-checked` alone; observed cleanup plus exit/closure evidence is required.
+- Ueye preflight can identify likely P0/P1 design risks while keeping completion truth capped until real implementation screenshot/comparison evidence exists.
+- Release reports now turn likely npm publish blockers into safe next actions instead of leaving beginners with only raw npm logs.
+- CLI smoke coverage now asserts JSON schemas and truth caps for context pressure, cleanup scan, tools doctor, Ueye preflight/report, and runtime cleanup evidence.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run forbidden-names:check`
+- `npm run verify:self`
+- `npm run cli-smoke`
+- `npm run dist:freshness`
+- `npm run package-boundary:check`
+- `npm_config_cache=/private/tmp/yam-npm-cache npm pack --dry-run`
+- `node ./dist/bin/yam.js release report --json`
+
 ## v0.1.6 - 2026-06-07
 
 ### Added

package/COMMANDS.md

@@ -42,9 +42,10 @@ yam template ueye-comparison
 Opt-in visual evidence helpers:
 
 ```bash
+yam ueye preflight /path/to/project --json
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --brief-dimension "primary CTA clarity" --constraint "mobile first" --review-session-id pricing-card-v1 --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --similar "overall hierarchy" --different "button glow intensity" --missing "mobile state" --design-quality needs-polish --json
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --json
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 yam proof --route ueye --truth partial --visual "browser/local screenshot comparison executed" --require-visual
@@ -116,6 +117,7 @@ Use the CLI to create and inspect the small project direction file.
 ```bash
 yam init-project /path/to/project
 yam pack /path/to/project
+yam context pressure /path/to/project
 yam template mission
 ```
 
@@ -144,6 +146,9 @@ Read-only readiness and evidence helpers. These do not install, deploy, query da
 ```bash
 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 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"
@@ -153,7 +158,8 @@ yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --js
 yam ueye report --reference ./reference.png --actual .yam/screens/home.png --design-quality pass --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --json
 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 runtime evidence --backend terminal --claim observed --evidence-id dev-server-1 --command "npm run dev" --json
+yam runtime evidence --backend terminal --claim observed --evidence-id dev-server-1 --command "npm run dev" --pid 123 --port 3000 --json
+yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-observed --exit-code 0 --cleanup-method "process exit checked" --json
 yam mission queue --agent-id implementer --scope "checkout form" --changed src/checkout.tsx --verification-hint "npm run typecheck" --rollback-hint "revert checkout form patch if typecheck or smoke fails" --json
 yam benchmark report --label "render time" --baseline 100 --current 86 --unit ms --target lower --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"}'
@@ -179,18 +185,24 @@ yam template mission
 yam template tuning
 yam tools doctor /path/to/project --json
 yam release report --json
-yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-checked --json
+yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-observed --exit-code 0 --cleanup-method "exit observed" --json
 yam mission queue --agent-id reviewer --scope "changed files review" --changed src/bin/yam.ts --verification-hint "npm run typecheck" --json
 yam benchmark report --label "bundle size" --baseline 120 --current 118 --unit kB --target lower --json
+yam loop report --route deep --intent "verify release readiness" --blocked "npm auth not verified" --next-action "refresh npm token, then rerun npm whoami" --json
 ```
 
 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.
+- 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.
 - Ueye continuity/comparison: previous report, current report, comparison delta, design quality, next action.
+- Ueye design brief/anti-slop: brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom P0 blockers.
+- Context pressure: project pack age/size, memory summary, dirty scope, scripts, instruction surfaces, and route hint.
+- Cleanup scan: advisory-only list of confusing surfaces with destructive=false.
 
 ## Lite Hook
 

package/DECISIONS.md

@@ -1,13 +1,16 @@
 # yam Decision Baseline
 
-Every `yam` change is evaluated against strict proof, modular skill, and minimal-core harness principles.
+Every `yam` change is evaluated against honest proof, progressive depth, security-first guidance, modular skills, and useful non-specialist insight.
 
 ## Fixed Questions
 
 1. What needs concrete evidence before completion?
 2. What should stay selective or low-context?
 3. What can be removed to keep the core obeyable?
-4. What should `yam` keep light by default, and what should deepen deliberately?
+4. What should `yam` keep fast by default, and what should deepen deliberately?
+5. What security surface could a non-specialist miss?
+6. What should the user learn from this change?
+7. Which external references informed the judgment, and how were those ideas reworked into yam style?
 
 ## Keep
 
@@ -27,12 +30,28 @@ Every `yam` change is evaluated against strict proof, modular skill, and minimal
 - Token optimization.
 - Project-specific rules instead of global bloat.
 
-### Minimal Core
+### Progressive Core
 
 - Short core.
 - Few route names.
 - Minimal context.
 - Rules the model can actually follow.
+- Fast momentum without pretending simple work is always enough.
+- Depth growth when the user's understanding, project risk, or product quality benefits from it.
+
+### Beginner Insight
+
+- Explain changed behavior in plain language.
+- Name the code area touched and what it is responsible for.
+- Separate implementation facts from judgment.
+- Always close with remaining tasks or useful improvements.
+
+### Security First
+
+- Treat auth, payment, DB, secrets, permissions, deployment, and public release as first-class risk surfaces.
+- Prefer read-only inspection before sensitive writes.
+- Do not hide destructive or production-like risk behind convenience.
+- Make safer defaults visible to the user.
 
 ## Reject
 
@@ -50,11 +69,13 @@ Every `yam` change is evaluated against strict proof, modular skill, and minimal
 - Hook runtime by default.
 - Too many always-on rules.
 
-### From Minimal Core
+### From Progressive Core
 
 - Under-verification.
 - Vague quality rules.
 - No route structure for risky work.
+- Lightweight-only posture that prevents the harness from teaching or protecting the user.
+- Broad ceremony that does not produce insight, security, or evidence.
 
 ## yam Standard
 
@@ -62,9 +83,11 @@ Every `yam` change is evaluated against strict proof, modular skill, and minimal
 Direction before execution.
 Context-reuse first.
 Token-aware by default.
-Start fast.
+Start with momentum.
 Deepen deliberately.
 Basic direction fit and honest verification always.
+Security first.
+Explain what changed.
 Honest by design.
 Heavy proof when risk or user intent calls for it.
 ```

package/README.md

@@ -4,7 +4,7 @@
 
 ```text
 Direction before execution.
-Start fast.
+Start with momentum.
 Deepen deliberately.
 Basic direction fit and honest verification always.
 Honest by design.
@@ -12,6 +12,9 @@ Heavy proof when risk or user intent calls for it.
 Token-aware by default.
 Context-reuse first.
 End with remaining tasks and fix-first items.
+Security-first project guidance.
+Useful change insight for non-specialists.
+Reference-led judgment with clear source boundaries.
 ```
 
 ## Routes
@@ -34,9 +37,12 @@ See `ROADMAP.md` for remaining implementation stages.
 - No automatic proof loops.
 - No automatic tmux.
 - No false completion claims: verification, cleanup, and visual checks must match actual evidence.
-- `yam` is not lightweight-only; it is progressive: quick entry, stronger proof as scope/risk grows.
+- `yam` is not lightweight-only; it is progressive: fast direction, broader judgment when useful, stronger proof as scope/risk grows.
 - Every route should check project direction and use an honest verification level.
 - Small work stays small, but serious work is allowed to become serious.
+- Security-sensitive work is never treated as ordinary polish.
+- Useful reports explain what the changed code does, how it changed, and why the change matters.
+- Research and reference scans should keep source boundaries clear, then rework good ideas into yam style.
 - Token economy is part of quality.
 - Project packs prevent re-reading and re-planning from scratch.
 - Memory is opt-in, project-local, and sparse.
@@ -123,16 +129,20 @@ yam verify
 yam doctor
 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 proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
 yam proof --route ueye --truth partial --visual-provenance '{"source_kind":"reference","source_hash":"unknown","comparison_result":"not-verified","truth_status":"partial"}'
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
+yam ueye preflight /path/to/project --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --preflight-id ueye-preflight-123 --p0-risk "mobile CTA may clip" --quality-gate-note "check CTA contrast before done" --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --app-surface codex-app --browser-surface in-app-browser --preserved-state --json
 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 release report --json
 yam safety "supabase db reset"
 yam detect /path/to/project
@@ -175,6 +185,7 @@ Publishing still requires confirming the final npm package name and account acce
 - completion proof shape
 - truth caps
 - fake versus real distinction
+- security-first risk signals
 - runtime truth matrix
 - visual evidence caps
 - Ueye visual run reports
@@ -184,7 +195,15 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime evidence mini summaries
 - mission patch queue lite records
 - release report JSON
+- loop report JSON
+- study note JSON
 - structured diagnostic next actions
+- context pressure summaries
+- advisory cleanup scans
+- publish blocker evidence
+- publish readiness evidence
+- change insight reporting
+- reference source boundary notes
 - media generation proof caps
 - DB/Supabase safety signals
 
@@ -197,11 +216,18 @@ 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.
+- 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.
+- 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.
 - Structured diagnostic next action: every doctor/release diagnostic should say what was observed, what evidence supports it, what to do next, owner route, severity, and truth status.
 - Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.
 - Ueye surface context: `$ueye` run reports can record provider context, provider badge, execution surface, app surface, browser surface, control mode, preserved URL/state, and evidence id.
 - Ueye design completion gate: `$ueye` can stay fast for draft work, but a `done` claim is capped until implementation evidence, comparison/design-quality status, P0/P1 status, key states, mobile/responsive behavior, contrast/accessibility visuals, CTA affordance, and direction/reference-read proof are recorded when relevant.
+- Ueye design brief and anti-slop review: `$ueye` reports can record operator-provided brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom anti-slop blockers. P0 anti-slop findings block `done` claims.
 
 ## Ueye Capture And Compare
 
@@ -210,7 +236,8 @@ These shapes keep reports machine-readable without turning normal work into a he
 ```bash
 yam ueye capture --url http://localhost:3000 --out .yam/screens/home.png
 yam ueye compare --reference ./reference.png --actual .yam/screens/home.png --json
-yam ueye report --reference ./reference.png --actual .yam/screens/home.png --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
+yam ueye preflight . --json
+yam ueye report --reference ./reference.png --actual .yam/screens/home.png --brief-dimension "primary CTA clarity" --constraint "mobile first" --anti-slop "placeholder copy remains" --completion-claim done --design-quality pass --direction-locked --reference-read --states-checked --mobile-checked --contrast-checked --cta-checked --provider-context local --execution-surface in-app-browser --browser-surface in-app-browser --preserved-state --json
 ```
 
 `capture` uses a Playwright install from the current project when present, then falls back to the package context. It does not install browsers or add runtime dependencies by itself. If capture is unavailable, the visual claim stays `partial` or `blocked` until a real screenshot is supplied.
@@ -219,6 +246,8 @@ yam ueye report --reference ./reference.png --actual .yam/screens/home.png --com
 
 `report` gathers reference sources, implementation screenshots, comparison result, continuity fields, design quality judgment, design completion gate, surface context, and next action into one compact proof-ready JSON object. Draft and needs-polish work can stay fast; `--completion-claim done` turns on the stricter design gate.
 
+`preflight` does not claim visual verification. It is a pre-work checklist for reference source, target states, mobile/responsive needs, CTA/contrast/accessibility risk, screenshot availability, and likely P0/P1 candidates.
+
 Generated media can guide visual direction, but it cannot prove the implemented UI by itself:
 
 ```bash

package/ROADMAP.md

@@ -97,7 +97,7 @@ Tasks:
 
 ### 8. Scout / Research Workflow
 
-Goal: give yam a research lane that is evidence-bound, lightweight, and decision-oriented.
+Goal: give yam a research lane that is broad enough to create better judgment, evidence-bound enough to stay honest, and compressed enough to remain usable.
 
 Research reference points:
 
@@ -115,7 +115,7 @@ Tasks:
   - macro view: broad direction and category movement
   - realistic view: near-term feasibility and cost
   - future view: second-order effects and durable bets
-- Keep source count bounded by default; heavy research remains opt-in. Done.
+- Match source count to the decision: focused scouts use a few high-signal sources, broad scouts may use more. Done.
 - Avoid making research a default gate for implementation. Done.
 
 ### 9. Question Workflow