opencode-agent-skill 13.0.0-beta.2 → 14.2.0-beta.1

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

@@ -1,75 +0,0 @@
-# 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.

package/docs/V11-PERCEPTION-ADAPTIVE.md

@@ -1,220 +0,0 @@
-# UES V11 — Perception & Adaptive Execution
-
-Status: stable (`11.0.0`). V11 is npm `latest`.
-
-## Goal
-
-V11 extends UES from a reliability-focused coding harness into a perception-aware adaptive execution system. The core rule remains:
-
-> minimum context necessary for maximum verified task success
-
-V11 must improve perception, routing and context efficiency without weakening V10 durability, verification or safety.
-
-## Runtime layers
-
-```text
-user task
-  -> intent/risk classification
-  -> capability requirements
-  -> evidence budget
-  -> semantic/repository evidence
-  -> content-addressed evidence pointers
-  -> selective skill/model routing
-  -> fresh executor
-  -> deterministic verification
-  -> visual/browser verifier when required
-  -> recovery/escalation only from observed failure
-```
-
-## Content-addressed Evidence Store
-
-Large evidence is stored below:
-
-```text
-.ues-cache/evidence-v1/
-```
-
-Records are addressed by SHA-256. Executor context receives bounded slices and evidence references instead of repeatedly embedding large tool output.
-
-Commands:
-
-```cmd
-ocskill store status .
-ocskill store put report.txt . --kind tool-output
-ocskill store get evidence:sha256:<hash> . --max 12000
-ocskill store gc . --max-entries 2000 --max-age-days 30
-```
-
-Evidence pointers are not proof by themselves. Any claim still needs the relevant content or a verification receipt.
-
-## Adaptive Evidence Budget
-
-V11 partitions context among instructions, task, declared code, tests, references, history and tools. Debugging, high-risk, visual and browser work can reallocate budget without automatically consuming the full 48k ceiling.
-
-Failure expands evidence in stages; it does not justify replaying already-proven exploration.
-
-## Prompt cache layout
-
-The prompt envelope is split into a stable prefix and dynamic tail.
-
-Stable:
-- role and invariants
-- loaded skill IDs
-- stable project facts
-- tool policy
-
-Dynamic:
-- current task
-- evidence pointers
-- recent failure
-- next action
-- recent messages
-
-Telemetry records stable/dynamic hashes, sizes and cacheable ratio. This is diagnostic; provider-side cache behavior is provider-dependent.
-
-## Capability-aware model routing
-
-Models may declare:
-- coding
-- reasoning
-- tool calling
-- vision
-- browser
-- filesystem
-- long context
-- cost class
-- latency class
-- quality hint
-
-Example:
-
-```cmd
-ocskill models capability provider/model --vision on --browser on --reasoning on --quality 0.9
-```
-
-Task text is converted to capability requirements. The existing light/standard/heavy tiers remain compatible, but V11 can select an eligible configured model instead of assuming every model has the same modalities.
-
-## Visual fidelity
-
-V11 verifies UI through three independent evidence layers:
-
-1. semantic/accessibility identity
-2. geometry/bounding boxes
-3. rendered pixels
-
-A visual task can use `VISUAL_SPEC.json` to define acceptance elements and tolerances.
-
-```cmd
-ocskill visual spec VISUAL_SPEC.json
-ocskill visual geometry VISUAL_SPEC.json actual-boxes.json
-ocskill visual compare expected.png actual.png --threshold 16 --max-diff-ratio 0.01
-ocskill visual crop actual.png failed-region.png --x 100 --y 200 --width 300 --height 120
-```
-
-PNG comparison is deterministic and dependency-free for supported 8-bit non-interlaced PNGs. Vision models are used for appearance judgment or cropped failure regions, not for measurements that DOM/geometry can prove exactly.
-
-## Browser QA and trust boundary
-
-Browser workflows are CLI/script-first. Rich browser tooling is used only when persistent exploration or richer introspection is necessary.
-
-```cmd
-ocskill browser capability .
-ocskill browser plan http://localhost:3000 --target Checkout
-```
-
-Remote webpage text, DOM, ARIA labels and downloaded content are untrusted evidence. They cannot:
-- change UES/system policy
-- expand permissions or filesystem scope
-- request secrets
-- authorize publish/deploy/purchases
-- weaken verification requirements
-
-## Dynamic workflow
-
-```cmd
-ocskill workflow-plan .ues-work/<slug>/PLAN.json --max-concurrent 4
-```
-
-The scheduler separates deterministic work from LLM/vision work, respects dependencies and serializes declared write conflicts. Deterministic commands should not consume agent slots. A schedule is planning evidence, not authorization for external side effects.
-
-## Hermes sidecar
-
-Hermes remains optional. UES owns durable state, safety and verification. Hermes can consume one-task or bounded workflow prompts and evidence pointers but does not own merge/push/publish/deploy.
-
-```cmd
-ocskill hermes status
-ocskill hermes workflow <slug> .
-ocskill hermes exec-workflow <slug> .
-```
-
-If Hermes is absent, core UES remains functional.
-
-## New skills and agents
-
-V11 adds nine focused skills:
-- visual-fidelity
-- browser-qa
-- design-source
-- responsive-verification
-- component-visual-testing
-- browser-security
-- skill-authoring
-- skill-evaluation
-- dynamic-workflow
-
-V11 adds two subagents:
-- `ues-visual-verifier`: read-only independent rendered-evidence verification
-- `ues-merge-arbiter`: conflict resolution across already-verified task changes
-
-More agents are not automatically better. New agents require a distinct capability/verification boundary and benchmark evidence.
-
-## Skill quality
-
-```cmd
-ocskill skills lint .
-```
-
-The linter checks metadata, entrypoint size and likely routing-description collisions. Skill instructions should use progressive disclosure and deterministic scripts for repeatable mechanics.
-
-## Evaluation metrics
-
-V11 keeps correctness first and additionally measures, when available:
-- initial and total tokens
-- cacheable prompt ratio
-- repeated stable input
-- evidence-reference reuse
-- visual repair attempts
-- context expansion count
-- model escalation count
-- latency/cost/tool calls
-
-Missing telemetry is `null`, not zero.
-
-Reference-vs-candidate gates can optionally require V11 telemetry:
-
-```cmd
-npm run evals:ablation -- v10-summary.json v11-summary.json --require-gate --min-cacheable-ratio 0.70 --min-evidence-reuse-ratio 0.20 --max-repeated-stable-ratio 0.20
-```
-
-An explicitly requested metric gate fails closed when its telemetry is unavailable.
-
-## Release gates
-
-Do not promote V11 to stable until all are satisfied:
-
-1. `npm run ci` passes on the V11 tree.
-2. No correctness/pass-rate regression versus the accepted V10 reference.
-3. Required initial-input/token efficiency gate passes.
-4. Visual geometry and PNG fixtures pass.
-5. Browser trust-boundary and routing tests pass.
-6. Compaction, timeout, provider recovery, lease recovery and loop guards remain green.
-7. Packed and plain npm-install smoke tests pass.
-8. Real weak-model evaluation shows no suite regression.
-9. Any configured cache/evidence target has sufficient telemetry and passes.
-10. npm `latest` is V11 stable; no release gate prevents promotion.
-
-## Compatibility
-
-OpenCode 1.x continues to receive resource/CLI behavior that does not require V2 runtime hooks.
-
-OpenCode 2.x receives the managed router plugin and fresh-session runtime, including V11 deterministic helper tools for capability inference, evidence retrieval, visual geometry/diff planning, browser planning and dynamic workflow scheduling.

package/docs/V12-WEAK-MODEL-INTELLIGENCE.md

@@ -1,27 +0,0 @@
-# V12 Weak-Model Intelligence Foundation
-
-Status: beta prerelease (`12.0.0-beta.0`, npm dist-tag `next`). V11 (`11.0.0`) remains the stable `latest` release until V12 earns stable-release evidence.
-
-## Goal
-
-V12 focuses on making weaker coding models more reliable on large repositories by improving measured context quality, empirical model routing, plan identity, bounded autonomous decisions, and repo-scale evaluation. It does not claim that orchestration makes one base model equivalent to a stronger model.
-
-## Foundations
-
-- Empirical model performance: observed pass rate, retries, token use and latency can rerank capability-eligible models by task class.
-- Context quality receipts: adaptive context reports required-file recall and irrelevant-context ratio.
-- Plan-scoped snapshots: every imported plan gets a SHA-256 keyed snapshot and active-plan fence before execution.
-- Decision policy: reversible local engineering choices can be auto-resolvable; publish/deploy/destructive/product decisions remain human-gated.
-- Repo-scale contract suite: deterministic generation of a 300-module monorepo fixture for larger-repository validation.
-
-## Release policy
-
-V12 is not stable merely because unit tests pass. Promotion requires healthy GitHub CI/Security gates, repo-scale validation, real weak-model baseline-vs-UES trials, no regression in existing suites, measured context recall, sufficient empirical routing samples, and Windows/Linux package/install smoke evidence.
-
-## Beta install
-
-```cmd
-npm install -g opencode-agent-skill@next
-ocskill install
-ocskill doctor
-```

package/docs/V13-PARALLEL-WEAK-MODEL-RUNTIME.md

@@ -1,86 +0,0 @@
-# V13 Parallel Weak-Model Runtime
-
-Status: beta prerelease (`13.0.0-beta.2`).
-
-## Goal
-
-V13 reduces wall-clock time for large engineering work by letting multiple fresh sessions of the **same configured model** execute independent approved tasks concurrently without sharing mutable context.
-
-## Runtime contract
-
-- `ues.dispatch_parallel` defaults to one shared model for every worker and verifier.
-- The root must be a Git repository. A pre-existing dirty working tree is allowed: V13 snapshots that baseline into each sandbox and integrates only the task delta, so valid inherited/user changes are preserved.
-- Writers execute in isolated Git worktrees.
-- Resource leases serialize overlapping files, unknown scope and shared configuration surfaces.
-- The scheduler is event-driven: when one task is independently verified, transactionally integrated and completed, newly unblocked dependencies may start immediately.
-- Initial and downstream sandboxes inherit the current dirty root through an internal snapshot commit on the sandbox branch; the user's root branch is never auto-committed.
-- A fresh `ues-verifier` session using the same model must return PASS before integration.
-- Integration is serialized. If receipt/completion fails after patch application, V13 reverses that task patch before marking the run failed.
-- No parallel worker pushes, publishes or deploys.
-
-## Same-model execution
-
-One model is sufficient. Parallelism means multiple isolated sessions, not multiple model families:
-
-```text
-provider/weak-model
-  ├─ fresh session A
-  ├─ fresh session B
-  ├─ fresh session C
-  └─ fresh verifier sessions
-```
-
-If no explicit model is supplied, the configured executor model is shared. If no configured model is selected, all sessions keep the OpenCode default model.
-
-## Runtime compatibility
-
-V13 keeps CLI, durable state, receipts, task graphs and Windows text hardening available on OpenCode 1.x. Native `ues.dispatch_task` and `ues.dispatch_parallel` require the V2 router plugin plus the fresh-session capability surface. The router checks capabilities at runtime and fails closed if create/prompt/wait/interrupt/context/switch-agent are incomplete.
-
-When npm blocks lifecycle scripts (common with stricter npm 11+ `allowScripts` policy), install still leaves the CLI available; run `ocskill install` to perform the documented resource sync explicitly.
-
-### Adaptive /ues-run admission on OpenCode V2
-
-V2 prompt aliases classify the **actual alias arguments** before choosing the prompt envelope. `/ues-run` no longer forces long-horizon mode merely because the alias was used:
-
-- FAST requests receive a compact prompt that preserves the exact user outcome and skips durable planning unless repository work is actually required.
-- STANDARD requests use targeted repository evidence, bounded edits and affected verification without creating durable state by default.
-- DEEP / long-horizon / high-risk requests retain the full durable `.ues-work/<slug>/`, plan-gate, fresh-verifier and integration-gate contract.
-- `/ues-resume` remains explicitly durable so an existing long-running workspace is not accidentally downgraded.
-
-If policy classification is unavailable, the router fails conservatively by preserving the full command contract rather than silently weakening verification.
-
-## CLI hardening
-
-V13 parses `--help` before positional arguments, so commands such as these are safe:
-
-```cmd
-ocskill work init --help
-ocskill work status --help
-ocskill work gate-receipt --help
-```
-
-`ocskill work status .` now lists durable workspaces instead of treating `.` as a slug.
-
-For machine callers, append `--json` to receive structured errors.
-
-On Windows, prefer:
-
-```cmd
-ocskill diff . --out dirty.diff
-```
-
-This writes UTF-8 directly and avoids PowerShell 5 redirection producing UTF-16 text that generic readers may classify as binary. On OpenCode 1.x, where the V2 `ues.text_read` tool is unavailable, read known text safely without creating a converted copy:
-
-```cmd
-ocskill text-read .ues-work/<slug>/PLAN.json --json
-```
-
-Existing UTF-8/UTF-16 text can be normalized with:
-
-```cmd
-ocskill normalize-text dirty.diff
-```
-
-## Release evidence
-
-V13 remains beta until parallel execution demonstrates measurable wall-clock improvement without reducing correctness, and Windows/Linux CI proves help parsing, encoding, dirty-baseline worktree inheritance, rollback, verifier receipts and package installation.

package/docs/V7-INTELLIGENCE-RUNTIME.md

@@ -1,166 +0,0 @@
-# UES 7.7 Intelligence Runtime
-
-UES 7.7 upgrades the V6 long-horizon harness into a more observable, crash-safe and adaptive engineering runtime. The model is still the model; UES improves how work is decomposed, bounded, verified, recovered and learned from.
-
-## V7.0 — Runtime reliability
-
-- live evals use an async process runner with periodic heartbeats
-- hard timeout and idle timeout are separate
-- Ctrl+C aborts the active OpenCode process tree instead of leaving an orphan
-- durable tasks carry `runId`, owner metadata, heartbeat time and lease expiry
-- stale running tasks can be recovered with `ocskill work recover`
-- `ocskill work resume` performs stale-lease recovery before reporting ready work
-- the V2 plugin probes actual session/runtime capabilities before fresh dispatch
-
-Example:
-
-```bash
-ocskill work status checkout .
-ocskill work recover checkout .
-ocskill work heartbeat checkout T1 . --run-id <run-id>
-```
-
-## V7.1 — Structured evidence
-
-`ocskill work verify-command` executes a concrete verification command and records a receipt in `EVIDENCE.json`.
-
-A receipt contains:
-
-- command and arguments
-- exit code and pass/fail
-- start/end/duration
-- SHA-256 of stdout/stderr rather than full output
-- workspace fingerprint before and after
-- task/runId binding
-
-This complements narrative evidence. Task state reports whether completed work is `receipt-backed` or `narrative`.
-
-```bash
-ocskill work verify-command checkout T1 . --run-id <run-id> -- npm test
-```
-
-## V7.2 — Context intelligence
-
-Fresh executor context packs now include a bounded context manifest:
-
-- declared task files
-- local import neighbors and reverse importers
-- likely related tests
-- top-level repository instruction/manifests
-- bounded source excerpts
-- repository graph hotspots
-- accepted learning items relevant to the task
-
-The goal is to reduce rediscovery cost without dumping the whole repository into one prompt.
-
-## V7.3 — Adaptive orchestration/model policy
-
-`ocskill task-policy <text>` deterministically classifies work by complexity/risk and recommends:
-
-- `inline`, `standard` or `long-horizon`
-- light/standard/heavy model tier
-- context budget
-- retry budget
-- whether plan/integration gates are required
-
-`ocskill model-policy <role> --attempt N --text <task>` combines role defaults, task risk and retry escalation.
-
-## V7.4 — Isolated parallel execution primitives
-
-The task graph distinguishes reads from writes. By default linked worktrees are created in a sibling `.REPO.ues-sandboxes/` directory on the same drive, avoiding nested worktrees inside the main checkout:
-
-- read/read overlap can share a safe wave
-- write/read and write/write conflicts serialize
-
-For parallel writers UES provides Git worktree sandboxes:
-
-```bash
-ocskill sandbox create <slug> <task-id> .
-ocskill sandbox list .
-ocskill sandbox remove <worktree-path> . --force
-```
-
-Sandbox creation is deterministic infrastructure. Integration/merging remains an explicit parent responsibility; UES does not silently merge branches.
-
-## V7.5 — Evidence-gated learning loop
-
-UES can mine its own eval traces for recurring failure patterns:
-
-```bash
-ocskill learn analyze . --eval-dir .ues-evals
-ocskill learn status .
-ocskill learn accept <proposal-id> .
-```
-
-Accepted lessons can appear in later context packs when relevant. UES never auto-edits skills or promotes a lesson from a single run without an explicit accept step.
-
-Current deterministic proposal classes include:
-
-- hard timeout
-- idle timeout
-- agent process failure
-- hidden grader failure
-- orchestration failure
-- telemetry parse drift
-
-## V7.6 — Optional Hermes bridge
-
-Hermes is treated as an optional external executor, not embedded as another runtime layer.
-
-```bash
-ocskill hermes status
-ocskill hermes prompt <slug> <task-id> .
-```
-
-The bridge emits a bounded UES delegation prompt. Hermes must not independently mutate durable UES state, merge, push, publish or deploy.
-
-## V7.7 — Control Center
-
-Generate a zero-dependency local dashboard:
-
-```bash
-ocskill dashboard .
-ocskill dashboard . --serve --port 4177
-```
-
-When served with `--serve`, the Control Center refreshes its data every few seconds without requiring a frontend build.
-
-The Control Center summarizes:
-
-- long-horizon work items and task status
-- attempts, blockers and receipt count
-- learning proposals/accepted lessons
-- recent baseline/UES evaluation summaries
-
-Generated state lives under `.ues-dashboard/` and is git-ignored.
-
-## Live benchmark observability
-
-The live harness accepts:
-
-```bash
-node scripts/eval-live.mjs \
-  --suite long \
-  --model provider/model \
-  --mode both \
-  --trials 3 \
-  --heartbeat-ms 30000 \
-  --idle-timeout-ms 300000 \
-  --timeout-ms 900000
-```
-
-Every active trial prints a start line and periodic heartbeat rather than appearing frozen.
-
-## Safety boundaries
-
-V7.7 deliberately keeps these actions explicit:
-
-- merging sandbox branches
-- forceful Git/history actions
-- publishing/releases
-- deployment
-- destructive database/filesystem operations
-- automatic promotion of learned rules
-- automatic execution through Hermes
-
-The goal is a stronger runtime without removing human control over irreversible side effects.