opencode-agent-skill 7.7.0 → 10.0.0

package/README.md

@@ -1,88 +1,36 @@
 # OpenCode Universal Engineering System (UES)
 
-**UES 7.7.0** là engineering harness cho OpenCode, tập trung vào việc giúp model hiện có xử lý repository lớn và task dài theo quy trình có trạng thái bền vững, fresh-context execution, deterministic evidence và verification gate.
+> **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`.
+> 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ế.
 
-UES không tuyên bố biến một model yếu thành model mạnh hơn về bản chất. Mục tiêu là giảm lượng reasoning mà model phải tự giữ trong một context: chia task rõ, lưu state ra filesystem, dùng code cho các việc có thể xác định được, chạy subagent với context mới, và chỉ cho phép hoàn tất khi có evidence.
+[![npm version](https://img.shields.io/npm/v/opencode-agent-skill.svg)](https://www.npmjs.com/package/opencode-agent-skill)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## UES 7.7.0 có gì?
+## Giới thiệu
 
-Ngoài nền V6 (durable PLAN/STATE/EVIDENCE, fresh executors, plan/integration gates), V7.7 thêm:
+**OpenCode Universal Engineering System (UES)** là một engineering harness dành cho OpenCode. UES không thay đổi năng lực nền tảng của model, mà tổ chức cách model làm việc để:
 
-- crash-safe task lease với `runId`, heartbeat, stale-task recovery
-- live benchmark heartbeat + hard/idle timeout + Ctrl+C process-tree cancellation
-- structured verification receipts gắn command/exit code/output hash/workspace fingerprint vào task run
-- context manifest tự chọn declared files, import neighbors, likely tests, manifests và accepted lessons
-- adaptive task policy: inline/standard/long-horizon + risk/model/context/retry guidance
-- read/write-aware safe waves và isolated Git worktree sandbox primitives cho parallel writers
-- evidence-gated learning loop từ `.ues-evals` → proposal → explicit accept → future context retrieval
-- optional Hermes bridge theo kiểu adapter, không nhúng Hermes runtime vào core
-- zero-dependency local **UES Control Center** cho work state, evidence, learning và eval summaries; chế độ `--serve` tự refresh dữ liệu
+- giảm lượng thông tin phải giữ trong một context dài;
+- chia tác vụ lớn thành các bước rõ ràng;
+- lưu trạng thái ra filesystem để có thể tiếp tục sau khi session bị ngắt;
+- chạy executor bằng context mới cho từng tác vụ;
+- yêu cầu bằng chứng kiểm thử trước khi đánh dấu hoàn tất;
+- kiểm tra thay đổi ở mức task và mức tích hợp toàn hệ thống;
+- hỗ trợ routing skill, model tier, task policy và recovery theo trạng thái thực tế của repository.
 
-Xem chi tiết: [V7 Intelligence Runtime](docs/V7-INTELLIGENCE-RUNTIME.md)
+Mục tiêu của UES là giúp quá trình làm việc với coding agent **ổn định hơn, có thể kiểm chứng hơn và phù hợp hơn với repository lớn**.
 
-### Lệnh V7 nhanh
-
-```cmd
-ocskill task-policy "refactor auth across the whole repository"
-ocskill work recover <slug> .
-ocskill work verify-command <slug> <task> . -- npm test
-ocskill sandbox create <slug> <task> .
-ocskill learn analyze . --eval-dir .ues-evals
-ocskill hermes status
-ocskill dashboard . --serve
-```
-
-
-
-- **39 engineering skills**
-- **11 slash commands**
-- **10 subagents**
-- durable long-task engine dưới `.ues-work/<slug>/`
-- machine-checkable `PLAN.json` + dependency DAG + safe execution waves
-- hard plan approval gate và integration verification gate
-- atomic/locked `STATE.json` + `EVIDENCE.json` để tránh mất state khi task độc lập hoàn tất đồng thời
-- OpenCode V2 runtime plugin với automatic skill routing, safety permission gate và fresh-session task dispatch
-- configurable `light / standard / heavy` model tiers với attempt-based escalation
-- deterministic repository tools: repo graph, impact, review scope, verification plan, task graph, context pack
-- **34 static skill-routing scenarios** phủ đủ 39 skill
-- **120 V2 router trigger cases** có positive/negative guards
-- **20 standard live hidden-graded tasks**
-- **5 long-horizon tasks**, gồm một bài tích hợp **15 source files**
-- hỗ trợ **OpenCode 1.x và 2.x**
+---
 
-Luồng long-horizon chính:
+## Cài đặt
 
-```text
-request
-  ↓
-repo evidence / codebase map
-  ↓
-SPEC.md
-  ↓
-PLAN.json
-  ↓
-ues-plan-checker
-  ↓
-machine approval gate
-  ↓
-dependency-safe tasks
-  ↓
-fresh ues-executor session / task
-  ↓
-task evidence + durable state
-  ↓
-ues-integration-verifier
-  ↓
-machine integration PASS gate
-  ↓
-workspace fingerprint unchanged
-  ↓
-finalize
-```
+Yêu cầu:
 
----
+- Node.js 20 trở lên;
+- npm;
+- OpenCode.
 
-## Cài đặt
+Cài đặt toàn cục từ npm:
 
 ```cmd
 npm install -g opencode-agent-skill
@@ -91,93 +39,134 @@ npm install -g opencode-agent-skill
 Kiểm tra:
 
 ```cmd
+ocskill version
 ocskill status
 ocskill doctor
 ```
 
-Nếu npm không chạy lifecycle script:
+Nếu npm không chạy lifecycle script trong lúc cài đặt, chạy thêm:
 
 ```cmd
 ocskill install
 ```
 
-Khi đồng bộ V7.7 đầy đủ, status sẽ phản ánh khoảng:
-
-```text
-Package version: 7.7.0
-Resource version: 7.7.0
-Skills: 39/39
-Commands: 11/11
-Subagents: 10/10
-Workflow: OK
-```
-
-Sau khi cài/cập nhật, nên mở OpenCode session mới để resource mới được nạp.
-
----
-
-# 1. Subagents
-
-| Subagent | Vai trò |
-|---|---|
-| `ues-codebase-mapper` | Map repository, entry point, boundary, hotspot, contract và test surface |
-| `ues-architect` | Architecture/change-impact analysis |
-| `ues-plan-checker` | Fresh-context gate kiểm tra SPEC/PLAN trước khi code |
-| `ues-executor` | Fresh-context implementation cho đúng một approved task |
-| `ues-debugger` | Root-cause debugging |
-| `ues-researcher` | Kiểm tra docs/API/version hiện hành |
-| `ues-reviewer` | Review correctness/regression/security/compatibility |
-| `ues-critic` | Adversarial falsification/counterexample |
-| `ues-verifier` | Verification độc lập theo acceptance criteria |
-| `ues-integration-verifier` | Cross-task/end-to-end integration verification |
-
-`ues-executor` là subagent 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/kiểm chứng và không được dùng để âm thầm mở rộng implementation.
+Sau khi cài hoặc cập nhật UES, nên mở một OpenCode session mới để các skill, command, subagent và plugin được nạp lại đầy đủ.
 
 ---
 
-# 2. Slash commands
+## Bắt đầu nhanh
 
-| Lệnh | Công dụng |
-|---|---|
-| `/ues-feature` | Làm feature theo workflow UES |
-| `/ues-fix` | Điều tra root cause rồi sửa bug |
-| `/ues-plan` | Lập implementation-ready plan |
-| `/ues-debug` | Điều tra bug/build/test failure |
-| `/ues-research` | Kiểm tra docs/API/package/version |
-| `/ues-review` | Review diff/code |
-| `/ues-verify` | Verification bằng evidence mới |
-| `/ues-critique` | Tìm assumption sai/counterexample |
-| `/ues-audit` | Audit repository/khu vực |
-| `/ues-run` | Chạy long-horizon workflow với durable state + fresh executors |
-| `/ues-resume` | Resume work item từ `.ues-work` thay vì dựa vào chat history |
-
-Với task lớn, ưu tiên:
+Với tác vụ lớn, dùng:
 
 ```text
 /ues-run <yêu cầu>
 ```
 
-Nếu session bị ngắt/compact:
+Nếu session bị ngắt hoặc context bị compact:
 
 ```text
 /ues-resume <slug>
 ```
 
+Một số lệnh hữu ích:
+
+```cmd
+ocskill inspect .
+ocskill repo-graph .
+ocskill verification-plan .
+ocskill task-policy "refactor auth across the whole repository"
+ocskill dashboard . --serve
+```
+
 ---
 
-# 3. Long-horizon engine
+## V10 có gì?
 
-V7 task records additionally track `runId`, executor owner, heartbeat, lease expiry and evidence strength. `ocskill work resume` can recover stale running tasks, while the V2 dispatcher refreshes leases during fresh-session execution.
+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.
 
-Structured verification can be recorded with:
+- telemetry đo riêng **initial input tokens** bên cạnh total tokens, tool calls, latency và cost;
+- global `AGENTS.md` được nén đáng kể, giữ lại contract, evidence, verification, safety và long-horizon invariants;
+- FAST context budget giảm từ 12k xuống **8k**, STANDARD từ 24k xuống **20k**, còn DEEP vẫn giữ **48k** cho task rủi ro/lớn;
+- OpenCode V2 runtime dùng policy-aware selective routing: FAST ưu tiên domain/debug/review skill trực tiếp thay vì tự động nạp generic orchestrator;
+- failed attempt tự mở rộng context theo tầng `initial -> diagnose -> deep-recovery`; retry tăng evidence, graph/critic và model tier khi cấu hình cho phép;
+- FAST không tự hạ executor thấp hơn tier đã cấu hình, nên tối ưu context không đồng nghĩa hạ năng lực model;
+- benchmark confidence gate kiểm tra thêm initial-input ratio và total-token ratio;
+- `npm run evals:ablation -- <reference> <candidate> --require-gate` so V10 với một reference run và từ chối candidate giảm pass-rate dù token có thấp hơn;
+- runtime reliability guard phát hiện no-progress/stall, chặn duplicate `read/grep/glob`, phát hiện loop và cắt output exploration quá lớn trước khi nó làm ngập context;
+- pre-compaction checkpoint lưu `currentTaskId`, `runId`, plan hash, workspace fingerprint, evidence pointers và structured `nextAction`; post-compaction bắt buộc thực thi action trước khi session được coi là hoàn tất;
+- provider recovery thử fresh session cùng model một lần, sau lỗi lặp lại dùng configured escalation model/provider nếu có;
+- lease supervisor tự thu hồi executor lease hết hạn sang trạng thái `retryable`, và explicit `long/high-risk` hard-override FAST thành DEEP/heavy.
 
-```cmd
-ocskill work verify-command <slug> <task> . --run-id <run-id> -- npm test
-```
+V10 stable kế thừa toàn bộ RC.2 reliability hardening. Local full gate trên Windows/Node 24 đã PASS với 182 test pass, 0 fail, 2 skip cùng package/install smoke PASS trước khi promote.
 
+---
+
+## UES 9.0.0 có gì?
+
+UES 9.0.0 cung cấp các khả năng sau (kế thừa từ 8.0.0):
+
+- **39 engineering skills**;
+- **11 slash commands**;
+- **10 subagents**;
+- long-task engine bền vững dưới `.ues-work/<slug>/`;
+- `PLAN.json`, `STATE.json`, `EVIDENCE.json` và append-only `EVENTS.jsonl`;
+- structured plan/integration receipts gắn với plan hash hoặc workspace fingerprint;
+- task lease với `runId`, heartbeat, session owner, lease expiry và task-scoped stale recovery;
+- strict verification cho long/high-risk task: receipt phải PASS đúng active run và đúng workspace hiện tại;
+- context manifest v3 với Git-change awareness, symbol hits, TF-IDF-style relevance, tests/instructions và centered excerpts;
+- task policy `inline / standard / long-horizon` cùng model tier `light / standard / heavy`;
+- bounded fresh executor với hard timeout, interrupt/cancel và recovery;
+- safe-wave scheduling cùng Git worktree isolation/integration có conflict detection;
+- learning v2: failure clustering, explicit acceptance và shadow-benchmark promotion;
+- benchmark matrix standard + long-horizon + polyglot;
+- optional Hermes adapter;
+- UES Control Center hiển thị runtime events, receipts và stale recovery;
+- OpenCode V2 router plugin với multilingual routing, safety gate, cancel/recover tools và fresh-session dispatch.
+
+V9 bổ sung:
+
+- persistent incremental source index dưới `.ues-cache/semantic-index-v1.json` cùng ACI search/refs/view/text;
+- FAST / STANDARD / DEEP execution profiles với bounded context budget, skill cap và verification depth;
+- context manifest v4 tiêu thụ incremental evidence index trước khi mở rộng graph;
+- redacted operational trajectory dưới `.ues-traces/*.jsonl` để replay/debug mà không lưu hidden chain-of-thought;
+- optional container verification sandbox (Docker/Podman) với network-off, dropped capabilities và resource bounds;
+- paired baseline-vs-UES confidence gate qua `npm run evals:matrix:gate`.
+
+---
 
+## Kiến trúc tác vụ dài
+
+Luồng long-horizon chính:
+
+```text
+Yêu cầu
+  ↓
+Khảo sát repository / bằng chứng
+  ↓
+SPEC.md
+  ↓
+PLAN.json
+  ↓
+ues-plan-checker
+  ↓
+Phê duyệt kế hoạch
+  ↓
+Các task theo dependency graph
+  ↓
+Fresh ues-executor session cho từng task
+  ↓
+Task evidence + durable state
+  ↓
+ues-integration-verifier
+  ↓
+Integration PASS
+  ↓
+Kiểm tra workspace không thay đổi
+  ↓
+Finalize
+```
 
-Mỗi work item dùng:
+Mỗi work item dùng cấu trúc:
 
 ```text
 .ues-work/<slug>/
@@ -185,103 +174,157 @@ Mỗi work item dùng:
 ├── PLAN.json
 ├── STATE.json
 ├── EVIDENCE.json
+├── EVENTS.jsonl
 ├── tasks/
 └── reports/
 ```
 
-`.ues-work/` được git-ignore. Đây là execution state, không phải hidden chain-of-thought.
+`.ues-work/` là trạng thái thực thi của workflow, không phải hidden chain-of-thought.
 
-## Hard gate 1 — Plan approval
+### Gate 1 — Phê duyệt kế hoạch
 
-`ocskill work plan` không đưa task thẳng sang executable state. Nó để state ở:
+Sau khi tạo plan, task chưa được chạy ngay. Trạng thái sẽ ở:
 
 ```text
 awaiting-plan-approval
 ```
 
-Sau khi `ues-plan-checker` trả PASS:
+Sau khi `ues-plan-checker` trả PASS, với long/high-risk work hãy tạo receipt gắn với đúng plan hiện tại rồi mới approve:
 
 ```cmd
-ocskill work approve-plan <slug> . --evidence "plan checker PASS: ..."
+ocskill work gate-receipt <slug> plan . --verifier ues-plan-checker --evidence "plan checker PASS" --out .ues-work/<slug>/reports/plan-receipt.json
+ocskill work approve-plan <slug> . --evidence "plan checker PASS" --receipt-file .ues-work/<slug>/reports/plan-receipt.json
 ```
 
-Nếu chưa có approval hợp lệ, `ocskill work start` sẽ từ chối.
+Nếu thiếu structured receipt ở workflow strict, `ocskill work start` sẽ không được mở gate.
 
-## Hard gate 2 — Concurrent durable state
+### Gate 2 — Bằng chứng cho từng task
 
-Mọi mutation của `STATE.json` và `EVIDENCE.json` dùng per-work-item lock + atomic replacement. Hai task độc lập có thể hoàn tất gần nhau mà không được phép ghi đè state/evidence của nhau.
+Có thể ghi verification receipt trực tiếp từ command:
 
-Safe-wave chỉ bảo vệ declared file overlap. Nếu task có implicit shared write surface như generated files/lockfiles, hãy serialize.
+```cmd
+ocskill work verify-command <slug> <task-id> . --run-id <run-id> -- npm test
+```
 
-## Hard gate 3 — Integration completion
+Receipt gắn kết kết quả command với đúng task run. Với long/high-risk work, receipt PASS còn phải khớp workspace fingerprint hiện tại; nếu code thay đổi sau khi test thì phải verify lại.
 
-Sau khi mọi task hoàn tất:
+### Gate 3 — Kiểm tra tích hợp
+
+Sau khi toàn bộ task hoàn tất, tạo integration receipt gắn với workspace hiện tại rồi ghi PASS:
 
 ```cmd
-ocskill work verify-integration <slug> . --verdict PASS --evidence "..."
+ocskill work gate-receipt <slug> integration . --verifier ues-integration-verifier --verdict PASS --evidence "integration PASS" --out .ues-work/<slug>/reports/integration-receipt.json
+ocskill work verify-integration <slug> . --verdict PASS --evidence "integration PASS" --receipt-file .ues-work/<slug>/reports/integration-receipt.json
 ```
 
-PASS lưu workspace fingerprint. `finalize` sẽ bị từ chối nếu:
-
-- còn task incomplete
-- còn blocker
-- chưa có integration PASS
-- workspace đã thay đổi sau PASS
-
 Sau đó:
 
 ```cmd
 ocskill work finalize <slug> . --evidence "final acceptance verified"
 ```
 
+`finalize` sẽ bị từ chối nếu còn task chưa hoàn tất, còn blocker, chưa có integration PASS hoặc workspace đã thay đổi sau lần kiểm tra tích hợp.
+
 ---
 
-# 4. Fresh-context executor trên OpenCode V2
+## Fresh-context executor trên OpenCode V2
 
-V2 plugin expose tool:
+OpenCode V2 plugin cung cấp tool:
 
 ```text
 ues.dispatch_task
 ```
 
-Nó thực hiện:
+Luồng thực thi:
 
 ```text
 work start
   ↓
-read bounded context pack
+đọc bounded context pack
   ↓
-resolve model tier theo attempt
+chọn model tier theo task + attempt
   ↓
-create fresh OpenCode session
+tạo OpenCode session mới
   ↓
 switchAgent(ues-executor)
   ↓
-switchModel(...) nếu được cấu hình
+switchModel(...) nếu đã cấu hình
+  ↓
+gửi đúng một task
+  ↓
+heartbeat + bounded wait
   ↓
-prompt đúng 1 task
+interrupt nếu timeout/cancel
   ↓
-wait
+isolate writer khi cần
   ↓
-return child-session report
+trả child-session report
 ```
 
-Parent vẫn phải inspect diff/evidence và gọi `work complete` hoặc `work fail`. Child session không được tự merge/push/publish/deploy.
+Parent session vẫn chịu trách nhiệm kiểm tra diff, evidence và quyết định gọi `work complete` hoặc `work fail`.
+
+Child session không được tự động merge, push, publish hoặc deploy.
+
+---
+
+## Subagents
+
+| Subagent | Vai trò |
+|---|---|
+| `ues-codebase-mapper` | Lập bản đồ repository, entry point, boundary, hotspot, contract và test surface |
+| `ues-architect` | Phân tích kiến trúc và phạm vi ảnh hưởng |
+| `ues-plan-checker` | Kiểm tra SPEC/PLAN trước khi cho phép thực thi |
+| `ues-executor` | Thực hiện một task đã được phê duyệt trong context mới |
+| `ues-debugger` | Điều tra nguyên nhân gốc của lỗi |
+| `ues-researcher` | Kiểm tra tài liệu, API và phiên bản hiện hành |
+| `ues-reviewer` | Review correctness, regression, security và compatibility |
+| `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-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.
 
 ---
 
-# 5. Adaptive task + model policy
+## Slash commands
 
-V7 adds deterministic task classification:
+| Lệnh | Công dụng |
+|---|---|
+| `/ues-feature` | Triển khai feature theo workflow UES |
+| `/ues-fix` | Điều tra nguyên nhân rồi sửa bug |
+| `/ues-plan` | Lập kế hoạch triển khai có thể thực thi |
+| `/ues-debug` | Điều tra lỗi build, runtime hoặc test |
+| `/ues-research` | Kiểm tra docs, API, package hoặc version |
+| `/ues-review` | Review code hoặc diff |
+| `/ues-verify` | Xác minh bằng evidence mới |
+| `/ues-critique` | Tìm assumption sai và counterexample |
+| `/ues-audit` | Audit repository hoặc một khu vực |
+| `/ues-run` | Chạy workflow long-horizon với durable state |
+| `/ues-resume` | Tiếp tục work item từ `.ues-work` |
+
+---
+
+## Task policy và model policy
+
+Phân loại yêu cầu kỹ thuật:
 
 ```cmd
 ocskill task-policy "your engineering request"
+```
+
+Kiểm tra model policy:
+
+```cmd
 ocskill model-policy executor --attempt 1 --text "your engineering request"
 ```
 
-Task risk/complexity can raise the base model tier before attempt-based escalation. User-configured provider/model IDs remain authoritative.
+UES dùng ba model tier:
 
-## Model tiers
+```text
+light
+standard
+heavy
+```
 
 Xem cấu hình:
 
@@ -289,13 +332,13 @@ Xem cấu hình:
 ocskill models status
 ```
 
-Bật:
+Bật model policy:
 
 ```cmd
 ocskill models on
 ```
 
-Gán model:
+Gán model cho từng tier:
 
 ```cmd
 ocskill models set light provider/cheap
@@ -310,31 +353,24 @@ ocskill models role executor standard
 ocskill models role plan-checker heavy
 ```
 
-Kiểm tra attempt:
-
-```cmd
-ocskill model-policy executor --attempt 1
-ocskill model-policy executor --attempt 2
-```
-
-Mặc định role quan trọng như architect, plan-checker, critic và integration-verifier ưu tiên `heavy`; executor/debugger/reviewer thường bắt đầu ở `standard`. Retry có thể escalate lên tier cao hơn nếu đã cấu hình.
+Model ID do người dùng cấu hình vẫn là nguồn quyết định cuối cùng; UES không tự đoán provider/model ID.
 
 ---
 
-# 6. Deterministic CLI tools
+## Công cụ CLI
 
 | Lệnh | Công dụng |
 |---|---|
-| `ocskill inspect [dir]` | Stack/package manager/root map/test commands |
-| `ocskill repo-graph [dir]` | Bounded import graph + coupling hotspots |
-| `ocskill impact <query> [dir]` | Bounded symbol/term impact search |
-| `ocskill evidence [dir]` | Repository + verification + Git evidence snapshot |
-| `ocskill working-tree [dir]` | Branch/HEAD/dirty state |
-| `ocskill review-scope [base] [dir]` | Changed-file coverage + deterministic risk hints |
-| `ocskill verification-plan [dir]` | Project-native verification recommendations |
-| `ocskill task-graph <PLAN.json>` | Validate DAG + compute safe waves |
-| `ocskill context-pack <slug> <task> [dir]` | Bounded handoff cho fresh executor |
-| `ocskill work ...` | Durable long-task state machine |
+| `ocskill inspect [dir]` | Phát hiện stack, package manager, root và test command |
+| `ocskill repo-graph [dir]` | Lập import graph có giới hạn và tìm hotspot |
+| `ocskill impact <query> [dir]` | Tìm phạm vi ảnh hưởng theo symbol hoặc từ khóa |
+| `ocskill evidence [dir]` | Thu thập snapshot về repository, verification và Git |
+| `ocskill working-tree [dir]` | Kiểm tra branch, HEAD và working tree |
+| `ocskill review-scope [base] [dir]` | Phân tích changed-file coverage và risk hint |
+| `ocskill verification-plan [dir]` | Đề xuất verification phù hợp với project |
+| `ocskill task-graph <PLAN.json>` | Kiểm tra DAG và tính safe waves |
+| `ocskill context-pack <slug> <task> [dir]` | Tạo bounded handoff cho executor |
+| `ocskill work ...` | Điều khiển durable long-task state machine |
 
 Ví dụ:
 
@@ -348,11 +384,11 @@ ocskill work status checkout .
 
 ---
 
-# 7. Skills
+## Skills
 
-UES giữ **39 skills**, không tăng catalog chỉ để tăng số lượng. Thông thường router chỉ cần 2–4 skill phù hợp.
+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.
 
-Các process skill quan trọng:
+Một số process skill quan trọng:
 
 - `ues-engineering-orchestrator`
 - `ues-repo-explorer`
@@ -367,23 +403,23 @@ Các process skill quan trọng:
 - `ues-long-task-state`
 - `ues-git-safety`
 
-Domain/framework skills bao gồm React, Next.js, React Native, Node.js, NestJS, Python, Django, FastAPI, .NET, Java/Spring, Flutter, database, REST/API contract, auth/security, payment, ecommerce, file upload, DevOps, UI/UX, accessibility và performance.
+Nhóm domain/framework hiện bao gồm React, Next.js, React Native, Node.js, NestJS, Python, Django, FastAPI, .NET, Java/Spring, Flutter, database, REST/API contract, authentication/security, payment, ecommerce, file upload, DevOps, UI/UX, accessibility và performance.
 
 ---
 
-# 8. OpenCode 1.x và 2.x
+## Tương thích OpenCode
 
-## OpenCode 1.x
+### OpenCode 1.x
 
-- skill/command/subagent file vẫn được cài
-- dùng permission frontmatter tương thích V1
-- không cài V2 runtime plugin
-- long-task CLI/durable state vẫn dùng được
-- fresh child-session dispatch phụ thuộc khả năng subagent của runtime V1; không có V2 `ues.dispatch_task`
+- cài skill, command và subagent;
+- dùng frontmatter tương thích V1;
+- không cài V2 runtime plugin;
+- durable long-task CLI vẫn dùng được;
+- không có V2 `ues.dispatch_task`.
 
-## OpenCode 2.x
+### OpenCode 2.x
 
-Ngoài resource file, UES cài managed plugin:
+Ngoài resource file, UES cài managed plugin tại:
 
 ```text
 ~/.config/opencode/plugins/ues-router/
@@ -391,13 +427,13 @@ Ngoài resource file, UES cài managed plugin:
 
 Plugin cung cấp:
 
-- prompt-time skill routing
-- context guardrail
-- permission safety gate cho destructive/high-impact shell action
-- read-only long-task helpers
-- `ues.dispatch_task` fresh-session executor runtime
+- automatic skill routing;
+- context guardrail;
+- permission safety gate;
+- read-only long-task helpers;
+- fresh-session executor runtime qua `ues.dispatch_task`.
 
-Router:
+Điều khiển router:
 
 ```cmd
 ocskill router status
@@ -407,175 +443,254 @@ ocskill router off
 
 ---
 
-# 9. Safety
+## Safety
 
-V2 permission gate nâng các thao tác nguy hiểm lên explicit confirmation, gồm nhóm như:
+OpenCode V2 permission gate yêu cầu xác nhận rõ ràng trước các thao tác có tác động lớn, ví dụ:
 
-- `git push --force` / `git push -f`
-- `git reset --hard`
-- destructive `git clean`
-- `npm publish`
-- recursive forced deletion
-- `DROP/TRUNCATE`
-- Terraform/Kubernetes/Helm high-impact deployment actions
+- `git push --force` hoặc `git push -f`;
+- `git reset --hard`;
+- destructive `git clean`;
+- `npm publish`;
+- recursive forced deletion;
+- `DROP` hoặc `TRUNCATE`;
+- Terraform, Kubernetes hoặc Helm action có tác động lớn.
 
-Instruction vẫn yêu cầu confirmation cho destructive/external side effects. Hook là lớp deterministic bổ sung, không thay thế review của người dùng.
+Safety hook là lớp bảo vệ deterministic bổ sung, không thay thế review của người dùng.
 
 ---
 
-# 10. Evaluation
+## Learning loop
+
+Phân tích eval trace:
+
+```cmd
+ocskill learn analyze . --eval-dir .ues-evals
+```
+
+Xem trạng thái:
 
-Live evals now print heartbeats and support `--heartbeat-ms`, `--idle-timeout-ms`, and `--timeout-ms`. Ctrl+C asks the harness to terminate the active OpenCode process tree cleanly.
+```cmd
+ocskill learn status .
+```
 
+Chấp nhận một proposal trước khi thử nghiệm:
 
+```cmd
+ocskill learn accept <proposal-id> .
+```
 
-## Static skill contract
+Sau khi shadow benchmark chứng minh candidate tốt hơn baseline:
 
 ```cmd
-npm run evals
+ocskill learn promote <proposal-id> . --baseline 0.50 --candidate 0.75 --samples 4
 ```
 
-Giữ **34 scenarios** để kiểm catalog và phủ đủ 39 skill.
+Proposal có `shadowRequired` chỉ được đưa trở lại context sau khi vừa được chấp nhận rõ ràng vừa có benchmark improvement đo được.
 
-## V2 router precision matrix
+---
+
+## Hermes adapter
+
+UES hỗ trợ Hermes theo dạng adapter tùy chọn, không nhúng Hermes runtime vào core:
 
 ```cmd
-npm run evals:router
+ocskill hermes status
+ocskill hermes prompt <slug> <task> .
+ocskill hermes exec <slug> <task> .
 ```
 
-V7.7 giữ **120 cases** với required routes và negative guards, cộng regression tests riêng cho cap-priority/capability runtime.
+Nếu máy không có Hermes CLI, các tính năng Hermes chỉ báo unavailable và không ảnh hưởng đến core UES.
+
+---
+
+## UES Control Center
 
-## Standard hidden graders
+Tạo dashboard tĩnh:
 
 ```cmd
-npm run evals:live:validate
+ocskill dashboard .
+```
+
+Chạy dashboard có tự refresh:
+
+```cmd
+ocskill dashboard . --serve --port 4177
+```
+
+Control Center hiển thị work state, verification receipts, runtime events, learning proposals và eval summary; server mode có safe stale-recovery action.
+
+---
+
+## Sandbox cho tác vụ ghi song song
+
+Tạo isolated Git worktree:
+
+```cmd
+ocskill sandbox create <slug> <task-id> .
 ```
 
-Có **20 standard live tasks**.
+Tích hợp sandbox sau khi đã inspect/verify:
 
-## Long-horizon integrity
+```cmd
+ocskill sandbox integrate <worktree-path> .
+```
+
+Liệt kê sandbox:
 
 ```cmd
-npm run evals:long:validate
+ocskill sandbox list .
+```
+
+Integration sẽ từ chối ghi đè lên file đang dirty ở root. Safe-wave scheduling chỉ bảo vệ declared file scope. Generated file, lockfile hoặc shared write surface ngầm định vẫn nên được serialize khi cần.
+
+---
+
+## Evaluation
+
+UES 9.0.0 hiện có:
+
+- **34 static skill-routing scenarios** phủ 39 skills;
+- **120 V2 router cases** với required routes và negative guards;
+- **20 standard live tasks**;
+- **5 long-horizon tasks**;
+- **8 polyglot tasks** cho Python, Java, .NET, Next.js, React Native, SQL migration, monorepo và generated contract;
+- benchmark matrix baseline-vs-UES nhiều trial;
+- một long task tích hợp tới **15 source modules**.
+
+Kiểm tra static routing:
+
+```cmd
+npm run evals
+```
+
+Kiểm tra V2 router:
+
+```cmd
+npm run evals:router
 ```
 
-Có **5 long tasks**, trong đó một task yêu cầu phối hợp **15 source modules**.
+Kiểm tra standard hidden graders:
 
-## Baseline vs UES model thật
+```cmd
+npm run evals:live:validate
+```
+
+Kiểm tra long-horizon và polyglot suite:
+
+```cmd
+npm run evals:long:validate
+npm run evals:polyglot:validate
+```
+
+Chạy benchmark với model thật:
 
 ```cmd
 ocskill eval-live --model provider/model --trials 3
 ocskill eval-live --suite long --model provider/model --trials 3
+npm run evals:matrix -- --model provider/model --trials 3
 ```
 
-Với suite `long`, UES mode chỉ được tính PASS khi:
+Live eval hỗ trợ heartbeat, hard timeout, idle timeout và Ctrl+C process-tree cancellation.
 
-- hidden grader PASS
-- có durable `.ues-work`
-- plan approval PASS
-- plan có ít nhất 2 task
-- mọi task đã được attempt + completed
-- integration verification PASS
-- integration evidence tồn tại
-- finalization evidence tồn tại
-- state cuối là `completed`
-
-Vì vậy model giải code trực tiếp trong một context nhưng bỏ qua long-horizon engine sẽ không được tính là UES long PASS.
+Với long suite, một run UES chỉ được tính PASS khi hidden grader PASS, durable work state tồn tại, plan approval hợp lệ, toàn bộ task hoàn tất, integration verification PASS và finalization hoàn tất.
 
 ---
 
-# 11. CI / package release
+## Phát triển và CI
+
+Yêu cầu:
 
-Yêu cầu phát triển:
+- Node.js 20+;
+- npm;
+- Git.
 
-- Node.js 20+
-- npm
-- Git
+Cài dependency mà không chạy lifecycle script:
 
 ```cmd
 npm ci --ignore-scripts
+```
+
+Chạy toàn bộ CI:
+
+```cmd
 npm run ci
 ```
 
-Pipeline gồm:
+Pipeline hiện kiểm tra:
 
 ```text
 syntax
 → resource validation
 → static skill routing
-→ 120-case router eval
+→ V2 router matrix
 → standard hidden-grader integrity
 → long hidden-grader integrity
+→ polyglot hidden-grader integrity
 → Node tests
 → npm pack --dry-run
 → packed global-install smoke
+→ plain one-command install compatibility smoke
 ```
 
-Packed smoke kiểm tra OpenCode V2 path, 39 skills, 11 commands, 10 subagents, router plugin, task graph, durable work state và model config.
+Packed smoke xác minh package cài được từ tarball và kiểm tra OpenCode V2 path, skills, commands, subagents, router plugin, task graph, durable state và model config.
 
 ---
 
-# 12. Update / remove
+## Cập nhật và gỡ cài đặt
 
-Update:
+Cập nhật lên bản npm mới nhất:
 
 ```cmd
 ocskill update
 ```
 
-Remove:
+Gỡ UES:
 
 ```cmd
 ocskill remove
 ```
 
-UES chỉ quản lý resource có namespace/marker của chính nó, giữ unmanaged collisions và chống accidental downgrade.
+UES chỉ quản lý resource có namespace/marker của chính nó và cố gắng giữ nguyên resource không thuộc quyền quản lý của UES.
 
 ---
 
-# Tài liệu
+## Tài liệu
 
-- [Engineering design](docs/ENGINEERING-DESIGN.md)
-- [OpenCode compatibility](docs/OPENCODE-COMPAT.md)
-- [Deterministic tools](docs/DETERMINISTIC-TOOLS.md)
+- [Thiết kế hệ thống](docs/ENGINEERING-DESIGN.md)
+- [Tương thích OpenCode](docs/OPENCODE-COMPAT.md)
+- [Công cụ deterministic](docs/DETERMINISTIC-TOOLS.md)
 - [Evaluation](docs/EVALS.md)
 - [Trace schema](docs/TRACE-SCHEMA.md)
-- [npm publish](docs/NPM-PUBLISH.md)
-- [Research sources](docs/RESEARCH-SOURCES.md)
-
-# License
-
-MIT
+- [Hướng dẫn publish npm](docs/NPM-PUBLISH.md)
+- [Nguồn nghiên cứu](docs/RESEARCH-SOURCES.md)
+- [V7 Intelligence Runtime](docs/V7-INTELLIGENCE-RUNTIME.md)
+- [V8 Intelligence & Reliability](docs/V8-INTELLIGENCE-RELIABILITY.md)
+- [V9 Speed & Intelligence](docs/V9-SPEED-INTELLIGENCE.md)
 
+---
 
-# 13. Learning, Hermes và Control Center
+## npm
 
-Evidence-gated learning:
+Package:
 
-```cmd
-ocskill learn analyze . --eval-dir .ues-evals
-ocskill learn status .
-ocskill learn accept <proposal-id> .
+```text
+opencode-agent-skill
 ```
 
-Optional Hermes adapter:
+Cài đặt:
 
 ```cmd
-ocskill hermes status
-ocskill hermes prompt <slug> <task> .
-ocskill hermes exec <slug> <task> .
+npm install -g opencode-agent-skill
 ```
 
-Local Control Center:
+Phiên bản hiện tại:
 
-```cmd
-ocskill dashboard .
-ocskill dashboard . --serve --port 4177
+```text
+9.0.0
 ```
 
-Parallel write isolation primitives:
+---
 
-```cmd
-ocskill sandbox create <slug> <task> .
-ocskill sandbox list .
-```
+## License
+
+MIT