yam-flow 2.2.1 → 2.3.1

package/AGENTS.md

@@ -21,3 +21,21 @@
 19. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
 20. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
 21. When relevant, include architecture hygiene in the Study Note: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
+
+## Latest Update Trigger
+
+When the user says exactly `yam 최신 업데이트 사항 반영해줘` in a chat for this project, treat that phrase as explicit authorization to update the globally installed package and refresh the installed yam skills.
+
+Run these commands sequentially from the yam project directory:
+
+```bash
+npm install -g yam-flow
+yam install
+yam version
+yam status
+```
+
+- Request any environment approval required for network access or writes outside the workspace.
+- Stop at the first failed command, report the blocker, and do not claim that later steps ran.
+- After all four commands pass, report the installed version and skill status, then tell the user that Codex can be restarted to reload the updated skills.
+- Do not restart Codex automatically.

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.3.1 - 2026-07-21
+
+### Added
+
+- Added a transactional skill installer that stages and SHA-256 verifies the complete managed skill set before replacing the active installation.
+- Added `yam.install-receipt.v1` with the installed package version, source identity, timestamp, destination, skill inventory, per-file hashes, and aggregate source digest.
+- Added deterministic install transaction smoke coverage for successful commit, forced mid-commit rollback, drift detection and repair, mirror cleanup, and concurrent-install locking.
+
+### Improved
+
+- `yam status` now detects missing files, unexpected files, hash drift, receipt drift, and package-version drift instead of checking only for `SKILL.md` and `references/` existence.
+- Failed commits restore the previous managed skill set and receipt; legacy and retired skill cleanup now participates in the same rollback boundary.
+- Unfinished transaction artifacts are surfaced by `yam status` and block a new install so recovery backups are not silently overwritten.
+- `yam uninstall` removes the install receipt and refuses to run while an install lock is present.
+
+### Verification
+
+- `npm run verify:self`
+- `npm run dist:freshness`
+- `npm run package-boundary:check`
+- `npm run cli-smoke`
+
+## v2.3.0 - 2026-07-13
+
+### Added
+
+- Added `yam mission receipt` with reviewer/doctor read-only contracts, explicit lifecycle/outcome separation, verification evidence, and per-thread completion eligibility.
+- Added `yam mission gate` to block Mission completion when expected thread receipts are missing, duplicated, unexpected, ambiguous, failed, or violate read-only role boundaries.
+- Added `yam ueye asset add|verify` for local reference provenance, license notes, protection/edit flags, dimensions, and SHA-256 integrity checks.
+- Added `yam ueye revision archive|verify` for non-overwriting round archives with hashed revision history.
+
+### Improved
+
+- Mission proof requests for `verified` or `proven` now recompute and validate supplied completion gates, then cap the claim when a passing gate is missing.
+- Ueye reports can attach asset and revision manifests; a supplied invalid manifest blocks a visual `done` claim.
+
 ## v2.2.1 - 2026-07-09
 
 ### Improved

package/COMMANDS.md

@@ -47,6 +47,10 @@ 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 --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" --acceptance-criterion "primary CTA remains visible on mobile" --design-system-evidence "uses existing button token" --implementation-evidence "browser screenshot reviewed" --state-check default:pass --state-check mobile:partial --skipped-check "hover state not checked on touch viewport" --residual-risk "tablet breakpoint still needs visual pass" --stop-condition "stop after primary states are checked and residual risk is recorded" --resume-hint "capture tablet screenshot next" --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 ueye asset add --manifest .yam/ueye/assets.json --id official-logo --file ./assets/logo.png --license-note "operator supplied; local review" --operator-provided --do-not-replace --json
+yam ueye asset verify --manifest .yam/ueye/assets.json --json
+yam ueye revision archive --file .yam/screens/home.png --round 1 --artifact-id home --root .yam/ueye/revisions --json
+yam ueye revision verify --manifest .yam/ueye/revisions/manifest.json --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
 ```
@@ -162,6 +166,9 @@ yam media proof --requested --attempted --output ./generated.png --wait-loop --j
 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 mission receipt --thread-id implementer-1 --role implementer --access-mode write --lifecycle stopped --outcome passed --scope "checkout form" --changed src/checkout.tsx --evidence "typecheck passed" --out .yam/mission/implementer-1.json --json
+yam mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "read-only checkout review" --evidence "review completed without edits" --out .yam/mission/reviewer-1.json --json
+yam mission gate --expected-thread implementer-1 --expected-thread reviewer-1 --receipt .yam/mission/implementer-1.json --receipt .yam/mission/reviewer-1.json --out .yam/mission/completion.json --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"}'
 yam proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
@@ -187,7 +194,7 @@ yam template tuning
 yam tools doctor /path/to/project --json
 yam release report --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 mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "changed files review" --evidence "read-only findings recorded" --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
 ```

package/README.md

@@ -96,21 +96,13 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-This copies each skill plus the shared `references/` directory into `~/.agents/skills/`, which is the user skill root used by this Codex desktop setup.
+`yam install` stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and only then replaces the active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
 
-Manual install is also possible by copying selected skill folders into your active Codex user skill root, but make sure each installed skill also receives a `references/` folder.
+A successful install writes `~/.agents/skills/.yam-flow-install-receipt.json`. The receipt records the package version, source identity, install timestamp, destination, managed skill inventory, and per-file hashes. `yam status` independently recomputes source and installed hashes, so a stale package install, local file change, unexpected file, or modified receipt is reported as drift.
 
-Recommended v0:
+An ordinary install error rolls back automatically. An abrupt process or machine termination can leave `.yam-flow-install.lock` and a hidden transaction directory; `yam status` surfaces the unfinished transaction and yam refuses another mutation while recovery state remains. Remove the lock only after confirming no install is running, and preserve any transaction directory until the previous installation state has been inspected.
 
-```bash
-mkdir -p ~/.agents/skills
-for skill in quick ueye question scout deep mission; do
-  rm -rf "$HOME/.agents/skills/$skill"
-  mkdir -p "$HOME/.agents/skills/$skill"
-  cp "skills/$skill/SKILL.md" "$HOME/.agents/skills/$skill/SKILL.md"
-  cp -R references "$HOME/.agents/skills/$skill/references"
-done
-```
+Manual copying can still make a skill loadable, but it intentionally remains unverified: without a matching receipt, `yam status` exits non-zero and recommends `yam install`.
 
 Restart Codex after installing so skills reload.
 
@@ -143,9 +135,15 @@ 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 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" --acceptance-criterion "primary CTA remains visible on mobile" --state-check default:pass --state-check mobile:partial --implementation-evidence "browser screenshot reviewed" --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 asset add --manifest .yam/ueye/assets.json --id official-logo --file ./assets/logo.png --license-note "operator supplied; local review" --operator-provided --do-not-replace --json
+yam ueye asset verify --manifest .yam/ueye/assets.json --json
+yam ueye revision archive --file .yam/screens/home.png --round 1 --artifact-id home --root .yam/ueye/revisions --json
+yam ueye revision verify --manifest .yam/ueye/revisions/manifest.json --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 mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "read-only review" --evidence "review completed without edits" --out .yam/mission/reviewer-1.json --json
+yam mission gate --expected-thread reviewer-1 --receipt .yam/mission/reviewer-1.json --out .yam/mission/completion.json --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" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --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" --avoidance-note "do not retry publish before npm auth is proven" --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"
@@ -181,6 +179,8 @@ npm install -g yam-flow
 yam status
 ```
 
+After `yam status` reports all skills and the install receipt as `ok`, restart Codex so the refreshed skills reload.
+
 Publishing still requires confirming the final npm package name and account access.
 
 ## Trust Kernel
@@ -199,6 +199,8 @@ Publishing still requires confirming the final npm package name and account acce
 - runtime backend evidence
 - runtime evidence mini summaries
 - mission patch queue lite records
+- Mission read-only reviewer/doctor contracts, subagent receipts, and completion gate
+- Ueye local asset provenance and non-overwriting revision history
 - release report JSON
 - loop report JSON
 - study note JSON
@@ -220,6 +222,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.
+- Mission completion receipt: every expected thread records lifecycle and outcome separately; reviewer/doctor write access, missing evidence, ambiguous stops, and receipt inventory gaps block the aggregate gate.
 - Verification Ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, and L5 bounded deep. Heavier claims require heavier evidence, but stop conditions prevent endless proof loops.
 - Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, readiness receipt, and final truth status.
 - Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, tool intent, truth status, and study note.
@@ -237,6 +240,7 @@ These shapes keep reports machine-readable without turning normal work into a he
 - 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 deep visual review: `$ueye` can record acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and a state matrix so serious UI work can carry Deep-grade verification without leaving the Ueye route.
+- Ueye asset/revision integrity: `$ueye` can record license/provenance and protected/editable flags for local references, then preserve pre-edit artifacts in hash-verified numbered rounds.
 
 ## Ueye Capture And Compare
 
@@ -246,6 +250,8 @@ These shapes keep reports machine-readable without turning normal work into a he
 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 preflight . --json
+yam ueye asset verify --manifest .yam/ueye/assets.json --json
+yam ueye revision verify --manifest .yam/ueye/revisions/manifest.json --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" --acceptance-criterion "pricing card CTA remains visible on mobile" --design-system-evidence "uses existing button token" --implementation-evidence "browser screenshot reviewed" --state-check default:pass --state-check mobile:partial --skipped-check "hover state not checked on touch viewport" --residual-risk "tablet breakpoint still needs visual pass" --stop-condition "stop after primary states are checked and residual risk is recorded" --resume-hint "capture tablet screenshot next" --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
 ```
 

package/ROADMAP.md

@@ -8,6 +8,7 @@ Implemented:
 - Six routes: quick, ueye, question, scout, deep, mission.
 - Shared references.
 - Local CLI: list, status, verify, doctor, examples, path, install, uninstall.
+- Transactional skill install with rollback, SHA-256 receipt, install lock, and status drift detection. Done.
 - CLI helpers: detect, budget, template, tune-log, version.
 - Optional advisory `yam-lite` hook with status/enable/disable. Done.
 - Opt-in project memory: init, add, list, summary, resolve.
@@ -71,6 +72,7 @@ Tasks:
 - Merge `ui`, `eye`, and `review` into `ueye`. Done.
 - Add Ueye checklist refinements. Done.
 - Add Visual Evidence Inventory, Reference Read Proof, Reference vs Implementation Matrix, and Design Quality Review. Done.
+- Add local reference asset provenance/protection manifest and non-overwriting revision history. Done.
 - Add optional browser/screenshot capture notes.
 - Keep image generation optional, never a gate.
 
@@ -93,6 +95,7 @@ Tasks:
 
 - Add symlink-friendly local install.
 - Add version command. Done.
+- Add staged transactional install, rollback, receipt, and drift-aware status. Done.
 - Consider npm packaging only after route behavior stabilizes.
 
 ### 8. Scout / Research Workflow
@@ -231,6 +234,7 @@ Tasks:
 - Add mission prompt template. Done.
 - Add doctor scan checklist. Done.
 - Require real subagent/team execution for full `$mission`; otherwise downgrade to `$deep` or report partial/blocked. Done.
+- Make Reviewer/Doctor lanes read-only by default and require explicit per-thread receipts plus an aggregate completion gate. Done.
 
 ### 14. Quick / Ueye Consolidation
 
@@ -421,3 +425,26 @@ Keep out for now:
 - required thread attachment ids.
 - app-specific visual gates.
 - blocking ordinary Ueye work when attachment metadata is absent.
+
+#### Plan Review Canvas Lite
+
+Status: deferred until repeated real-use demand.
+
+Trigger:
+
+- Users repeatedly need to annotate a generated plan or design report at exact elements instead of replying in prose.
+- Terminal-only approval causes revision ambiguity or costly re-reading.
+- A local browser review surface would materially shorten an approved Mission or Ueye feedback loop.
+
+First shape:
+
+- local-only artifact review.
+- anchored comments and approve/request-changes verdict.
+- explicit session end and bounded idle shutdown.
+- Host/Origin checks, path confinement, and sandboxed artifact rendering.
+
+Keep out for now:
+
+- default local server.
+- remote sharing or hosting.
+- automatic implementation start without an explicit approval verdict.