opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/docs/TRACE-SCHEMA.md

@@ -1,122 +0,0 @@
-# UES evaluation trace schema
-
-Live evaluations write machine-readable JSON under `.ues-evals/`.
-
-Each result item contains:
-
-- `task`
-- `mode`: `baseline` or `ues`
-- `model` and optional `variant`
-- `trial`
-- `passed`
-- `agentExit` and `graderExit`
-- `durationMs`
-- `authMode`: `env-only` or `current`
-- `changedFiles`: added/removed/modified workspace paths
-- bounded agent/grader stdout and stderr
-- optional kept workspace path when `--keep` is used
-- timestamp
-
-## Telemetry
-
-`telemetry` currently has schema version 1:
-
-```json
-{
-  "schemaVersion": 1,
-  "format": "best-effort-opencode-jsonl",
-  "jsonLines": 42,
-  "parseErrors": 0,
-  "toolCalls": 12,
-  "tools": {
-    "bash": 4,
-    "read": 5,
-    "skill": 2,
-    "subagent": 1
-  },
-  "skillsLoaded": ["ues-bug-diagnosis"],
-  "subagents": ["ues-verifier"],
-  "tokens": {
-    "input": 12000,
-    "output": 2200,
-    "total": 14200
-  },
-  "cost": 0.18
-}
-```
-
-OpenCode JSON event shapes can evolve, so telemetry extraction is best-effort. Hidden-grader correctness and process exit status remain the primary benchmark evidence.
-
-The trace intentionally does not collect or score hidden chain-of-thought.
-
-## Run summary
-
-Each result file also contains:
-- suite version
-- auth mode
-- selected model/variant
-- trial count
-- optional task filter
-- modes executed
-- pass counts and pass rates per mode
-
-Use `ocskill eval-report` or `npm run evals:report -- <paths>` to aggregate multiple result files.
-
-## Fair comparisons
-
-Keep constant:
-- model and variant
-- task fixture
-- prompt
-- grader
-- runtime/provider environment
-- trial count when possible
-
-Compare observable success, regressions, elapsed time, tool behavior and cost rather than narrative confidence.
-
-
-## V11 runtime and evidence fields
-
-Each live result may additionally contain:
-
-- `timedOut`
-- `idleTimedOut`
-- `aborted`
-- detected `opencodeVersion` / `opencodeMajor`
-- configured heartbeat/hard/idle timeout values
-- long-suite receipt coverage inside orchestration inspection
-
-Long-task `EVIDENCE.json` schema 3 may contain `receipts` and `gateReceipts` arrays. Command receipt fields include:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "uuid",
-  "task": "T1",
-  "runId": "attempt-uuid",
-  "command": "npm",
-  "args": ["test"],
-  "exitCode": 0,
-  "passed": true,
-  "durationMs": 1234,
-  "stdoutSha256": "...",
-  "stderrSha256": "...",
-  "workspaceBefore": "...",
-  "workspaceAfter": "..."
-}
-```
-
-Full stdout/stderr are not stored in receipts; hashes provide binding without persisting potentially sensitive logs.
-
-
-### Structured gate receipts
-
-Strict plan/integration gates use receipt schema version 1. A plan receipt includes the exact `planHash`; an integration receipt includes the exact `workspaceFingerprint`. Both include verifier identity, optional session/run IDs, evidence text and an optional report hash.
-
-### Runtime event journal
-
-Each long work item may include `EVENTS.jsonl`. Every line is an independent JSON event with schema version, UUID, event type, timestamp and task/work metadata. It records operational events only and never hidden chain-of-thought.
-
-### Benchmark matrix summary
-
-`scripts/eval-matrix.mjs` writes a matrix summary containing selected suites/model/trials, expected runs per mode, actual baseline/UES counts, coverage completeness and aggregated pass-rate statistics.

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.