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

package/README.md

@@ -1,849 +1,1798 @@
-# OpenCode Universal Engineering System (UES)
+# UES for Pi Agent
 
-> **V13 beta: 13.0.0-beta.2** — parallel weak-model runtime với same-model worker pool, event-driven DAG, transactional worktree integration và hardened CLI/Windows runtime.
-> **Stable latest vẫn là V11: 11.0.0.** V13 được đóng gói dưới prerelease `13.0.0-beta.2`; npm prerelease dùng dist-tag `next`, còn `latest` tiếp tục giữ V11 cho đến khi V13 được promote stable.
+> Universal Engineering System (UES) là một engineering runtime dành cho **Pi Agent**, tập trung vào việc giúp model coding nhỏ/yếu làm việc có cấu trúc hơn trên repository thật: lấy đúng context, chia task, giữ trạng thái dài hạn, cô lập thay đổi, thu evidence và chỉ kết luận khi có verification.
 
-[![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)
+**Package:** <code>opencode-agent-skill</code>  
+**Host chính:** Pi Agent  
+**Phiên bản package hiện tại:** <code>14.2.0-beta.1</code>  
+**Nhánh phát triển hiện tại:** V14.2 Turbo Weak-Model Runtime  
+**Runtime:** Node.js 22.19+  
+**License:** MIT
 
-## Giới thiệu
+> UES không biến một model nhỏ thành model lớn theo nghĩa năng lực nền tảng. UES cố gắng giảm phần suy luận hạ tầng mà model phải tự gánh bằng deterministic tooling, bounded context, specialist roles, durable state và evidence-gated verification.
 
-**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 để:
+---
+
+## Mục lục
+
+1. [UES giải quyết vấn đề gì?](#ues-giải-quyết-vấn-đề-gì)
+2. [Kiến trúc tổng thể](#kiến-trúc-tổng-thể)
+3. [Luồng /ues-run end-to-end](#luồng-ues-run-end-to-end)
+4. [Task Policy: FAST / STANDARD / DEEP](#task-policy-fast--standard--deep)
+5. [12 specialist agents](#12-specialist-agents)
+6. [48 skills](#48-skills)
+7. [11 slash prompts](#11-slash-prompts)
+8. [Context Engine L0/L1/L2](#context-engine-l0l1l2)
+9. [Semantic index, repo graph và ACI](#semantic-index-repo-graph-và-aci)
+10. [Model routing và recovery](#model-routing-và-recovery)
+11. [Task graph, Dynamic Workflow và parallel runtime](#task-graph-dynamic-workflow-và-parallel-runtime)
+12. [Worktree sandbox](#worktree-sandbox)
+13. [Evidence Store, receipts và verification gates](#evidence-store-receipts-và-verification-gates)
+14. [V14.1 reversible output compaction](#v141-reversible-output-compaction)
+15. [V14.2 Turbo Weak-Model Runtime](#v142-turbo-weak-model-runtime)
+16. [Verified Persistent Memory](#verified-persistent-memory)
+17. [Capability Fabric](#capability-fabric)
+18. [Playwright / Browser MCP on-demand](#playwright--browser-mcp-on-demand)
+19. [Trajectory và observability](#trajectory-và-observability)
+20. [Learning engine và benchmark confidence](#learning-engine-và-benchmark-confidence)
+21. [Durable long-horizon work](#durable-long-horizon-work)
+22. [Control Center](#control-center)
+23. [Safety model](#safety-model)
+24. [Cài đặt](#cài-đặt)
+25. [Cập nhật](#cập-nhật)
+26. [Đóng gói npm](#đóng-gói-npm)
+27. [Các CLI quan trọng](#các-cli-quan-trọng)
+28. [Benchmark model yếu](#benchmark-model-yếu)
+29. [Cấu trúc repository](#cấu-trúc-repository)
+30. [Triết lý thiết kế](#triết-lý-thiết-kế)
+31. [Giới hạn có chủ đích](#giới-hạn-có-chủ-đích)
+
+---
+
+# UES giải quyết vấn đề gì?
 
-- 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.
+Một coding model yếu thường gặp các vấn đề sau khi làm việc trên repository thật:
 
-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**.
+| Vấn đề | Nếu để model tự xử lý | UES xử lý thế nào |
+|---|---|---|
+| Repository lớn | đọc quá nhiều file, mất context | semantic index + hierarchy L0/L1/L2 + bounded context |
+| Task dài | quên mục tiêu, lặp lại việc | durable work state + PLAN/STATE/EVENTS |
+| Nhiều thay đổi song song | đụng file, ghi đè nhau | task graph + safe waves + worktree sandbox |
+| Không biết test gì | chạy full CI hoặc đoán | detect-tests + verification plan + declared verification commands |
+| Model báo xong quá sớm | false PASS | verifier + integration-verifier + receipts |
+| Retry mù | vá chồng vá | diagnosis-first recovery policy |
+| Log quá lớn | token phình | reversible model-visible compaction |
+| Tool quá nhiều | model chọn sai tool | role allowlist + capability-based routing |
+| UI/browser | đoán thay vì quan sát | Playwright/Browser MCP lane + visual verifier |
+| Kinh nghiệm cũ | nhớ sai hoặc nhiễm | verified persistent memory |
+| Tối ưu không có bằng chứng | nhanh hơn nhưng yếu đi | baseline-vs-UES eval + promotion confidence |
 
 ---
 
+# Kiến trúc tổng thể
+
+~~~mermaid
+flowchart TD
+    U[User task] --> P[Pi Agent]
+    P --> X[UES extension]
+
+    X --> TP[Task Policy]
+    TP --> C[Context Engine]
+    TP --> M[Model Policy]
+    TP --> W[Workflow Policy]
+
+    C --> H[Hierarchy L0 L1 L2]
+    C --> SI[Semantic Index]
+    C --> MEM[Verified Memory]
+    C --> CAP[Capability Fabric]
+    C --> EV[Evidence Store]
+
+    W --> A[Specialist Agents]
+    W --> TG[Task Graph]
+    W --> DW[Dynamic Workflow]
+    W --> SB[Worktree Sandbox]
+
+    A --> EX[Executor]
+    A --> VE[Verifier]
+    A --> IV[Integration Verifier]
+    A --> VV[Visual Verifier]
+
+    EX --> CHECK[Project-native checks]
+    VE --> CHECK
+    IV --> CHECK
+    VV --> BROWSER[Playwright Browser evidence]
 
-## V13 beta: Parallel Weak-Model Runtime
+    CHECK --> R[Fresh Evidence]
+    BROWSER --> R
+    R --> G{Verification gates}
+    G -->|PASS| DONE[Verified completion]
+    G -->|FAIL| REC[Diagnosis and bounded retry]
+    REC --> C
+~~~
 
-V13 cho phép **một model duy nhất** chạy nhiều fresh child sessions song song. `ues.dispatch_parallel` chọn một shared model (hoặc giữ OpenCode default model), chạy các task độc lập theo event-driven DAG, dùng resource lease để tránh writer conflict, tạo worktree riêng cho writer, dùng fresh same-model `ues-verifier`, rồi tích hợp tuần tự. Nếu bước receipt/complete thất bại sau khi patch đã áp dụng, integration transaction tự rollback patch của task đó.
+## Các lớp chính
 
-```text
-approved PLAN
-    ↓
-event-driven DAG
-    ↓
-same model × N fresh sessions
-    ↓
-isolated worktrees + resource leases
-    ↓
-fresh same-model verifier
-    ↓
-transactional integration queue
-    ↓
-unlock dependencies immediately
-```
+### 1. Pi host layer
 
-CLI V13 cũng xử lý `--help` trước positional parsing, hỗ trợ `ocskill work status .`, structured errors với `--json`, đọc UTF-8/UTF-16 an toàn và cung cấp `ocskill diff . --out dirty.diff` để tránh PowerShell tạo diff UTF-16 bị OpenCode nhận nhầm là binary.
+Pi chịu trách nhiệm session, model provider, thinking level, built-in tools và extension runtime.
 
-Parallel resume không còn yêu cầu root phải sạch tuyệt đối. Nếu repository đã có dirty diff hợp lệ từ phiên trước, V13 chụp baseline đó vào worktree cô lập và chỉ tích hợp delta của task; thay đổi cũ được giữ nguyên. Root vẫn phải là Git repository và resource leases vẫn chặn các writer xung đột.
+### 2. UES Pi extension
 
-> **Compatibility:** V13 CLI/durable-state/verification hardening vẫn dùng được trên OpenCode 1.x. Native `ues.dispatch_task` / `ues.dispatch_parallel` cần router plugin và fresh-session APIs của OpenCode V2; nếu capability không đủ, runtime fail closed thay vì giả vờ chạy song song.
+File chính: <code>pi/extensions/ues.ts</code>.
 
-### V13 beta validation gate
+Extension đăng ký ba tool orchestration:
 
-Mỗi V13 prerelease, bao gồm beta.2, chỉ được publish sau khi full gate hiện tại PASS. Không hard-code số lượng test vào tài liệu này vì suite tiếp tục tăng; nguồn đúng là output của chính các lệnh gate:
+| Tool | Vai trò |
+|---|---|
+| <code>ues_execute</code> | Chạy task engineering end-to-end |
+| <code>ues_cli</code> | Gọi deterministic UES CLI không qua shell interpolation |
+| <code>ues_dispatch</code> | Gọi specialist child agents theo single / chain / bounded parallel |
+
+### 3. Deterministic engine
+
+Thư mục <code>lib/</code> chứa các engine cho:
+
+- task/risk classification;
+- semantic index;
+- repo graph;
+- context manifest;
+- evidence storage;
+- receipts;
+- work state;
+- task graph;
+- safe-wave scheduling;
+- model routing;
+- memory;
+- capability selection;
+- browser evidence;
+- benchmark/learning;
+- safety;
+- Windows compatibility.
+
+### 4. Specialist layer
+
+UES không dùng một prompt khổng lồ cho mọi việc. Nó có 12 specialist roles với tool boundary khác nhau.
 
-- `npm run evals:v13`;
-- `npm test`;
-- `npm run ci`;
-- `npm pack --dry-run`;
-- packed-install smoke và plain-install smoke;
-- live OpenCode V2 check: router load, `/ues-run` FAST/STANDARD/DEEP admission, prompt dài, MCP/provider path và restart trên session mới;
-- npm 11+ có thể chặn lifecycle script theo `allowScripts`; `ocskill install` vẫn là resource-sync fallback chính thức.
+### 5. Verification layer
 
+Hoàn thành không đồng nghĩa model nói “done”. UES cố gắng ràng buộc completion với fresh evidence, receipt và verifier độc lập.
 
 ---
 
+# Luồng /ues-run end-to-end
+
+<code>/ues-run</code> là entry point khuyến nghị cho engineering task.
+
+~~~mermaid
+sequenceDiagram
+    participant U as User
+    participant P as Pi
+    participant UES as UES Controller
+    participant CTX as Context Engine
+    participant EX as Executor
+    participant V as Verifier
+    participant IV as Integration Verifier
+    participant VV as Visual Verifier
+
+    U->>P: /ues-run task
+    P->>UES: ues_execute(task)
+    UES->>UES: classify task/risk/profile
+    UES->>CTX: build bounded context
+    CTX-->>UES: hierarchy + evidence + memory + capability hints
+
+    alt long/high risk
+        UES->>UES: architect + structured plan
+        UES->>UES: plan-checker gate
+    end
+
+    UES->>EX: fresh specialist execution
+    EX-->>UES: implementation handoff
+
+    UES->>V: independent verification
+    V-->>UES: PASS / FAIL / PARTIAL
+
+    alt integration required
+        UES->>IV: cross-task/final repository verification
+        IV-->>UES: PASS / FAIL / PARTIAL
+    end
+
+    alt visual/browser evidence required
+        UES->>VV: rendered-state verification
+        VV-->>UES: PASS / FAIL / PARTIAL
+    end
+
+    alt all required gates PASS
+        UES-->>P: verified completion
+        P-->>U: final result
+    else failure
+        UES->>UES: diagnosis / recovery / bounded retry
+    end
+~~~
+
+## UES không làm gì ở luồng này?
+
+- không tự push;
+- không tự publish npm;
+- không tự deploy production;
+- không coi executor report là bằng chứng hoàn thành;
+- không bỏ verifier chỉ vì compile pass;
+- không lưu hidden chain-of-thought.
+
+---
+
+# Task Policy: FAST / STANDARD / DEEP
+
+Task Policy nằm trong <code>lib/task-policy.mjs</code> và phân loại task theo tín hiệu có thể quan sát.
+
+~~~mermaid
+flowchart LR
+    T[Task text + repo facts] --> S[Risk and complexity signals]
 
-## Cài đặt
+    S --> F{Classification}
+    F -->|low + bounded| FAST[FAST]
+    F -->|medium| STD[STANDARD]
+    F -->|long horizon or high risk| DEEP[DEEP]
 
-Yêu cầu:
+    FAST --> F1[8k context budget]
+    FAST --> F2[max 2 skills]
+    FAST --> F3[targeted verification]
 
-- Node.js 20 trở lên;
-- npm;
-- OpenCode.
+    STD --> S1[20k context budget]
+    STD --> S2[max 4 skills]
+    STD --> S3[targeted + affected verification]
 
-Cài đặt stable hiện tại từ npm:
+    DEEP --> D1[48k context budget]
+    DEEP --> D2[max 5 skills]
+    DEEP --> D3[plan + integration + durable state]
+~~~
 
-```cmd
-npm install -g opencode-agent-skill
-```
+## FAST
 
-Cài V13 beta từ npm sau khi prerelease đã có trên registry:
+Dành cho task nhỏ, low-risk, bounded.
 
-```cmd
-npm install -g opencode-agent-skill@next
-ocskill install
-```
+Đặc điểm:
 
-Nếu đang kiểm thử một commit mới hơn bản registry, cài trực tiếp từ checkout:
+- context budget mặc định khoảng 8k;
+- tối đa 2 skills;
+- direct skill loading;
+- không bắt durable work;
+- verification targeted;
+- không bật full CI mặc định.
 
-```cmd
-npm install -g .
-ocskill install
-```
+## STANDARD
 
-Kiểm tra:
+Dành cho task vừa, có debugging/change scope đáng kể.
 
-```cmd
-ocskill version
-ocskill status
-ocskill doctor
-```
+Đặc điểm:
 
-Nếu npm không chạy lifecycle script trong lúc cài đặt (npm 11+ có thể cảnh báo `install-scripts ... not yet covered by allowScripts`), package CLI vẫn có thể đã được cài. Chạy resource sync rõ ràng:
+- context budget khoảng 20k;
+- tối đa 4 skills;
+- selective skill loading;
+- affected verification;
+- worktree khi có conflict.
 
-```cmd
-ocskill install
-```
+## DEEP
 
-Đây là fallback được CI smoke kiểm tra; không cần dùng `--force` chỉ để vượt cảnh báo lifecycle script.
+Dành cho long-horizon/high-risk.
 
-Sau khi cài hoặc cập nhật UES, hãy restart OpenCode service rồi mở một session mới để skill, command, subagent và plugin được nạp lại đầy đủ:
+Đặc điểm:
 
-```cmd
-opencode service restart
-```
+- context budget đến khoảng 48k;
+- tối đa 5 skills;
+- structured plan;
+- durable state;
+- plan checker;
+- worktree cho writers;
+- integration verification;
+- full CI policy;
+- critic ở high-risk/final paths.
 
-Trên OpenCode V2 có thể kiểm tra router bằng `/plugins`, sau đó gọi `ues.capabilities`. Native parallel chỉ nên dùng khi `freshDispatch` báo `true`.
+## High-risk signals
+
+UES phân biệt “chỉ nhắc tới database/security” với “thực sự thay đổi database/security”.
+
+Những thay đổi như sau có thể nâng risk:
+
+- auth/permission/security mutation;
+- payment flow;
+- database/schema migration;
+- production deploy;
+- secret/credential rotation;
+- breaking public API;
+- destructive Git/database action.
 
 ---
 
-## Bắt đầu nhanh
+# 12 specialist agents
+
+Thư mục: <code>global-config/agents/</code>.
+
+| Agent | Nhiệm vụ | Có ghi file? | Khi dùng |
+|---|---|---:|---|
+| architect | thiết kế plan/contract/dependency | không | task phức tạp, long-horizon |
+| codebase-mapper | đọc repo và map scope | không | repo lớn/không rõ vị trí |
+| critic | phản biện plan/solution | không | high-risk hoặc recovery sâu |
+| debugger | tìm nguyên nhân gốc từ evidence | không | bug/failure/retry |
+| executor | thực thi thay đổi nhỏ nhất hợp lý | có | implementation |
+| integration-verifier | kiểm tra final cross-task state | không | standard/deep/high-risk |
+| merge-arbiter | xử lý integration/merge boundary | có | conflict/merge workflow |
+| plan-checker | kiểm tra plan có grounded không | không | trước long/high-risk execution |
+| researcher | nghiên cứu bằng chứng | không | uncertainty/external facts |
+| reviewer | review thay đổi | không | code review/audit |
+| verifier | fresh independent verification | không | completion gate |
+| visual-verifier | verify rendered UI/browser state | không | visual/browser task |
+
+## Quan hệ giữa các agent
+
+~~~mermaid
+flowchart TD
+    MAP[codebase-mapper] --> ARCH[architect]
+    ARCH --> PC[plan-checker]
+    PC --> EX[executor]
+
+    EX --> V[verifier]
+    V -->|PASS| IV[integration-verifier]
+    V -->|FAIL| D[debugger]
+
+    D --> EX
+    D --> C[critic]
+    C --> ARCH
+
+    IV -->|visual task| VV[visual-verifier]
+    IV -->|non visual| DONE[complete]
+    VV --> DONE
+
+    R[researcher] -. evidence .-> ARCH
+    R -. evidence .-> D
+    REV[reviewer] -. review .-> V
+~~~
 
-Với tác vụ lớn, dùng:
+---
 
-```text
-/ues-run <yêu cầu>
-```
+# 48 skills
+
+UES hiện có 48 skill directories trong <code>global-config/skills/</code>. Skills không phải 48 agent độc lập; chúng là bounded domain instructions để UES chỉ nạp đúng chuyên môn cần thiết.
+
+## Nhóm orchestration và reasoning
+
+- engineering-orchestrator
+- dynamic-workflow
+- task-planner
+- software-architect
+- context-engineering
+- change-impact-analysis
+- repo-explorer
+- research-verification
+- long-task-state
+- implementation-engineer
+- bug-diagnosis
+- code-review
+- skill-authoring
+- skill-evaluation
+
+## Nhóm verification và testing
+
+- test-driven-development
+- test-verification
+- accessibility
+- responsive-verification
+- component-visual-testing
+- visual-fidelity
+- browser-qa
+- browser-security
+- web-security-review
+- performance-engineering
+
+## Nhóm backend / API / data
+
+- api-contract
+- rest-api-design
+- auth-security
+- database-engineering
+- payment-engineering
+- ecommerce-engineering
+- file-upload-engineering
+- dependency-management
+- devops-engineering
+- documentation-engineering
+- git-safety
+
+## Nhóm framework / language
+
+- nodejs-engineering
+- nextjs-engineering
+- react-engineering
+- react-native-engineering
+- nestjs-engineering
+- fastapi-engineering
+- django-engineering
+- python-engineering
+- java-spring-engineering
+- dotnet-engineering
+- flutter-engineering
+
+## Nhóm UI/design
+
+- ui-ux-engineering
+- design-source
+
+> Mục tiêu của skill routing là progressive disclosure: model không phải đọc tất cả 48 skills cho một task.
 
-Nếu session bị ngắt hoặc context bị compact:
+---
 
-```text
-/ues-resume <slug>
-```
+# 11 slash prompts
 
-Một số lệnh hữu ích:
+Pi package cung cấp 11 slash prompts:
 
-```cmd
-ocskill inspect .
-ocskill repo-graph . --compact
-ocskill verification-plan .
-ocskill task-policy "refactor auth across the whole repository"
-ocskill dashboard . --serve
-```
+| Command | Ý nghĩa |
+|---|---|
+| <code>/ues-run</code> | controller end-to-end |
+| <code>/ues-plan</code> | lập kế hoạch |
+| <code>/ues-feature</code> | triển khai feature |
+| <code>/ues-fix</code> | sửa bug |
+| <code>/ues-debug</code> | điều tra failure |
+| <code>/ues-review</code> | review code/scope |
+| <code>/ues-verify</code> | xác minh claim |
+| <code>/ues-audit</code> | audit scope |
+| <code>/ues-research</code> | research |
+| <code>/ues-critique</code> | phản biện proposal |
+| <code>/ues-resume</code> | tiếp tục durable work |
+
+~~~mermaid
+flowchart LR
+    CMD[Slash command] --> ROUTE[UES router/controller]
+    ROUTE --> POLICY[Task policy]
+    POLICY --> AGENT[Relevant specialist path]
+    AGENT --> EVIDENCE[Fresh evidence]
+    EVIDENCE --> RESULT[Result]
+~~~
 
 ---
 
-## V11 có gì?
+# Context Engine L0/L1/L2
 
-V11 chuyển UES từ một reliability harness thành **perception-aware adaptive execution engine**. Mục tiêu là model yếu chỉ nhận đúng bằng chứng cần thiết, dùng đúng capability/model/tool và có thể kiểm chứng UI bằng semantic structure + geometry + pixels thay vì đoán từ screenshot.
+Một trong các mục tiêu lớn của UES là **nạp ít context hơn nhưng đúng hơn**.
 
-- content-addressed Evidence Store dưới `.ues-cache/evidence-v1/`; output lớn được lưu theo SHA-256 và context nhận bounded excerpt + `evidence:sha256:...` pointer;
-- adaptive EvidenceBudget chia context cho instructions/task/source/tests/references/history/tools theo rủi ro và loại task thay vì luôn tiêu hết FAST/STANDARD/DEEP budget;
-- prompt-envelope telemetry tách stable prefix và dynamic tail để đo cacheable ratio/repeated stable input;
-- capability-aware model routing bổ sung `vision`, `browser`, `reasoning`, `toolCalling`, `filesystem`, `longContext` nhưng vẫn giữ light/standard/heavy để tương thích;
-- `VISUAL_SPEC.json` + geometry receipt kiểm tra vị trí/kích thước element có tolerance rõ ràng;
-- zero-dependency PNG diff/crop định vị vùng pixel sai rồi chỉ đưa crop cần thiết cho vision model;
-- browser QA dùng targeted semantic/accessibility evidence + bounding boxes + screenshots; webpage content luôn được xem là untrusted;
-- responsive viewport matrix và component visual testing/Storybook routing;
-- dynamic workflow scheduler tách deterministic task khỏi LLM/vision fan-out, serialize overlapping writers và giới hạn concurrency;
-- skill linter đo entrypoint size và description collisions; catalog tăng từ 39 lên **48 skills** nhưng router chỉ load skill có tín hiệu hẹp;
-- hai subagent mới: `ues-visual-verifier` và `ues-merge-arbiter`, tổng **12 subagents**;
-- Hermes được nâng thành optional sidecar: UES vẫn sở hữu durable state/evidence/safety, Hermes chỉ nhận bounded schedule/context khi được dùng;
-- Control Center hiển thị Evidence Store và V11 runtime efficiency state.
+~~~mermaid
+flowchart TD
+    Q[Task query] --> TERM[Extract bounded terms]
+    TERM --> IDX[Semantic index]
+    IDX --> H0[L0 routing abstract]
+    H0 --> H1[L1 subtree overview]
+    H1 --> H2[L2 exact excerpts on demand]
 
-Các CLI V11 chính:
+    GIT[Git changed files] --> RANK[Ranking]
+    DECL[Declared files] --> RANK
+    TEST[Likely tests] --> RANK
+    SYM[Symbol hits] --> RANK
+    MEM[Verified memory] --> RANK
 
-```cmd
-ocskill store status .
-ocskill store get evidence:sha256:<hash> . --max 12000
-ocskill capabilities "match this screenshot in the browser"
-ocskill visual spec VISUAL_SPEC.json
-ocskill visual geometry VISUAL_SPEC.json actual-boxes.json
-ocskill visual compare expected.png actual.png --threshold 16
-ocskill visual crop actual.png failed-region.png --x 10 --y 20 --width 300 --height 120
-ocskill visual viewports
-ocskill browser capability .
-ocskill browser plan http://localhost:3000 --target Checkout
-ocskill browser inspect http://localhost:3000 . --selector "button" --width 1440 --height 900
-ocskill ui tokens src/styles.css
-ocskill ui layout boxes.json --width 390 --height 844
-ocskill workflow-plan PLAN.json --max-concurrent 4
-ocskill skills lint .
-ocskill models capability provider/model --vision on --browser on --quality 0.9
-```
-
-V11 stable được promote sau full local CI trên Windows PASS: 234 tests, 232 pass, 0 fail, 2 platform-specific skips; router/contract/package/install smoke đều PASS. Stable npm install dùng `npm install -g opencode-agent-skill`.
-
----
-
-## V10 có gì?
-
-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.
-
-- 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.
-
-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 cấu trúc:
-
-```text
-.ues-work/<slug>/
-├── SPEC.md
-├── PLAN.json
-├── STATE.json
-├── EVIDENCE.json
-├── EVENTS.jsonl
-├── tasks/
-└── reports/
-```
+    H2 --> RANK
+    RANK --> PACK[Bounded context pack]
+    PACK --> CHILD[Fresh child agent]
+~~~
+
+## L0
+
+Routing abstract rất ngắn:
+
+- khu vực nào có vẻ liên quan;
+- key symbols;
+- child areas.
+
+## L1
+
+Scope overview:
+
+- file count;
+- extension mix;
+- symbols;
+- bounded file names;
+- subtree relation.
+
+## L2
+
+Exact excerpts chỉ load khi cần.
+
+## Context pack có thể bao gồm
+
+- declared files;
+- import neighbors;
+- likely tests;
+- nearby instructions;
+- Git-changed files;
+- semantic references;
+- symbol hits;
+- evidence refs;
+- verified memories;
+- provider hints;
+- recent failure.
+
+---
+
+# Semantic index, repo graph và ACI
+
+UES có ba lớp khác nhau; chúng không phải một thứ.
 
-`.ues-work/` là trạng thái thực thi của workflow, không phải hidden chain-of-thought.
+## Semantic Index
 
-### Gate 1 — Phê duyệt kế hoạch
+<code>lib/semantic-index.mjs</code>
 
-Sau khi tạo plan, task chưa được chạy ngay. Trạng thái sẽ ở:
+Dùng để tạo persistent incremental index phục vụ retrieval.
 
-```text
-awaiting-plan-approval
-```
+~~~mermaid
+flowchart LR
+    SRC[Source files] --> PARSE[Bounded parse]
+    PARSE --> SYMBOLS[Symbols]
+    PARSE --> TERMS[Terms]
+    SYMBOLS --> INDEX[Persistent semantic index]
+    TERMS --> INDEX
+    INDEX --> QUERY[Task query]
+    QUERY --> RANK[Ranked references]
+~~~
 
-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:
+CLI:
 
-```cmd
-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
-```
+~~~text
+ues index status .
+ues index build .
+ues index rebuild .
+~~~
 
-Nếu thiếu structured receipt ở workflow strict, `ocskill work start` sẽ không được mở gate.
+## Repo Graph
 
-### Gate 2 — Bằng chứng cho từng task
+<code>lib/repo-graph.mjs</code>
 
-Có thể ghi verification receipt trực tiếp từ command:
+Tạo bounded import/dependency graph:
 
-```cmd
-ocskill work verify-command <slug> <task-id> . --run-id <run-id> -- npm test
-```
+- local edges;
+- external imports;
+- coupling hotspots.
 
-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.
+Nó **không tự nhận là full language-server call graph**.
 
-### Gate 3 — Kiểm tra tích hợp
+~~~mermaid
+flowchart LR
+    FILES[Source files] --> IMPORTS[Import extraction]
+    IMPORTS --> LOCAL[Local dependency edges]
+    IMPORTS --> EXT[External import frequency]
+    LOCAL --> HOT[Coupling hotspots]
+    EXT --> HOT
+~~~
 
-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:
+CLI:
 
-```cmd
-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
-```
+~~~text
+ues repo-graph .
+ues repo-graph . --compact
+~~~
 
-Sau đó:
+## ACI
 
-```cmd
-ocskill work finalize <slug> . --evidence "final acceptance verified"
-```
+<code>lib/aci.mjs</code>
 
-`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.
+Evidence-first code interface cho:
+
+- search;
+- references;
+- view;
+- bounded text search.
+
+CLI:
+
+~~~text
+ues aci search ...
+ues aci refs ...
+ues aci view ...
+ues aci text ...
+~~~
 
 ---
 
-## Fresh-context executor trên OpenCode V2
+# Model routing và recovery
+
+UES không hard-code tên model “mạnh nhất”. Model IDs do người dùng cấu hình.
+
+## Tier
+
+- light
+- standard
+- heavy
 
-OpenCode V2 plugin cung cấp tool:
+Role có default tier, và attempt có thể escalate trong giới hạn cấu hình.
 
-```text
-ues.dispatch_task
-```
+~~~mermaid
+flowchart TD
+    TASK[Task] --> CLASS[Task class + risk]
+    CLASS --> BASE[Base tier]
+    BASE --> CAPS[Required capabilities]
+    CAPS --> PERF[Historical model performance]
+    PERF --> SELECT[Select configured model]
 
-Luồng thực thi:
+    SELECT --> RUN[Attempt]
+    RUN -->|PASS| DONE[Done]
+    RUN -->|FAIL attempt 1| DIAG[Diagnosis]
+    DIAG --> RETRY[Attempt 2]
+    RETRY -->|FAIL| DEEP[Deep recovery + critic]
+    DEEP --> STRONGER[Eligible stronger tier]
+~~~
 
-```text
-work start
-  ↓
-đọc bounded context pack
-  ↓
-chọn model tier theo task + attempt
-  ↓
-tạo OpenCode session mới
-  ↓
-switchAgent(ues-executor)
-  ↓
-switchModel(...) nếu đã cấu hình
-  ↓
-gửi đúng một task
-  ↓
-heartbeat + bounded wait
-  ↓
-interrupt nếu timeout/cancel
-  ↓
-isolate writer khi cần
-  ↓
-trả child-session report
-```
+## Recovery policy
 
-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`.
+### Attempt 1
 
-Child session không được tự động merge, push, publish hoặc deploy.
+- normal bounded context;
+- smallest coherent implementation.
+
+### Attempt 2
+
+- dedicated diagnosis;
+- mở rộng context vừa phải;
+- caller/test/failure-adjacent evidence;
+- không vá speculative chồng lên patch cũ.
+
+### Attempt 3
+
+- deep recovery;
+- semantic + graph + Git context;
+- critic;
+- re-investigate failed hypothesis;
+- architecture/coupling review khi cần.
 
 ---
 
-## Subagents
+# Task graph, Dynamic Workflow và parallel runtime
 
-| 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-visual-verifier` | Xác minh độc lập screenshot/geometry/responsive/interaction mà không sửa code |
-| `ues-merge-arbiter` | Hòa giải conflict giữa các task đã verify theo intent/evidence, không push/publish/deploy |
+Structured plan dùng JSON schema version 1.
+
+Mỗi task có thể khai báo:
+
+- id;
+- title;
+- summary;
+- dependsOn;
+- files create/modify/test/delete/read;
+- acceptance;
+- verification;
+- optional verificationCommands;
+- risk.
+
+## Dependency validation
+
+UES kiểm tra:
+
+- duplicate IDs;
+- missing dependency;
+- self dependency;
+- cycles;
+- path escape;
+- acceptance/verification thiếu;
+- invalid risk.
+
+## Safe waves
+
+~~~mermaid
+flowchart TD
+    PLAN[PLAN tasks] --> DAG[Dependency DAG]
+    DAG --> READY[Ready tasks]
+    READY --> FILES[Read/write file scope]
+    FILES --> CONFLICT{Conflict?}
+
+    CONFLICT -->|No| SAME[Same safe wave]
+    CONFLICT -->|Yes| SERIAL[Serialize]
+
+    SAME --> PAR[Bounded parallel execution]
+    SERIAL --> NEXT[Later wave]
+~~~
+
+Read/read overlap có thể chạy cùng wave. Writer xung đột với reader/writer sẽ bị serialize nếu scope overlap hoặc không đủ rõ.
 
-`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.
+## Dynamic Workflow
+
+<code>lib/dynamic-workflow.mjs</code> phân task thành:
+
+- deterministic;
+- inline;
+- agent;
+- vision-related work.
+
+~~~mermaid
+flowchart LR
+    T[Task] --> K{Kind}
+    K -->|test lint typecheck compile| DET[Deterministic]
+    K -->|small bounded reasoning| INLINE[Inline]
+    K -->|independent substantial work| AG[Agent]
+    K -->|visual judgment| VISION[Vision agent]
+
+    DET --> SAVE[No unnecessary executor slot]
+    INLINE --> SAVE
+    AG --> SLOT[LLM slot]
+    VISION --> VSLOT[Vision slot]
+~~~
+
+V14.1 có fast path: deterministic read-only task có thể bỏ executor nhưng **verifier vẫn phải PASS**.
 
 ---
 
-## Slash commands
+# Worktree sandbox
 
-Trên OpenCode 1.x, UES tiếp tục cài các command Markdown native. Trên OpenCode V2, 11 lệnh `/ues-*` được cài dưới dạng **prompt aliases** của `ues-router`: UI gửi chúng qua đường `session.prompt` đang ổn định, router mới mở rộng template UES. Cách này tránh phụ thuộc vào `session.command` V2 khi endpoint custom-command trả lỗi transport/content-type. Cú pháp người dùng không đổi, cả hai dạng đều hợp lệ:
+Parallel writers không được cùng sửa một checkout.
 
-```text
-/ues-run <yêu cầu>
-```
+~~~mermaid
+sequenceDiagram
+    participant R as Root repo
+    participant U as UES Scheduler
+    participant W1 as Worktree T1
+    participant W2 as Worktree T2
 
-hoặc:
+    U->>R: inspect dirty state
+    U->>W1: create isolated worktree
+    U->>W2: create isolated worktree
 
-```text
-/ues-run
+    W1->>W1: execute + verify T1
+    W2->>W2: execute + verify T2
 
-<yêu cầu nhiều dòng>
-```
+    U->>W1: inspect changed files
+    U->>W2: inspect changed files
+    U->>R: conflict check
 
-Trên V2 các alias này có thể không xuất hiện trong autocomplete slash menu vì UES chủ động không đăng ký native custom-command để tránh đường `session.command` đang lỗi; vẫn có thể gõ trực tiếp `/ues-run`, `/ues-fix`, v.v.
+    alt safe integration
+        U->>R: apply T1 patch
+        U->>R: apply T2 patch
+    else conflict/failure
+        U->>R: refuse or rollback integrated wave
+    end
+~~~
 
-Sau khi nâng cấp từ bản V13 cũ, chạy `ocskill install`; installer sẽ xóa các native UES command file cũ do chính UES quản lý để OpenCode V2 không còn bắt chúng qua `session.command`.
+## Safety của worktree
 
-| 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` |
+- root dirty mặc định bị chặn nếu không dùng explicit inheritance;
+- dirty root có thể được snapshot vào sandbox theo policy;
+- integration kiểm tra overlap với thay đổi root;
+- branch cleanup chỉ xóa branch namespace UES;
+- rollback dùng reverse patch;
+- không force-push.
 
 ---
 
-## Task policy và model policy
+# Evidence Store, receipts và verification gates
 
-Phân loại yêu cầu kỹ thuật:
+## Evidence Store
 
-```cmd
-ocskill task-policy "your engineering request"
-```
+UES có content-addressed Evidence Store.
 
-Kiểm tra model policy:
+~~~mermaid
+flowchart LR
+    RAW[Raw output / artifact] --> HASH[SHA-256]
+    HASH --> STORE[Evidence Store]
+    STORE --> REF[evidence:sha256:...]
+    REF --> RECEIPT[Verification / memory / gate receipt]
+    REF --> GET[Bounded retrieval]
+~~~
 
-```cmd
-ocskill model-policy executor --attempt 1 --text "your engineering request"
-```
+CLI:
 
-UES dùng ba model tier:
+~~~text
+ues store status .
+ues store put ...
+ues store get evidence:sha256:<hash>
+ues store gc .
+~~~
 
-```text
-light
-standard
-heavy
-```
+## Verification receipts
 
-Xem cấu hình:
+Receipt có thể bind:
 
-```cmd
-ocskill models status
-```
+- command result;
+- output digest;
+- before/after workspace fingerprint;
+- verifier;
+- verdict;
+- active run/task.
 
-Bật model policy:
+Mục tiêu là tránh tình trạng:
 
-```cmd
-ocskill models on
-```
+~~~text
+test từng PASS ở trạng thái A
+→ code thay đổi sang trạng thái B
+→ model vẫn dùng PASS cũ để tuyên bố hoàn thành
+~~~
 
-Gán model cho từng tier:
+## Gate model
 
-```cmd
-ocskill models set light provider/cheap
-ocskill models set standard provider/mid
-ocskill models set heavy provider/strong
-```
+~~~mermaid
+flowchart TD
+    PLAN[Plan] --> PG[Plan checker]
+    PG --> PR[Plan receipt]
+    PR --> EXEC[Execution]
 
-Gán tier theo role:
+    EXEC --> TV[Task verifier]
+    TV --> TR[Task verification receipt]
 
-```cmd
-ocskill models role executor standard
-ocskill models role plan-checker heavy
-```
+    TR --> INT[Integration verifier]
+    INT --> IR[Integration receipt]
 
-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.
+    IR --> FP{Workspace fingerprint unchanged?}
+    FP -->|Yes| FINAL[Finalize]
+    FP -->|No| INVALID[Receipt stale - reverify]
+~~~
 
 ---
 
-## Công cụ CLI
+# V14.1 reversible output compaction
+
+Mục tiêu của V14.1 là giảm model-visible noise mà **không bỏ raw evidence**.
+
+~~~mermaid
+flowchart TD
+    OUT[Large CLI/tool output] --> SIZE{Over limit?}
+    SIZE -->|No| RAW[Return unchanged]
+    SIZE -->|Yes| SAVE[Store exact raw bytes in Evidence Store]
+    SAVE --> PREVIEW[Build head + high-signal + tail preview]
+    PREVIEW --> MODEL[Send bounded preview to model]
+    MODEL --> NEED{Need more?}
+    NEED -->|Yes| REF[Retrieve exact slices by evidence ref]
+    NEED -->|No| CONT[Continue]
+~~~
+
+Default model-visible limit hiện khoảng 64 KiB.
+
+High-signal lines ưu tiên các pattern như:
+
+- error;
+- failed;
+- exception;
+- warning;
+- timeout;
+- traceback;
+- mismatch;
+- conflict;
+- passed;
+- tests;
+- exit code;
+- changed.
+
+## Quan trọng
+
+- thinking level không bị hạ bởi compaction;
+- raw output được lưu trước khi compact;
+- small output giữ nguyên;
+- failure của compaction fail-open về raw output.
 
-| Lệnh | Công dụng |
-|---|---|
-| `ocskill inspect [dir]` | Phát hiện stack, package manager, root và test command |
-| `ocskill repo-graph [dir] [--compact] [--max-files N]` | Lập import graph; dùng `--compact` để lấy hotspot/counts trước, tránh đổ toàn bộ edges trên repo lớn |
-| `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 text-read <file> [--start N] [--max N]` | Đọc bounded UTF-8/UTF-16 an toàn khi generic Read nhận nhầm text là binary |
-| `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ụ:
+# V14.2 Turbo Weak-Model Runtime
+
+V14.2 tối ưu hot path cho model yếu/siêu yếu mà không hạ thinking hoặc bỏ verification gate.
+
+~~~mermaid
+flowchart TD
+    T[Task] --> P[Task Policy]
+    P --> C[Adaptive context]
+    C --> G[Semantic + dependency graph rank]
+    G --> S[Bounded micro-skills]
+    S --> W[Warm Pi RPC worker]
+
+    W --> E[Executor]
+    E --> R[Tool-boundary verification receipts]
+    R --> V[Verifier]
+
+    V -->|fresh receipt fully covers check| REUSE[Reuse exact PASS receipt]
+    V -->|missing/stale/high-risk| RUN[Run fresh check]
+
+    REUSE --> IV[Integration verification when required]
+    RUN --> IV
+
+    E --> O[Large tool output]
+    O --> COMP[Command-aware compaction]
+    COMP --> RAW[Raw bytes in Evidence Store]
+    RAW --> REC[Selective recovery on demand]
+~~~
+
+Các thay đổi chính:
+
+- warm Pi RPC worker pool với fresh session giữa specialist runs;
+- interactive steering/abort khi một child đang active;
+- unified process-tree supervisor + bounded I/O drain;
+- rolling Jest/open-handle detection;
+- adaptive role-aware context budgets;
+- runtime context + dependency-graph cache theo workspace fingerprint;
+- bounded micro-skill compiler thay vì load toàn bộ skill catalog;
+- affected-test hints;
+- verification receipt reuse chỉ khi fingerprint còn nguyên;
+- high-risk verifier không dùng receipt reuse optimization;
+- child test/lint/typecheck/build có timeout theo profile;
+- full shell output được recover từ Pi `fullOutputPath` khi có;
+- command-aware reversible compaction ngay ở child tool-result boundary;
+- JSON evidence selector để lấy đúng subtree;
+- personalized dependency graph ranking;
+- task-specific Browser MCP subset;
+- confidence-bound weak-model routing;
+- DEEP task auto-promote sang `.ues-work` durable workflow;
+- paired benchmark có turbo promotion gate: **quality non-regression + efficiency gain + zero controller false-PASS**.
+
+Các optimization quan trọng có thể rollback riêng:
+
+~~~text
+UES_CHILD_RUNTIME=cli
+UES_ADAPTIVE_CONTEXT=0
+UES_MICRO_SKILLS=0
+UES_AFFECTED_TEST_HINTS=0
+UES_CHILD_TOOL_COMPACTION=0
+~~~
+
+Chi tiết: `docs/V14.2-TURBO-WEAK-MODEL-RUNTIME.md`.
+
+---
 
-```cmd
-ocskill repo-graph . --compact
-ocskill review-scope main .
-ocskill verification-plan .
-ocskill task-graph .ues-work/checkout/PLAN.json
-ocskill work status checkout .
-```
+# Verified Persistent Memory
+
+Memory của UES không phải “chat memory tự do”. Retrieval chỉ dùng memory đủ điều kiện.
+
+~~~mermaid
+flowchart TD
+    EXPERIENCE[Task outcome] --> CAND[Memory candidate]
+    CAND --> EVID{Has durable evidence?}
+    EVID -->|No| DROP[Not retrievable]
+    EVID -->|Yes| VER{Verifier PASS?}
+    VER -->|No| DROP
+    VER -->|Yes| VM[Verified memory]
+
+    VM --> RANK[Hybrid retrieval]
+    RANK --> LEX[Lexical relevance]
+    RANK --> VEC[Deterministic vector similarity]
+    RANK --> FILE[File affinity]
+    RANK --> REC[Recency/confidence]
+    RANK --> TASK[Task-class affinity]
+
+    LEX --> TOP[Bounded top memories]
+    VEC --> TOP
+    FILE --> TOP
+    REC --> TOP
+    TASK --> TOP
+~~~
+
+Memory hỗ trợ:
+
+- candidate / verified / superseded lifecycle;
+- confidence;
+- expiry;
+- task-class affinity;
+- usage accounting;
+- evidence references;
+- supersession.
+
+CLI:
+
+~~~text
+ues memory status .
+ues memory retrieve ...
+ues memory propose ...
+ues memory verify ...
+ues memory supersede ...
+~~~
 
 ---
 
-## Skills
+# Capability Fabric
 
-V11 stable hiện có **48 skills**; V10 stable có 39. Router vẫn chỉ chọn tập skill phù hợp thay vì nạp toàn bộ catalog vào mỗi task.
+Capability Fabric giúp model không phải tự đoán backend/tool nào đang khỏe.
 
-Một số process skill quan trọng:
+## Built-in capability groups
 
-- `ues-engineering-orchestrator`
-- `ues-repo-explorer`
-- `ues-context-engineering`
-- `ues-task-planner`
-- `ues-change-impact-analysis`
-- `ues-bug-diagnosis`
-- `ues-test-driven-development`
-- `ues-test-verification`
-- `ues-code-review`
-- `ues-research-verification`
-- `ues-long-task-state`
-- `ues-git-safety`
+Source hiện có các nhóm như:
 
-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.
+- code.search;
+- memory;
+- evidence;
+- output.compaction;
+- filesystem;
+- git;
+- agent.host;
+- github;
+- browser.
+
+~~~mermaid
+flowchart TD
+    NEED[Required capability] --> REG[Provider registry]
+    REG --> PROBE[Health probe]
+    PROBE --> SCORE[Score]
+
+    OBS[Persisted success/failure/latency] --> SCORE
+    QUALITY[Quality] --> SCORE
+    COST[Cost class] --> SCORE
+    LAT[Latency class] --> SCORE
+
+    SCORE --> PRIMARY[Selected provider]
+    SCORE --> FALLBACK[Fallback providers]
+~~~
+
+Provider score xét:
+
+- configured priority;
+- quality;
+- current health;
+- historical success/failure;
+- cost class;
+- latency class.
+
+## Output compaction providers
+
+V14.1 có registry cho:
+
+- built-in <code>ues-reversible-compactor</code> — mặc định;
+- RTK CLI — optional;
+- Caveman CLI — optional experimental;
+- Headroom CLI — optional experimental.
+
+Detection **không có nghĩa auto-enable** external provider.
 
 ---
 
-## Tương thích OpenCode
+# Playwright / Browser MCP on-demand
+
+UES có browser adapter/runtime riêng và thêm routing cho Playwright/Browser MCP đang có trong Pi host.
 
-### OpenCode 1.x
+Mục tiêu: browser tools chỉ xuất hiện khi task thực sự cần browser/visual evidence.
 
-- 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`.
+~~~mermaid
+flowchart TD
+    TASK[Task] --> NEED{Needs browser or visual evidence?}
 
-### OpenCode 2.x
+    NEED -->|No| NORMAL[Normal agent tool allowlist]
+    NEED -->|Yes| DISCOVER[Inspect host Pi tool registry]
 
-Ngoài resource file, UES cài managed plugin tại:
+    DISCOVER --> SELECT[Select Playwright/browser tools]
+    SELECT --> CHILD[Add selected names to child --tools]
 
-```text
-~/.config/opencode/plugins/ues-router/
-```
+    CHILD --> SNAP[Semantic/accessibility snapshot]
+    CHILD --> INT[Targeted interaction]
+    CHILD --> LOG[Console/network evidence]
+    CHILD --> SHOT[Screenshot when visual proof needed]
 
-Plugin cung cấp:
+    SNAP --> VV[Visual verifier]
+    INT --> VV
+    LOG --> VV
+    SHOT --> VV
 
-- automatic skill routing;
-- context guardrail;
-- permission safety gate;
-- read-only long-task helpers;
-- fresh-session executor runtime qua `ues.dispatch_task` và same-model parallel runtime qua `ues.dispatch_parallel`.
+    VV -->|PASS| DONE[Visual claim verified]
+    VV -->|FAIL / no evidence| STOP[No browser-visible PASS claim]
+~~~
 
-Điều khiển router:
+## Routing behavior
 
-```cmd
-ocskill router status
-ocskill router on --max 4
-ocskill router off
-```
+### Backend task
+
+Ví dụ:
+
+~~~text
+/ues-run sửa transaction inventory backend và chạy test
+~~~
+
+Playwright không cần được thêm vào child agent.
+
+### Browser E2E task
+
+Ví dụ:
+
+~~~text
+/ues-run kiểm tra checkout form bằng browser, click flow và console error
+~~~
+
+Browser MCP lane được yêu cầu.
+
+### Visual task
+
+Ví dụ:
+
+~~~text
+/ues-run sửa giao diện theo ảnh mẫu và kiểm tra responsive
+~~~
+
+Sau code verifier/integration verifier, UES có thể chạy thêm <code>ues-visual-verifier</code>.
+
+## Evidence order
+
+UES ưu tiên:
+
+1. semantic/accessibility snapshot;
+2. DOM/target state;
+3. targeted interaction;
+4. console/network evidence;
+5. viewport checks;
+6. screenshot khi cần visual proof.
+
+## Browser security
+
+Webpage text, accessibility content, console output và network payload được coi là **untrusted external evidence**.
+
+Page content không được:
+
+- thay đổi permissions;
+- yêu cầu secret;
+- override system/task instructions;
+- tự cấp quyền external/destructive side effect.
+
+## Optional overrides
+
+Nếu Browser MCP dùng tên tool lạ:
+
+~~~cmd
+set UES_BROWSER_MCP_TOOL_NAMES=browser_navigate,browser_snapshot,browser_screenshot,browser_click
+set UES_BROWSER_MCP_TOOL_LIMIT=14
+~~~
 
 ---
 
-## Safety
+# Trajectory và observability
+
+<code>lib/trajectory.mjs</code> lưu **operational events**, không lưu hidden chain-of-thought.
+
+~~~mermaid
+flowchart LR
+    RUN[Agent run] --> EVT[Observable event]
+    EVT --> SCRUB[Secret redaction]
+    SCRUB --> LIMIT[Bound event size]
+    LIMIT --> JSONL[.ues-traces trace.jsonl]
+
+    JSONL --> SHOW[trace show]
+    JSONL --> DEBUG[Debug/replay analysis]
+~~~
+
+Trajectory scrub các dạng dữ liệu 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ụ:
+- Authorization Bearer;
+- OpenAI-style API keys;
+- GitHub tokens;
+- npm tokens;
+- generic api_key/token/secret/password/credential fields.
 
-- `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.
+Large event payload được bounded và có SHA-256 digest.
 
-Safety hook là lớp bảo vệ deterministic bổ sung, không thay thế review của người dùng.
+CLI:
+
+~~~text
+ues trace append ...
+ues trace show ...
+~~~
 
 ---
 
-## Learning loop
+# Learning engine và benchmark confidence
+
+Learning của UES được thiết kế theo hướng **proposal → shadow evidence → promotion**, không phải “agent fail một lần rồi tự sửa rule vĩnh viễn”.
 
-Phân tích eval trace:
+~~~mermaid
+flowchart TD
+    EVAL[Eval artifacts] --> ANALYZE[Analyze recurring failures]
+    ANALYZE --> PROP[Learning proposal]
+    PROP --> ACCEPT[Manual acceptance]
+    ACCEPT --> SHADOW[Shadow benchmark required]
 
-```cmd
-ocskill learn analyze . --eval-dir .ues-evals
-```
+    SHADOW --> PAIR[Paired baseline vs UES]
+    PAIR --> CONF[Statistical confidence checks]
 
-Xem trạng thái:
+    CONF -->|Eligible| PROMOTE[Promote learning]
+    CONF -->|Not eligible| HOLD[Keep unpromoted]
+~~~
 
-```cmd
-ocskill learn status .
-```
+## Failure patterns được phân tích
 
-Chấp nhận một proposal trước khi thử nghiệm:
+Ví dụ:
 
-```cmd
-ocskill learn accept <proposal-id> .
-```
+- hard-timeout;
+- idle-timeout;
+- agent-exit;
+- grader-failure;
+- orchestration-failure;
+- telemetry parse errors.
 
-Sau khi shadow benchmark chứng minh candidate tốt hơn baseline:
+## Promotion confidence
 
-```cmd
-ocskill learn promote <proposal-id> . --baseline 0.50 --candidate 0.75 --samples 4
-```
+<code>lib/benchmark-confidence.mjs</code> so sánh paired baseline/UES:
 
-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.
+- total paired samples;
+- both pass;
+- both fail;
+- baseline-only win;
+- UES-only win;
+- pass-rate delta;
+- exact sign-test p-value;
+- per-suite regression;
+- duration ratio;
+- initial input ratio;
+- token ratio;
+- cost summary.
+
+Promotion yêu cầu nhiều điều kiện cùng đạt, không chỉ “UES thắng một vài task”.
 
 ---
 
-## Hermes adapter
+# Durable long-horizon work
 
-V11 giữ Hermes theo dạng **optional sidecar**, không nhúng Hermes runtime vào core. UES vẫn sở hữu durable state, evidence và safety boundaries:
+Task dài có thể dùng <code>.ues-work/&lt;slug&gt;/</code> làm source of truth.
 
-```cmd
-ocskill hermes status
-ocskill hermes prompt <slug> <task> .
-ocskill hermes exec <slug> <task> .
-```
+~~~text
+.ues-work/<slug>/
+  SPEC.md
+  PLAN.json
+  STATE.json
+  EVIDENCE.json
+  EVENTS.jsonl
+  ACTIVE_PLAN.json
+  tasks/
+  reports/
+  plans/
+~~~
+
+## State machine khái quát
+
+~~~mermaid
+stateDiagram-v2
+    [*] --> Initialized
+    Initialized --> Planned
+    Planned --> PlanApproved
+    PlanApproved --> Running
+    Running --> Running: next task
+    Running --> Blocked
+    Blocked --> Running
+    Running --> IntegrationVerification
+    IntegrationVerification --> Finalized: PASS + fresh fingerprint
+    IntegrationVerification --> Running: FAIL / rework
+    Running --> Recovering: stale lease / interruption
+    Recovering --> Running
+~~~
+
+## Locking
+
+State/evidence mutation dùng:
+
+- per-work lock;
+- heartbeat;
+- stale lock recovery;
+- atomic file replacement.
+
+## Runtime events
+
+<code>EVENTS.jsonl</code> append-only cho operational observability.
 
-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.
+---
+
+# Control Center
+
+UES có local Control Center qua:
+
+~~~text
+ues dashboard .
+ues dashboard . --serve
+~~~
+
+Control Center tổng hợp các loại dữ liệu như:
+
+- durable work;
+- task state;
+- blockers;
+- receipts;
+- recent events;
+- eval summaries;
+- learning state;
+- evidence store;
+- verified memory;
+- capability fabric health.
+
+~~~mermaid
+flowchart LR
+    WORK[.ues-work] --> CC[Control Center]
+    EVENTS[EVENTS.jsonl] --> CC
+    EV[Evidence Store] --> CC
+    MEM[Memory] --> CC
+    CAP[Capability Fabric] --> CC
+    LEARN[Learning] --> CC
+    EVAL[Eval artifacts] --> CC
+~~~
+
+Control Center là observer/controller cục bộ; nó không bypass verification/safety gates.
 
 ---
 
-## UES Control Center
+# Safety model
+
+UES cố gắng đưa safety vào code thay vì chỉ nhắc model.
+
+## Shell safety
+
+Có detection/gate cho các thao tác rủi ro như:
+
+- force push;
+- history rewrite;
+- reset hard;
+- recursive destructive deletion;
+- destructive database commands;
+- deploy/apply;
+- publish.
+
+## Scope safety
+
+Structured task phải khai báo file scope. Scheduler kiểm tra actual changed files so với declared write scope.
+
+## Parallel safety
+
+Writer agents chạy parallel phải ở distinct worktree/cwd.
 
-Tạo dashboard tĩnh:
+## Evidence safety
 
-```cmd
-ocskill dashboard .
-```
+Old PASS không tự được coi là hợp lệ nếu workspace đã thay đổi.
 
-Chạy dashboard có tự refresh:
+## Browser safety
 
-```cmd
-ocskill dashboard . --serve --port 4177
-```
+External page content là untrusted.
 
-Control Center hiển thị work state, verification receipts, runtime events, learning proposals và eval summary; server mode có safe stale-recovery action.
+## Memory safety
+
+Candidate hoặc superseded memory không được retrieval như verified memory.
+
+## Learning safety
+
+Proposal không tự promote nếu chưa có benchmark evidence phù hợp.
 
 ---
 
-## Sandbox cho tác vụ ghi song song
+# Cài đặt
 
-Tạo isolated Git worktree:
+## Yêu cầu
 
-```cmd
-ocskill sandbox create <slug> <task-id> .
-```
+- Node.js 22.19+
+- Git
+- Pi Agent
 
-Tích hợp sandbox sau khi đã inspect/verify:
+Cài Pi:
 
-```cmd
-ocskill sandbox integrate <worktree-path> .
-```
+~~~cmd
+npm install -g @earendil-works/pi-coding-agent
+pi --version
+~~~
 
-Liệt kê sandbox:
+Cài UES trực tiếp từ GitHub:
 
-```cmd
-ocskill sandbox list .
-```
+~~~cmd
+pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi list
+pi
+~~~
 
-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.
+Nếu đã clone repo local:
+
+~~~cmd
+cd /d E:\Code\opencode-agent-skill-
+npm install
+pi install .
+~~~
 
 ---
 
-## Evaluation
+# Cập nhật
 
-V11 hiện có:
+Nếu cài từ clone local:
 
-- **43 static skill-routing scenarios** phủ 48 skills;
-- **129 V2 router cases** với required routes và negative guards;
-- **13 V11 contract tasks** across 6 categories;
-- **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**.
+~~~cmd
+cd /d E:\Code\opencode-agent-skill-
+git status
+git pull --ff-only origin main
+pi install .
+~~~
 
-Kiểm tra static routing:
+Nếu local có thay đổi chưa commit, hãy backup/stash hoặc xử lý diff trước khi pull. Không nên reset/clean mù quáng.
 
-```cmd
-npm run evals
-```
+---
 
-Kiểm tra V2 router:
+# Đóng gói npm
 
-```cmd
-npm run evals:router
-```
+Kiểm tra đầy đủ trước khi pack:
 
-Kiểm tra standard hidden graders:
+~~~cmd
+npm install
+npm run ci
+npm pack --dry-run
+npm pack
+~~~
 
-```cmd
-npm run evals:live:validate
-```
+Package version hiện tại trong <code>package.json</code> là:
 
-Kiểm tra long-horizon và polyglot suite:
+~~~text
+14.2.0-beta.1
+~~~
 
-```cmd
-npm run evals:long:validate
-npm run evals:polyglot:validate
-npm run evals:v11:validate
-```
+V14.2 Turbo Weak-Model Runtime hiện là incremental work trên package version đó.
 
-Chạy benchmark với model thật:
+Test file packed với Pi:
 
-```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
-```
+~~~cmd
+pi install .\opencode-agent-skill-14.2.0-beta.1.tgz
+pi list
+~~~
 
-Live eval hỗ trợ heartbeat, hard timeout, idle timeout và Ctrl+C process-tree cancellation.
+Publish thật chỉ nên thực hiện sau khi CI và package smoke tests 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.
+---
+
+# Các CLI quan trọng
+
+CLI ưu tiên là <code>ues</code>; <code>ocskill</code> vẫn là compatibility alias.
+
+## Repository intelligence
+
+~~~text
+ues inspect .
+ues impact <query> .
+ues evidence .
+ues working-tree .
+ues repo-graph .
+ues index status .
+ues index build .
+ues aci search ...
+~~~
+
+## Task và verification
+
+~~~text
+ues task-policy "<task>"
+ues verification-plan .
+ues task-graph PLAN.json
+ues workflow-plan PLAN.json
+ues review-scope main .
+~~~
+
+## Durable work
+
+~~~text
+ues work init <slug> . --goal "..."
+ues work plan <slug> PLAN.json .
+ues work approve-plan <slug> . --evidence "..."
+ues work start <slug> <task-id> .
+ues work verify-command <slug> <task-id> . --run-id <id> -- npm test
+ues work complete <slug> <task-id> . --run-id <id> --evidence "..."
+ues work verify-integration <slug> . --verdict PASS --evidence "..."
+ues work finalize <slug> . --evidence "..."
+ues work events <slug> .
+ues work resume <slug> .
+~~~
+
+## Sandbox
+
+~~~text
+ues sandbox list .
+ues sandbox create ...
+ues sandbox integrate ...
+ues sandbox rollback ...
+ues sandbox remove ...
+~~~
+
+## Context / memory / capability
+
+~~~text
+ues hierarchy "<query>" .
+ues hierarchy "<query>" . --full
+ues memory status .
+ues capability-fabric status .
+ues capabilities "<task>"
+~~~
+
+## Evidence / trace
+
+~~~text
+ues store status .
+ues store get evidence:sha256:<hash>
+ues trace show ...
+~~~
+
+## Browser / visual
+
+~~~text
+ues browser capability .
+ues browser plan ...
+ues browser inspect ...
+ues visual ...
+ues ui tokens ...
+ues ui layout ...
+~~~
+
+## Models
+
+~~~text
+ues models status
+ues models on
+ues models set light <provider/model>
+ues models set standard <provider/model>
+ues models set heavy <provider/model>
+ues models role verifier standard
+~~~
+
+## Learning / eval
+
+~~~text
+ues eval-pi --model provider/model --thinking low --suite live --trials 3 --mode both
+ues learn analyze . --eval-dir .ues-evals
+~~~
 
 ---
 
-## Phát triển và CI
+# Benchmark model yếu
 
-Yêu cầu:
+UES có Pi-native baseline-vs-UES benchmark.
 
-- Node.js 20+;
-- npm;
-- Git.
+~~~mermaid
+flowchart LR
+    TASKS[Same benchmark tasks] --> B[Baseline Pi]
+    TASKS --> U[Pi + UES]
 
-Cài dependency mà không chạy lifecycle script:
+    B --> BG[External grader]
+    U --> UG[External grader]
 
-```cmd
-npm ci --ignore-scripts
-```
+    B --> BT[Tokens/cost/tool telemetry]
+    U --> UT[Tokens/cost/tool telemetry]
 
-Chạy toàn bộ CI:
+    BG --> PAIR[Paired comparison]
+    UG --> PAIR
+    BT --> PAIR
+    UT --> PAIR
 
-```cmd
-npm run ci
-```
+    PAIR --> CONF[Confidence / regression checks]
+~~~
 
-Pipeline hiện kiểm tra:
+Ví dụ:
+
+~~~cmd
+ues eval-pi --model provider/model --thinking low --suite live --trials 3 --mode both
+~~~
+
+Eval script thu thập:
+
+- pass/fail;
+- duration;
+- parent tool calls;
+- child tool calls;
+- input/output/cache token telemetry;
+- reported cost;
+- controller usage;
+- workspace changes;
+- external grader result.
+
+## Eval suites trong repo
 
-```text
-syntax
-→ resource validation
-→ docs:check
-→ static skill routing
-→ V2 router matrix
-→ standard hidden-grader integrity
-→ long hidden-grader integrity
-→ polyglot hidden-grader integrity
-→ V11 contract validation
-→ Node tests
-→ npm pack --dry-run
-→ packed global-install smoke
-→ plain one-command install compatibility smoke
-```
+Hiện có các nhóm như:
 
-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.
+- live;
+- long;
+- polyglot;
+- repo-scale;
+- v11;
+- v14;
+- routing/router trigger suites.
 
 ---
 
-## Cập nhật và gỡ cài đặt
+# Cấu trúc repository
+
+~~~text
+opencode-agent-skill-/
+├─ bin/
+│  └─ ocskill.mjs
+│
+├─ lib/
+│  ├─ task-policy.mjs
+│  ├─ task-engine.mjs
+│  ├─ task-graph.mjs
+│  ├─ dynamic-workflow.mjs
+│  ├─ context-engine-v11.mjs
+│  ├─ hierarchical-context.mjs
+│  ├─ semantic-index.mjs
+│  ├─ repo-graph.mjs
+│  ├─ aci.mjs
+│  ├─ evidence-store.mjs
+│  ├─ evidence-receipt.mjs
+│  ├─ gate-receipt.mjs
+│  ├─ memory-engine.mjs
+│  ├─ capability-fabric.mjs
+│  ├─ model-policy.mjs
+│  ├─ model-performance.mjs
+│  ├─ worktree-sandbox.mjs
+│  ├─ container-sandbox.mjs
+│  ├─ performance-fabric.mjs
+│  ├─ trajectory.mjs
+│  ├─ learning-engine.mjs
+│  ├─ benchmark-confidence.mjs
+│  ├─ browser-adapter.mjs
+│  ├─ browser-runtime.mjs
+│  ├─ browser-mcp-routing.mjs
+│  └─ ...
+│
+├─ pi/
+│  ├─ extensions/
+│  │  └─ ues.ts
+│  └─ prompts/
+│     └─ 11 UES slash prompts
+│
+├─ global-config/
+│  ├─ agents/
+│  │  └─ 12 specialist agents
+│  └─ skills/
+│     └─ 48 domain/workflow skills
+│
+├─ evals/
+│  ├─ live/
+│  ├─ long/
+│  ├─ polyglot/
+│  ├─ repo-scale/
+│  ├─ v11/
+│  └─ v14/
+│
+├─ scripts/
+│  └─ eval, validation, smoke, install helpers
+│
+├─ test/
+│  └─ deterministic/runtime/regression tests
+│
+└─ docs/
+   ├─ ENGINEERING-DESIGN.md
+   ├─ DETERMINISTIC-TOOLS.md
+   ├─ V11-PERCEPTION-ADAPTIVE-EXECUTION.md
+   ├─ V12-WEAK-MODEL-INTELLIGENCE.md
+   ├─ V13-PARALLEL-WEAK-MODEL-RUNTIME.md
+   ├─ V14-CONTEXT-MEMORY-FABRIC.md
+   └─ V14.1-QUALITY-PERFORMANCE-FABRIC.md
+~~~
+
+---
+
+# Một ví dụ đầy đủ
+
+Task:
+
+~~~text
+/ues-run sửa checkout inventory reservation, chạy test liên quan và xác minh UI checkout
+~~~
 
-Cập nhật lên bản npm mới nhất:
+Luồng có thể diễn ra:
 
-```cmd
-ocskill update
-```
+~~~mermaid
+flowchart TD
+    T[User task] --> P[Task Policy STANDARD/DEEP]
+    P --> C[Context selection]
+    C --> R[Repo graph + semantic refs + likely tests]
+    R --> E[Executor]
+    E --> TEST[Targeted backend tests]
+    TEST --> V[Verifier]
 
-Gỡ UES:
+    V -->|PASS| I[Integration verifier]
+    V -->|FAIL| D[Debugger]
+    D --> E
 
-```cmd
-ocskill remove
-```
+    I --> B{Visual/browser required?}
+    B -->|No| DONE[Verified completion]
+    B -->|Yes| MCP[Playwright MCP lane]
+    MCP --> VV[Visual verifier]
+    VV -->|PASS| DONE
+    VV -->|FAIL| D
+~~~
 
-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.
+Điểm khác với “một model tự làm tất cả” là:
+
+1. context được bounded;
+2. implementation và verification tách vai;
+3. browser evidence chỉ nạp khi cần;
+4. retry có diagnosis;
+5. long task có state;
+6. parallel writers có isolation;
+7. completion bị ràng buộc bởi evidence.
 
 ---
 
-## Tài liệu
+# Triết lý thiết kế
+
+## Deterministic facts trước probabilistic reasoning
+
+Những việc có thể tính bằng code thì ưu tiên tính bằng code:
+
+- Git state;
+- dependency graph;
+- changed files;
+- plan cycle;
+- file overlap;
+- command exit status;
+- workspace fingerprint;
+- provider health;
+- token/cost telemetry.
+
+Model tập trung vào phần cần semantic judgment.
+
+## Progressive disclosure
+
+Không nạp:
+
+- toàn repo;
+- toàn bộ 48 skills;
+- mọi MCP tool;
+- mọi memory;
+- mọi log.
+
+Chỉ nạp bounded evidence phù hợp.
+
+## Fresh specialists
+
+Child specialist được tạo với prompt/tool boundary hẹp hơn để giảm contamination từ conversation dài.
 
-- [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)
-- [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)
-- [V12 Weak-Model Intelligence (beta)](docs/V12-WEAK-MODEL-INTELLIGENCE.md)
-- [V13 Parallel Weak-Model Runtime (beta)](docs/V13-PARALLEL-WEAK-MODEL-RUNTIME.md)
+## Evidence-first completion
+
+“Agent nói đã xong” không phải completion gate.
+
+## Reversible optimization
+
+Tối ưu output/context phải giữ đường lấy raw evidence trở lại.
+
+## Benchmark-gated learning
+
+Không promote rule/tool/provider chỉ vì cảm giác “có vẻ nhanh”.
 
 ---
 
-## npm
+# Giới hạn có chủ đích
 
-Package:
+UES cố ý **không**:
 
-```text
-opencode-agent-skill
-```
+- tạo hàng trăm agents;
+- load mọi skill cho mọi task;
+- auto push;
+- auto publish;
+- auto deploy;
+- ghi hidden chain-of-thought;
+- coi keyword routing là semantic truth tuyệt đối;
+- coi import scan là full compiler/LSP semantic graph;
+- coi một benchmark là bằng chứng model-equivalence;
+- bỏ verifier chỉ để tăng tốc;
+- dùng browser tool cho backend task không cần browser.
 
-Cài đặt:
+---
 
-```cmd
-npm install -g opencode-agent-skill
-```
+# Quick start
 
-Phiên bản hiện tại:
+~~~cmd
+npm install -g @earendil-works/pi-coding-agent
+pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi
+~~~
 
-```text
-13.0.0-beta.2
-```
+Trong Pi:
 
-V13 beta dùng npm dist-tag `next`; `latest` tiếp tục trỏ tới V11 stable cho đến khi các release gate V13 hoàn tất.
+~~~text
+/ues-run kiểm tra project, tìm lỗi, sửa lỗi cần thiết và chạy test xác minh
+~~~
 
-Maintainer packaging gate:
+Kiểm tra deterministic runtime:
 
-```cmd
-npm run ci
-npm pack --dry-run
-npm pack
-```
+~~~cmd
+ues task-policy "fix checkout bug" --json
+ues capability-fabric status .
+ues hierarchy "checkout inventory" .
+ues memory status .
+~~~
 
-Trước khi publish, kiểm tra version chưa tồn tại trên registry:
+---
 
-```cmd
-npm view opencode-agent-skill@13.0.0-beta.2 version --registry=https://registry.npmjs.org/
-```
+# Tài liệu sâu hơn
 
-Nếu version chưa tồn tại, prerelease được publish với dist-tag `next`.
+- <code>docs/ENGINEERING-DESIGN.md</code> — engineering architecture.
+- <code>docs/DETERMINISTIC-TOOLS.md</code> — deterministic CLI/evidence tools.
+- <code>docs/V11-PERCEPTION-ADAPTIVE-EXECUTION.md</code> — perception/adaptive execution.
+- <code>docs/V12-WEAK-MODEL-INTELLIGENCE.md</code> — weak-model intelligence.
+- <code>docs/V13-PARALLEL-WEAK-MODEL-RUNTIME.md</code> — parallel runtime.
+- <code>docs/V14-CONTEXT-MEMORY-FABRIC.md</code> — context, memory, capability fabric.
+- <code>docs/V14.1-QUALITY-PERFORMANCE-FABRIC.md</code> — quality-preserving performance.
+- <code>docs/EVALS.md</code> — evaluation.
+- <code>docs/PI-COMPAT.md</code> — Pi compatibility.
+- <code>docs/NPM-PUBLISH.md</code> — npm publishing.
 
 ---
 
-## License
+# License
 
-MIT
+MIT