opencode-agent-skill 10.0.0 → 11.0.0

package/CHANGELOG.md

@@ -6,6 +6,73 @@ The project follows Semantic Versioning.
 
 ## [Unreleased]
 
+## [11.0.0] - 2026-09-22
+
+### Released
+- Promoted V11 perception-aware adaptive execution to stable after the full local CI gate passed on Windows with 234 tests total, 232 passed, 0 failed and 2 platform-specific skips.
+- Stable npm installs use the default `latest` dist-tag, so users install with `npm install -g opencode-agent-skill`.
+- Includes content-addressed Evidence Store, adaptive EvidenceBudget/context externalization, stable-prefix prompt telemetry, capability-aware model routing, visual geometry receipts, deterministic PNG diff/crop, responsive/design-token inspection, optional Playwright browser inspection, cost-aware dynamic workflow scheduling, 48 focused skills and 12 subagents.
+
+### Verified
+- Syntax: 178 JavaScript modules.
+- Catalog: 48 skills, 11 commands and 12 subagents.
+- Router: 129 cases, 294/294 required routes and 61/61 negative guards.
+- V11 contracts: 13 tasks across 6 categories and 15 required runtime files.
+- Live/long/polyglot fixture validation: 20 / 5 / 8 tasks.
+- npm pack dry-run, packed-install smoke and plain one-command install/resource auto-sync smoke: PASS.
+
+### Changed
+- Package version is 11.0.0.
+- V11 becomes the stable npm release line; V10 remains in Git history as the previous stable release.
+
+
+### V11 dev.2
+- Added project-local, fail-closed Playwright browser inspection that returns bounded semantic elements, bounding boxes, computed visual properties and a screenshot path while treating page content as untrusted evidence.
+- Exposed browser inspection through CLI and the OpenCode V2 router without making Playwright a required package dependency.
+- Fixed duplicate `ui_layout` router tool registration and aligned durable context packs with V11 context schema version 6.
+- Extended V11 validation and regression coverage for the browser runtime.
+- Package development version is 11.0.0-dev.2.
+
+## [11.0.0-dev.1] - 2026-09-22
+
+### Added
+- Adaptive context engine that externalizes oversized source/test/reference excerpts into content-addressed evidence pointers while keeping bounded inline previews.
+- Deterministic UI layout and design-token tools exposed to the OpenCode V2 runtime.
+- Cost- and modality-aware workflow scheduling with inline thresholds, deterministic-first waves, independent LLM/vision concurrency and bounded wave cost.
+- Repeated-stable prompt ratio telemetry and an optional fail-closed ablation gate for repeated input efficiency.
+- Stronger V11 contract coverage for adaptive context, UI inspection and evidence externalization.
+
+### Changed
+- V11 router metadata now reports version 11.
+- Task context packs transport large contextual evidence through `evidence:sha256` pointers and report externalized byte/ref counts.
+- Capability-aware model routing fails closed when an enabled configured model set cannot satisfy required capabilities such as vision/browser.
+- Package development version is 11.0.0-dev.1.
+
+### Fixed
+- V11 eval-report regression tests now account for expanded adaptive telemetry coverage instead of using the old V10-only telemetry shape.
+
+## [11.0.0-dev.0] - 2026-09-22
+
+### Added
+- Content-addressed Evidence Store with bounded retrieval, deduplication and garbage collection.
+- Adaptive Evidence Budget planning and context-manifest integration for evidence-efficient execution.
+- Prompt stable-prefix/cache telemetry for repeated-input measurement.
+- Capability registry and capability-aware model selection for coding, reasoning, tools, vision, browser, filesystem and long-context needs.
+- Visual specification, geometry receipts, responsive viewport matrix, dependency-free PNG decode/diff/crop and bounded visual repair planning.
+- Browser QA adapter with CLI-first verification planning, targeted semantic evidence and explicit untrusted-page security boundaries.
+- Cost-aware dynamic workflow scheduler separating deterministic work from LLM/vision work.
+- Skill-quality linting for entrypoint size, metadata and routing-description collision detection.
+- Nine V11 skills: visual-fidelity, browser-qa, design-source, responsive-verification, component-visual-testing, browser-security, skill-authoring, skill-evaluation and dynamic-workflow.
+- Two V11 subagents: visual-verifier and merge-arbiter.
+- Optional Hermes sidecar workflow contract with evidence-pointer transport.
+- V11 Control Center evidence-store/runtime telemetry and V11-specific tests/eval routing cases.
+
+### Changed
+- Model policy schema supports per-model capability metadata plus cost, latency and quality hints.
+- Adaptive model resolution can select configured models by required task capabilities.
+- OpenCode V2 router recognizes visual/browser/design/skill-workflow intents and keeps FAST routing selective.
+- Package version is 11.0.0-dev.0 while npm latest remains V10 stable until V11 release gates pass.
+
 ## [10.0.0] - 2026-09-22
 
 ### Released

package/README.md

@@ -1,6 +1,6 @@
 # OpenCode Universal Engineering System (UES)
 
-> **V10 stable: 10.0.0** — bản phát hành chính thức của V10, dùng trực tiếp qua npm `latest`.
+> **V11 stable: 11.0.0** — perception-aware adaptive execution engine với evidence-efficient context, capability routing và visual/browser verification.
 > UES là bộ công cụ hỗ trợ OpenCode xử lý dự án lớn, tác vụ dài và quy trình kỹ thuật cần kiểm chứng bằng bằng chứng thực tế.
 
 [![npm version](https://img.shields.io/npm/v/opencode-agent-skill.svg)](https://www.npmjs.com/package/opencode-agent-skill)
@@ -80,6 +80,49 @@ ocskill dashboard . --serve
 
 ---
 
+## V11 có gì?
+
+V11 chuyển UES từ một reliability harness thành **perception-aware adaptive execution engine**. Mục tiêu là model yếu chỉ nhận đúng bằng chứng cần thiết, dùng đúng capability/model/tool và có thể kiểm chứng UI bằng semantic structure + geometry + pixels thay vì đoán từ screenshot.
+
+- content-addressed Evidence Store dưới `.ues-cache/evidence-v1/`; output lớn được lưu theo SHA-256 và context nhận bounded excerpt + `evidence:sha256:...` pointer;
+- adaptive EvidenceBudget chia context cho instructions/task/source/tests/references/history/tools theo rủi ro và loại task thay vì luôn tiêu hết FAST/STANDARD/DEEP budget;
+- prompt-envelope telemetry tách stable prefix và dynamic tail để đo cacheable ratio/repeated stable input;
+- capability-aware model routing bổ sung `vision`, `browser`, `reasoning`, `toolCalling`, `filesystem`, `longContext` nhưng vẫn giữ light/standard/heavy để tương thích;
+- `VISUAL_SPEC.json` + geometry receipt kiểm tra vị trí/kích thước element có tolerance rõ ràng;
+- zero-dependency PNG diff/crop định vị vùng pixel sai rồi chỉ đưa crop cần thiết cho vision model;
+- browser QA dùng targeted semantic/accessibility evidence + bounding boxes + screenshots; webpage content luôn được xem là untrusted;
+- responsive viewport matrix và component visual testing/Storybook routing;
+- dynamic workflow scheduler tách deterministic task khỏi LLM/vision fan-out, serialize overlapping writers và giới hạn concurrency;
+- skill linter đo entrypoint size và description collisions; catalog tăng từ 39 lên **48 skills** nhưng router chỉ load skill có tín hiệu hẹp;
+- hai subagent mới: `ues-visual-verifier` và `ues-merge-arbiter`, tổng **12 subagents**;
+- Hermes được nâng thành optional sidecar: UES vẫn sở hữu durable state/evidence/safety, Hermes chỉ nhận bounded schedule/context khi được dùng;
+- Control Center hiển thị Evidence Store và V11 runtime efficiency state.
+
+Các CLI V11 chính:
+
+```cmd
+ocskill store status .
+ocskill store get evidence:sha256:<hash> . --max 12000
+ocskill capabilities "match this screenshot in the browser"
+ocskill visual spec VISUAL_SPEC.json
+ocskill visual geometry VISUAL_SPEC.json actual-boxes.json
+ocskill visual compare expected.png actual.png --threshold 16
+ocskill visual crop actual.png failed-region.png --x 10 --y 20 --width 300 --height 120
+ocskill visual viewports
+ocskill browser capability .
+ocskill browser plan http://localhost:3000 --target Checkout
+ocskill browser inspect http://localhost:3000 . --selector "button" --width 1440 --height 900
+ocskill ui tokens src/styles.css
+ocskill ui layout boxes.json --width 390 --height 844
+ocskill workflow-plan PLAN.json --max-concurrent 4
+ocskill skills lint .
+ocskill models capability provider/model --vision on --browser on --quality 0.9
+```
+
+V11 stable được promote sau full local CI trên Windows PASS: 234 tests, 232 pass, 0 fail, 2 platform-specific skips; router/contract/package/install smoke đều PASS. Stable npm install dùng `npm install -g opencode-agent-skill`.
+
+---
+
 ## V10 có gì?
 
 V10 tập trung vào **minimum context necessary for maximum task success**: giảm context luôn nạp nhưng không cắt các lớp correctness, verification hay recovery.
@@ -281,6 +324,8 @@ Child session không được tự động merge, push, publish hoặc deploy.
 | `ues-critic` | Tìm giả định sai, counterexample và điểm yếu trong phương án |
 | `ues-verifier` | Xác minh độc lập theo acceptance criteria |
 | `ues-integration-verifier` | Kiểm tra tích hợp giữa nhiều task và luồng end-to-end |
+| `ues-visual-verifier` | Xác minh độc lập screenshot/geometry/responsive/interaction mà không sửa code |
+| `ues-merge-arbiter` | Hòa giải conflict giữa các task đã verify theo intent/evidence, không push/publish/deploy |
 
 `ues-executor` là subagent chính có quyền sửa code theo scope được giao. Các agent còn lại chủ yếu phục vụ phân tích, review và xác minh.
 
@@ -386,7 +431,7 @@ ocskill work status checkout .
 
 ## Skills
 
-UES hiện có **39 skills**. Router chỉ chọn các skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task.
+V11 development hiện có **48 skills**; V10 stable có 39. Router vẫn chỉ chọn tập skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task. Router chỉ chọn các skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task.
 
 Một số process skill quan trọng:
 
@@ -491,7 +536,7 @@ Proposal có `shadowRequired` chỉ được đưa trở lại context sau khi v
 
 ## Hermes adapter
 
-UES hỗ trợ Hermes theo dạng adapter tùy chọn, không nhúng Hermes runtime vào core:
+V11 giữ Hermes theo dạng **optional sidecar**, không nhúng Hermes runtime vào core. UES vẫn sở hữu durable state, evidence và safety boundaries:
 
 ```cmd
 ocskill hermes status
@@ -580,6 +625,7 @@ Kiểm tra long-horizon và polyglot suite:
 ```cmd
 npm run evals:long:validate
 npm run evals:polyglot:validate
+npm run evals:v11:validate
 ```
 
 Chạy benchmark với model thật:

package/bin/ocskill.mjs

@@ -59,13 +59,22 @@ import {
 } from "../lib/task-engine.mjs"
 import { reviewScope } from "../lib/review-scope.mjs"
 import { buildVerificationPlan } from "../lib/verification-plan.mjs"
-import { resolveAdaptiveModel, resolveModel } from "../lib/model-policy.mjs"
+import { resolveAdaptiveModel, resolveCapabilityModel, resolveModel } from "../lib/model-policy.mjs"
 import { createVerificationReceipt } from "../lib/evidence-receipt.mjs"
 import { classifyEngineeringTask } from "../lib/orchestrator-policy.mjs"
 import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
 import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
-import { hermesStatus, buildHermesDelegationPrompt, hermesOneShotArgs } from "../lib/hermes-bridge.mjs"
+import { hermesStatus, buildHermesDelegationPrompt, buildHermesWorkflowPrompt, hermesOneShotArgs, hermesSidecarPlan } from "../lib/hermes-bridge.mjs"
 import { readModelPolicy, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
+import { evidenceStoreStatus, gcEvidenceStore, getEvidence, putEvidence } from "../lib/evidence-store.mjs"
+import { inferTaskCapabilities } from "../lib/capability-registry.mjs"
+import { browserCapability, buildBrowserVerificationPlan } from "../lib/browser-adapter.mjs"
+import { inspectBrowserPage, summarizeBrowserInspection } from "../lib/browser-runtime.mjs"
+import { comparePngFiles, cropPngFile } from "../lib/png-diff.mjs"
+import { createGeometryReceipt, responsiveViewportMatrix, validateVisualSpec } from "../lib/visual-spec.mjs"
+import { planDynamicWorkflow } from "../lib/dynamic-workflow.mjs"
+import { lintSkillCatalog } from "../lib/skill-quality.mjs"
+import { designTokenEvidence, extractDesignTokens, inspectResponsiveLayout } from "../lib/ui-inspector.mjs"
 import {
   clipOutput,
   errorMessage,
@@ -117,7 +126,14 @@ Usage:
   ocskill sandbox <action> ...  Create, integrate and clean isolated Git worktree sandboxes
                               Also supports capability/exec for fail-closed container verification
   ocskill learn <action> ...    Analyze eval traces and promote benchmark-validated lessons
-  ocskill hermes <action> ...   Optional Hermes adapter/status
+  ocskill hermes <action> ...   Optional Hermes sidecar/status/task/workflow planning
+  ocskill store <status|put|get|gc> ... Content-addressed evidence storage and bounded retrieval
+  ocskill capabilities <text>     Infer required execution/model capabilities
+  ocskill visual <action> ...     Geometry receipts, PNG diff/crop and viewport matrix
+  ocskill browser <action> ...    Browser capability, plan and bounded Playwright inspection
+  ocskill ui <tokens|layout> ...  Extract design tokens or verify responsive geometry
+  ocskill workflow-plan <plan>    Cost-aware deterministic/LLM/vision wave schedule
+  ocskill skills lint [dir]       Lint skill size, metadata and routing-description collisions
   ocskill dashboard [dir] [--serve] [--port N]
                               Generate/serve the local UES Control Center
   ocskill models <status|on|off|set|role> ...
@@ -154,6 +170,7 @@ Usage:
     ocskill models on|off
     ocskill models set <light|standard|heavy> <provider/model[#variant]>
     ocskill models role <role> <light|standard|heavy>
+    ocskill models capability <provider/model> [--vision on|off] [--browser on|off] [--reasoning on|off] [--long-context on|off] [--cost low|medium|high] [--latency fast|medium|slow] [--quality 0..1]
 
   --force backs up and replaces/removes state owned by another package.
 `)
@@ -741,7 +758,8 @@ async function modelPolicy() {
   const normalizedAttempt = Number.isInteger(attempt) && attempt > 0 ? attempt : 1
   const taskText = optionValue(args, "--text")
   if (taskText) {
-    printJson(resolveAdaptiveModel(role, normalizedAttempt, classifyEngineeringTask(taskText), policy))
+    const taskPolicy = classifyEngineeringTask(taskText)
+    printJson(resolveCapabilityModel(role, normalizedAttempt, taskText, taskPolicy, policy))
     return
   }
   printJson(resolveModel(role, normalizedAttempt, policy))
@@ -794,6 +812,48 @@ async function modelsControl() {
     return
   }
 
+  if (action === "capability") {
+    const model = args[2]
+    if (!validateModelID(model)) {
+      console.error("Usage: ocskill models capability <provider/model> [capability flags]")
+      process.exitCode = 2
+      return
+    }
+    const current = policy.capabilities?.[model] || {}
+    const boolFlag = (name, prior) => {
+      const value = optionValue(args, name)
+      if (value == null) return prior
+      if (!["on", "off", "true", "false"].includes(String(value).toLowerCase())) throw new Error(name + " must be on/off")
+      return ["on", "true"].includes(String(value).toLowerCase())
+    }
+    const qualityRaw = optionValue(args, "--quality")
+    const quality = qualityRaw == null ? current.quality : Number(qualityRaw)
+    if (qualityRaw != null && (!Number.isFinite(quality) || quality < 0 || quality > 1)) throw new Error("--quality must be from 0 to 1")
+    const cost = optionValue(args, "--cost") || current.costClass
+    const latency = optionValue(args, "--latency") || current.latencyClass
+    if (cost && !["low", "medium", "high"].includes(cost)) throw new Error("--cost must be low|medium|high")
+    if (latency && !["fast", "medium", "slow"].includes(latency)) throw new Error("--latency must be fast|medium|slow")
+    policy = await writeModelPolicy(getConfigDir(), {
+      capabilities: {
+        [model]: {
+          ...current,
+          coding: boolFlag("--coding", current.coding),
+          reasoning: boolFlag("--reasoning", current.reasoning),
+          toolCalling: boolFlag("--tool-calling", current.toolCalling),
+          vision: boolFlag("--vision", current.vision),
+          browser: boolFlag("--browser", current.browser),
+          filesystem: boolFlag("--filesystem", current.filesystem),
+          longContext: boolFlag("--long-context", current.longContext),
+          ...(cost ? { costClass: cost } : {}),
+          ...(latency ? { latencyClass: latency } : {}),
+          ...(quality != null ? { quality } : {}),
+        },
+      },
+    })
+    printJson(policy)
+    return
+  }
+
   console.error("Usage: ocskill models <status|on|off|set|role> ...")
   process.exitCode = 2
 }
@@ -956,6 +1016,40 @@ async function hermesControl() {
     printJson(hermesStatus())
     return
   }
+  if (action === "workflow" || action === "exec-workflow") {
+    const slug = args[2]
+    const root = positionalArg(args, 3) || process.cwd()
+    if (!slug) {
+      console.error("Usage: ocskill hermes <workflow|exec-workflow> <slug> [dir] [--max-concurrent N]")
+      process.exitCode = 2
+      return
+    }
+    const planFile = path.join(path.resolve(root), ".ues-work", slug, "PLAN.json")
+    const plan = readJsonFile(planFile)
+    const schedule = planDynamicWorkflow(plan.tasks || [], {
+      maxConcurrent: optionInt(args, "--max-concurrent", 4),
+    })
+    const sidecar = hermesSidecarPlan({ mode: "dynamic-workflow", maxConcurrent: schedule.maxConcurrent })
+    const prompt = buildHermesWorkflowPrompt({ slug, goal: plan.goal || null, plan }, schedule)
+    if (action === "workflow") {
+      printJson({ sidecar, schedule, prompt })
+      return
+    }
+    const status = hermesStatus()
+    if (!status.available) {
+      console.error(status.error || "Hermes CLI is unavailable")
+      process.exitCode = 1
+      return
+    }
+    const result = runCapture("hermes", hermesOneShotArgs(prompt), {
+      cwd: path.resolve(root),
+      maxBuffer: 8 * 1024 * 1024,
+    })
+    if (result.stdout) process.stdout.write(result.stdout)
+    if (result.stderr) process.stderr.write(result.stderr)
+    if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
+    return
+  }
   if (action === "prompt" || action === "exec") {
     const slug = args[2]
     const taskID = args[3]
@@ -986,10 +1080,220 @@ async function hermesControl() {
     if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
     return
   }
-  console.error("Usage: ocskill hermes <status|prompt|exec> ...")
+  console.error("Usage: ocskill hermes <status|prompt|exec|workflow|exec-workflow> ...")
   process.exitCode = 2
 }
 
+async function evidenceStoreControl() {
+  const action = args[1] || "status"
+  try {
+    if (action === "status") {
+      printJson(await evidenceStoreStatus(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "put") {
+      const file = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!file) throw new Error("Usage: ocskill store put <file> [dir] [--kind <kind>] [--summary <text>]")
+      const content = readTextFile(file)
+      printJson(await putEvidence(root, content, {
+        kind: optionValue(args, "--kind") || "file",
+        source: path.resolve(file),
+        summary: optionValue(args, "--summary"),
+      }))
+      return
+    }
+    if (action === "get") {
+      const ref = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!ref) throw new Error("Usage: ocskill store get <evidence-ref> [dir] [--max N] [--start N]")
+      printJson(await getEvidence(root, ref, {
+        maxChars: optionInt(args, "--max", 24_000),
+        start: optionInt(args, "--start", 0),
+      }))
+      return
+    }
+    if (action === "gc") {
+      const root = positionalArg(args, 2) || process.cwd()
+      printJson(await gcEvidenceStore(root, {
+        maxEntries: optionInt(args, "--max-entries", 2000),
+        maxAgeDays: optionInt(args, "--max-age-days", 30),
+      }))
+      return
+    }
+    throw new Error("Usage: ocskill store <status|put|get|gc> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function capabilityControl() {
+  const text = args.slice(1).join(" ").trim()
+  if (!text) {
+    console.error("Usage: ocskill capabilities <task text>")
+    process.exitCode = 2
+    return
+  }
+  printJson(inferTaskCapabilities(text))
+}
+
+async function visualControl() {
+  const action = args[1]
+  try {
+    if (action === "spec") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill visual spec <VISUAL_SPEC.json>")
+      printJson(validateVisualSpec(readJsonFile(file)))
+      return
+    }
+    if (action === "geometry") {
+      const specFile = args[2]
+      const actualFile = args[3]
+      if (!specFile || !actualFile) throw new Error("Usage: ocskill visual geometry <VISUAL_SPEC.json> <actual-boxes.json>")
+      printJson(createGeometryReceipt(readJsonFile(specFile), readJsonFile(actualFile)))
+      return
+    }
+    if (action === "compare") {
+      const expected = args[2]
+      const actual = args[3]
+      if (!expected || !actual) throw new Error("Usage: ocskill visual compare <expected.png> <actual.png> [--threshold N] [--max-diff-ratio N]")
+      const threshold = Number(optionValue(args, "--threshold") ?? 16)
+      const maxDiffRatio = Number(optionValue(args, "--max-diff-ratio") ?? 0)
+      printJson(await comparePngFiles(expected, actual, { threshold, maxDiffRatio }))
+      return
+    }
+    if (action === "crop") {
+      const input = args[2]
+      const output = args[3]
+      if (!input || !output) throw new Error("Usage: ocskill visual crop <input.png> <output.png> --x N --y N --width N --height N")
+      printJson(await cropPngFile(input, output, {
+        x: optionInt(args, "--x", 0),
+        y: optionInt(args, "--y", 0),
+        width: optionInt(args, "--width", 1),
+        height: optionInt(args, "--height", 1),
+      }))
+      return
+    }
+    if (action === "viewports") {
+      printJson(responsiveViewportMatrix())
+      return
+    }
+    throw new Error("Usage: ocskill visual <spec|geometry|compare|crop|viewports> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function browserControl() {
+  const action = args[1] || "capability"
+  try {
+    if (action === "capability") {
+      printJson(await browserCapability(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "plan") {
+      const url = args[2] || null
+      printJson(buildBrowserVerificationPlan({
+        url,
+        target: optionValue(args, "--target"),
+      }))
+      return
+    }
+    if (action === "inspect") {
+      const url = args[2]
+      if (!url) throw new Error("Usage: ocskill browser inspect <url> [dir] [--selector <css>] [--screenshot <path>] [--width N] [--height N] [--max-elements N]")
+      const root = positionalArg(args, 3) || process.cwd()
+      const report = await inspectBrowserPage(root, url, {
+        selector: optionValue(args, "--selector"),
+        screenshot: optionValue(args, "--screenshot"),
+        width: optionInt(args, "--width", 1440),
+        height: optionInt(args, "--height", 900),
+        maxElements: optionInt(args, "--max-elements", 80),
+        timeoutMs: optionInt(args, "--timeout-ms", 30000),
+        waitMs: optionInt(args, "--wait-ms", 0),
+        fullPage: !args.includes("--viewport-only"),
+      })
+      printJson(args.includes("--full") ? report : summarizeBrowserInspection(report, { limit: optionInt(args, "--limit", 20) }))
+      return
+    }
+    throw new Error("Usage: ocskill browser <capability|plan|inspect> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function uiControl() {
+  const action = args[1]
+  try {
+    if (action === "tokens") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill ui tokens <styles.css>")
+      const tokens = extractDesignTokens(readTextFile(file))
+      printJson({ tokens, evidence: designTokenEvidence(tokens) })
+      return
+    }
+    if (action === "layout") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill ui layout <boxes.json> --width N --height N [--min-touch N] [--overlap-ratio N]")
+      const payload = readJsonFile(file)
+      const items = Array.isArray(payload) ? payload : payload.elements || payload.boxes || []
+      printJson(inspectResponsiveLayout(items, {
+        width: optionInt(args, "--width", Number(payload.viewport?.width || 0)),
+        height: optionInt(args, "--height", Number(payload.viewport?.height || 0)),
+      }, {
+        minTouchTarget: optionInt(args, "--min-touch", 44),
+        overlapRatio: Number(optionValue(args, "--overlap-ratio") ?? 0.15),
+      }))
+      return
+    }
+    throw new Error("Usage: ocskill ui <tokens|layout> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function workflowPlanControl() {
+  const file = args[1]
+  if (!file) {
+    console.error("Usage: ocskill workflow-plan <PLAN.json> [--max-concurrent N]")
+    process.exitCode = 2
+    return
+  }
+  try {
+    const plan = readJsonFile(file)
+    printJson(planDynamicWorkflow(plan.tasks || [], {
+      maxConcurrent: optionInt(args, "--max-concurrent", 4),
+      maxLLMConcurrent: optionInt(args, "--max-llm-concurrent", optionInt(args, "--max-concurrent", 4)),
+      maxVisionConcurrent: optionInt(args, "--max-vision-concurrent", 2),
+      maxWaveCost: optionInt(args, "--max-wave-cost", 24),
+      minAgentCost: optionInt(args, "--min-agent-cost", 5),
+      minVisionAgentCost: optionInt(args, "--min-vision-agent-cost", 4),
+    }))
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function skillsControl() {
+  const action = args[1] || "lint"
+  if (action !== "lint") {
+    console.error("Usage: ocskill skills lint [dir]")
+    process.exitCode = 2
+    return
+  }
+  try {
+    printJson(await lintSkillCatalog(positionalArg(args, 2) || packageRoot))
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
 async function dashboardControl() {
   const forwarded = args.slice(1)
   const code = run(process.execPath, [path.join(packageRoot, "scripts", "control-center.mjs"), ...forwarded])
@@ -1162,6 +1466,27 @@ switch (command) {
   case "hermes":
     await hermesControl()
     break
+  case "store":
+    await evidenceStoreControl()
+    break
+  case "capabilities":
+    await capabilityControl()
+    break
+  case "visual":
+    await visualControl()
+    break
+  case "browser":
+    await browserControl()
+    break
+  case "workflow-plan":
+    await workflowPlanControl()
+    break
+  case "ui":
+    await uiControl()
+    break
+  case "skills":
+    await skillsControl()
+    break
   case "dashboard":
     await dashboardControl()
     break

package/docs/V11-PERCEPTION-ADAPTIVE-EXECUTION.md

@@ -0,0 +1,75 @@
+# V11 Perception & Adaptive Execution
+
+## Goal
+
+V11 minimizes context and model cost without deleting evidence needed for correctness. It adds perception-aware UI/browser verification so the system can reason about **what an element is, where it is and how it looks** using different evidence channels.
+
+## Runtime layers
+
+```text
+Task
+  -> intent/risk
+  -> capability requirements
+  -> adaptive evidence budget
+  -> semantic/index evidence
+  -> content-addressed evidence pointers
+  -> focused skills
+  -> capability-aware model
+  -> fresh executor
+  -> deterministic verification
+  -> visual/browser verifier when required
+  -> diagnosis + evidence expansion only on failure
+```
+
+## Evidence Store
+
+Large raw tool output, durable specs and dependency reports are stored under:
+
+```text
+.ues-cache/evidence-v1/<hash-prefix>/<sha256>.blob
+.ues-cache/evidence-v1/<hash-prefix>/<sha256>.json
+```
+
+A prompt receives a bounded excerpt and a reference such as `evidence:sha256:<hash>`. Use `ocskill store get` to retrieve only the needed slice. `.ues-cache` is runtime state and is excluded from workspace verification fingerprints.
+
+## Adaptive evidence budget
+
+FAST/STANDARD/DEEP remain outer safety ceilings. Inside that ceiling V11 allocates characters by evidence role instead of treating all context as equally valuable. Debugging shifts budget toward tests/history; high-risk work shifts toward tests/references; browser/visual work shifts toward deterministic tool evidence.
+
+Failure expands evidence through the existing initial -> diagnose -> deep-recovery stages instead of loading maximum context on the first attempt.
+
+## Prompt cache shape
+
+Stable material is separated conceptually from dynamic task/evidence. The runtime records stable/dynamic hashes and cacheable ratio. This is telemetry, not a promise that every provider supports prompt caching.
+
+## Capability-aware routing
+
+Model profiles may declare coding, reasoning, toolCalling, vision, browser, filesystem, longContext, cost/latency class and a quality hint. UES never invents an unavailable capability. If no configured candidate satisfies a requirement it exposes capability fallback instead of silently claiming that a text-only model can see screenshots.
+
+## Visual fidelity
+
+Visual verification uses three complementary layers: semantic DOM/accessibility identity, geometry/bounding boxes, and screenshot pixels. VISUAL_SPEC describes important anchors and tolerances. Geometry receipts prove position/size claims. PNG diff finds changed pixels and their bounding region. A failed region can be cropped so vision only sees the area that needs judgment.
+
+Screenshot equality does not prove accessibility or interaction; DOM equality does not prove appearance.
+
+## Browser QA and security
+
+Browser workflows prefer bounded deterministic scripts/CLI for ordinary verification. Remote webpage content is untrusted and cannot change UES/tool permissions, request secrets, expand the approved task or authorize external side effects.
+
+## Dynamic workflows
+
+The scheduler classifies units as deterministic, LLM judgment or vision judgment. Deterministic work does not spawn agents. Independent tasks may share a wave only when dependencies are ready and file ownership does not conflict. Each wave is integrated and verified before later waves rely on it.
+
+## Skill system
+
+V11 keeps progressive disclosure: description metadata for routing, short SKILL.md entrypoint, references only when the selected mode needs them, and deterministic logic in runtime/scripts rather than repeated prompt text.
+
+`ocskill skills lint` flags oversized entrypoints and highly overlapping descriptions.
+
+## Hermes sidecar
+
+Hermes remains optional. UES owns durable `.ues-work` state, evidence references, task leases/runId fencing, verification receipts and safety/permission boundaries. Hermes may execute a bounded task/workflow when explicitly available but does not become the source of truth.
+
+## Release evidence
+
+V11 must pass syntax/resource/router/V11 contract tests, all Node tests, package/install smokes, no-regression live suites, capability-routing tests, visual geometry/pixel fixtures, browser security/targeted-evidence fixtures and token/cache/evidence telemetry benchmarks before stable promotion.