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

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.

package/docs/V8-INTELLIGENCE-RELIABILITY.md

@@ -1,206 +0,0 @@
-# UES 8.0 Intelligence & Reliability
-
-UES 8.0 focuses on runtime reliability, stronger evidence gates, context quality, safe parallelism and measurable learning. It does not change the underlying model; it improves how engineering work is selected, executed, verified, recovered and evaluated.
-
-## 1. Hard evidence gates
-
-Long-horizon and high-risk work uses strict evidence policy.
-
-Plan approval requires a structured `plan-verification` receipt bound to the current `PLAN.json` hash:
-
-```bash
-ocskill work gate-receipt checkout plan .   --verifier ues-plan-checker   --evidence "plan checker PASS"   --out .ues-work/checkout/reports/plan-receipt.json
-
-ocskill work approve-plan checkout .   --evidence "plan checker PASS"   --receipt-file .ues-work/checkout/reports/plan-receipt.json
-```
-
-Task completion requires a successful verification receipt for the active `runId`. In strict mode, the receipt's `workspaceAfter` must also equal the current workspace fingerprint.
-
-Integration PASS requires an `integration-verification` receipt bound to the current workspace fingerprint. `finalize` still rejects any later workspace change.
-
-## 2. Durable runtime journal
-
-Each long work item now includes:
-
-```text
-.ues-work/<slug>/
-  SPEC.md
-  PLAN.json
-  STATE.json
-  EVIDENCE.json
-  EVENTS.jsonl
-  tasks/
-  reports/
-```
-
-`EVENTS.jsonl` is append-only runtime evidence for:
-
-- work initialization;
-- plan import and approval;
-- task start/session binding/heartbeat;
-- verification receipts;
-- failure and stale recovery;
-- task completion;
-- integration verification;
-- finalization.
-
-Read recent events with:
-
-```bash
-ocskill work events <slug> . --limit 100
-```
-
-## 3. Bounded executor lifecycle
-
-The OpenCode V2 dispatcher probes capabilities instead of assuming them from a version string.
-
-A fresh executor has:
-
-- a durable `runId`;
-- attached OpenCode session ID;
-- heartbeat and lease expiry;
-- bounded runtime;
-- `session.interrupt` on timeout/cancel;
-- task-scoped stale recovery;
-- process-tree cancellation for external eval processes.
-
-On Unix, timed-out external process trees receive SIGTERM followed by SIGKILL after a bounded grace period if necessary. Windows uses `taskkill /T /F`.
-
-The V2 plugin exposes task cancellation/recovery tools when the runtime supports session interruption.
-
-## 4. Context manifest v3
-
-Context selection now combines:
-
-- declared task files;
-- local imports and reverse importers;
-- likely related tests;
-- nearby repository instructions/manifests;
-- current Git-changed files;
-- multilingual task terms;
-- symbol hits;
-- TF-IDF-style content relevance;
-- centered source excerpts around matched terms;
-- accepted benchmark-validated lessons.
-
-The context remains bounded by a per-task budget rather than dumping the whole repository.
-
-## 5. Safer parallel writes
-
-Safe-wave analysis still serializes declared read/write conflicts.
-
-Writer tasks are isolated in Git worktrees by default when the root checkout is clean (unless isolation is explicitly disabled). This keeps the first writer off the canonical root as well as later concurrent writers. Integration:
-
-- captures tracked and untracked sandbox changes;
-- rejects overlap with dirty files in the root checkout;
-- applies the patch to the root only after explicit integration;
-- cleans temporary UES worktree branches;
-- refuses to delete non-UES branches.
-
-Manual flow:
-
-```bash
-ocskill sandbox create <slug> <task-id> .
-ocskill sandbox integrate <worktree-path> .
-ocskill sandbox list .
-```
-
-## 6. Learning v2
-
-Evaluation failures are clustered into recurring patterns and candidate rules.
-
-```bash
-ocskill learn analyze . --eval-dir .ues-evals
-ocskill learn accept <proposal-id> .
-```
-
-Acceptance alone does not make a shadow-required lesson active. Promotion additionally requires measured benchmark improvement:
-
-```bash
-ocskill learn promote <proposal-id> . --report .ues-evals/matrix/matrix-summary-<timestamp>.json
-```
-
-Promotion reads the benchmark matrix artifact itself, verifies complete/equal baseline-vs-UES coverage, hashes the artifact, and refuses caller-supplied pass-rate claims. Only promoted lessons are eligible for future context retrieval.
-
-## 7. Benchmark matrix
-
-Run standard, long-horizon and polyglot baseline-vs-UES evaluations:
-
-```bash
-npm run evals:matrix -- --model provider/model --trials 3
-```
-
-The matrix checks expected baseline/UES coverage before producing a summary. Options include:
-
-```text
---long-only
---standard-only
---polyglot-only
---without-polyglot
-```
-
-The polyglot suite adds eight tasks covering Python authorization, Java money validation, .NET authorization, Next.js API error handling, React Native platform logic, safe SQL migration, monorepo dependency boundaries and generated-contract discipline.
-
-Benchmark results are evidence for the measured tasks only. They are not evidence that UES converts one model into another model.
-
-## 8. Control Center
-
-```bash
-ocskill dashboard . --serve --port 4177
-```
-
-V8 adds:
-
-- runtime event visibility;
-- verification-receipt inspection;
-- stale-task recovery action;
-- existing work/learning/eval summaries.
-
-Executor cancellation remains a runtime operation because a standalone dashboard server cannot safely interrupt an OpenCode session it does not own.
-
-## 9. Package migration
-
-The npm package remains:
-
-```text
-opencode-agent-skill
-```
-
-Users already on 7.7.0 can update normally:
-
-```bash
-ocskill update
-```
-
-The installer now writes:
-
-```text
-<!-- managed-by: opencode-agent-skill -->
-```
-
-It still recognizes the former scoped package owner and marker, then migrates them during re-sync.
-
-## 10. Release and supply-chain checks
-
-V8 adds:
-
-- CodeQL workflow;
-- dependency-review workflow;
-- Dependabot for GitHub Actions and npm;
-- package/tag version consistency guard;
-- tag-only npm publish workflow;
-- OIDC-only npm Trusted Publishing permissions (no long-lived NODE_AUTH_TOKEN);
-- fail-closed tag/version guard;
-- exact plain global-install compatibility smoke in addition to packed-install smoke.
-
-Trusted Publishing still requires the npm account-side trust relationship to be configured for `laivannha0202/opencode-agent-skill-` and `publish.yml`.
-
-## Validation before release
-
-Run:
-
-```bash
-npm run ci
-```
-
-Then run a real benchmark matrix with the target model. Merge/publish only after local CI is green and benchmark output has been inspected.

package/docs/V9-SPEED-INTELLIGENCE.md

@@ -1,102 +0,0 @@
-# UES 9.0 Speed & Intelligence
-
-UES 9.0 builds on the V8 evidence and reliability gates. The goal is not to make the underlying model generate tokens faster; it is to reduce time-to-correct-result by finding the right code sooner, shrinking unnecessary context, avoiding unsafe retries and requiring evidence before completion.
-
-## Execution profiles
-
-UES classifies work into three execution profiles:
-
-- **FAST**: small/low-risk work, up to 2 skills, 12k context budget, targeted verification, no durable worktree/critic overhead by default.
-- **STANDARD**: medium work, up to 4 skills, 24k context budget, semantic+Git context and targeted/affected verification.
-- **DEEP**: long-horizon or high-risk work, up to 5 skills, 48k context budget, durable state, worktree isolation, critic/integration verification and full CI.
-
-Risk still overrides speed. Authentication, security, payment, schema/migration, production/deploy and public-contract work remains fail-closed.
-
-## Incremental evidence index
-
-The V9 index caches bounded source metadata under `.ues-cache/semantic-index-v1.json`. Unchanged files reuse cached evidence while changed files are reparsed. It records:
-
-- concrete source paths;
-- bounded symbol definitions with line numbers;
-- lexical identifier counts;
-- cache reuse/reparse statistics.
-
-This is intentionally labelled **syntax-aware lexical evidence**. It must not be presented as proof of program semantics or as a full AST/LSP call graph.
-
-Commands:
-
-```bash
-ocskill index status .
-ocskill index build .
-ocskill index rebuild .
-ocskill aci search "checkout total" .
-ocskill aci refs calculateTotal .
-ocskill aci view src/checkout.ts . --line 120 --lines 80
-ocskill aci text "exact marker" .
-```
-
-## Weak-model ACI
-
-The ACI keeps search/view output bounded and evidence-first. Path traversal outside the repository is rejected. Large/binary files are refused by the bounded viewer. Reference results distinguish lexical references from concrete definition lines so an agent cannot honestly claim deeper semantic certainty than the tool measured.
-
-## Runtime traces
-
-Operational trace events are appended under `.ues-traces/*.jsonl`. Common credentials/tokens are redacted before persistence, oversized payloads are hashed/truncated, and traces explicitly exclude hidden chain-of-thought.
-
-```bash
-ocskill trace show <trace-id> .
-```
-
-## Verification sandbox
-
-When Docker or Podman is available, deterministic verification commands can run with:
-
-- network disabled by default;
-- Linux capabilities dropped;
-- no-new-privileges;
-- read-only container root;
-- bounded PIDs/memory/CPU;
-- only the requested workspace bind-mounted;
-- no host secrets forwarded by default.
-
-This protects verification commands; it does **not** claim to sandbox the OpenCode model process itself.
-
-## Benchmark confidence gate
-
-The matrix now embeds paired baseline/UES evidence and computes:
-
-- paired wins/losses/ties;
-- pass-rate delta;
-- exact two-sided sign-test p-value;
-- per-suite regression checks;
-- mean duration ratio;
-- optional cost ratio.
-
-Normal reporting:
-
-```bash
-npm run evals:matrix -- --model provider/model --trials 3
-```
-
-Fail-closed release gate:
-
-```bash
-npm run evals:matrix:gate -- --model provider/model --trials 3
-```
-
-The gate requires enough paired samples, positive uplift, more UES wins than losses, statistical support, no suite regression and acceptable speed. This is evidence for the measured benchmark only; it is not evidence that UES turns a weaker model into a different model.
-
-## Lock and Windows hardening
-
-State locking now uses owner tokens and heartbeats. Stale takeover renames the old lock before removal, and release only removes a lock whose token still belongs to the caller. Windows CLI/router invocation resolves Node-backed shims and refuses unrecognized batch shims rather than falling back to shell execution.
-
-## Release validation
-
-Before publishing 9.0.0:
-
-```bash
-npm run ci
-npm run evals:matrix:gate -- --model provider/model --trials 3
-```
-
-If GitHub-hosted Actions still fails before the first workflow step, treat that as an infrastructure/repository-action issue rather than test evidence; local CI and the paired benchmark remain required release gates.