opencode-plugin-flow 4.1.6 → 4.1.8

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{createHash as Fe}from"node:crypto";import{mkdir as Ce,readdir as ee,readFile as Ue,rm as qe,writeFile as y}from"node:fs/promises";import{createRequire as Ae}from"node:module";import{dirname as Te,join as l,normalize as Pe,sep as De}from"node:path";var j=`# Flow worker handoff contract
+import{createHash as qe}from"node:crypto";import{mkdir as Pe,readdir as te,readFile as Te,rm as De,writeFile as y}from"node:fs/promises";import{createRequire as je}from"node:module";import{dirname as Be,join as l,normalize as We,sep as Se}from"node:path";var j=`# Flow worker handoff contract
 
 Flow managers merge only the worker's final response. Treat that response as the
 worker report of record: it must include the assigned scope, what was actually
@@ -118,7 +118,7 @@ live-verified | test-verified | type-check-only | not-verified
 
 The manager must inspect and validate any candidate patch before recording Flow
 completion.
-`;var W=`# Parallel orchestration
+`;var B=`# Parallel orchestration
 
 Use fan-out when Flow work is broad enough that independent workers can gather
 evidence faster than one linear pass. The manager still owns the Flow session:
@@ -247,7 +247,7 @@ Start a follow-up wave when first-wave handoffs reveal:
 
 Do not recurse by default. If a worker says it needs another worker, the manager
 decides whether that is a second wave and writes the next bounded prompt.
-`;var O='# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';var z=`# Verification gates
+`;var W='# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';var S=`# Verification gates
 
 Verification is how Flow keeps parallel work from turning into parallel
 guesswork. Worker handoffs are candidate evidence; the manager decides what can
@@ -337,9 +337,9 @@ Before presenting or recording the result:
 
 \`Status: success\` only says the worker believes its slice is done. The manager
 still checks coverage and evidence before trusting the result.
-`;var B=`---
+`;var z=`---
 name: flow
-description: Main Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning, autonomous execution, resumable implementation, session status, or end-to-end delivery with validation and review gates.
+description: Run the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning through implementation, resumable autonomous delivery, session status, or completion with validation and review gates.
 ---
 
 # Flow
@@ -353,13 +353,17 @@ Use Flow as a minimal state ledger, not as a framework. Skills provide judgment;
    load Flow skills in this startup. A just-synced skill can be on disk while
    unavailable to the running OpenCode process.
 2. If there is no active session and the user gave a goal, load \`flow-plan\`, save a plan with \`flow_plan_save\`, then approve it with \`flow_plan_approve\` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.
-3. Load \`flow-run\`, call \`flow_run_start\`, implement exactly one feature, validate it, and prepare a \`flow_feature_complete\` payload.
+3. Load \`flow-run\`, call \`flow_run_start\`, implement exactly one feature, validate it, and prepare a \`flow_feature_complete\` payload. For validation-heavy, regression-sensitive, or browser/UI work, use \`flow-test\` to choose and summarize evidence before completion.
 4. Load \`flow-review\` for the required feature review. The reviewer reports a \`featureReview\` payload; the manager records it inside \`flow_feature_complete\`.
 5. On the final feature, run broad validation and include \`finalReview\` in the same \`flow_feature_complete\` call. Its \`reviewDepth\` must match the plan's \`finalReviewPolicy\`.
 6. After all features are complete, archive the session with \`flow_session_close\` using \`kind: "completed"\`.
 
 Use \`references/parallel-orchestration.md\` for broad read-only discovery, audit, validation, review, verification, or candidate implementation waves. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. Its \`references/handoff-format.md\` and \`references/verification-gates.md\` companions define the worker contracts. The manager owns every \`flow_*\` state change.
 
+Do not commit, push, amend, rebase, publish, or mutate releases during the
+autonomous Flow loop. Load \`flow-commit\` only when the user explicitly asks for
+commit preparation or commit creation.
+
 ## Skill Availability
 
 If \`flow_status\` returns \`setup.skills\`, report that setup status and stop
@@ -367,9 +371,10 @@ loading Flow skills in the current OpenCode startup. Missing, incomplete, or
 outdated managed skills require a sync/restart cycle before their instructions
 can be trusted by the running process.
 
-If optional helper skills such as \`flow-deslop\` or \`flow-ui-quality\` are
-unavailable, continue only with explicit coverage gaps. Do not copy their
-rubrics into another skill and do not claim their quality checks were completed.
+If optional helper skills such as \`flow-test\`, \`flow-deslop\`, or
+\`flow-ui-quality\` are unavailable, continue only with explicit coverage gaps. Do
+not copy their rubrics into another skill and do not claim their quality checks
+were completed.
 
 ## Runtime Surface
 
@@ -404,7 +409,121 @@ Planning and running require loaded Flow tools; do not simulate plan approval or
 - Unknown runtime error: read \`summary\` and \`recovery\`; see \`references/recovery-playbook.md\` for common cases.
 
 Never fabricate validation output, backfill review approval you did not perform, or close as \`deferred\`/\`abandoned\` merely to avoid an unfinished-work blocker.
-`;var N=`# Safe refactor workflow
+`;var O=`---
+name: flow-commit
+description: Prepare safe Git commits and commit messages. Use only when the user asks to inspect, stage, validate, write a commit message, or create a commit; preserves unrelated work and never pushes, amends, rebases, or publishes without explicit authorization.
+---
+
+# Flow Commit
+
+Use this skill only when the user asks to prepare or create a commit, write a
+commit message, stage intended work, or validate staged changes before
+committing. It is not part of the autonomous Flow loop and must not be loaded
+automatically by \`flow\`, \`flow-run\`, or \`flow_feature_complete\`.
+
+When a Flow session exists, a commit never substitutes for Flow completion. The
+manager still records validation and review evidence through
+\`flow_feature_complete\` before claiming a Flow feature is done. Default to commit
+preparation only after \`flow_feature_complete\` has recorded the relevant
+completion evidence. If the user explicitly asks for a WIP commit, preserve
+failing or incomplete validation context in the message.
+
+## Boundaries
+
+- Preserve unrelated user work.
+- Stage explicit paths or hunks only. Do not default to \`git add .\` or
+  \`git add -A\`.
+- Do not commit \`.flow/**\` state unless the maintainer explicitly asks to
+  archive those exact files.
+- Do not push, amend, rebase, squash, reset, force-push, tag, release, publish,
+  or mutate remote state unless the user explicitly authorizes that exact
+  operation.
+- Stop before committing secrets, local config, credentials, private keys,
+  generated release artifacts, or suspicious environment files.
+- Stop when validation fails unless the user explicitly wants an unfinished WIP
+  commit and the commit message says so.
+
+## Inspect
+
+Start with the worktree and intent:
+
+1. Run \`git status --short\`.
+2. Inspect unstaged and staged changes separately with \`git diff\` and
+   \`git diff --cached\`.
+3. Inspect untracked files before deciding whether they belong.
+4. Group changes by intent, feature, and risk. Prefer one coherent commit over
+   one large mixed commit.
+5. Identify exclusions: unrelated files, local notes, \`.flow/**\`, generated
+   artifacts, logs, caches, credentials, and temporary outputs.
+
+If the commit boundary is unclear, propose the boundary and ask before staging.
+
+## Stage
+
+Stage only the intended boundary:
+
+- Use explicit file paths for whole-file staging.
+- Use patch staging for mixed-intent files.
+- Re-run \`git status --short\` and \`git diff --cached --stat\` after staging.
+- Review the full staged diff before validation and commit.
+
+Never undo or rewrite user changes to make staging easier. If a file contains
+mixed user and agent work, either stage selected hunks or ask for direction.
+
+## Screen and Validate
+
+Before commit creation, check the staged diff for:
+
+- Secrets, tokens, private keys, credentials, cookies, and unredacted personal
+  data.
+- \`.env\`, local config, machine-specific paths, and editor files.
+- \`.flow/**\` state.
+- Generated artifacts that are not normally versioned.
+- Package or version metadata drift unrelated to the requested change.
+
+When this repository-local contribution preflight exists, defer to it for staged
+and outgoing validation instead of duplicating its checks:
+
+\`\`\`bash
+.agents/skills/flow-contribution-check/scripts/preflight.sh commit
+\`\`\`
+
+Run it after staging and rerun it after any staging change. The preflight
+validates staged or outgoing work; it does not choose commit boundaries or write
+commit messages. If the script is absent, use the repository's documented commit
+preflight from package scripts, AGENTS/docs, or CI guidance.
+
+Use the repository's documented broad validation gate when a full local check is
+appropriate, such as package scripts, AGENTS/docs, or CI guidance. Use narrower
+tests only when the user has asked for a lighter pass or when the change is
+intentionally not ready for the broad gate.
+
+## Message
+
+Propose a commit message that reflects the staged diff:
+
+- Subject: imperative, specific, and scoped.
+- Body when useful: context, changed areas, validation run, and remaining risk.
+- Do not mention unstaged or excluded work as if it were included.
+- Include WIP or failing-validation context only when the user explicitly chose
+  that path.
+
+## Create Commit
+
+Create the commit only after the user explicitly asks for commit creation or has
+already authorized it in the current request.
+
+Before running \`git commit\`, report:
+
+- Staged paths.
+- Excluded dirty or untracked paths.
+- Validation command and result.
+- Proposed message.
+- Any risks or gaps.
+
+After a successful commit, report the commit hash and leave push or release
+actions for a separate explicit request.
+`;var E=`# Safe refactor workflow
 
 Refactoring is a behavior-preserving sequence of small changes. This workflow keeps cleanup from becoming an unreviewable rewrite.
 
@@ -446,7 +565,7 @@ Weak evidence includes:
 - Public contracts and compatibility shims remain intact or were explicitly planned.
 - Deleted code is actually unreachable or obsolete.
 - Validation can catch a realistic mistake in the refactor.
-`;var V=`# Deslop smell rubric
+`;var N=`# Deslop smell rubric
 
 Use this rubric to turn vague cleanup instincts into reviewable findings.
 
@@ -480,9 +599,9 @@ class; severity; location; evidence read; refutation checked; why it matters; sa
 \`\`\`
 
 Rate as blocking only when the smell materially raises defect risk, blocks planned work, hides behavior, or makes the success claim unverifiable. Style-only cleanup is advisory.
-`;var E=`---
+`;var V=`---
 name: flow-deslop
-description: Flow guidance for evidence-backed code smell cleanup, AI-slop removal, overengineering reduction, maintainability refactors, and behavior-preserving cleanup. Use when planning, executing, or reviewing broad cleanup/refactor work, code smell findings, duplicated or bloated code, speculative abstractions, dead code, or agent-introduced mess.
+description: Clean up and refactor code with evidence-backed code-smell analysis. Use for AI-slop removal, overengineering reduction, maintainability refactors, behavior-preserving cleanup, duplicated or bloated code, speculative abstractions, dead code, or broad cleanup/refactor review.
 ---
 
 # Flow deslop
@@ -522,7 +641,7 @@ For each claimed smell removal, verify:
 - **blast radius** — public contracts and downstream callers still work.
 
 Never approve cleanup because it "looks cleaner" without evidence. Tests passing is necessary but not sufficient when the refactor changes structure across files.
-`;var S=`# Parallel discovery
+`;var G=`# Parallel discovery
 
 Use this only after a serial orientation pass has identified the repo shape and the likely slices. Workers are read-only evidence gatherers; the planner owns the plan.
 
@@ -588,7 +707,7 @@ Convert only evidence-backed work into plan fields:
 - feature \`validation\`: checks expected to prove the feature.
 
 If workers disagree, inspect the source artifact yourself. If a candidate finding lacks a concrete citation or refutation pass, make it a review-first deliverable rather than a fix feature.
-`;var G=`# Planning examples
+`;var L=`# Planning examples
 
 ## Rate limiting feature set
 
@@ -688,6 +807,9 @@ If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the
 
 - Read the files, docs, tests, package scripts, and local conventions that determine the work.
 - For broad discovery, read \`references/parallel-discovery.md\` after a serial orientation pass. Use \`../flow/references/parallel-orchestration.md\` when discovery needs multiple workers, and apply its coverage gate before fan-out.
+- For complex validation, regression-sensitive changes, browser/UI workflows,
+  or uncertain test strategy, load \`flow-test\`. If it is unavailable, record a
+  planning gap and keep validation claims conservative.
 - For cleanup/refactor goals, load \`flow-deslop\`. If it is unavailable, record
   a planning gap and keep cleanup claims conservative.
 - For UI/frontend goals, load \`flow-ui-quality\`. If it is unavailable, record a
@@ -730,14 +852,17 @@ Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonic
 - Split by dependency order: foundations before callers, schema before consumers, implementation before docs when docs depend on behavior.
 - Avoid "misc cleanup" features. Tie cleanup to evidence and targets.
 - Keep feature ids stable once the plan is approved.
-- Put scope boundaries in \`targets\` and expected checks in \`validation\`.
+- Put scope boundaries in \`targets\` and expected checks in \`validation\`. Each
+  validation entry should name the expected test level, such as targeted unit,
+  integration, browser/e2e, package/build, docs/static, cleanup preservation, or
+  broad project gate.
 
 ## Approval
 
 After saving, summarize the plan to the user. Call \`flow_plan_approve\` only after explicit user approval, unless the user already authorized autonomous implementation. Approved plans are immutable; changing them later requires reset/closure rather than silent edits.
 
 See \`references/planning-examples.md\` for payload examples and decomposition anti-patterns.
-`;var L=`# Review rubric
+`;var K=`# Review rubric
 
 Use this to decide whether a \`featureReview\` or \`finalReview\` payload may pass.
 
@@ -844,6 +969,9 @@ recorded.
 - Identify whether this is a feature review or final review.
 - Read the approved plan fields relevant to the work: \`requirements\`, \`decisions\`, feature \`targets\`, feature \`validation\`, and dependencies.
 - Inspect the actual diff, changed files, tests, and validation output. Do not review only the completion summary.
+- Load \`flow-test\` for validation-heavy, regression-sensitive, browser/UI, or
+  unclear coverage reviews. If it is unavailable, record a coverage gap and
+  treat missing validation evidence as a gap or blocker based on user impact.
 - Load \`references/review-rubric.md\` for severity, depth, and payload shape.
 
 ## Feature Review Depth
@@ -892,7 +1020,7 @@ Use \`status: "failed"\` when any blocking finding remains. Advisory findings ma
   \`finalReview\` payload.
 
 Never approve to unblock completion, fix findings in the review pass, or vouch for validation you did not inspect.
-`;var K=`# Audit findings rubric
+`;var Q=`# Audit findings rubric
 
 What counts as a valid finding when the feature's deliverable is a findings report: a codebase audit, a review-first feature, or any report whose findings a later feature will fix. The commands you run are still governed by \`validation-rubric.md\`; this rubric governs the findings themselves.
 
@@ -1028,9 +1156,18 @@ If \`flow_run_start\` is unavailable, stop and tell the user to check that \`ope
 - Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.
 - Preserve unrelated user changes in the worktree.
 - When a wrong assumption invalidates the feature, use \`flow_feature_reset\`; do not pile patches onto a bad path.
+- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part
+  of feature execution. If the user explicitly asks for commit preparation, load
+  \`flow-commit\` only after \`flow_feature_complete\` has been recorded, unless the
+  user explicitly asks for a WIP commit path. Keep Git boundaries separate from
+  Flow state recording.
 
 ## Validate
 
+- For complex validation, regression-sensitive changes, browser/UI workflows,
+  failure-prone checks, unclear coverage, route QA, exploratory QA, or
+  \`validationRun\` summarization, load \`flow-test\`. If it is unavailable, record
+  the coverage gap and keep validation claims conservative.
 - Read \`references/validation-rubric.md\` before completing.
 - Run the strongest practical checks for the changed behavior.
 - Record concrete command names, status, and observed results. "Tests pass" is not evidence.
@@ -1057,8 +1194,9 @@ and records it.
 
 If \`flow_status\` reports \`setup.skills\` or \`flow-review\` cannot be loaded, do
 not record a Flow-gated \`featureReview\` or \`finalReview\`. You may perform an
-advisory review using available context or bundled reviewer fallback text, then
-complete with \`status: "needs_input"\` if review evidence is required to proceed.
+advisory review using available context or the bundled review fallback provided
+by plugin config, then complete with \`status: "needs_input"\` if review evidence
+is required to proceed.
 
 For the final feature, also obtain a \`finalReview\` payload whose \`reviewDepth\` equals the approved plan's \`finalReviewPolicy\`.
 
@@ -1079,7 +1217,131 @@ Complete with:
 \`\`\`
 
 If genuinely blocked, call \`flow_feature_complete\` with \`status: "needs_input"\` and an \`outcome\` that explains the blocker and next step. Never fabricate validation or review evidence to force progress.
-`;var J=`# UI quality rubric
+`;var J=`---
+name: flow-test
+description: Test, validate, make test plans, triage failures, and gather Flow validation evidence. Use when selecting checks, running tests, running browser QA for UI changes, classifying failures, or preparing validationRun evidence for flow_feature_complete.
+---
+
+# Flow Test
+
+Use this skill to decide and gather validation evidence. It produces validation
+evidence only: the manager still owns \`flow_feature_complete\`, review payloads,
+plan approval, session closure, and every other Flow state change.
+
+Do not mutate \`.flow/**\`, approve plans, complete features, close sessions, or
+substitute for \`flow-review\`. If Flow tools are unavailable, this skill can still
+produce an advisory validation plan or test summary, but it cannot record Flow
+state.
+
+## Inputs
+
+Start from the smallest concrete surface:
+
+- The approved feature \`summary\`, \`targets\`, and \`validation\` entries when a
+  Flow session exists.
+- The actual diff, changed files, package scripts, docs, and test conventions.
+- Recent command output from this session or from a trusted worker handoff.
+- Any user-stated acceptance criteria, browser target, fixture, or environment
+  constraint.
+
+Prefer repository scripts and local conventions over invented commands. If a
+command has not been run in this session or directly reported by a trusted
+worker with raw outcome, recommend it instead of claiming it passed.
+
+## Select Coverage
+
+Choose checks from changed-surface risk, not from habit:
+
+- **Targeted behavior**: unit, integration, CLI, route, or component tests that
+  exercise the changed behavior and would fail without the fix.
+- **Integration and persistence**: database, filesystem, API, adapter, lock, or
+  serialization paths touched by the feature.
+- **Browser or e2e**: user-visible workflows, responsive states, accessibility
+  basics, form flows, and screenshots when a local target and browser tooling
+  are available.
+- **Package and build shape**: typecheck, lint, build, generated distribution,
+  or schema checks when public contracts, bundling, or package exports changed.
+- **Docs and mechanical edits**: markdown rendering, link/path sanity, spelling
+  of commands, or the narrowest project check when behavior is unchanged.
+- **Cleanup/refactor**: behavior-preservation tests plus the relevant broad
+  check; formatting alone is not evidence of preserved behavior.
+- **Final feature**: the repository's broad gate, full relevant suite, build, or
+  equivalent release gate before \`validationScope: "broad"\` is recorded.
+
+If the planned coverage is weaker than the risk, say so explicitly and list the
+missing evidence.
+
+## Run Discipline
+
+For each check:
+
+1. State the hypothesis: what behavior or contract the check is expected to
+   prove.
+2. Run the command or manual workflow when the environment allows it.
+3. Record exact command, status, and observed result.
+4. If it fails, classify the failure before editing:
+   - product failure
+   - test failure
+   - environment failure
+   - pre-existing failure
+   - flake
+   - unrelated failure
+5. Before a fix attempt, write a short failure hypothesis that names the likely
+   cause and the file or behavior to inspect.
+6. After a fix, rerun the failing check and one appropriate regression check.
+
+Do not trim failure output so far that the manager cannot understand the
+failure. Do redact secrets and credentials.
+
+## Browser and Exploratory QA
+
+For meaningful UI or browser workflow changes, browser evidence is expected when
+a local target can run:
+
+- Open the relevant route or story with the available browser tooling.
+- Exercise the main changed workflow, not only page load.
+- Check desktop and mobile breakpoints when responsive behavior is in scope.
+- Capture screenshots or describe the viewport, route, steps, and observed
+  result.
+- Inspect visible error states, empty states, long labels, focus behavior, and
+  console or network failures when the tooling exposes them.
+
+Browser claims are evidence requirements, not guaranteed coverage. If browser
+tooling, credentials, seed data, or a local server is unavailable, record the
+gap and provide the next-best evidence such as component tests, build output, or
+static inspection.
+
+Exploratory QA should be scenario-based. Name the user path, the state varied,
+and the expected outcome. Do not replace automated evidence with exploratory QA
+when a practical automated check exists.
+
+## Output
+
+Return a concise validation summary and a \`validationRun\` array that the manager
+can record through \`flow_feature_complete\` if it accepts the evidence:
+
+\`\`\`json
+{
+  "validationRun": [
+    {
+      "command": "bun test tests/foo.test.ts",
+      "status": "passed",
+      "summary": "3 pass; covered foo creation, duplicate rejection, and reset behavior"
+    }
+  ],
+  "testSummary": "Targeted behavior and package shape passed. Browser evidence was not applicable.",
+  "gaps": []
+}
+\`\`\`
+
+Only passing checks belong in \`validationRun\` for completion. Failed, skipped,
+or unavailable checks belong in \`testSummary\`, \`gaps\`, or a blocker outcome.
+Each summary must state what behavior, file set, route, command, or state was
+covered. Static inspection alone is a gap for behavioral changes.
+
+Never relabel a failed command as passed, invent output, or use "not run" as
+completion evidence.
+`;var Z=`# UI quality rubric
 
 Use this rubric for frontend planning, implementation, and review.
 
@@ -1123,7 +1385,7 @@ class; severity; location or screenshot area; evidence inspected; user impact; f
 \`\`\`
 
 Blocking UI findings are issues that prevent task completion, hide required information, break accessibility basics, create incoherent layout at supported sizes, or make the visual success claim unverifiable.
-`;var Z=`# Visual verification workflow
+`;var H=`# Visual verification workflow
 
 Use this workflow when UI changes can be run locally. Flow execution may create visual evidence; Flow review usually assesses recorded evidence because the reviewer is read-only.
 
@@ -1163,9 +1425,9 @@ Record the reason and use the strongest available substitute:
 - code inspection against existing component patterns.
 
 Do not claim visual polish was verified if no visual artifact was inspected.
-`;var Q=`---
+`;var ee=`---
 name: flow-ui-quality
-description: Flow guidance for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, and avoiding generic AI-generated UI. Use when planning, executing, or reviewing frontend pages, components, dashboards, visual redesigns, interaction states, screenshots, or browser-verified UI work.
+description: Review and improve frontend UI quality for Flow work. Use for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, interaction states, screenshots, browser-verified UI work, and avoiding generic AI-generated UI.
 ---
 
 # Flow UI quality
@@ -1191,6 +1453,9 @@ Use this skill when Flow work changes what a user sees or how they interact with
 ## Verify visually
 
 - For meaningful UI changes, run the app and capture screenshots when a local browser target is available.
+- For browser-driven QA, route selection, failure classification, and
+  \`validationRun\` summaries, load \`flow-test\`. Keep visual judgment, design
+  quality, and screenshot assessment in \`flow-ui-quality\`.
 - Check desktop and mobile breakpoints, not only the viewport you developed in.
 - Verify text does not overlap, truncate unintentionally, or escape controls; long labels and empty/error states must fit.
 - Compare against provided screenshots, design references, or the stated product intent. List meaningful differences and fix the ones that violate the goal.
@@ -1208,16 +1473,16 @@ Approve only when the interface is both useful and inspectable:
 - Screenshot/browser evidence supports the claim whenever feasible.
 
 Never approve a UI change based only on code shape. If users will judge it visually, Flow evidence should include visual inspection.
-`;var w=[{name:"flow",files:[{relativePath:"SKILL.md",content:B},{relativePath:"references/recovery-playbook.md",content:O},{relativePath:"references/parallel-orchestration.md",content:W},{relativePath:"references/handoff-format.md",content:j},{relativePath:"references/verification-gates.md",content:z}]},{name:"flow-plan",files:[{relativePath:"SKILL.md",content:M},{relativePath:"references/planning-examples.md",content:G},{relativePath:"references/parallel-discovery.md",content:S}]},{name:"flow-run",files:[{relativePath:"SKILL.md",content:Y},{relativePath:"references/validation-rubric.md",content:X},{relativePath:"references/audit-rubric.md",content:K}]},{name:"flow-review",files:[{relativePath:"SKILL.md",content:$},{relativePath:"references/review-rubric.md",content:L}]},{name:"flow-deslop",files:[{relativePath:"SKILL.md",content:E},{relativePath:"references/smell-rubric.md",content:V},{relativePath:"references/refactor-workflow.md",content:N}]},{name:"flow-ui-quality",files:[{relativePath:"SKILL.md",content:Q},{relativePath:"references/ui-rubric.md",content:J},{relativePath:"references/visual-verification.md",content:Z}]}];var U=".flow-skill-version";function x(){return process.env.HOME??process.env.USERPROFILE??""}function q(e=x()){return l(e,".config","opencode","skills")}function _(e){return Fe("sha256").update(e).digest("hex")}function b(e,a){return[`version=${a}`,...e.files.map((t)=>`file=${t.relativePath} sha256=${_(t.content)}`),""].join(`
-`)}async function f(e){try{return await Ue(e,"utf8")}catch(a){if(a.code==="ENOENT")return null;throw a}}function A(e){let a=new Map;if(!e)return a;for(let t of e.split(/\r?\n/)){let r=/^file=(.+) sha256=([a-f0-9]{64})$/.exec(t)??/^file=(.+)=sha256:([a-f0-9]{64})$/.exec(t);if(r?.[1]&&r[2])a.set(r[1],r[2]);let n=/^hash=sha256:([a-f0-9]{64})$/.exec(t);if(n?.[1]&&!a.has("SKILL.md"))a.set("SKILL.md",n[1])}return a}function je(e){if(!e)return null;for(let a of e.split(/\r?\n/)){let t=/^version=(.+)$/.exec(a);if(t?.[1])return t[1]}return null}function k(e,a){let t=Pe(l(e,...a.split("/")));if(t!==e&&t.startsWith(`${e}${De}`))return t;throw Error(`Unsafe skill file path '${a}'.`)}async function We(e,a,t){let r=l(t,e.name),n=l(r,U),s=await f(n),d=A(s);if(await f(l(r,"SKILL.md"))!==null&&s===null)return{name:e.name,action:"skipped_foreign"};let p=!1,m=!1;for(let o of e.files){let i=k(r,o.relativePath),u=await f(i);if(u===o.content)continue;p=!0;let v=d.get(o.relativePath);if(u!==null&&(v?_(u)!==v:s!==null))await y(`${i}.backup`,u,"utf8"),m=!0}if(!p&&s===b(e,a))return{name:e.name,action:"unchanged"};if(!p)return await y(n,b(e,a),"utf8"),{name:e.name,action:"marker_updated"};let g=s!==null;for(let o of e.files){let i=k(r,o.relativePath);await Ce(Te(i),{recursive:!0}),await y(i,o.content,"utf8")}return await y(n,b(e,a),"utf8"),{name:e.name,action:m?"updated_with_backup":g?"updated":"installed"}}function Oe(){return w.map((e)=>e.name)}function ze(e){return`npx -y opencode-plugin-flow@${e} doctor`}function T(){if(process.env.npm_package_version)return process.env.npm_package_version;try{let e=Ae(import.meta.url);for(let a of["../package.json","../../package.json"])try{let t=e(a);if(t.version)return t.version}catch{}}catch{}return"0.0.0"}async function ae(e,a=x()){let t=q(a);return Promise.all(w.map((r)=>We(r,e,t)))}async function te(e=T(),a=x()){let t=q(a),r=new Set(Oe()),n=await Promise.all(w.map(async(o)=>{let i=l(t,o.name),u=await f(l(i,U)),v=je(u),P=A(u);if(await f(l(i,"SKILL.md"))===null)return{name:o.name,path:i,status:"missing",markerVersion:v,missingFiles:o.files.map((h)=>h.relativePath),editedFiles:[],outdatedFiles:[]};if(u===null)return{name:o.name,path:i,status:"foreign",markerVersion:v,missingFiles:[],editedFiles:[],outdatedFiles:[]};let I=[],R=[],F=[];for(let h of o.files){let C=await f(k(i,h.relativePath));if(C===null){I.push(h.relativePath);continue}if(C===h.content)continue;let D=P.get(h.relativePath);if(D&&_(C)!==D){R.push(h.relativePath);continue}F.push(h.relativePath)}let ne=u!==b(o,e),se=I.length>0?"incomplete":R.length>0?"edited":ne||F.length>0?"outdated":"ok";return{name:o.name,path:i,status:se,markerVersion:v,missingFiles:I,editedFiles:R,outdatedFiles:F}})),s=[];try{s=await ee(t)}catch(o){if(o.code!=="ENOENT")throw o}let d=s.filter((o)=>(o==="flow"||o.startsWith("flow-"))&&!r.has(o)).map((o)=>l(t,o)),c=n.filter((o)=>["missing","incomplete","outdated"].includes(o.status)).map((o)=>o.name),p=n.filter((o)=>["foreign","edited"].includes(o.status)).map((o)=>o.name),m=p.length>0,g=c.length>0;return{status:m?"action_required":g?"sync_required":"ok",version:e,root:t,expectedSkills:[...r],skills:n,syncRequiredSkills:c,actionRequiredSkills:p,unmanagedFlowSkills:d}}function H(e,a,t){if(t.length===0)return;e.push(`- ${a}: ${t.join(", ")}`)}function oe(e){let a=["Flow doctor",`- status: ${e.status}`,`- plugin version: ${e.version}`,`- skills root: ${e.root}`,`- expected skills: ${e.expectedSkills.join(", ")}`];H(a,"startup sync can install/update",e.syncRequiredSkills),H(a,"needs user decision",e.actionRequiredSkills),a.push("","Skills:");for(let t of e.skills){if(a.push(`- ${t.name}: ${t.status} (${t.path})${t.markerVersion?` marker=${t.markerVersion}`:""}`),t.missingFiles.length>0)a.push(`  missing: ${t.missingFiles.join(", ")}`);if(t.editedFiles.length>0)a.push(`  edited: ${t.editedFiles.join(", ")}`);if(t.outdatedFiles.length>0)a.push(`  outdated: ${t.outdatedFiles.join(", ")}`)}if(e.unmanagedFlowSkills.length>0){a.push("","Unmanaged Flow-like skill folders:");for(let t of e.unmanagedFlowSkills)a.push(`- ${t}`)}if(a.push("","Recommendation:"),e.status==="ok")a.push("- Flow skills are present and current.");else if(e.status==="sync_required")a.push("- Start or restart OpenCode with opencode-plugin-flow enabled so startup sync can install or update the listed skills. If Flow then reports restart_required, restart OpenCode once more so the refreshed skill registry is used.");else a.push("- Resolve user-owned or edited managed skill folders, then restart OpenCode. Move a folder aside to let Flow recreate it, or keep it intentionally as a local override.");return a.push(`- Details command: ${ze(e.version)}`),`${a.join(`
+`;var w=[{name:"flow",files:[{relativePath:"SKILL.md",content:z},{relativePath:"references/recovery-playbook.md",content:W},{relativePath:"references/parallel-orchestration.md",content:B},{relativePath:"references/handoff-format.md",content:j},{relativePath:"references/verification-gates.md",content:S}]},{name:"flow-plan",files:[{relativePath:"SKILL.md",content:M},{relativePath:"references/planning-examples.md",content:L},{relativePath:"references/parallel-discovery.md",content:G}]},{name:"flow-run",files:[{relativePath:"SKILL.md",content:Y},{relativePath:"references/validation-rubric.md",content:X},{relativePath:"references/audit-rubric.md",content:Q}]},{name:"flow-test",files:[{relativePath:"SKILL.md",content:J}]},{name:"flow-review",files:[{relativePath:"SKILL.md",content:$},{relativePath:"references/review-rubric.md",content:K}]},{name:"flow-deslop",files:[{relativePath:"SKILL.md",content:V},{relativePath:"references/smell-rubric.md",content:N},{relativePath:"references/refactor-workflow.md",content:E}]},{name:"flow-ui-quality",files:[{relativePath:"SKILL.md",content:ee},{relativePath:"references/ui-rubric.md",content:Z},{relativePath:"references/visual-verification.md",content:H}]},{name:"flow-commit",files:[{relativePath:"SKILL.md",content:O}]}];var C=".flow-skill-version";function x(){return process.env.HOME??process.env.USERPROFILE??""}function A(e=x()){return l(e,".config","opencode","skills")}function _(e){return qe("sha256").update(e).digest("hex")}function b(e,a){return[`version=${a}`,...e.files.map((t)=>`file=${t.relativePath} sha256=${_(t.content)}`),""].join(`
+`)}async function f(e){try{return await Te(e,"utf8")}catch(a){if(a.code==="ENOENT")return null;throw a}}function q(e){let a=new Map;if(!e)return a;for(let t of e.split(/\r?\n/)){let r=/^file=(.+) sha256=([a-f0-9]{64})$/.exec(t)??/^file=(.+)=sha256:([a-f0-9]{64})$/.exec(t);if(r?.[1]&&r[2])a.set(r[1],r[2]);let s=/^hash=sha256:([a-f0-9]{64})$/.exec(t);if(s?.[1]&&!a.has("SKILL.md"))a.set("SKILL.md",s[1])}return a}function ze(e){if(!e)return null;for(let a of e.split(/\r?\n/)){let t=/^version=(.+)$/.exec(a);if(t?.[1])return t[1]}return null}function k(e,a){let t=We(l(e,...a.split("/")));if(t!==e&&t.startsWith(`${e}${Se}`))return t;throw Error(`Unsafe skill file path '${a}'.`)}async function Oe(e,a,t){let r=l(t,e.name),s=l(r,C),n=await f(s),d=q(n);if(await f(l(r,"SKILL.md"))!==null&&n===null)return{name:e.name,action:"skipped_foreign"};let p=!1,m=!1;for(let o of e.files){let i=k(r,o.relativePath),u=await f(i);if(u===o.content)continue;p=!0;let v=d.get(o.relativePath);if(u!==null&&(v?_(u)!==v:n!==null))await y(`${i}.backup`,u,"utf8"),m=!0}if(!p&&n===b(e,a))return{name:e.name,action:"unchanged"};if(!p)return await y(s,b(e,a),"utf8"),{name:e.name,action:"marker_updated"};let g=n!==null;for(let o of e.files){let i=k(r,o.relativePath);await Pe(Be(i),{recursive:!0}),await y(i,o.content,"utf8")}return await y(s,b(e,a),"utf8"),{name:e.name,action:m?"updated_with_backup":g?"updated":"installed"}}function Ee(){return w.map((e)=>e.name)}function Ne(e){return`npx -y opencode-plugin-flow@${e} doctor`}function P(){if(process.env.npm_package_version)return process.env.npm_package_version;try{let e=je(import.meta.url);for(let a of["../package.json","../../package.json"])try{let t=e(a);if(t.version)return t.version}catch{}}catch{}return"0.0.0"}async function oe(e,a=x()){let t=A(a);return Promise.all(w.map((r)=>Oe(r,e,t)))}async function re(e=P(),a=x()){let t=A(a),r=new Set(Ee()),s=await Promise.all(w.map(async(o)=>{let i=l(t,o.name),u=await f(l(i,C)),v=ze(u),T=q(u);if(await f(l(i,"SKILL.md"))===null)return{name:o.name,path:i,status:"missing",markerVersion:v,missingFiles:o.files.map((h)=>h.relativePath),editedFiles:[],outdatedFiles:[]};if(u===null)return{name:o.name,path:i,status:"foreign",markerVersion:v,missingFiles:[],editedFiles:[],outdatedFiles:[]};let I=[],R=[],F=[];for(let h of o.files){let U=await f(k(i,h.relativePath));if(U===null){I.push(h.relativePath);continue}if(U===h.content)continue;let D=T.get(h.relativePath);if(D&&_(U)!==D){R.push(h.relativePath);continue}F.push(h.relativePath)}let ie=u!==b(o,e),ce=I.length>0?"incomplete":R.length>0?"edited":ie||F.length>0?"outdated":"ok";return{name:o.name,path:i,status:ce,markerVersion:v,missingFiles:I,editedFiles:R,outdatedFiles:F}})),n=[];try{n=await te(t)}catch(o){if(o.code!=="ENOENT")throw o}let d=n.filter((o)=>(o==="flow"||o.startsWith("flow-"))&&!r.has(o)).map((o)=>l(t,o)),c=s.filter((o)=>["missing","incomplete","outdated"].includes(o.status)).map((o)=>o.name),p=s.filter((o)=>["foreign","edited"].includes(o.status)).map((o)=>o.name),m=p.length>0,g=c.length>0;return{status:m?"action_required":g?"sync_required":"ok",version:e,root:t,expectedSkills:[...r],skills:s,syncRequiredSkills:c,actionRequiredSkills:p,unmanagedFlowSkills:d}}function ae(e,a,t){if(t.length===0)return;e.push(`- ${a}: ${t.join(", ")}`)}function se(e){let a=["Flow doctor",`- status: ${e.status}`,`- plugin version: ${e.version}`,`- skills root: ${e.root}`,`- expected skills: ${e.expectedSkills.join(", ")}`];ae(a,"startup sync can install/update",e.syncRequiredSkills),ae(a,"needs user decision",e.actionRequiredSkills),a.push("","Skills:");for(let t of e.skills){if(a.push(`- ${t.name}: ${t.status} (${t.path})${t.markerVersion?` marker=${t.markerVersion}`:""}`),t.missingFiles.length>0)a.push(`  missing: ${t.missingFiles.join(", ")}`);if(t.editedFiles.length>0)a.push(`  edited: ${t.editedFiles.join(", ")}`);if(t.outdatedFiles.length>0)a.push(`  outdated: ${t.outdatedFiles.join(", ")}`)}if(e.unmanagedFlowSkills.length>0){a.push("","Unmanaged Flow-like skill folders:");for(let t of e.unmanagedFlowSkills)a.push(`- ${t}`)}if(a.push("","Recommendation:"),e.status==="ok")a.push("- Flow skills are present and current.");else if(e.status==="sync_required")a.push("- Start or restart OpenCode with opencode-plugin-flow enabled so startup sync can install or update the listed skills. If Flow then reports restart_required, restart OpenCode once more so the refreshed skill registry is used.");else a.push("- Resolve user-owned or edited managed skill folders, then restart OpenCode. Move a folder aside to let Flow recreate it, or keep it intentionally as a local override.");return a.push(`- Details command: ${Ne(e.version)}`),`${a.join(`
 `)}
-`}async function re(e=x()){let a=q(e),t=[],r=[],n;try{n=await ee(a)}catch(s){if(s.code==="ENOENT")return{removed:t,kept:r};throw s}for(let s of n){if(s!=="flow"&&!s.startsWith("flow-"))continue;let d=l(a,s),c=await f(l(d,U));if(c===null){r.push(d);continue}let p=A(c),m=!1;for(let[g,o]of p){let i=await f(k(d,g));if(i!==null&&_(i)!==o){m=!0;break}}if(m){r.push(d);continue}await qe(d,{recursive:!0,force:!0}),t.push(d)}return{removed:t,kept:r}}async function Be(e){let a=e[2];if(a!=="uninstall"&&a!=="doctor"&&a!=="sync"){process.stderr.write(`usage: opencode-plugin-flow <doctor|sync|uninstall>
-`),process.exitCode=2;return}if(a==="doctor"){process.stdout.write(oe(await te()));return}if(a==="sync"){let r=T(),n=await ae(r),s=n.filter((c)=>["installed","updated","updated_with_backup"].includes(c.action)),d=n.filter((c)=>c.action==="skipped_foreign");process.stdout.write(`Flow skill sync (${r})
-`);for(let c of n)process.stdout.write(`- ${c.name}: ${c.action}
-`);if(s.length>0)process.stdout.write(`Restart OpenCode so the refreshed skill registry is used.
+`}async function ne(e=x()){let a=A(e),t=[],r=[],s;try{s=await te(a)}catch(n){if(n.code==="ENOENT")return{removed:t,kept:r};throw n}for(let n of s){if(n!=="flow"&&!n.startsWith("flow-"))continue;let d=l(a,n),c=await f(l(d,C));if(c===null){r.push(d);continue}let p=q(c),m=!1;for(let[g,o]of p){let i=await f(k(d,g));if(i!==null&&_(i)!==o){m=!0;break}}if(m){r.push(d);continue}await De(d,{recursive:!0,force:!0}),t.push(d)}return{removed:t,kept:r}}async function Ve(e){let a=e[2];if(a!=="uninstall"&&a!=="doctor"&&a!=="sync"){process.stderr.write(`usage: opencode-plugin-flow <doctor|sync|uninstall>
+`),process.exitCode=2;return}if(a==="doctor"){process.stdout.write(se(await re()));return}if(a==="sync"){let r=P(),s=await oe(r),n=s.filter((c)=>["installed","updated","updated_with_backup"].includes(c.action)),d=s.filter((c)=>c.action==="skipped_foreign");process.stdout.write(`Flow skill sync (${r})
+`);for(let c of s)process.stdout.write(`- ${c.name}: ${c.action}
+`);if(n.length>0)process.stdout.write(`Restart OpenCode so the refreshed skill registry is used.
 `);if(d.length>0)process.stdout.write(`Some managed skill folders are user-owned or edited; run doctor for repair guidance.
-`);return}let t=await re();for(let r of t.removed)process.stdout.write(`Removed Flow skill: ${r}
+`);return}let t=await ne();for(let r of t.removed)process.stdout.write(`Removed Flow skill: ${r}
 `);for(let r of t.kept)process.stdout.write(`Kept non-Flow or user-edited skill: ${r}
 `);process.stdout.write(`Remove opencode-plugin-flow from your OpenCode plugin config and restart OpenCode.
-`)}Be(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
+`)}Ve(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
 `),process.exitCode=1});