yam-flow 0.1.0

package/references/doctor-scan.md

@@ -0,0 +1,56 @@
+# Doctor Scan
+
+Doctor scan is the final mission pass that looks for false completion, stale context, hidden failures, and avoidable follow-up risk.
+
+It is not another broad implementation pass.
+
+## Checklist
+
+Direction:
+
+- `yam.project.md` was read when project direction matters.
+- The implementation still matches product direction, UI direction, tech stack, and no-go rules.
+- New complexity is justified by the mission scope.
+
+Changed surface:
+
+- Changed files are within the approved mission scope.
+- No unrelated refactors or metadata churn were introduced.
+- Any generated files or markdown artifacts are intentional.
+
+Verification:
+
+- The smallest honest checks were run.
+- Failed or skipped checks are reported.
+- Browser, screenshot, or visual claims have actual visual evidence.
+- Runtime/tmux/process claims have PID, port, session, pane, log, or equivalent evidence when relevant.
+
+Cleanup:
+
+- Dev servers, watchers, tmux panes, or child processes are stopped or intentionally left running.
+- Cleanup is not claimed unless exit/closure was checked.
+- Remaining running processes are named.
+
+Truth status:
+
+- `verified` or `proven` is used only when evidence supports it.
+- `partial`, `blocked`, `skipped`, or `assumed` is used when appropriate.
+- Fixture or mock evidence is not promoted to real runtime proof.
+
+Report hygiene:
+
+- Final answer includes remaining tasks when real work remains.
+- Fix-first items are listed before planned tasks when they can block or distort the next run.
+- The report is concise enough to avoid wasting context in the next session.
+
+## Output Shape
+
+```text
+Doctor scan:
+- Direction fit:
+- Scope control:
+- Verification:
+- Runtime/cleanup:
+- Truth status:
+- Fix-first:
+```

package/references/eye.md

@@ -0,0 +1,30 @@
+# Eye
+
+`eye` is visual inspection for UI/UX quality.
+
+Inputs:
+
+- Screenshot.
+- URL.
+- Current local app screen.
+- Reference image.
+
+Review dimensions:
+
+- Direction fit.
+- Visual hierarchy.
+- CTA clarity.
+- Spacing and alignment.
+- Contrast.
+- Responsive behavior.
+- Empty, loading, error, disabled states.
+- Interaction affordance.
+
+Output:
+
+- P0: blocker.
+- P1: major issue.
+- P2: noticeable quality issue.
+- P3: polish.
+- Safe fix suggestions.
+

package/references/final-report.md

@@ -0,0 +1,61 @@
+# Final Report
+
+Every `yam` route should end with a compact handoff that helps the next run avoid re-reading and re-planning.
+
+## Required Closing Check
+
+Include these when they are useful and keep them short:
+
+- What changed or what was found.
+- What verification ran.
+- What was not checked.
+- Truth status, when verification or runtime claims matter.
+- Remaining tasks.
+- Fix-first items before planned tasks.
+
+## Anti-False-Completion Check
+
+Before final response, compare claim strength to evidence:
+
+- Do not say `verified` unless a relevant check actually ran and passed.
+- Do not say cleanup is complete unless exit/closure was checked or the process is intentionally left running.
+- Do not say UI was reviewed unless a screen, screenshot, browser check, or equivalent visual evidence was inspected.
+- Do not hide skipped or blocked checks.
+
+Use `references/honest-completion.md` and `references/truth-matrix.md` when the route has meaningful verification claims.
+
+## Remaining Tasks
+
+Use this for work that still belongs to the current roadmap or request.
+
+Examples:
+
+- Implement the next UI state.
+- Add browser verification.
+- Move large component logic into a helper.
+- Run build after a data-flow change.
+
+## Fix-First Items
+
+Use this for issues that should be considered before starting the next planned task because they can slow work, break verification, or distort product direction.
+
+Examples:
+
+- Current lint/build errors.
+- Failing tests.
+- Broken dev server.
+- Stale `yam.project.md`.
+- Active hooks or instruction files that conflict with the route.
+- Warnings that keep obscuring real problems.
+
+## Route Weight
+
+For `$quick`, one short paragraph or a compact verification matrix is enough.
+
+For `$ueye`, include source evidence, states/viewports checked, and P0-P3 issues only when they matter.
+
+For `$deep` and `$mission`, include evidence, remaining risks, remaining tasks, and fix-first items.
+
+Do not pad the final answer when there are no meaningful remaining tasks or fix-first items.
+
+When budget drift matters, include or run `yam measure <route>` with approximate files, commands, report lines, and seconds.

package/references/honest-completion.md

@@ -0,0 +1,61 @@
+# Honest Completion
+
+`yam` should prevent false completion without turning every task into a heavy proof ceremony.
+
+## Completion Rule
+
+Never claim that work is done, verified, cleaned up, visually checked, deployed, or fixed unless the matching evidence exists.
+
+Use precise language:
+
+- `done`: the requested edit or answer was completed.
+- `verified`: an actual relevant check passed.
+- `partial`: meaningful evidence exists, but not the full surface.
+- `assumed`: inferred from code or context, with no execution evidence.
+- `blocked`: the check could not run.
+- `skipped`: intentionally not checked because it was not worth the cost.
+
+## Default Guard
+
+Every route should ask before final response:
+
+- What did I actually change or answer?
+- What evidence do I actually have?
+- What did I not check?
+- Is the truth status stronger than the evidence?
+- Are there fix-first items before the next planned task?
+
+## Lightweight By Default
+
+For small work, the guard can be one sentence:
+
+```text
+Verification: not run; change was limited to copy/CSS and inspected locally.
+```
+
+For larger work, include proof summary and residual risk.
+
+## Runtime Guard
+
+Runtime work needs stronger evidence because long-running processes can create false success:
+
+- Record the command or process that was started.
+- Record the PID, port, session, or tmux pane when available.
+- Do not claim cleanup unless process exit or intended persistence is confirmed.
+- Do not claim browser/visual verification unless a browser check, screenshot, or equivalent evidence exists.
+
+## What yam Does Not Do By Default
+
+- No automatic proof gates.
+- No forced subagents.
+- No automatic tmux for ordinary work.
+- No release-blocking runtime proof unless the user chooses `$deep` or `$mission`.
+- No full `$mission` claim without real subagent/team evidence; downgrade to `$deep`, or mark mission partial/blocked.
+
+Design baseline:
+
+- Strict proof collects stronger physical proof and gates completion more aggressively.
+- Modular skill workflows keep evidence boundaries and report what is known vs inferred.
+- Minimal-core design keeps the rule short and obeyable.
+
+`yam` keeps the guard explicit, cheap, and route-aware.

package/references/hook-lite.md

@@ -0,0 +1,55 @@
+# Hook Lite
+
+`yam-lite` is an opt-in advisory hook.
+
+It exists to keep yam's direction present without turning every request into a proof gate.
+It does not mean `yam` itself should stay shallow; it only keeps the always-on layer small enough to preserve momentum.
+
+## Contract
+
+Allowed:
+
+- Add short route guidance through `UserPromptSubmit` additional context.
+- Remind the agent to check project direction and keep ordinary work moving.
+- Remind the agent not to overclaim verification, cleanup, or visual evidence.
+- Suggest `$quick`, `$ueye`, `$question`, `$scout`, `$deep`, or `$mission` based on obvious prompt signals.
+- Mention a project pack or memory summary when present.
+- Warn when conflicting proof-harness surfaces are active in the current project.
+
+Not allowed:
+
+- Run verification commands.
+- Start tmux, browser QA, dev servers, or subagents.
+- Block tools or permissions.
+- Read broad project context.
+- Force `$quick` or any other route.
+- Install dependencies.
+- Modify source files.
+
+## Toggle
+
+```bash
+yam hook status --global
+yam hook enable lite --global
+yam hook disable lite --global
+
+yam hook status --project /path/to/project
+yam hook enable lite --project /path/to/project
+yam hook disable lite --project /path/to/project
+```
+
+Global hooks write to `~/.codex/hooks.json`.
+
+Project hooks write to `<project>/.codex/hooks.json`.
+
+`yam` backs up an existing hook file before enabling the lite hook.
+
+## Design Baseline
+
+Broad hook systems often use route prep, tool evidence, permission gates, subagent evidence, and stop gates.
+
+Selective skill systems favor lower-context workflows.
+
+Minimal-core systems avoid hooks unless the rule is short and changes behavior.
+
+`yam` keeps this hook advisory-only so beginner momentum is preserved while the agent still receives a direction nudge. Deeper proof belongs in `$deep` and real team execution belongs in `$mission`, not in an always-on prompt hook.

package/references/markdown-management.md

@@ -0,0 +1,56 @@
+# Markdown Management
+
+`yam` uses markdown as a small direction layer, not as an automatic control system.
+
+## Design Baseline
+
+Strict proof systems:
+
+- Creates and manages more markdown surfaces for agent control, route instructions, proof, and dashboards.
+- Good for strict verification and anti-fake-work pressure.
+- Risk: too much generated context and too much automatic intervention.
+
+Modular skill systems:
+
+- Splits markdown into modular instructions, rules, skills, and commands.
+- Good for selective installation and low-context operation.
+- Risk: too many optional files can still become noisy if installed wholesale.
+
+Minimal-core systems:
+
+- Keeps the core instruction document short and human-readable.
+- Good for speed, obedience, and easy maintenance.
+- Risk: weaker automated structure when work becomes broad or risky.
+
+## yam Policy
+
+- `yam.project.md` is project-local, short, and user-owned.
+- `SKILL.md` files are route instructions managed by the `yam` source.
+- `references/*.md` files are optional detail and should be opened only when needed.
+- `.yam/*.md` files are optional logs, summaries, or proof notes.
+- `.yam/memory/records/*.json` files are opt-in sparse memory records, not an automatic control layer.
+- Do not install hooks or automations to keep markdown "fresh".
+- Do not overwrite an existing project pack during normal init.
+- Update stale project packs narrowly instead of re-reading the whole project every run.
+
+## Project Pack Size
+
+Target:
+
+```text
+500 to 1200 words
+```
+
+Hard preference:
+
+- Short enough to read before each route.
+- Specific enough to prevent re-planning from scratch.
+- Focused on product direction, UI direction, commands, risks, and no-go rules.
+
+## Write Rules
+
+- Create `yam.project.md` only when missing.
+- Never replace a user-edited pack without explicit approval.
+- If command detection changes, report the new command and let the user or route update the pack narrowly.
+- Keep generated sections clearly marked.
+- Prefer one project pack over multiple competing instruction files.

package/references/memory.md

@@ -0,0 +1,59 @@
+# Memory
+
+`yam memory` is an opt-in, project-local memory layer.
+
+It keeps only the lightest useful parts from heavier harness patterns:
+
+- Sparse records, one file per durable claim, and deliberate forgetting instead of injecting every old claim.
+- Wrongness memory for repeated mistakes, wrong decisions, stale assumptions, and overconfident claims.
+- Separate evidence, inference, and recommendation.
+- Keep the mechanism small enough to obey.
+
+Storage:
+
+```text
+.yam/memory/records/<id>.json
+.yam/memory/summary.md
+```
+
+Use it for:
+
+- Wrong decisions that should not be repeated.
+- Repeated mistakes that waste time.
+- Project direction changes.
+- Lessons learned after a bug, failed implementation, or UX review.
+- Verification command notes that should survive across sessions.
+
+Do not use it for:
+
+- Secrets, tokens, credentials, local private paths that should not be committed, or personal data.
+- Full proof logs.
+- Large research reports.
+- Automatic gates or route enforcement.
+- Every minor thought from a session.
+
+Commands:
+
+```bash
+yam memory init .
+yam memory add . --kind wrong_decision --summary "..." --evidence "..." --action "..."
+yam memory list .
+yam memory summary .
+yam memory resolve . mem-YYYYMMDD... --note "..."
+```
+
+Kinds:
+
+- `wrong_decision`
+- `repeat_mistake`
+- `direction_change`
+- `lesson`
+- `risk`
+- `command`
+
+Route behavior:
+
+- Routes may read `.yam/memory/summary.md` only when the task is likely to repeat a known mistake or touch project direction.
+- Routes should not read all memory records by default.
+- If memory is stale or noisy, report that as a fix-first item instead of expanding context.
+- Memory never proves completion by itself; it only informs direction and avoids repeated waste.

package/references/mission.md

@@ -0,0 +1,86 @@
+# Mission
+
+`mission` is the real-subagent/team execution route for approved plans.
+
+It exists so `deep` can stay single-agent and verification-centered while `mission` owns real team/subagent implementation and cross-verification.
+
+Use it when:
+
+- The user has approved a broad implementation plan.
+- Real subagent/team lanes would reduce risk.
+- Implementation, review, visual/runtime verification, and final proof need to happen together.
+- The work is too broad for `quick` or `ueye`.
+
+Do not use it for:
+
+- Small edits.
+- Ordinary scoped feature work.
+- Pure research.
+- Pure verification or single-agent heavy work.
+- Tasks without an approved plan or clear acceptance criteria.
+- Tasks where real subagents are unavailable, unsafe, or not worth the token/time cost; use `deep` instead.
+
+Role model:
+
+- Implementer: makes the scoped changes.
+- Reviewer: checks correctness, risk, architecture, and direction.
+- UX/browser verifier: checks UI behavior, browser state, screenshots, or flows when relevant.
+- Doctor/scanner: checks direction fit, scope control, command output, stale instructions, runtime/cleanup evidence, false-completion risk, and remaining fix-first items.
+
+Subagent policy:
+
+- Mission requires real subagent/team orchestration to be considered a full mission.
+- Use mission when the environment supports subagents and the work can be split into independent implementation, review, or verification lanes.
+- If the task is bounded, the split is artificial, or the token/time cost would exceed the safety benefit, choose `deep` instead.
+- If the user invoked mission but real subagents are unavailable or unsafe, downgrade to `deep` by default and report `subagent decision: downgraded_to_deep`.
+- If the user explicitly insists on mission despite missing subagents, mark the result `partial` or `blocked`; do not treat self-review as team execution.
+- The final proof must record the subagent decision: `used`, `downgraded_to_deep`, `unavailable_partial`, or `blocked`, with the reason.
+
+Runtime use:
+
+- Mission may use deep runtime verification when needed, but runtime proof alone does not make a mission if subagents were not used.
+- tmux is recommended when a persistent dev server, watcher, or browser QA loop materially improves evidence.
+- tmux is not mandatory for every mission.
+
+Completion rule:
+
+- No verified claim without evidence.
+- No cleanup claim without exit/closure confirmation or intentional persistence.
+- No visual claim without screen, browser, or screenshot evidence.
+
+Suggested prompt:
+
+```text
+$mission
+아래 구현 계획은 확정됐어.
+
+목표:
+-
+
+범위:
+-
+
+금지사항:
+-
+
+Acceptance criteria:
+-
+
+실제 subagent/team 단위로 구현하고,
+implementer/reviewer/UX verifier/doctor lane으로 교차 검증해줘.
+필요하면 tmux/dev server/browser QA/process cleanup proof까지 사용해줘.
+최종 보고에는 evidence, truth status, cleanup status, fix-first items, remaining tasks를 포함해줘.
+```
+
+Doctor scan:
+
+Use `references/doctor-scan.md` before final completion.
+Keep the scan short, but cover direction fit, scope control, verification, runtime/cleanup, truth status, and fix-first items.
+
+Design baseline:
+
+- Strict proof would likely make this a team route with stronger gates and required agent evidence.
+- Modular skill workflows split role responsibilities and keep evidence boundaries.
+- Minimal-core design avoids adding this unless it clearly replaces a confusing middle route.
+
+`yam` uses mission to replace the old standalone runtime route with a clearer heavy execution route.

package/references/question.md

@@ -0,0 +1,25 @@
+# Question
+
+`question` is the smallest yam route: direct Q&A without implementation, broad research, or proof loops.
+
+Use it when:
+
+- The user asks a simple explanation question.
+- The answer can be given from stable knowledge or current conversation context.
+- A local fact can be checked with one narrow file/command.
+- The user wants a quick answer, not a decision memo.
+
+Default behavior:
+
+- Answer first.
+- Keep the answer compact.
+- Do not change files.
+- Do not turn the answer into research unless freshness or uncertainty requires it.
+- If comparison, market context, external references, or third-party judgment are needed, switch to `scout`.
+
+Useful output shape:
+
+- Direct answer.
+- Why.
+- Practical next step.
+- Uncertainty, only when relevant.

package/references/quick.md

@@ -0,0 +1,70 @@
+# Quick
+
+`quick` is the merged small-work route: fast patching, ordinary scoped implementation, and fast error scanning.
+
+## Selected Principles
+
+Strict proof:
+
+- Honest completion language.
+- Real versus assumed verification.
+- Stop instead of claiming success when evidence is missing.
+
+Focused execution:
+
+- Detect the smallest useful command.
+- Group build/type/lint/test errors by file and root cause.
+- Fix one error class at a time.
+- Re-run the same focused command after a fix.
+- Use a compact PASS/FAIL matrix.
+
+Minimal core:
+
+- Keep the instruction short enough to obey.
+- Read the smallest useful context.
+- Avoid ceremony unless it changes the result.
+
+## Lanes
+
+Patch:
+
+- Best for copy, CSS, labels, simple bugs, small docs, and small config changes.
+- Usually read 1-3 files.
+- Usually run 0-1 command.
+
+Build-fix:
+
+- Best when there is a concrete command failure.
+- Read the error output first.
+- Sort dependency/import/type errors before logic errors.
+- Fix one root cause before moving to the next.
+
+Scan:
+
+- Best when the user wants to know what is broken before editing.
+- Report grouped errors, likely root cause, smallest first fix, and verification command.
+- If the scan sees destructive DB/Supabase, migration, production write, or RLS/policy signals, stop quick mode and recommend `$deep`.
+
+## Stop Conditions
+
+Stop or recommend a heavier route when:
+
+- The same error survives three focused attempts.
+- A fix creates more errors than it removes.
+- The change requires a new dependency, architecture change, or broad refactor.
+- The surface touches auth, payments, data mutation, security, deployment, or process lifecycle.
+- The requested work needs visual reference interpretation or screenshot-led QA.
+
+## Verification Matrix
+
+Use this compact shape when commands were run:
+
+```text
+Verification:
+- typecheck: pass/fail/skipped
+- lint: pass/fail/skipped
+- test: pass/fail/skipped
+- build: pass/fail/skipped
+```
+
+Only include rows that matter to the actual run.

package/references/risk-escalation.md

@@ -0,0 +1,27 @@
+# Risk Escalation
+
+Escalate by recommendation, not silent mode switching.
+
+Recommend `$deep` when work touches:
+
+- DB schema or data mutation.
+- Supabase destructive commands, migrations, production writes, RLS, or policy changes.
+- Auth, payment, billing, permissions.
+- Security-sensitive code.
+- Deployment or release configuration.
+- Broad refactor or many files.
+- Failing verification.
+- Unknown ownership or unclear acceptance criteria.
+- Long-running process lifecycle.
+
+Recommend `$mission` only when the user has an approved plan and real subagent/team execution would materially reduce risk.
+
+Suggested phrase:
+
+```text
+This looks like a deeper route because it touches <risk>.
+I can continue lightly, or switch to $deep for stronger single-agent verification.
+Use $mission only if you want real subagent/team execution.
+```
+
+Use `db-supabase-safety-lite.md` for the short DB/Supabase guardrail.

package/references/runtime-orchestration.md

@@ -0,0 +1,57 @@
+# Runtime Verification
+
+Runtime verification now lives inside `$deep` and may be used by `$mission`.
+
+It combines tmux/process management, cleanup confirmation, browser QA, and proof summary when a verification claim needs runtime evidence.
+
+Use for:
+
+- Long-running dev servers.
+- Test watchers.
+- Multi-step broad tasks.
+- Browser QA sessions.
+- Work requiring before/after evidence.
+
+Do not use for ordinary small edits.
+
+## tmux Policy
+
+tmux is a first-class runtime verification tool in `yam`, but it is not automatic.
+
+Use tmux when it improves the work:
+
+- Long-running dev servers.
+- Test watchers.
+- Multiple concurrent panes.
+- Work where preserving logs or panes helps verification.
+- Tasks that need a stable server while browser QA runs.
+
+Do not use tmux just to make a small task look more verified.
+
+When tmux is used, record:
+
+- Session name.
+- Pane id when available.
+- Command running in the pane.
+- Before/during/after observation.
+- Whether the pane was left running intentionally or closed.
+
+Runtime proof should include:
+
+- Goal.
+- Steps run.
+- Commands/processes started.
+- PIDs, ports, sessions, or panes when available.
+- Checks before and after.
+- Cleanup result.
+- Truth status: proven, verified, partial, fixture_only, fixture_instrumented_real, integration_optional, real_required_missing, skipped, blocked, assumed.
+
+## Cleanup Rule
+
+Do not claim cleanup succeeded unless one of these is true:
+
+- Process exit was checked.
+- tmux pane/session was checked closed.
+- The process was intentionally left running and reported that way.
+
+For `$deep` runtime verification and `$mission`, cleanup evidence matters more than a polished final sentence.

package/references/scout.md

@@ -0,0 +1,38 @@
+# Scout
+
+`scout` is practical investigation and judgment, not academic research.
+
+Use for:
+
+- Current docs.
+- Library or tool comparison.
+- Design references.
+- Product direction options.
+- Risk discovery before implementation.
+- Third-party judgment before implementation.
+- Objective and subjective evaluation together.
+- Macro, realistic, and future-facing direction checks.
+
+Default behavior:
+
+- Define the question narrowly.
+- Prefer official or primary sources.
+- Gather 3-7 high-signal references by default.
+- Use current docs proof only for modern SDK/API/cloud-service behavior where stale knowledge is plausible.
+- Summarize options and recommendation.
+- Separate fact, inference, opinion, and recommendation.
+- Do not change code unless the user asks.
+
+Judgment format:
+
+- Objective judgment: evidence, constraints, cost, feasibility, and known reality.
+- Subjective judgment: taste, product instinct, design sensibility, and likely user perception.
+- Macro view: category direction and broad movement.
+- Realistic view: what can be done soon with the current project and skill level.
+- Future view: second-order effects, durability, and what may age well or badly.
+
+Escalate:
+
+- Use `question` for direct answers that do not need sources.
+- Use `deep` only when the user asks for heavy verification.
+- Use implementation routes only after the user asks to change code.