opencode-agent-skill 14.4.0 → 15.0.0

package/README.md

@@ -4,8 +4,9 @@
 
 **Package:** <code>opencode-agent-skill</code>  
 **Host chính:** Pi Agent  
-**Phiên bản package hiện tại:** <code>14.4.0</code>  
-**Release hiện tại:** V14.4 Stable Weak-Model Intelligence Runtime  
+**Phiên bản package hiện tại:** <code>15.0.0</code>  
+**Nhánh phát triển hiện tại:** V15.19 Finalization Hardening  
+**Stable npm hiện tại:** <code>15.0.0</code>  
 **Runtime:** Node.js 22.19+  
 **License:** MIT
 
@@ -17,11 +18,11 @@
 
 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)
+3. [Luồng Auto Router và /ues-run fallback](#luồng-auto-router-và-ues-run-fallback)
 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)
+7. [Pi commands và 10 prompt templates](#pi-commands-và-10-prompt-templates)
 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)
@@ -49,6 +50,22 @@
 
 ---
 
+## Zero-command UX mặc định
+
+Người dùng bình thường không cần nhớ `/ues-run`, không cần chọn skill và không cần chọn specialist agent. Trong một Git worktree, prompt engineering dạng text được định tuyến tự động theo ba lane: chat/giải thích ở Pi native, task kỹ thuật rõ ràng vào UES, và task high-risk vào UES với safety/verification mạnh hơn.
+
+Nếu một UES run đang hoạt động, các câu tiếp diễn rõ ràng như `tiếp tục`, `làm tiếp` hoặc `continue` chỉ được forward khi runtime xác định được một active child an toàn. Một prompt mới không liên quan sẽ không bị UES nuốt mất. `/ues-run` vẫn tồn tại như force-entry/debug fallback.
+
+Trước khi chốt release candidate, chạy một lệnh:
+
+```cmd
+npm run release:verify
+```
+
+Lệnh này chạy full CI/package smoke trước rồi chạy lại V15 regression suite trọng tâm.
+
+---
+
 # UES giải quyết vấn đề gì?
 
 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:
@@ -159,9 +176,9 @@ Hoàn thành không đồng nghĩa model nói “done”. UES cố gắng ràng
 
 ---
 
-# Luồng /ues-run end-to-end
+# Luồng Auto Router và /ues-run fallback
 
-<code>/ues-run</code> là entry point khuyến nghị cho engineering task.
+Prompt engineering dạng text trong Git worktree là entry point mặc định: Auto Router tự chọn Pi native, UES auto hoặc UES high-risk. <code>/ues-run</code> chỉ còn là force-entry/debug fallback.
 
 ~~~mermaid
 sequenceDiagram
@@ -174,8 +191,8 @@ sequenceDiagram
     participant IV as Integration Verifier
     participant VV as Visual Verifier
 
-    U->>P: /ues-run task
-    P->>UES: ues_execute(task)
+    U->>P: natural engineering prompt
+    P->>UES: Auto Router -> ues_execute(task)
     UES->>UES: classify task/risk/profile
     UES->>CTX: build bounded context
     CTX-->>UES: hierarchy + evidence + memory + capability hints
@@ -420,13 +437,13 @@ UES hiện có 48 skill directories trong <code>global-config/skills/</code>. Sk
 
 ---
 
-# 11 slash prompts
+# Pi commands và 10 prompt templates
 
-Pi package cung cấp 11 slash prompts:
+Pi package cung cấp 1 deterministic extension command `/ues-run` và 10 prompt templates:
 
 | Command | Ý nghĩa |
 |---|---|
-| <code>/ues-run</code> | controller end-to-end |
+| <code>/ues-run</code> | **extension command deterministic**; 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 |
@@ -1411,13 +1428,13 @@ npm pack --dry-run
 npm pack
 ~~~
 
-Package stable hiện tại trong <code>package.json</code> là:
+Package version hiện tại trên nhánh <code>main</code> là:
 
 ~~~text
-14.4.0
+15.0.0-beta.13
 ~~~
 
-V14.4 gom V14/V14.1/V14.2 cùng code intelligence, hash-anchored editing, completion auditor, stable memory snapshots, reversible context/document ingestion và MCP health-aware routing thành release stable.
+Stable npm public hiện vẫn là <code>14.4.0</code>. V15.3 DEEP Speed giảm exploration trùng lặp ở long-horizon bằng diagnosis deduplication và bounded specialist exploration, nhưng giữ nguyên plan/verifier/integration gates. V15.4 ACP-safe child runtime ngăn UES spawn lại ACP/Zed entrypoint; child specialist luôn được chạy bằng Pi CLI thật. V15.5 Per-Leaf Turbo cho phép leaf task nhỏ trong DEEP plan tự xuống FAST, giữ failure delta task-local, và tái sử dụng context theo root namespace + workspace fingerprint để giảm retry/rebuild latency. V15.6 Fast Planning đặt soft-steer/hard-idle budget riêng cho architect/plan-checker, recovery từ warm context thay vì scan lại, và lease/cleanup sandbox orphan an toàn sau crash/Stop. V15.7 Lightweight Sandbox Cleanup thu hồi worktree theo trace ngay khi /ues-run kết thúc, dọn metadata mồ côi, giảm legacy grace xuống 30 phút và cung cấp /ues-clean để dọn stale artifacts an toàn mà không đụng sandbox đang active. V15.8 Plan Gate Recovery bổ sung soft-steer + bounded recovery cho plan-checker và quét cả detached physical sandbox folders mà Git worktree registry đã quên. V15.9 Runtime Artifact Isolation loại .ues-traces/.ues-cache/.ues-services/.ues-work và runtime state khác khỏi task delta, write-scope conflict và sandbox integration, nhưng vẫn giữ safety gate cho source/config thật như apps/mobile/package.json. V15.10 Adaptive Stability Runtime thay hard-timeout tuyệt đối bằng activity-aware bounded deadlines, giữ absolute cap chống treo, salvage plan JSON đã validate từ partial output, phát graph trước prose, và role-bound context cho read-only planner trong task high-risk mà không giảm evidence budget của executor/verifier. V15.1 bắt đầu bằng deterministic <code>/ues-run</code> admission và Managed Background Services để model yếu không thể bỏ qua controller và không bị treo bởi dev server foreground.
 
 Test file packed với Pi:
 
@@ -1625,7 +1642,7 @@ opencode-agent-skill-/
 │  ├─ extensions/
 │  │  └─ ues.ts
 │  └─ prompts/
-│     └─ 11 UES slash prompts
+│     └─ 10 UES prompt templates (`/ues-run` thuộc extension)
 │
 ├─ global-config/
 │  ├─ agents/
@@ -1802,6 +1819,7 @@ ues memory status .
 - <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/V15-MANAGED-RUNTIME.md</code> — deterministic controller admission và managed background services.
 - <code>docs/EVALS.md</code> — evaluation.
 - <code>docs/PI-COMPAT.md</code> — Pi compatibility.
 - <code>docs/NPM-PUBLISH.md</code> — npm publishing.

package/docs/PI-COMPAT.md

@@ -50,7 +50,7 @@ pi install .
 
 - extension: `./pi/extensions/ues.ts`
 - skills: `./global-config/skills`
-- prompts: `./pi/prompts/*.md`
+- prompts: `./pi/prompts/*.md` (10 prompt templates; `/ues-run` is owned by the extension command)
 
 The packaged runtime also contains `global-config/agents/`, `bin/ocskill.mjs`, and `lib/` because the Pi extension uses them for specialist child-agent execution and deterministic UES operations.
 
@@ -96,6 +96,146 @@ Child Pi processes keep extension discovery enabled so custom model providers re
 Each child also has bounded runtime supervision: a 30-minute hard timeout, a 5-minute idle timeout and a 15-second heartbeat by default. These can be tuned with `UES_CHILD_HARD_TIMEOUT_MS`, `UES_CHILD_IDLE_TIMEOUT_MS` and `UES_CHILD_HEARTBEAT_MS`.
 
 
+## V15.19 Finalization Hardening
+
+Zero-friction admission now protects active runs from prompt loss. While a direct UES controller is active, a second ordinary interactive prompt is never auto-admitted into another controller and then silently consumed. Explicit natural continuations such as `tiếp tục`, `làm tiếp`, and `continue` may be forwarded only when the RPC pool can deterministically target an active child; otherwise the prompt remains on Pi's normal path.
+
+Unrelated new prompts are not treated as continuations. Slash commands are never rewritten as continuations. `/ues-status` reports the safe-continuation capability alongside the native/auto/high-risk router.
+
+For release-candidate validation, `npm run release:verify` runs the complete package CI/smoke chain and then the focused V15 regression suite.
+
+## V15.18 Three-Tier Zero-Friction Routing
+
+Automatic admission now distinguishes three user-facing lanes instead of treating every engineering-looking prompt the same:
+
+- `native`: greetings, casual discussion, explanatory/code-understanding questions, slash commands, image-bearing prompts, and non-Git workspaces stay on Pi's normal path.
+- `auto`: confident engineering actions such as inspect/fix/test/build/refactor on repository/code targets enter the UES controller automatically.
+- `high-risk`: engineering tasks classified as high risk enter the same UES controller with the stronger safety/verification profile and explicit warning UI.
+
+The router returns a confidence level and reason, reuses the same classified task policy inside `ues_execute`, and avoids reclassifying the task during direct admission. Automatic controller launch is non-blocking from the input hook so stop/steer/follow-up input can remain responsive while the supervised run continues.
+
+This keeps the no-command UX while reducing false-positive orchestration for questions such as “giải thích đoạn code này”. `/ues-run` remains an explicit force-entry fallback, not a requirement.
+
+## V15.17 Zero-Friction Autopilot Admission
+
+Interactive text-only engineering requests inside a Git worktree can now enter the deterministic UES controller without requiring the user to type `/ues-run`. Admission is deterministic and conservative: long structured engineering prompts, read-only repository inspections, and prompts with both an engineering action and engineering target are admitted; greetings, casual discussion, slash commands, non-Git workspaces, and image-bearing prompts remain on the normal Pi path.
+
+The parent model still does not see UES tools during ordinary chat. Automatic admission calls the same direct controller used by `/ues-run`, so supervised child processes, idle/hard timeouts, abort handling, phase gates, durable state, verification, and cleanup remain identical. `/ues-run` remains available as an explicit force-entry command but is no longer required for normal text engineering tasks.
+
+Automatic admission is enabled by default and can be disabled with `UES_AUTO_ADMIT=0` (also accepts `false` or `off`). `/ues-status` reports whether zero-friction engineering admission is active.
+
+## V15.16 Portable Cross-Tool Temp Paths
+
+On Windows, POSIX-style temporary paths such as `/tmp/foo` and `/var/tmp/foo` are not safe to pass between Pi file tools and bash/MSYS because each tool may resolve that path in a different filesystem namespace. This can make a file created or addressed by one tool invisible to another and wastes weak-model retries.
+
+UES child file tools now fail closed on those ambiguous POSIX temp paths when running on Windows. The agent receives deterministic recovery guidance: keep transient transforms inside one shell pipeline, or use a repository-local ignored UES scratch path such as `.ues-cache/tmp` for cross-tool scratch. Linux/macOS behavior is unchanged.
+
+The Pi specialist bridge carries the same rule into child prompts, and `/ues-status` exposes `Portable temp-path guard: on` so the active runtime can be verified without guessing.
+
+## V15.15 Execution Contracts + Phase Gates
+
+Long-horizon `/ues-run` now derives a deterministic execution contract before planning. The controller snapshots source-facing pre-existing dirty paths, blocks destructive Git discard commands such as `git restore`, `git checkout --`, and `git stash` in UES children, and injects the inherited-work boundary into every specialist role. Existing dirty work may only be changed when it is explicitly inside the approved task write scope; generated/UES runtime artifacts are excluded from this baseline.
+
+Local `.env` files are treated as runtime inputs, not repository implementation targets. UES child edit/write/code-edit and common shell-write paths are blocked for `.env`, `.env.local`, `.env.development`, and similar files unless the original task explicitly requests that local mutation. Templates such as `.env.example`, `.env.sample`, and `.env.template` remain writable. When local environment setup is missing but not authorized, agents should report `NEEDS_USER_ENV` instead of silently editing secrets/configuration.
+
+Explicit `PHASE N — ...` contracts are parsed before planning. Execution phases must be represented in the structured plan with an integer `phase`; constraint-only phases remain invariants rather than fake tasks. UES then adds deterministic previous-phase barriers so a later phase cannot begin until every task in the previous execution phase has independently verified and integrated. Durable runs persist `EXECUTION_CONTRACT.json`, `phases/MANIFEST.json`, one deterministic JSON artifact per phase, and `FINAL_VERDICTS.json`, so resume can use durable state instead of replaying a very large prompt.
+
+Database/fixture cleanup tasks receive an additional fail-closed contract: refuse production, dry-run first, record exact candidate IDs plus pre/post counts, use deterministic audited markers, preserve canonical/user data, prove a second idempotent cleanup pass, and prefer transaction/rollback protection when available. A final `DB_CLEAN_PASS` requires cleanup evidence, counts, and idempotency evidence rather than a narrative claim alone.
+
+Final completion is split into independent `SOURCE_PASS`, `RUNTIME_PASS`, `DB_CLEAN_PASS`, and `DEVICE_PASS` dimensions when relevant. Runtime PASS may be derived from fresh executable checks; database cleanup and real-device PASS require their own concrete evidence. If source/runtime/data are verified but requested Expo/physical-device testing was not performed, UES reports `SOURCE_RUNTIME_PASS_DEVICE_NOT_VERIFIED` instead of overstating full PASS.
+
+## V15.14 Deterministic Read-Only Fast Path
+
+Command-only read-only Git inspections no longer depend on a verifier model following a report template. When the user explicitly asks to run only whitelisted Git inspection commands such as `git status`, `git branch --show-current`, `git rev-parse HEAD`, `git rev-parse --show-toplevel`, or `git status --short`, UES executes them directly through the supervised process runner, captures their exit codes and output, compares the source workspace fingerprint before and after, and synthesizes the structured verification report deterministically.
+
+This path is fail-closed: an unrecognized Git command disables the deterministic shortcut and falls back to the verifier model. Any command failure, abort, or source-facing workspace mutation prevents PASS. The model-backed read-only lane also now receives the exact required report sections and verdict format to reduce weak-model schema drift.
+
+## V15.13 Read-Only Completion Semantics
+
+Read-only verification now distinguishes real acceptance gaps from optional or explicitly out-of-scope checks. Localized no-failure wording such as `Không có lệnh git nào bị lỗi` is treated as an empty failure section, while statements such as `không có yêu cầu` / `out of scope` are warnings rather than completion failures.
+
+The verifier contract now requires `None` when no actual failures or requested unresolved gaps remain, and directs optional checks to `## Checks not run`. This fixes false-negative READ-ONLY runs that had fresh successful command evidence, an unchanged source fingerprint, and `UES_VERDICT: PASS` but were still rejected by the generic completion auditor.
+
+## V15.12 Safe Autopilot + Disk Hygiene
+
+At V15.12, UES became command-only in the parent Pi session: ordinary prompts kept the parent `ues_*` tools hidden, while explicit `/ues-*` commands activated UES for that turn. V15.17 supersedes only the admission UX: confident text engineering tasks can now enter the same controller automatically, while ordinary chat still keeps UES tools hidden. Direct `/ues-run`, `/ues-clean`, and `/ues-status` remain supported.
+
+`/ues-run`, `ues_execute`, `ues_cli`, `ues_service`, specialist dispatch, and `/ues-clean` fail closed unless their working directory resolves inside a Git worktree. The runtime canonicalizes to the Git top-level before creating cache, trace, sandbox, or durable state, preventing accidental artifact spill into parent folders such as `E:\\dev`.
+
+Read-only tasks use a dedicated inspection policy: no writer worktree, no behavioral-receipt requirement, no integration gate, and a before/after source fingerprint check. Structured read-only leaves run in the root workspace and never allocate duplicate Git worktrees.
+
+Runtime storage is bounded. Trace files are rotated/pruned by file count, total bytes, per-file size, and age. Evidence cache uses entry, age, and byte quotas with automatic garbage collection. Durable runtime event journals compact before unbounded growth. Active task sandboxes are reclaimed on session shutdown. `/ues-clean` removes transient traces/services/dashboard state and rebuildable semantic/verification cache entries; evidence blobs are quota-pruned instead of blindly deleted, and evidence referenced by live verified memory is protected. Durable `.ues-work`, memory, learning, eval state, and verified-memory evidence are preserved. Parallel read-only work may still use the wider worker pool, while write waves are capped separately (`UES_MAX_WRITER_CONCURRENCY`, default 2 on Windows) to reduce peak worktree/build disk pressure.
+
+A semantic `REVISE` from the plan checker now receives one bounded architect revision and one re-check before UES surfaces the failure to the user. This keeps fail-closed verification while avoiding needless manual prompt retries.
+
+## V15.11 Session Identity Sync
+
+UES keeps Pi session metadata aligned with the active engineering command instead of leaving the session selector named after an earlier conversational message. `/ues-run` derives a bounded deterministic session name from the task without an extra model call. Prompt-style commands such as `/ues-resume`, `/ues-fix`, `/ues-review`, and related UES aliases synchronize through Pi's interactive input hook.
+
+Session display synchronization is UX-only and fail-safe: `pi.setSessionName()` updates the durable Pi session label, while `ctx.ui.setTitle()` is best-effort. Failure to update display metadata must never block controller execution, verification, resume, or cleanup.
+
+## V15.10 Adaptive Stability Runtime
+
+Planning children use activity-aware bounded deadlines. The initial hard deadline remains short for responsiveness, but recent real activity may extend it in bounded increments; an absolute deadline and the independent idle watchdog still terminate hung work. RPC timeout paths preserve partial assistant output before worker teardown, and CLI fallback uses the same deadline model.
+
+Structured architect work is machine-first: when `UES_PLAN_JSON` is requested, the graph is emitted before optional prose. If transport ends after a complete graph has already been emitted, UES may salvage it only when normalization and deterministic plan validation succeed; the independent plan-checker is still mandatory before execution.
+
+High-risk DEEP tasks keep full evidence budgets for executor/verifier/integration roles. Only read-only architect and plan-checker context is role-bounded, using targeted repository tools to fill concrete evidence gaps.
+
+## V15.9 Runtime Artifact Isolation
+
+UES runtime state is not task source state. Structured sandbox delta, declared write-scope checks, same-wave conflict detection, dirty-root inheritance, and sandbox integration now exclude UES-owned runtime directories such as `.ues-traces/**`, `.ues-cache/**`, `.ues-services/**`, `.ues-work/**`, and the other runtime-state directories covered by the shared runtime-artifact contract.
+
+This filtering does not weaken source safety. Real repository files such as `apps/mobile/package.json` remain source-facing mutations and must still be declared by the task before integration.
+
+## V15.8 Plan Gate Recovery
+
+Plan-checker now uses an adaptive bounded policy instead of failing immediately at the old 45-second hard limit. The first pass is soft-steered toward an immediate verdict before its hard timeout; transport/runtime timeout without a semantic verdict receives one shorter warm-context recovery pass. A real REVISE verdict still fails closed.
+
+Sandbox cleanup also scans the repository-specific UES sandbox directory directly. This allows `/ues-clean` to remove stale physical sandbox folders whose Git worktree registration was already lost after a crash or manual prune, while protecting active/live-owner sandboxes.
+
+## V15.7 Lightweight Sandbox Cleanup
+
+UES direct controller runs now track active task worktrees by trace and reclaim their own leftovers when the run ends, including Stop/error paths. Active worktrees remain protected. Stale same-process worktrees can be reclaimed without waiting for Pi to exit, legacy pre-lease worktrees use a 30-minute grace, orphan metadata sidecars are removed, and an empty sandbox base directory is deleted automatically.
+
+The `/ues-clean` command performs the same safe stale-artifact cleanup on demand for the current repository.
+
+## V15.6 Fast Planning
+
+DEEP planning now has explicit latency budgets. Architect exploration is soft-steered after roughly 30 seconds or 16 tool calls and is terminated if it exceeds a 60-second hard or 25-second idle budget. A failed first pass gets one shorter cached recovery rather than a full rediscovery pass. Plan-checker has its own short budget; executor/verifier limits are unchanged.
+
+Task worktree sandboxes now carry an owner PID lease. Before a new controller run, UES may remove old UES sandboxes whose recorded owner is no longer alive. Legacy sandboxes without leases use a conservative grace period.
+
+## V15.5 Per-Leaf Turbo
+
+Large DEEP tasks are decomposed into independently classified leaf tasks. A low-risk single-file leaf can use FAST execution and deterministic-first verification while the root plan still keeps final integration/completion gates. Retry evidence is reduced to a task-local failure delta, and context reuse is keyed by root repository namespace plus workspace fingerprint so equivalent retry worktrees can hit warm context safely. UES does not promise a universal 99% cache hit rate: first runs and changed source must miss; the target is very high warm-hit reuse for unchanged stable state without stale evidence.
+
+## V15.4 ACP-safe child runtime
+
+When UES is hosted by an ACP adapter such as Zed, specialist children must not reuse the ACP adapter's Node entrypoint. UES now verifies that a reusable host script belongs to `@earendil-works/pi-coding-agent`; otherwise Windows resolves the real managed Pi CLI or PATH Pi command. This prevents child specialists from rebinding the ACP host port and failing with `EADDRINUSE`.
+
+## V15.3 DEEP Speed
+
+DEEP/high-risk work keeps its full evidence and verification gates, but avoids redundant exploration. Generic long-horizon "fix" wording no longer forces a debugger before architecture unless concrete failure evidence exists. Architect, plan-checker and executor roles must consume the supplied UES context pack and declared task scope before broad repository searches, and stop discovery when the required evidence is already sufficient.
+
+## V15.2 Turbo Fast Path
+
+FAST low-risk single-file work now preserves the original task policy through internal executor/verifier prompts, uses bounded first-attempt latency budgets, and prefers deterministic fresh verification receipts before spending a second model turn. Timeout/recovery remains fail-closed.
+
+Pi headless eval diagnostics are collected from both stdout and stderr so direct `/ues-run` controller usage is measured correctly.
+
+## V15.1 deterministic admission and managed services
+
+On `main`, `/ues-run` is now an extension command rather than only a prompt template. Pi resolves extension commands before templates, so the controller starts deterministically even when a weak model would otherwise ignore `ues_execute`.
+
+Long-running servers/watchers should use `ues_service`:
+
+```text
+start -> wait-ready/status/logs -> stop
+```
+
+The runtime blocks common foreground server commands in bash/powershell and directs the agent to `ues_service`. Services support TCP/log readiness, bounded log evidence and session cleanup. See `docs/V15-MANAGED-RUNTIME.md`.
+
 ## V14.2 Turbo Weak-Model Runtime
 
 V14.2 keeps the Pi-native controller and specialist roles but changes the hot path to reduce repeated startup, context and verification work.
@@ -124,10 +264,17 @@ UES_CHILD_TOOL_COMPACTION=1
 
 See `docs/V14.2-TURBO-WEAK-MODEL-RUNTIME.md`.
 
-## Prompts
+## Commands and prompt templates
+
+Deterministic extension command:
 
 ```text
 /ues-run
+```
+
+Prompt templates:
+
+```text
 /ues-plan
 /ues-feature
 /ues-fix
@@ -140,6 +287,8 @@ See `docs/V14.2-TURBO-WEAK-MODEL-RUNTIME.md`.
 /ues-resume
 ```
 
+There is intentionally no `pi/prompts/ues-run.md`; keeping that file would create two visible `/ues-run` entries in Pi.
+
 ## Safety
 
 The extension intercepts risky `bash`/`powershell` calls and applies the UES destructive-command guard. Interactive Pi can ask for confirmation; non-interactive risky execution fails closed.

package/docs/V15-MANAGED-RUNTIME.md

@@ -0,0 +1,128 @@
+# V15 Managed Runtime
+
+V15 starts by fixing two weak-model/runtime failures observed after the 14.4.0 stable release:
+
+1. a weak parent model can ignore a prompt telling it to call `ues_execute`;
+2. a foreground development server can keep a shell tool open indefinitely and stall the workflow.
+
+## Deterministic /ues-run admission
+
+`/ues-run` is now registered as a Pi extension command. Pi resolves extension commands before prompt templates, so engineering work enters the UES controller directly instead of depending on the parent model to remember a tool call.
+
+The existing `ues_execute` tool remains available for programmatic/tool-driven use.
+
+The Pi benchmark harness also invokes the UES arm through `/ues-run`, so controller effectiveness is measured rather than parent-tool-admission compliance.
+
+## Managed background services
+
+Both the parent extension and specialist child runtime expose `ues_service` with these actions:
+
+- `start`
+- `wait-ready`
+- `status`
+- `logs`
+- `stop`
+- `restart`
+
+Service execution is shell-free. Commands are launched as executable + argument arrays, with Windows shim resolution through the existing safe resolver.
+
+Readiness may be proven by:
+
+- TCP port;
+- literal log marker;
+- or process survival when no explicit readiness criterion is supplied.
+
+Logs are bounded and may be stored as Evidence Store snapshots.
+
+Lifecycle is bounded as well:
+
+- default maximum service lifetime: 30 minutes;
+- configurable `lifetimeMs`: 10 seconds to 2 hours;
+- optional `idleTimeoutMs`: stop a service after 5 seconds to 1 hour without stdout/stderr activity;
+- session shutdown stops every service owned by that Pi runtime.
+
+## Foreground-service guard
+
+Common long-running foreground commands are blocked in ordinary bash/powershell execution and redirected to `ues_service`. Examples include:
+
+- `npm run dev`
+- `pnpm start:dev`
+- `node apps/api/dist/main.js`
+- `nest start`
+- `next dev`
+- `vite`
+- `uvicorn`
+- `dotnet run`
+- `docker compose up` without `-d`
+
+Normal test/build commands are not classified as services.
+
+## Lifecycle and cleanup
+
+Managed services are owned by the current Pi runtime. Session shutdown stops owned process trees. The runtime intentionally refuses to kill historical/unowned PID metadata, avoiding unsafe PID-reuse termination.
+
+Runtime state lives under `.ues-services/`. It is ignored by Git and excluded from workspace fingerprints, semantic indexing, repository graphs and affected-test scans.
+
+## Validation
+
+Focused validation:
+
+```cmd
+npm run eval:v15
+```
+
+Full release gate:
+
+```cmd
+npm run ci
+```
+
+Live weak-model comparison:
+
+```cmd
+npm run eval:pi -- --model kilo/stepfun/step-3.7-flash:free --thinking low --suite live --task multi-file-contract-compatibility --trials 3 --mode both --min-pairs 3
+```
+
+For the UES arm, `controllerUsed` must now be true because admission is deterministic.
+
+
+## V15.2 Turbo Fast Path
+
+V15.2 addresses latency observed in weak-model live evaluation without weakening completion gates.
+
+For a first-attempt task to enter Turbo Fast Path it must be:
+
+- FAST profile;
+- low risk;
+- single-file bounded;
+- executor/verifier role;
+- no required integration verification;
+- no browser/visual evidence requirement.
+
+The original user-task policy is propagated into controller-generated specialist prompts. UES therefore does not reclassify its own orchestration text as if it were new user scope.
+
+Default first-attempt budgets:
+
+- hard child timeout: 180 seconds;
+- child idle timeout: 60 seconds;
+- post-tool-error idle timeout: 30 seconds;
+- behavioral verification command timeout: 90 seconds.
+
+A timeout is not a PASS. The attempt fails closed and the existing recovery policy can widen context, diagnose, and escalate the model on a later attempt.
+
+Fresh behavioral verification receipts remain the preferred FAST completion proof. A separate verifier model turn is skipped only when the deterministic FAST gate proves the required acceptance criteria at the current workspace fingerprint.
+
+### Pi benchmark telemetry
+
+Pi headless/JSON mode keeps protocol stdout clean and extension/application diagnostics may appear on stderr. V15.2 therefore writes direct-controller eval telemetry to stderr and the eval harness parses both stdout and stderr.
+
+This prevents a successful UES implementation from being mislabeled as `controllerUsed=false` merely because telemetry was read from the wrong stream.
+
+
+## V15.10 adaptive stability
+
+The planning watchdog is progress-aware rather than a fixed wall-clock kill switch. Architect and plan-checker retain short initial deadlines, soft-steer toward early machine output, and may receive bounded deadline extensions only when recent activity is observed. Idle timeouts remain independent and an absolute deadline always wins.
+
+Architect structured planning is JSON-first. A complete graph emitted before a late transport timeout can be recovered only through deterministic normalization/validation and must still pass the independent plan-checker.
+
+High-risk execution and verification retain the original evidence ceiling. Only read-only planning context is role-bounded to reduce first-token latency and duplicate repository ingestion.

package/global-config/agents/architect.md

@@ -12,7 +12,23 @@ Inspect only the repository context needed to answer the assigned question. Map
 
 Prefer repository evidence over generic advice. Separate facts from assumptions.
 
-Return exactly these sections:
+Efficiency contract for DEEP/long-horizon work:
+- Treat the supplied UES runtime context pack, hierarchy, ranked references and exact task text as the first evidence source.
+- Do not inventory the whole repository and do not repeat broad grep/find/list operations after relevant paths are known.
+- Prefer targeted `ues_code` symbol/search evidence and direct reads of likely files/interfaces over shell-wide scans.
+- For each unresolved architecture boundary, use at most two targeted search pivots before either recording the remaining assumption or using the nearest repository-backed pattern.
+- Stop repository exploration as soon as every planned task has exact file/interface scope, dependency ordering, observable acceptance criteria, concrete verification, and risk/rollback coverage.
+- Re-reading an unchanged file is not additional evidence unless a specific unresolved question requires a different range/symbol.
+
+
+When the parent explicitly asks for `UES_PLAN_JSON:`, use **machine-first planning mode**:
+- Emit `UES_PLAN_JSON:` and the complete JSON object before the prose sections below.
+- Do not spend output tokens restating the task before the JSON.
+- After the JSON, keep each prose section concise and add only evidence/assumptions that are not already obvious from the graph.
+- The JSON must already be self-contained and valid when emitted; never rely on later prose to repair missing fields.
+- Once the JSON is emitted, do not resume broad repository exploration.
+
+Otherwise, return exactly these sections:
 
 ## Confirmed facts
 Evidence-backed architecture facts with paths/symbols.
@@ -36,3 +52,49 @@ Compatibility, rollout, rollback, or migration concerns.
 Evidence needed to prove the chosen design works.
 
 The parent agent owns implementation and final decisions.
+
+When the parent explicitly asks for `UES_PLAN_JSON:`, emit exactly one JSON object after that marker in machine-first position as described above. Do not put prose inside scalar enum fields.
+
+Required shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "goal": "observable repository goal",
+  "tasks": [
+    {
+      "id": "task-01",
+      "title": "short title",
+      "summary": "what changes and why",
+      "dependsOn": [],
+      "files": {
+        "create": [],
+        "modify": ["path/inside/repo"],
+        "test": [],
+        "delete": [],
+        "read": []
+      },
+      "acceptance": [
+        "observable behavior or repository state that must be true"
+      ],
+      "verification": [
+        "concrete executable or inspectable check that proves the criterion"
+      ],
+      "verificationCommands": [
+        { "command": "npm", "args": ["test", "--", "target"] }
+      ],
+      "risk": "low",
+      "riskNotes": "optional prose describing the risk"
+    }
+  ]
+}
+```
+
+Rules for `UES_PLAN_JSON`:
+- `risk` is only one of `low`, `medium`, `high`, `critical`; put descriptive prose in `riskNotes`.
+- `acceptance` is a non-empty array of observable criteria, never a paragraph field with another name.
+- `verification` is a non-empty array of concrete checks, never omitted even when `verificationCommands` is present.
+- `dependsOn` is always an array of task IDs.
+- paths are repository-relative and must not escape the repository.
+- do not invent acceptance criteria that are not supported by the assigned task/repository evidence.
+

package/global-config/agents/executor.md

@@ -13,6 +13,13 @@ Before editing:
 3. Confirm dependencies named by the task exist in the working tree.
 4. Preserve unrelated user changes.
 
+Quality-preserving bounded-exploration policy:
+- Start from the supplied context pack and the task's declared read/modify/test files; do not inventory the repository.
+- Prefer direct reads and targeted `ues_code` symbol/search queries. Use broad grep/find only when a declared path/interface is stale or a concrete acceptance gap cannot otherwise be resolved.
+- Read the direct caller/consumer or nearest test only when it materially affects the assigned acceptance criteria.
+- Once the code path is understood well enough to make the smallest safe edit, stop exploring, implement, and spend the remaining effort on fresh verification.
+- Do not re-read unchanged files merely for confidence; new reads must answer a named unresolved question.
+
 Quality-preserving minimal-solution policy:
 - First understand the real code path and acceptance criteria; do not optimize before understanding.
 - Prefer, in order: reuse an existing codebase primitive; use the standard library or native platform capability; use an already-installed dependency; then write the smallest maintainable new implementation that fully satisfies the task.

package/global-config/agents/plan-checker.md

@@ -15,7 +15,14 @@ ocskill task-graph <path-to-PLAN.json>
 ocskill verification-plan .
 ```
 
-Reject a plan when it relies on invented files/interfaces, has dependency cycles, missing consumers, untestable acceptance criteria, unsafe same-wave write/read conflicts, unexplained destructive operations, or verification that cannot prove the requested behavior. Two read-only tasks may share files; any writer must be serialized against readers/writers unless isolated worktrees plus an explicit integration step make the boundary safe.
+Reject a plan when it relies on invented files/interfaces, has dependency cycles, missing consumers, untestable acceptance criteria, unsafe same-wave write/read conflicts, unexplained destructive operations, or verification that cannot prove the requested behavior.
+
+Efficiency contract:
+- Validate the declared plan and supplied context first; do not independently rescan the whole repository.
+- Inspect only paths/interfaces whose existence, dependency ordering, write overlap, acceptance, or verification is uncertain.
+- Prefer targeted symbol/path checks over broad repository searches.
+- Once every blocking plan property is proven or disproven, return PASS/REVISE immediately; additional exploration is not stronger evidence.
+ Two read-only tasks may share files; any writer must be serialized against readers/writers unless isolated worktrees plus an explicit integration step make the boundary safe.
 
 Return exactly:
 

package/global-config/agents/verifier.md

@@ -19,13 +19,13 @@ Command/check, exit/result, and what claim it proves.
 Criterion-by-criterion evidence.
 
 ## Failures
-Actual failed checks or unmet criteria.
+Actual failed checks or unmet criteria. If none, write exactly `None`.
 
 ## Unresolved gaps
-Important behavior not proven.
+Only requested acceptance criteria or requested behavior that remain unproven. If none, write exactly `None`. Do not put optional or out-of-scope checks here.
 
 ## Checks not run
-What was skipped and why.
+What was skipped and why. Put optional or out-of-scope checks here rather than treating them as unresolved acceptance gaps.
 
 ## Completion evidence
 A concise statement limited to what the fresh evidence supports.

package/global-config/skills/database-engineering/references/workflow.md

@@ -13,3 +13,18 @@ Define the invariant and the smallest atomic boundary. Consider retries, unique
 
 ## Verification
 Validate migration up/down strategy when supported, run affected data tests, and inspect generated SQL/schema diff. For risky changes use representative existing data or a dry run. Confirm old/new application compatibility when rollout can overlap.
+
+
+## Fixture/demo cleanup safety
+
+Treat cleanup of test/demo records as a data migration, not a UI concern.
+
+- refuse production targets and never silently fall back from a test database to a development database;
+- dry-run before deletion and report the exact candidate IDs/keys plus pre-cleanup counts;
+- match deterministic markers or audited source provenance, never a broad substring that could include legitimate records;
+- preserve canonical seed/demo records and real user history;
+- delete in dependency-safe FK order and use a transaction/rollback boundary when the stack supports it;
+- report post-cleanup counts and run the cleanup a second time to prove idempotency;
+- verify public/API data after cleanup. Frontend filtering is not cleanup evidence.
+
+Only claim `DB_CLEAN_PASS` when fresh data-layer evidence proves the cleanup candidates, counts, canonical preservation, public-data result, and zero-change second pass.