yam-flow 2.2.0 → 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/scout-wide-scan.md

@@ -0,0 +1,150 @@
+# Scout Wide Scan
+
+Use this reference when `$scout` needs broad search, powerful outside patterns, ecosystem comparison, agent/harness discovery, or source-heavy direction setting.
+
+## Activation
+
+Use wide scan when the user asks for:
+
+- Broad search or "find powerful patterns".
+- Tool, library, agent, harness, protocol, or market landscape comparison.
+- Third-party perspective before committing to a direction.
+- Evidence from multiple source classes.
+- Ideas worth reworking into yam style.
+
+Do not use wide scan for:
+
+- Stable direct answers.
+- Small implementation tasks.
+- Local code questions that a focused file read answers.
+- Heavy verification; use `$deep`.
+- Real subagent/team execution; use `$mission` unless the user explicitly asks for parallel agent work inside the current route and the environment supports it.
+
+## Scan Lanes
+
+1. Decision frame: name the decision, audience, constraints, and what would change the recommendation.
+2. Source map: decide which source classes are needed before reading deeply.
+3. Acquisition: gather enough sources; recover blocked high-signal sources only when needed.
+4. Triage: rank sources by authority, freshness, relevance, bias, and directness.
+5. Comparison: compare by fit, risk, cost, implementation effort, durability, and evidence quality.
+6. Opposition pass: name the strongest argument against the preferred direction.
+7. Synthesis: compress into a practical recommendation and yam-style rework ideas.
+8. Evidence ledger: record the important claims, evidence, confidence, and uncertainty.
+
+## Source Map
+
+Prefer a small balanced map over a large pile:
+
+- Official or primary source: docs, specs, vendor pages, source repos, standards.
+- Implementation evidence: source code, examples, package metadata, changelogs, local files.
+- Third-party analysis: credible writeups, benchmarks, incident reports, adoption notes.
+- Community evidence: issues, forum posts, social reports, user complaints; useful but lower trust.
+- Contrarian source: the best reason the attractive option may be wrong.
+- Local evidence: project constraints, existing route boundaries, installed tools, package scripts.
+
+Default focused scout remains 3-7 high-signal sources. Wide scan may use more, but stop once the decision is supported and marginal sources repeat what is already known.
+
+## Acquisition Ladder
+
+1. Use local project context packs and relevant local files first when the decision is project-specific.
+2. Use official or primary docs for current SDK/API/cloud-service behavior.
+3. Use ordinary web search or documentation search for accessible external sources.
+4. Use platform-specific public APIs or feeds when they are cleaner than rendered pages.
+5. Use blocked-source fallback only for high-signal sources that ordinary access cannot read.
+
+Blocked-source fallback:
+
+- Treat `insane-search` as a source acquisition subroutine.
+- Use it for blocked/WAF/platform-protected sources such as X, Reddit, YouTube, Naver, LinkedIn, Medium, Substack, or similar pages when they matter to the decision.
+- Preserve provenance: original URL, access path, trace or fallback note, and whether the content came from API, cache, feed, rendered HTML, or archive.
+- Do not use it for ordinary searches that normal web search can handle.
+- Do not treat authentication, paywall, private data, or rate-limit boundaries as something to force through.
+
+## Evidence Ledger
+
+Use a compact ledger for broad scans:
+
+```text
+Claim:
+Evidence:
+Source class:
+Confidence: high / medium / low
+Uncertainty:
+Decision impact:
+```
+
+Keep the ledger short. Include only claims that materially shape the recommendation.
+
+## Parallel Research
+
+Scout stays single-agent by default.
+
+Use real subagents or parallel agent lanes only when all are true:
+
+- The user explicitly asked for subagents, delegation, or parallel agent work.
+- The available environment provides real subagent tools.
+- The questions are independent and self-contained.
+- The results can be summarized without flooding the main context.
+
+Good lanes:
+
+- Official/docs lane.
+- Implementation/source lane.
+- Community/contrarian lane.
+- Security/risk lane.
+
+Bad lanes:
+
+- Multiple agents reading the same sources.
+- Delegating the immediate blocking question.
+- Role-playing subagents when no real subagent tool is available.
+- Turning a normal scout into `$mission`.
+
+## Opposition Pass
+
+Before the recommendation, ask:
+
+- What would make the best pick fail in this project?
+- Which source is least trustworthy or most stale?
+- What is the strongest cheaper/simpler alternative?
+- What security or operational risk is easy to miss?
+- What would we need to verify before implementation?
+
+Report the opposition pass briefly. It should sharpen the recommendation, not bury it.
+
+## Output
+
+Use the normal Scout shape, adding only the sections that help:
+
+- Best pick.
+- Objective judgment.
+- Subjective judgment.
+- Macro / realistic / future view.
+- Alternatives.
+- Risks.
+- Security lens.
+- Opposition pass.
+- Evidence ledger.
+- Ideas to rework into yam style.
+- Sources or local evidence.
+- Remaining tasks.
+
+## Source Clarity
+
+When outside systems shape the answer, preserve boundaries:
+
+- Fact: what the source says or what local files show.
+- Inference: what follows from comparing sources.
+- Opinion: taste, product instinct, or likely user perception.
+- Recommendation: the action Scout would take.
+
+Useful outside patterns to rework, not copy wholesale:
+
+- Agent Skills: progressive disclosure through `SKILL.md` plus optional references/scripts/assets.
+- Deep Research: multi-step search, backtracking, citations, and synthesis.
+- Coding-agent subagents: isolated read-only research lanes for context-heavy side tasks.
+- Agents SDK-style guardrails and tracing: lightweight checks and evidence records around runs.
+- Deep Agents-style harnesses: planning, context offloading, subagents, memory, and human checkpoints.
+- MCP/ACP-style protocols: standard tool/resource discovery and agent-client boundaries.
+
+Keep yam's bias: start with momentum, deepen deliberately, stay security-first, and avoid always-on orchestration.

package/references/scout.md

@@ -14,15 +14,20 @@ Use for:
 - Macro, realistic, and future-facing direction checks.
 - Security-centered direction checks.
 - Reference scans that find useful patterns to rework into yam style.
+- Wide scans across tools, agent systems, protocols, harnesses, markets, or third-party ecosystems.
 
 Default behavior:
 
 - Define the decision clearly.
 - Prefer official or primary sources.
 - Gather 3-7 high-signal references for focused scouting, or more when the user asks for a wide scan.
+- For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community evidence, contrarian sources, and local evidence.
 - Use current docs proof only for modern SDK/API/cloud-service behavior where stale knowledge is plausible.
+- Use blocked-source fallback only when a high-signal source is blocked or platform-protected; treat `insane-search` as source acquisition, not as the default search path.
 - Summarize options and recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use a compact evidence ledger for broad recommendations.
+- Run an opposition pass when false confidence would make the recommendation brittle.
 - Keep source boundaries clear: cite what was read and do not present reference-derived judgment as direct verification.
 - Put security before convenience: auth, payment, DB, secrets, permissions, deployment, supply chain, and public release get called out early.
 - Do not change code unless the user asks.
@@ -36,9 +41,13 @@ Judgment format:
 - Future view: second-order effects, durability, and what may age well or badly.
 - Security view: sensitive surfaces, safer defaults, failure modes, and what a non-specialist might miss.
 - Rework view: what ideas should be adapted into yam style and what should be rejected.
+- Evidence view: important claim, source class, confidence, uncertainty, and decision impact.
+- Opposition view: the strongest reason the preferred direction could be wrong.
 
 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.
+
+For broad scan mechanics, use `references/scout-wide-scan.md`.

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/scout/SKILL.md

@@ -16,6 +16,7 @@ Use for:
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing judgment.
 - Broad reference scans when the user needs wider perspective.
+- Wide search across source classes, markets, tools, harnesses, agent patterns, or third-party ecosystems.
 - Security-centered direction checks before implementation.
 - Finding patterns worth reworking into yam style.
 
@@ -31,6 +32,11 @@ Use for:
 - Do not change code unless the user asks.
 - Return a practical recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use an evidence ledger for wide scans: claim, source or local evidence, confidence, and uncertainty.
+- Run an opposition pass for broad recommendations: name the strongest reason the preferred direction may be wrong.
+- Use blocked-source acquisition only when a high-signal source is blocked, protected by WAF, or hosted on a platform that ordinary fetch cannot read.
+- Treat `insane-search` as a source acquisition subroutine, not as Scout's default search path.
+- Use real subagents or parallel agent lanes only when the user explicitly asks for delegation, subagents, or parallel agent work and the environment supports it.
 - Treat "objective" as evidence plus constraints, not certainty theater.
 - Treat "subjective" as named taste, product instinct, and likely user perception.
 - Security is the first lens: call out auth, payment, DB, secrets, permission, deployment, supply-chain, and public-release risks early.
@@ -46,13 +52,17 @@ Use for:
    - design/reference scan
    - product/technical direction memo
    - risk discovery
+   - wide scan
 3. Read `yam.project.md` first when project direction matters.
 4. Gather enough high-signal sources to support the decision; keep source quality higher than source volume.
-5. Compare options by fit, risk, cost, implementation effort, and durability.
-6. Identify security and trust implications before convenience or aesthetics.
-7. Give both objective and subjective judgment when useful.
-8. Recommend a direction and which ideas are worth reworking into yam style.
-9. State uncertainty and what would change the recommendation.
+5. For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community reports, contrarian sources, and local evidence.
+6. Recover blocked high-signal sources through the blocked-source fallback only when ordinary access fails or is predictably blocked.
+7. Compare options by fit, risk, cost, implementation effort, durability, and evidence quality.
+8. Identify security and trust implications before convenience or aesthetics.
+9. Give both objective and subjective judgment when useful.
+10. Run an opposition pass when making a broad recommendation.
+11. Recommend a direction and which ideas are worth reworking into yam style.
+12. State uncertainty and what would change the recommendation.
 
 ## Output
 
@@ -65,6 +75,8 @@ Use concise sections:
 - Alternatives.
 - Risks.
 - Security lens.
+- Evidence ledger.
+- Opposition pass.
 - Ideas to rework into yam style.
 - Sources or local evidence.
 - Remaining tasks or useful next improvements.
@@ -72,6 +84,7 @@ Use concise sections:
 Use `references/token-economy.md`; default to 3-7 high-signal sources unless the user asks for a broad research scan.
 Use `references/current-docs.md` for current SDK/API/cloud-service questions.
 Use `references/context-reuse.md`; do not rescout known decisions unless they may be stale.
+Use `references/scout-wide-scan.md` when the user asks for broad search, powerful outside patterns, harness/agent comparisons, or ecosystem scans.
 Use `references/markdown-management.md` before creating or updating project packs.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.

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.