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

package/docs/ENGINEERING-DESIGN.md

@@ -1,194 +0,0 @@
-# UES engineering design
-
-V11 evolves the project from an engineering workflow harness into a **perception-aware adaptive execution engine** designed to reduce context pressure on coding models while keeping evidence needed for correctness.
-
-The selected model remains the selected model. UES improves orchestration, evidence, task boundaries, state persistence and verification; it does not claim model equivalence.
-
-## Core design
-
-### Thin orchestrator, durable artifacts, fresh workers
-
-For long work:
-
-```text
-main/orchestrator
-  ↓
-SPEC + PLAN + STATE
-  ↓
-fresh executor per approved task
-  ↓
-task report + evidence
-  ↓
-integration verifier
-```
-
-Conversation history is not the source of truth. Durable artifacts are.
-
-### Deterministic facts before probabilistic reasoning
-
-UES moves cheap/reliable work into code:
-
-- stack/test-command discovery
-- repository import graph
-- bounded impact search
-- Git state
-- changed-file review coverage
-- risk hints
-- verification recommendations
-- task dependency validation
-- safe-wave scheduling
-- persistent work state
-- completion gates
-
-Models still reason about semantics and read affected code.
-
-### Progressive disclosure
-
-The catalog spans 48 skills. UES prefers a small active skill set and loads deeper references only when needed.
-
-### Hard gates, not reminders
-
-V11 machine-enforces the important boundaries:
-
-1. long/high-risk plans are not executable until a structured plan-verification receipt matches the current plan hash;
-2. long/high-risk task completion requires a successful verification receipt for the active run and the current workspace fingerprint;
-3. durable state/evidence mutations are serialized with a per-work-item lock and atomic replacement;
-4. integration PASS for strict work requires a structured integration receipt bound to the current workspace fingerprint;
-5. finalization requires PASS and rejects any later workspace change.
-
-These checks do not depend on a model remembering an instruction.
-
-## Long-task state model
-
-```text
-.ues-work/<slug>/
-  SPEC.md
-  PLAN.json
-  STATE.json
-  EVIDENCE.json
-  EVENTS.jsonl
-  tasks/
-  reports/
-```
-
-The state contains operational facts only: task status, attempts, decisions, blockers, approvals and evidence. It is not chain-of-thought.
-
-`PLAN.json` is validated for task IDs, dependencies, cycles, acceptance criteria, verification and risk. Safe waves serialize overlapping or unknown declared file scopes.
-
-## Fresh-context execution
-
-On OpenCode V2, the managed plugin exposes `ues.dispatch_task`.
-
-It:
-
-1. calls the state engine to start one ready task;
-2. obtains the bounded Context Manifest v3 pack;
-3. resolves the configured model tier for the executor attempt;
-4. optionally isolates a concurrent writer in a Git worktree;
-5. creates a fresh OpenCode session rooted at the execution directory;
-6. binds the session ID to the durable lease;
-7. switches to `ues-executor` and optionally to the configured model;
-8. prompts exactly the approved task;
-9. heartbeats while waiting under a bounded timeout;
-10. interrupts the child on timeout/cancel and returns a bounded report.
-
-The parent is still responsible for inspecting the child diff and recording completion/failure evidence.
-
-## Model escalation
-
-Roles map to `light`, `standard`, or `heavy`. Attempt number can raise a role one tier up to the configured cap. Model IDs are always user-configured; UES never invents provider/model identifiers.
-
-Escalation follows evidence, not panic:
-
-```text
-attempt 1 fails
-→ diagnose
-→ fresh retry
-→ stronger tier if configured
-→ repeated causal failure
-→ re-plan / architecture review
-```
-
-## OpenCode runtime
-
-### V1
-
-Uses compatible file-based skills, commands and agents. V2-only plugin behavior is not installed.
-
-### V2
-
-The managed plugin uses current V2 domains for:
-
-- prompt admission skill routing
-- model-context guardrails
-- permission evaluation
-- custom tools
-- fresh session creation
-- agent/model switching
-- session waiting
-
-Only UES-managed resources are rewritten/removed.
-
-## Evaluation architecture
-
-UES separates:
-
-1. **static skill contract** — 43 scenarios covering the 48-skill catalog;
-2. **V2 router precision matrix** — 120 required-route/negative-guard cases;
-3. **standard live benchmark** — 20 executable hidden-graded tasks;
-4. **long-horizon benchmark** — 5 tasks, including one 15-source-file integration workload;
-5. **polyglot benchmark** — 8 tasks spanning Python, Java, .NET, Next.js, React Native, SQL migration, monorepo boundaries and generated contracts;
-6. **matrix runner** — baseline vs UES across multiple suites/trials with coverage validation.
-
-For long-suite UES mode, final behavior alone is insufficient. A PASS also requires a completed durable work item with plan approval, at least two tasks, attempted/completed task records, integration PASS and finalization evidence.
-
-This prevents a strong model from bypassing the architecture and still being counted as proof that the long-horizon engine worked.
-
-## Package lifecycle and release safety
-
-npm owns package installation. UES owns only its marked/namespaced OpenCode resources.
-
-CI validates syntax, resource contracts, routing, hidden graders, unit tests, package contents and packed global installation. Update logic resolves npm's explicit `latest` tag and refuses accidental downgrade.
-
-## Deliberate limits
-
-UES deliberately avoids:
-
-- hundreds of agents/tools
-- loading every skill
-- treating keyword routing as truth
-- hidden chain-of-thought storage
-- automatic merge/push/publish/deploy
-- claiming success without fresh evidence
-- claiming that one benchmark proves general model equivalence
-
-The target is a small number of strong control loops: correct context, small tasks, durable state, deterministic checks and independent verification.
-
-
-## V7.7 intelligence runtime additions
-
-V7 adds four control loops around the V6 state machine:
-
-1. **runtime reliability** — task attempts carry run fencing, heartbeats and leases; expired `running` state can be recovered after process/session interruption;
-2. **evidence binding** — verification commands can emit structured receipts containing exit status, output digests and before/after workspace fingerprints;
-3. **context intelligence** — fresh executors receive a bounded manifest of declared files, import neighbors, likely tests, instruction/manifests and accepted learnings;
-4. **adaptive policy + learning** — deterministic task risk/complexity influences workflow/model tier and eval traces can produce explicit learning proposals.
-
-Parallelism is now read/write aware. Read/read overlap can share a wave; writers serialize against readers/writers unless the parent intentionally moves them into isolated Git worktree sandboxes.
-
-The V2 plugin probes actual session capabilities before dispatch rather than treating a major version number as sufficient proof that every runtime API exists.
-
-Hermes is deliberately adapter-only. UES can detect Hermes and generate a bounded task handoff, but does not embed Hermes' runtime, memory, scheduler or gateway into core.
-
-## V8 intelligence and reliability additions
-
-V8 adds six control loops around the V7 runtime:
-
-1. **hard evidence binding** — structured plan/integration receipts plus current-workspace task receipts;
-2. **bounded executor lifecycle** — session binding, timeout interrupt, cancellation and task-scoped recovery;
-3. **event sourcing for observability** — append-only `EVENTS.jsonl` alongside snapshot state;
-4. **context manifest v3** — Git-change awareness, symbol hits, TF-IDF-style ranking and centered excerpts;
-5. **safe parallel integration** — isolated worktrees with dirty-root conflict refusal and UES-only branch cleanup;
-6. **benchmark-gated learning** — clustered proposals require explicit acceptance and measured shadow improvement before retrieval.
-
-The local Control Center remains a safe local observer/controller. It can inspect receipts/events and request stale recovery, but it does not bypass plan, verification, safety or finalization gates and does not directly own OpenCode sessions.

package/docs/EVALS.md

@@ -1,158 +0,0 @@
-# UES evaluations
-
-V11 separates catalog correctness, routing precision, benchmark integrity, final behavior, long-horizon orchestration and cross-stack coverage.
-
-## 1. Static skill-routing contract
-
-`evals/routing.json` keeps 43 representative scenarios and covers all installed skills.
-
-```bash
-npm run evals
-# or
-ocskill eval
-```
-
-This checks catalog consistency, not model behavior.
-
-## 2. V2 router trigger matrix
-
-`evals/router-triggers.json` contains **120 cases** spanning positive routes, negative guards and wording variations.
-
-```bash
-npm run evals:router
-```
-
-The evaluator reports required-route recall and negative-guard success. It exists to catch deterministic router drift separately from LLM behavior.
-
-## 3. Standard live-suite integrity
-
-The standard live suite contains **20 executable hidden-graded tasks**.
-
-```bash
-npm run evals:live:validate
-```
-
-Each grader must reject its intentionally broken fixture with an assertion failure. A grader that already passes or fails for unrelated setup reasons invalidates the suite.
-
-## 4. Long-horizon suite integrity
-
-The long suite contains **5 tasks**. Four exercise coordinated 3–4 file domains; one combines all four domains into a **15-source-file** integration workload.
-
-```bash
-npm run evals:long:validate
-```
-
-The same broken-fixture rule applies.
-
-## 5. Polyglot suite integrity
-
-The polyglot suite contains **8 tasks** covering Python, Java, .NET, Next.js, React Native, SQL migration, monorepo boundaries and generated contract discipline.
-
-```bash
-npm run evals:polyglot:validate
-```
-
-The hidden graders must reject the intentionally broken fixture before the suite is considered valid.
-
-## 6. Live baseline vs UES
-
-```bash
-ocskill eval-live --model provider/model --trials 3
-ocskill eval-live --suite long --model provider/model --trials 3
-ocskill eval-live --suite polyglot --model provider/model --trials 3
-```
-
-Each task runs as:
-
-- **baseline** — isolated empty OpenCode config
-- **ues** — same model/task with repository UES resources installed
-
-Use multiple trials because coding-agent behavior is nondeterministic.
-
-### Long-suite orchestration gate
-
-For `--suite long`, a UES-mode result is PASS only if:
-
-1. OpenCode agent process exits successfully;
-2. hidden behavior grader passes;
-3. at least one `.ues-work/<slug>/` item is valid;
-4. the plan contains at least two tasks;
-5. plan approval status is `passed` and contains a structured plan-verification receipt for the current plan hash;
-6. every planned task has an attempt and ends `completed`;
-7. every task is backed by a successful verification receipt;
-8. integration verification is `PASS` and contains a structured integration-verification receipt for the verified workspace fingerprint;
-9. integration and finalization evidence exist;
-10. work item status is `completed`.
-
-Therefore a model that directly patches all files in its main context but bypasses the long-task engine is not counted as a successful UES long-horizon run.
-
-## 7. Benchmark matrix
-
-Run all three behavioral suites in baseline and UES mode:
-
-```bash
-npm run evals:matrix -- --model provider/model --trials 3
-```
-
-The matrix verifies that the expected number of baseline and UES runs was produced before summarizing pass-rate delta. Use `--long-only`, `--standard-only`, `--polyglot-only`, or `--without-polyglot` to narrow the matrix.
-
-## 8. Authentication isolation
-
-Default mode:
-
-```text
---auth env-only
-```
-
-The harness isolates HOME, USERPROFILE, XDG config/data/cache/state and `OPENCODE_CONFIG_DIR`.
-
-If provider auth was established through OpenCode itself:
-
-```bash
-ocskill eval-live --model provider/model --auth current --trials 3
-```
-
-`current` copies only the current auth file, not the user's global UES configuration.
-
-## 9. Telemetry
-
-Results may include:
-
-- pass/fail
-- process exit status
-- duration
-- changed files
-- bounded stdout/stderr
-- best-effort tool calls
-- loaded skills/subagent targets
-- token/cost data when exposed
-- long-suite orchestration inspection
-
-No hidden chain-of-thought is collected.
-
-## 10. Report aggregation
-
-```bash
-ocskill eval-report .ues-evals
-```
-
-Compare the same model, variant, prompt, fixture, grader and environment. Report multiple trials.
-
-A benchmark result is evidence only for the measured workload. UES does not claim to turn one base model into another.
-
-
-## V11 live-run observability and evidence gate
-
-Live runs accept:
-
-```bash
---heartbeat-ms 30000
---idle-timeout-ms 300000
---timeout-ms 900000
-```
-
-The harness prints a start line and heartbeat for an active model run. Hard timeout and idle timeout are recorded separately. Ctrl+C aborts the active OpenCode process tree and sets exit code 130 after the current result is recorded.
-
-V8 long-suite UES mode requires **receipt-backed verification for every planned task**, a structured plan receipt bound to the current plan hash, and a structured integration receipt bound to the verified workspace fingerprint. Strict task completion additionally rejects a successful command receipt if the workspace changed after that receipt.
-
-This intentionally raises the benchmark bar: final code correctness + durable orchestration + current machine-observable verification are all required.

package/docs/GITHUB-RULESET.md

@@ -1,50 +0,0 @@
-# GitHub Ruleset Readiness
-
-This document records the recommended GitHub repository ruleset configuration for the `main` branch, to be activated only after CI Gate and Security Gate have each achieved at least one successful run.
-
-## Recommended ruleset
-
-- **Ruleset name:** `main-protection`
-- **Target:** default branch / `main`
-- **Enforcement:** Active
-
-## Rules
-
-1. **Restrict deletions** — block deleting the default branch or force-pushing over it.
-2. **Block force pushes** — no `git push --force` or `git push -f` to `main`.
-3. **Require pull request before merge** — all changes must go through a PR.
-4. **Require conversation resolution** — PR reviewers must resolve all inline comments before merge.
-5. **Require status checks** — PRs must have passing CI Gate and Security Gate checks before merge.
-6. **Require branch up to date** — PR branches must be up to date with `main` before merge (applies when there are multiple contributors; can be relaxed for single-maintainer setups).
-7. **Required check: CI Gate** — the aggregate CI check from `.github/workflows/ci.yml`.
-8. **Required check: Security Gate** — the aggregate security check from `.github/workflows/security.yml`.
-
-## Approval policy for single-maintainer repo
-
-This repository currently has one maintainer. Setting `required approval = 1` would prevent the owner from merging their own PRs (they cannot approve their own PR). Therefore:
-
-- **Required approval = 0** for now.
-- When a collaborator or external reviewer is added, raise to `required approval = 1` to restore oversight.
-
-## Classic branch protection vs ruleset
-
-GitHub supports both classic branch protection rules and repository rulesets simultaneously. When both are configured:
-
-- They can apply independently to different aspects of branch protection.
-- Be cautious of duplicate or conflicting protections (e.g., two rules both requiring status checks but with different required lists).
-- If migrating from classic protection to ruleset, remove the classic rule after confirming the ruleset is active and working.
-
-## Activation prerequisite
-
-Do not enable the ruleset until:
-
-1. CI Gate has at least one successful run on `main`.
-2. Security Gate has at least one successful run on `main` or a PR.
-
-Without these prerequisites, the ruleset would block all merges immediately after activation, effectively locking the repository.
-
-## Current status
-
-- **CI Gate:** Added in `.github/workflows/ci.yml`. Awaiting first successful run.
-- **Security Gate:** Added in `.github/workflows/security.yml`. Awaiting first successful run.
-- **Ruleset:** NOT YET ACTIVATED. Will be configured via GitHub admin settings after both gates have successful runs.

package/docs/NPM-PUBLISH.md

@@ -1,116 +0,0 @@
-# Publishing to npm
-
-The package is published as:
-
-```text
-opencode-agent-skill
-```
-
-## Release prerequisites
-
-1. The npm account must have publish rights to the unscoped `opencode-agent-skill` package name.
-2. `package.json` and `package-lock.json` versions must match.
-3. `CHANGELOG.md` must contain the release.
-4. Run the complete local validation:
-
-```cmd
-npm run ci
-```
-
-CI includes syntax validation, resource validation, static skill routing, the 129-case V2 router matrix, 13 V11 contract tasks, standard/long/polyglot hidden-grader integrity checks, unit/integration tests, package dry-run, packed global-install smoke, and a plain one-command install/resource sync smoke.
-
-## Manual release-like test
-
-Do not use `npm install -g .` as a release simulation because npm may create a symlink/junction back to the checkout.
-
-Use:
-
-```cmd
-npm pack
-npm install -g .\opencode-agent-skill-13.0.0-beta.1.tgz --allow-scripts=opencode-agent-skill
-ocskill install
-ocskill status
-ocskill doctor
-```
-
-For the current V13 beta, also open a fresh OpenCode V2 session, check `/plugins`, and call `ues.capabilities`. Native parallel should only be exercised when `freshDispatch` is `true`.
-
-For routine development, the automated `smoke:pack` test uses an isolated npm prefix/OpenCode config so it does not replace the developer's currently installed UES.
-
-## Manual publish
-
-Before publishing, verify the exact prerelease version is not already present:
-
-```cmd
-npm view opencode-agent-skill@13.0.0-beta.1 version --registry=https://registry.npmjs.org/
-```
-
-If it is not present, a manual prerelease publish uses `next`, not `latest`:
-
-```cmd
-npm login
-npm whoami
-npm run ci
-npm publish --access public --provenance --tag next
-```
-
-After publication verify:
-
-```cmd
-npm view opencode-agent-skill versions --json
-npm view opencode-agent-skill@13.0.0-beta.1 version
-npm dist-tag ls opencode-agent-skill
-```
-
-For V13 beta the expected dist-tags are:
-
-```text
-latest: 11.0.0
-next: 13.0.0-beta.1
-```
-
-Do not move `latest` to V13 until the prerelease is intentionally promoted stable.
-
-## GitHub Actions publishing
-
-The repository's publish workflow is OIDC/provenance-ready and runs the same package validation before `npm publish`.
-
-For stronger long-term supply-chain security, configure npm Trusted Publishing for:
-
-```text
-GitHub owner: laivannha0202
-Repository: opencode-agent-skill-
-Workflow: publish.yml
-```
-
-Then the GitHub-hosted workflow can authenticate through OIDC instead of a long-lived npm publish token. npm Trusted Publishing requires the corresponding publisher relationship to be configured on npm; repository code alone cannot create that account-side trust relationship.
-
-The current `publish.yml` is tag-only. A matching prerelease tag such as `v13.0.0-beta.1` runs the full package gate and publishes with npm dist-tag `next`; a stable version publishes to `latest`. The workflow first checks whether that exact version already exists and skips duplicate publication.
-
-## Release checklist
-
-1. Confirm version/changelog/package-lock consistency.
-2. Run `npm run ci` locally on Windows and at least one Unix-like environment when practical.
-3. Run `npm pack` and inspect the tarball contents.
-4. Verify packed install/state/resource counts.
-5. When installer compatibility changed, exercise both forced V1 and V2 paths through tests.
-6. When updater behavior changed, test explicit latest-tag resolution, equal-version behavior, and downgrade refusal.
-7. Commit and push the release branch.
-8. Merge only after review/local validation is clean.
-9. Create/push the matching `vX.Y.Z` tag or run the publish workflow.
-10. Verify registry version and dist-tags (`next` for prerelease, `latest` for stable).
-11. Install the published package on a clean environment before announcing it.
-
-## One-command user install
-
-After publication:
-
-```cmd
-npm install -g opencode-agent-skill
-```
-
-If lifecycle execution is blocked by local npm policy:
-
-```cmd
-ocskill install
-```

package/docs/RESEARCH-SOURCES.md

@@ -1,37 +0,0 @@
-# Research sources
-
-UES is informed by public engineering-agent patterns and current primary platform documentation.
-
-## Engineering-agent and skill-system references
-
-- Alibaba OpenCodeReview: https://github.com/alibaba/open-code-review
-- Open GSD Core: https://github.com/open-gsd/gsd-core
-- Superpowers: https://github.com/obra/superpowers
-- Agent Skills open specification: https://github.com/agentskills/agentskills
-- Anthropic Skills: https://github.com/anthropics/skills
-- OpenAI Agents SDK: https://github.com/openai/openai-agents-python
-- NVIDIA Skills: https://github.com/NVIDIA/skills
-- Ruflo / Claude Flow: https://github.com/ruvnet/ruflo
-
-## OpenCode references
-
-V1/current installed-system references:
-- Skills: https://opencode.ai/docs/skills
-- Agents: https://opencode.ai/docs/agents
-- Commands: https://opencode.ai/docs/commands
-
-OpenCode V2 compatibility/runtime references:
-- Migration from V1: https://opencode.ai/v2/docs/migrate-v1
-- Agent permissions: https://opencode.ai/v2/docs/permissions
-- Agents: https://opencode.ai/v2/docs/agents
-- Skills: https://opencode.ai/v2/docs/skills
-- Plugin discovery/configuration: https://opencode.ai/v2/docs/plugins
-- Plugin API and prompt hooks: https://opencode.ai/v2/docs/build/plugins
-- V1 plugin migration: https://opencode.ai/v2/docs/build/plugins/migrate-v1
-
-## npm release references
-
-- Trusted Publishing: https://docs.npmjs.com/trusted-publishers/
-- Provenance: https://docs.npmjs.com/generating-provenance-statements/
-
-The project does not vendor or copy these projects. External documentation is used to verify platform behavior and inform UES's own implementation.

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.