yam-flow 2.2.1 → 2.3.0

package/references/mission.md

@@ -27,6 +27,13 @@ Role model:
 - 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.
 
+Read-only role contract:
+
+- Reviewer and Doctor default to `access_mode: read_only`.
+- They may read files, search, inspect diffs, and run non-mutating diagnostics.
+- They must not claim `changed_files` or use write access.
+- When review finds a needed fix, return a patch request to an Implementer lane instead of silently changing the implementation.
+
 Subagent policy:
 
 - Mission requires real subagent/team orchestration to be considered a full mission.
@@ -36,6 +43,15 @@ Subagent policy:
 - 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.
 
+Subagent completion receipts:
+
+- Record one `yam.mission-subagent-receipt.v1` for every expected thread.
+- Lifecycle and outcome are separate: `stopped` only means the thread ended.
+- A passed receipt requires an explicit `outcome: passed`, bounded scope, and verification evidence.
+- Failed, blocked, ambiguous, missing, duplicated, unexpected, or read-only-violating receipts block the aggregate gate.
+- `yam mission gate` compares receipt files with the expected thread inventory and produces `yam.mission-completion-gate.v1`.
+- A Mission proof requesting `verified` or `proven` is capped when this gate is missing or blocked.
+
 Patch envelope:
 
 Use a small envelope when a real mission lane changes code:

package/references/tool-trust-layer.md

@@ -138,6 +138,7 @@ Tool intent labels stay advisory and route-scoped:
 - browser/screenshot evidence
 - visual provenance for reference-based UI work
 - mission patch envelopes for real team lanes
+- per-thread Mission receipts and aggregate completion gate
 - runtime evidence mini for route-level runtime claims
 - patch queue lite when mission lane apply/verify order matters
 - rollback hints for risky changes
@@ -146,6 +147,8 @@ Tool intent labels stay advisory and route-scoped:
 - truth status
 - skipped/blocked/assumed items
 
+Reviewer and doctor Mission lanes use `read_only` intent by default. A receipt that claims write access or changed files for those roles is a contract violation, and a stopped thread without an explicit outcome is not success evidence.
+
 `yam release report --json` should collect release readiness into a machine-readable artifact:
 
 - typecheck

package/references/trust-kernel.md

@@ -40,6 +40,8 @@ The module provides:
 - runtime truth matrix
 - completion proof object creation
 - Ueye design completion gate creation
+- Mission subagent receipt and aggregate completion gate creation
+- Ueye asset/revision integrity helpers through the CLI
 
 ## Policy
 
@@ -54,5 +56,6 @@ For example:
 - Required runtime evidence that is missing becomes `real_required_missing`.
 - Cleanup claims require cleanup evidence.
 - Ueye `done` claims require a passing design completion gate or stay capped at `partial` or `blocked`.
+- Mission `verified` or `proven` claims require a passing completion gate built from the expected thread inventory and explicit receipts.
 
 This keeps the trust layer progressive and route-scoped.

package/references/truth-matrix.md

@@ -42,6 +42,8 @@ Never say cleanup is `proven` from a cleanup intention alone. Cleanup needs obse
 
 Never say full visual `verified` when the only evidence is a reference image, generated image, code reading, or text-only critique.
 
+Never say a Mission is `verified` or `proven` because every thread emitted a stop event. Every expected thread needs one unambiguous receipt with outcome and evidence, and the aggregate completion gate must pass.
+
 Ueye preflight is `partial` by design. It can identify design risks before work starts, but it cannot prove visual quality without implementation screenshot/comparison evidence.
 
 For ordinary routes, prefer `verified`, `partial`, `skipped`, `blocked`, or `assumed`.

package/references/ueye-proof.md

@@ -26,6 +26,10 @@ Ueye is one route. It should not split into separate lite/deep skills. Use these
 ```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 asset add --manifest .yam/ueye/assets.json --id official-logo --file ./assets/logo.png --source-page-url https://example.com/brand --license-note "official brand asset; local review use" --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 ueye report --reference ./reference.png --actual .yam/screens/home.png --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 --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
 ```
 
@@ -34,6 +38,8 @@ yam ueye report --reference ./reference.png --actual .yam/screens/home.png --acc
 - `report` records the Ueye run as reference sources, implementation sources, comparison result, surface context, design quality, blocked reason, next action, and truth status.
 - `report` can also record a deep visual review with acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
 - `report` may include continuity fields when a previous review or screenshot is being rechecked.
+- `asset` records and verifies local reference provenance, protection/edit flags, dimensions, bytes, and hashes without downloading remote content.
+- `revision` copies a live artifact into a non-overwriting round archive and verifies the revision history before it supports a done claim.
 - Without capture or user-provided screenshots, report implementation/source review separately from visual verification and cap the visual claim.
 
 ### Media Generation Proof

package/references/ueye.md

@@ -68,6 +68,8 @@ Use these when the task depends on visual truth, reference matching, or design q
 5. Review Continuity and Comparison Report.
 6. Design Completion Gate.
 7. Deep Visual Review, when Ueye needs Deep-grade verification.
+8. Asset Manifest, when local reference media affects the design.
+9. Revision History, when an iterative visual artifact is about to be replaced.
 
 Default bound:
 
@@ -77,6 +79,16 @@ Default bound:
 - Do not require voxel grids, exhaustive callouts, or generated annotations.
 - Do not let proof artifacts turn Ueye into always-on heavy orchestration.
 
+### Asset Manifest
+
+Use `yam ueye asset add|verify` for important local references such as official identity files, supplied photos, and editable visual sources.
+
+Record source URL/page when known, a license or usage note, operator-provided status, `do_not_replace`, `allowed_for_edit`, dimensions, bytes, and SHA-256. Missing licensing stays visible as a warning. The helper does not fetch URLs or infer usage rights.
+
+### Revision History
+
+Use `yam ueye revision archive` before replacing an artifact during an iterative design pass. Archives are written to numbered round folders with exclusive-copy behavior, so a different payload cannot silently overwrite an existing round. `yam ueye revision verify` recomputes hashes before the history supports a done claim.
+
 ### Visual Evidence Inventory
 
 Record the real screens and image sources behind the review.

package/references/verification-levels.md

@@ -143,7 +143,7 @@ Stop condition:
 - `$quick`: L1-L2 by default; L3 only when the claim needs it.
 - `$ueye`: L1-L3 for ordinary UI work; L4 when claiming visual done.
 - `$deep`: L3-L5 when risk or user intent calls for strong verification.
-- `$mission`: L4-L5 when real subagents/team lanes are used, with cross-verification.
+- `$mission`: L4-L5 when real subagents/team lanes are used, with cross-verification, per-thread receipts, and a passing aggregate completion gate.
 
 ## Completion Claim Rule
 
@@ -154,5 +154,6 @@ Completion claims require evidence at or above the level implied by the claim:
 - UI done claim: L3-L4 with visual evidence when feasible.
 - Runtime/cleanup claim: L4.
 - Release/auth/DB/security claim: L4-L5.
+- Mission verified/proven claim: L4-L5 plus expected-thread receipt coverage and completion gate.
 
 If the evidence level is lower than the claim, lower the truth status and report the gap.

package/skills/mission/SKILL.md

@@ -35,6 +35,8 @@ Do not use for:
 - If the user explicitly insists on `$mission` despite unavailable subagents, mark the mission `partial` or `blocked` instead of pretending role-play is team execution.
 - Use tmux/dev server/browser QA only when the mission needs runtime evidence.
 - Cross-verify before claiming completion.
+- Reviewer and doctor lanes are read-only by default: they may inspect and run non-mutating checks, but they must not claim changed files or write access.
+- A subagent stop event is lifecycle evidence, not success evidence. Every spawned thread needs an explicit outcome and verification evidence.
 - Do not claim verified, cleaned up, or visually checked without evidence.
 - Doctor scan is mandatory for mission finalization, but it should stay concise.
 
@@ -48,15 +50,18 @@ Do not use for:
    - Reviewer: checks code, risk, and project direction.
    - UX/browser verifier: checks screen behavior when relevant.
    - Doctor/scanner: checks direction fit, scope control, verification, cleanup, stale context, and false-completion risk.
+   - Keep Reviewer and Doctor read-only; if either must implement a fix, hand it back to an Implementer lane or create a new bounded write lane.
 5. Execute the implementation in bounded steps.
 6. Record a compact patch envelope for each real lane that changes code.
 7. Add rollback hints for touched files, generated files, before checks, and safe revert notes.
 8. Use `$deep`-style runtime verification when the mission needs dev server, tmux, test watcher, browser QA, cleanup, or before/after evidence.
 9. Cross-check findings and resolve contradictions.
-10. Run the smallest honest final verification set.
-11. Run doctor scan with `references/doctor-scan.md`.
-12. Confirm cleanup or explicitly report intentionally running processes.
-13. Produce final proof summary, truth status, remaining tasks, and fix-first items.
+10. Record one `yam mission receipt` for every spawned thread. `stopped` without `passed|failed|blocked` remains ambiguous and cannot support completion.
+11. Run `yam mission gate` against the expected thread inventory and receipts.
+12. Run the smallest honest final verification set.
+13. Run doctor scan with `references/doctor-scan.md`.
+14. Confirm cleanup or explicitly report intentionally running processes.
+15. Produce final proof summary, truth status, remaining tasks, and fix-first items.
 
 Mission stop condition:
 
@@ -73,6 +78,8 @@ Include:
 - Subagent decision: used / downgraded_to_deep / unavailable_partial / blocked, with reason.
 - Files or surfaces changed.
 - Patch envelope for each real code-changing lane.
+- Subagent receipt for every expected thread.
+- Passing Mission completion gate before a `verified` or `proven` Mission claim.
 - Rollback hint for risky or multi-file changes.
 - Runtime/tmux/browser evidence when used.
 - Cross-verification result.
@@ -91,6 +98,14 @@ Use `references/study-note.md` for every lane that changes code, config, docs, r
 Use `references/final-report.md` to close with remaining tasks and fix-first items.
 Use `references/token-budget-reporter.md` when budget drift matters.
 
+Useful CLI artifacts:
+
+```bash
+yam mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "read-only review" --evidence "review findings recorded" --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 proof --route mission --truth verified --mission-completion "$(<.yam/mission/completion.json)" --json
+```
+
 ## Prompt Pattern
 
 Good mission prompts include:

package/skills/ueye/SKILL.md

@@ -60,6 +60,9 @@ Do not use for:
    - Mark any ambiguous or unobservable detail instead of inventing it.
 5. Inspect nearby UI patterns, tokens, styles, and state handling.
 6. Implement the smallest coherent design improvement when implementation is requested.
+   - When local reference assets materially shape the design, record them with `yam ueye asset add` before editing.
+   - Use `do_not_replace` for protected identity assets and enable `allowed_for_edit` only when usage rights and task scope support editing.
+   - Before overwriting an iterative visual artifact, preserve the current file with `yam ueye revision archive`.
 7. Check default, loading, error, empty, disabled, hover/focus, and mobile states when relevant.
 8. Run browser/screenshot verification when feasible.
    - Prefer the in-app browser for local pages, localhost, file URLs, and ordinary visual QA.
@@ -127,6 +130,13 @@ Use these artifacts for reference-led implementation or serious visual review. K
    - record whether generation was requested, attempted, blocked, or produced an output.
    - use `yam media proof --requested --attempted --output path.png --wait-loop --json` when a generated image materially affects the design direction.
    - never use generated media proof as a substitute for implemented screen evidence.
+10. Asset Manifest, when logos, photos, illustrations, or other local reference files materially affect the work:
+   - record local file path, source URL/page when known, retrieval time, license note, operator-provided status, `do_not_replace`, `allowed_for_edit`, dimensions, bytes, and SHA-256.
+   - `yam ueye asset` records local files only; it does not download remote content.
+11. Revision History, when an artifact will be regenerated or overwritten:
+   - archive the current file under a numbered round before editing it.
+   - never overwrite a different archived payload for the same artifact and round.
+   - verify the revision manifest before using it in a visual `done` claim.
 
 ## Visual Truth Caps
 
@@ -177,3 +187,4 @@ Report:
 - Architecture hygiene when relevant: flag if the change risks dumping unrelated UI logic into `page.tsx`, one-off component styling into `global.css`, or structured product data into broad DB `jsonb` blobs.
 - Truth status and visual verification cap.
 - Handoff when useful: fix-first visual issues, remaining tasks, recommended direction, why that next step matters, blocker kind, safe retry, evidence level/stamp, and owner scope when another route or person may continue.
+- Asset manifest and revision history status when reference media or iterative artifact replacement materially affected the work.