@piagent/platform 1.2.13 → 1.2.14

package/docs/en/maintainer-guide.md

@@ -0,0 +1,121 @@
+# Maintainer guide
+
+[Tiếng Việt](../vi/maintainer-guide.md)
+
+## Placement rule
+
+Before adding code, answer one ownership question:
+
+| Question | Destination |
+|---|---|
+| Does it register a Pi hook, command, tool, or session UI? | `packages/piagent-core/runtime/` |
+| Is it a deterministic policy or scoring decision? | A focused core service module; no Pi API or direct UI output |
+| Does it persist local runtime evidence? | State service with owner-only mode and bounded retention |
+| Does it integrate MCP? | `packages/piagent-core/mcp/` |
+| Does it resolve profiles, packs, or locks? | `packages/piagent-core/capabilities/` |
+| Is it a CLI command? | Thin `scripts/` entrypoint calling a package service |
+| Is it project-specific? | Project profile/adapter, never `piagent-core` |
+
+Do not create a `utils` dumping ground. Name a module after the capability it owns.
+
+## Current split queue
+
+### P0: composition root
+
+`packages/piagent-core/extensions/piagent-guard.ts` remains the main architecture debt. It is 8,290 lines after the lifecycle extraction and may only shrink under the architecture gate.
+
+Already extracted:
+
+- `runtime/session/message-signals.ts`
+- `runtime/session/runtime-state.ts`
+- `runtime/session/system-prompt.ts`
+- `runtime/session/usage.ts`
+- `runtime/session/tool-result-compaction.ts`
+- `runtime/input/chat-images.ts`
+- `runtime/hooks/session-start-hook.ts`
+- `runtime/hooks/session-hooks.ts`
+- `runtime/hooks/input-hook.ts`
+- `runtime/hooks/agent-start-hook.ts`
+- `runtime/hooks/completion-hook.ts`
+- `runtime/hooks/tool-result-hook.ts`
+- `runtime/tools/tool-groups.ts`
+- `runtime/workflows/input-routing.ts`
+- `runtime/workflows/task-intake.ts`
+- `runtime/runtime-limits.ts`
+
+Next cohesive extractions:
+
+1. `runtime/hooks/tool-call-hook.ts`: pre-call capability, path, shell, external-action, task-scope, and confirmation enforcement.
+2. `runtime/tools/`: policy, task, context, memory, onboarding, profile, document, and source tools.
+3. `runtime/commands/`: workflow, session, permission, context, MCP, profile, onboarding, and compatibility aliases.
+4. Focused core services for the remaining profile, memory, onboarding, and source-cache algorithms still embedded in the composition root.
+
+Target: the composition root stays below 500 lines and contains registration order plus a small shared runtime state object.
+
+### P1: policy engine
+
+Split `extensions/policy-core.js` by decision boundary:
+
+- `policy/shell/tokenize.js`
+- `policy/shell/expansion.js`
+- `policy/path/match.js`
+- `policy/path/candidates.js`
+- `policy/exec/evaluate.js`
+
+Keep one compatibility barrel until all internal imports move. Differential shell tests remain attached to the parser/matcher boundary.
+
+### P1: Context Engine
+
+Split `extensions/context-engine.js` into:
+
+- `context/index/store.js`
+- `context/index/policy.js`
+- `context/retrieval/search.js`
+- `context/retrieval/pack.js`
+- `context/telemetry.js`
+- `context/test-impact.js`
+
+The index store owns SQLite and secure deletion. Retrieval never opens policy on its own; it receives an explicit resolved exclusion policy.
+
+### P2: capability resolver
+
+Split `capabilities/capability-core.js` into manifest validation, dependency resolution, permission projection, and lock integrity. Atomic file writes belong in an infrastructure module rather than the resolver.
+
+### P2: benchmark runner
+
+Split `scripts/benchmark-runner.mjs` into a thin CLI plus package modules for suite materialization, surface execution, evidence collection, grading, and report rendering. The CLI must not calculate a second version of a benchmark metric.
+
+### P2: long documentation and tests
+
+- Split the operator manual by install, daily workflow, session/usage, MCP, recovery, and reporting; keep an index at its stable path.
+- Split `piagent-guard-integration.test.mjs` by runtime hook family while retaining shared harness helpers.
+- Mirror each extracted source feature with one focused test file.
+
+## Runtime composition rules
+
+- Registration functions receive an explicit dependency object. They do not import mutable state from the composition root.
+- Shared session state has one typed owner and is passed to hook/tool/command registrars.
+- Tool and command aliases call the same handler; aliases do not duplicate behavior.
+- UI formatting stays in runtime adapters. Policy services return structured decisions.
+- Every file under `packages/piagent-core/runtime/` is listed in
+  `capabilities/runtime-integrity.js`; the capability lock must pin executable
+  runtime code before a release can pass.
+- Every filesystem write declares path, mode, retention, and source of truth.
+- Every derived metric names its inputs and has a unit test with a hand-computed example.
+
+## Change checklist
+
+1. Put code in the owning layer.
+2. Add or update the EN/VI pair for normative behavior.
+3. Run `npm run architecture:check` before broad tests.
+4. Run focused tests for the changed feature.
+5. Run `npm run verify` before release.
+6. Update both language files in the same commit when semantics change.
+
+## Definition of done for the migration
+
+- Composition root is at most 500 lines.
+- No non-growth exception remains in `architecture/layers.json`.
+- Core policy modules do not import runtime or CLI code.
+- Every normative maintainer topic has an EN/VI pair.
+- Full verification, package distribution, benchmark schema, and published docs gates remain green.

package/docs/languages.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "defaultLanguage": "en",
+  "preservedTechnicalTerms": [
+    "agent",
+    "terminal",
+    "workflow",
+    "MCP",
+    "tool",
+    "runtime",
+    "context",
+    "session",
+    "token",
+    "model",
+    "thinking",
+    "benchmark"
+  ],
+  "pairs": [
+    {
+      "topic": "repository-readme",
+      "en": "README.md",
+      "vi": "README.vi.md"
+    },
+    {
+      "topic": "documentation-index",
+      "en": "docs/en/README.md",
+      "vi": "docs/vi/README.md"
+    },
+    {
+      "topic": "architecture",
+      "en": "docs/en/architecture.md",
+      "vi": "docs/vi/architecture.md"
+    },
+    {
+      "topic": "maintainer-guide",
+      "en": "docs/en/maintainer-guide.md",
+      "vi": "docs/vi/maintainer-guide.md"
+    }
+  ]
+}

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.13`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.14`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.13 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.14 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -971,8 +971,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.13` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.13` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.14` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.14` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1083,7 +1083,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 command -v piagent-install
 ```
 

package/docs/package-architecture-notes.md

@@ -1,5 +1,14 @@
 # Package architecture notes
 
+This path is retained for stable links. The maintained architecture documents are:
+
+- [Architecture (English)](en/architecture.md)
+- [Architecture (Tiếng Việt)](vi/architecture.md)
+- [Maintainer guide (English)](en/maintainer-guide.md)
+- [Maintainer guide (Tiếng Việt)](vi/maintainer-guide.md)
+
+The remaining notes below describe historical package decisions and should not be used as the current file-placement map.
+
 ## Mục tiêu
 
 Pi Agent Platform được đóng gói như một reusable Pi package để dùng cho nhiều project mà không kéo theo rule nghiệp vụ của một repo cụ thể.

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.2.13 | Rollout guidance |
+| Surface | Status for v1.2.14 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.13` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.14` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.2.13 (helper package version)
-tag: v1.2.13
+currentRelease: v1.2.14 (helper package version)
+tag: v1.2.14
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.13
+pi install git:github.com/Vt-mmm/piagent@v1.2.14
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -22,7 +22,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.13, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.14, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 piagent-install --stable
 cd /path/to/project
 pi
@@ -43,7 +43,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.13
+npm install -g --ignore-scripts @piagent/platform@1.2.14
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs/vi/README.md

@@ -0,0 +1,13 @@
+# Tài liệu Pi Agent Platform
+
+[English](../en/README.md)
+
+## Bắt đầu từ đây
+
+- [Architecture](architecture.md): chiều dependency, ownership của code, luồng runtime và ranh giới state.
+- [Maintainer guide](maintainer-guide.md): code mới đặt ở đâu, file budget, thứ tự tách file và checklist review.
+- [Release và install policy](../release-install-policy.md)
+- [Quality benchmark](../quality-benchmark.md)
+- [Security threat model](../security-threat-model.md)
+
+Tài liệu tiếng Việt giữ nguyên các keyword kỹ thuật: agent, terminal, workflow, MCP, tool, runtime, context, session, token, model, thinking và benchmark. Code, schema, command name và reusable workflow prompt luôn dùng tiếng Anh.

package/docs/vi/architecture.md

@@ -0,0 +1,81 @@
+# Architecture của Pi Agent Platform
+
+[English](../en/architecture.md)
+
+## Mục tiêu
+
+Platform là một Pi harness dùng lại cho nhiều project, không phải application chứa business logic riêng của một project. Architecture phải thể hiện rõ bốn tính chất trong code:
+
+1. Policy decision phải test được mà không cần mở Pi.
+2. Pi lifecycle hook chỉ compose feature, không ôm toàn bộ implementation của feature.
+3. Local state, MCP, process và filesystem access nằm sau adapter rõ ràng.
+4. Business rule riêng của project nằm trong project profile và adapter, không nằm trong core.
+
+## Chiều dependency
+
+```text
+entrypoints/scripts
+        |
+        v
+composition: extensions/piagent-guard.ts
+        |
+        +--------------------+
+        v                    v
+runtime adapters        integrations
+        |                MCP / capabilities
+        v                    |
+core services <-------------+
+policy / task / context / security
+```
+
+Dependency chỉ đi xuống. Core service không import Pi composition root hay runtime adapter. Runtime adapter được gọi core service và integration. Chỉ composition root mới register toàn bộ Pi extension.
+
+Rule máy đọc nằm tại `architecture/layers.json`; chạy `npm run architecture:check` để enforce.
+
+## Các layer vật lý
+
+| Layer | Vị trí hiện tại | Ownership | Không được chứa |
+|---|---|---|---|
+| Composition | `packages/piagent-core/extensions/piagent-guard.ts` | Wiring, dependency construction, thứ tự registration | Feature algorithm, mutable state implementation, formatter lớn |
+| Runtime adapters | `packages/piagent-core/runtime/` | Pi lifecycle hook, shared session state, command/tool registration, input routing | Policy decision dùng lại |
+| Core services | `packages/piagent-core/extensions/` trừ entrypoint | Policy, context, task lifecycle, state service | Pi command menu và UI text |
+| MCP integration | `packages/piagent-core/mcp/` | MCP config layer, readiness, approval, command action | Task và context policy |
+| Capabilities | `packages/piagent-core/capabilities/` | Profile resolution, pack validation, lock, source root | Pi session lifecycle |
+| Security foundation | `packages/piagent-core/security/` | Sensitive-data primitive | Workflow behavior |
+| Benchmark | `packages/piagent-core/benchmark/`, `benchmarks/` | Suite validation, scoring, evidence | Runtime enforcement |
+| Entrypoints | `scripts/` | CLI argument và gọi use case | Domain logic trùng lặp |
+| Product assets | `prompts/`, `skills/`, `subagents/`, `adapters/`, `packs/`, `schemas/` | Declarative behavior và contract | Hidden runtime state |
+
+Folder `extensions/` vẫn chứa một số service module do lịch sử. Tên folder này là legacy; chỉ `piagent-guard.ts` được Pi load như extension. Mỗi lần migrate phải tách theo một feature trọn vẹn và giữ compatibility cho đến khi migration hoàn tất.
+
+## Luồng runtime
+
+1. Pi load một extension entrypoint duy nhất.
+2. Composition resolve base policy, project profile, capability lock và local session state.
+3. Runtime hook normalize input và thu session evidence qua một session-scoped state owner.
+4. Core service quyết định path, shell, MCP, task, context và final-gate policy.
+5. Runtime adapter register tool và slash command ngắn gọn.
+6. Owner-only local state ghi evidence; prompt chỉ là hướng dẫn, không phải enforcement boundary.
+
+## Ownership của state
+
+| State | Owner | Vị trí | Commit |
+|---|---|---|---:|
+| OAuth và provider auth | Pi/provider | user config | Không |
+| Platform install config | Piagent installer | global Pi settings | Không |
+| Project profile và lock | Project | `.pi/piagent-profile*.json` | Có |
+| Task, trace, telemetry, capture | Runtime | `.pi/piagent-state/` | Không |
+| Session history | Pi | Pi session store | Không |
+| Shared project instructions | Project | `AGENTS.md`, project docs | Có |
+
+Một feature không được tạo representation authoritative thứ hai cho cùng một state. Derived index phải có policy digest và phải rebuild được từ source of truth.
+
+## Ranh giới file
+
+- Runtime module mới: tối đa 500 dòng.
+- Core module mới: tối đa 1.000 dòng.
+- CLI entrypoint: tối đa 800 dòng; use case phải chuyển vào package module.
+- File lớn đang tồn tại có non-growth budget rõ ràng trong `architecture/layers.json`.
+- Test mirror feature path và test public behavior, không phụ thuộc private implementation order.
+
+Thứ tự tách file và ownership rule chi tiết nằm trong [maintainer guide](maintainer-guide.md).

package/docs/vi/maintainer-guide.md

@@ -0,0 +1,121 @@
+# Maintainer guide
+
+[English](../en/maintainer-guide.md)
+
+## Rule đặt code
+
+Trước khi thêm code, cần trả lời một câu hỏi về ownership:
+
+| Câu hỏi | Vị trí |
+|---|---|
+| Code register Pi hook, command, tool hay session UI? | `packages/piagent-core/runtime/` |
+| Code là policy decision hoặc scoring decision deterministic? | Core service module nhỏ, không dùng Pi API và không format UI |
+| Code persist local runtime evidence? | State service có owner-only mode và bounded retention |
+| Code integrate MCP? | `packages/piagent-core/mcp/` |
+| Code resolve profile, pack hay lock? | `packages/piagent-core/capabilities/` |
+| Code là CLI command? | `scripts/` chỉ parse argument và gọi package service |
+| Code riêng cho một project? | Project profile/adapter, không đưa vào `piagent-core` |
+
+Không tạo folder `utils` để gom code không rõ ownership. Module phải mang tên capability mà nó quản lý.
+
+## Thứ tự tách file hiện tại
+
+### P0: composition root
+
+`packages/piagent-core/extensions/piagent-guard.ts` là architecture debt lớn nhất. Sau đợt tách lifecycle file còn 8.290 dòng và architecture gate chỉ cho phép file nhỏ dần.
+
+Đã tách:
+
+- `runtime/session/message-signals.ts`
+- `runtime/session/runtime-state.ts`
+- `runtime/session/system-prompt.ts`
+- `runtime/session/usage.ts`
+- `runtime/session/tool-result-compaction.ts`
+- `runtime/input/chat-images.ts`
+- `runtime/hooks/session-start-hook.ts`
+- `runtime/hooks/session-hooks.ts`
+- `runtime/hooks/input-hook.ts`
+- `runtime/hooks/agent-start-hook.ts`
+- `runtime/hooks/completion-hook.ts`
+- `runtime/hooks/tool-result-hook.ts`
+- `runtime/tools/tool-groups.ts`
+- `runtime/workflows/input-routing.ts`
+- `runtime/workflows/task-intake.ts`
+- `runtime/runtime-limits.ts`
+
+Những feature cần tách tiếp theo một khối trọn vẹn:
+
+1. `runtime/hooks/tool-call-hook.ts`: enforcement trước tool call cho capability, path, shell, external action, task scope và confirmation.
+2. `runtime/tools/`: policy, task, context, memory, onboarding, profile, document và source tools.
+3. `runtime/commands/`: workflow, session, permission, context, MCP, profile, onboarding và compatibility alias.
+4. Tạo core service tập trung cho profile, memory, onboarding và source-cache algorithm vẫn còn nằm trong composition root.
+
+Mục tiêu: composition root dưới 500 dòng, chỉ giữ registration order và một shared runtime state object nhỏ.
+
+### P1: policy engine
+
+Tách `extensions/policy-core.js` theo decision boundary:
+
+- `policy/shell/tokenize.js`
+- `policy/shell/expansion.js`
+- `policy/path/match.js`
+- `policy/path/candidates.js`
+- `policy/exec/evaluate.js`
+
+Giữ một compatibility barrel cho đến khi toàn bộ internal import đã migrate. Differential shell test phải nằm sát parser/matcher boundary.
+
+### P1: Context Engine
+
+Tách `extensions/context-engine.js` thành:
+
+- `context/index/store.js`
+- `context/index/policy.js`
+- `context/retrieval/search.js`
+- `context/retrieval/pack.js`
+- `context/telemetry.js`
+- `context/test-impact.js`
+
+Index store owner SQLite và secure deletion. Retrieval không tự load policy; nó nhận resolved exclusion policy bắt buộc từ caller.
+
+### P2: capability resolver
+
+Tách `capabilities/capability-core.js` thành manifest validation, dependency resolution, permission projection và lock integrity. Atomic file write thuộc infrastructure module, không thuộc resolver.
+
+### P2: benchmark runner
+
+Tách `scripts/benchmark-runner.mjs` thành CLI mỏng và package module cho suite materialization, surface execution, evidence collection, grading và report rendering. CLI không được tự tính một bản benchmark metric thứ hai.
+
+### P2: docs và test dài
+
+- Tách operator manual theo install, daily workflow, session/usage, MCP, recovery và reporting; stable path cũ trở thành index.
+- Tách `piagent-guard-integration.test.mjs` theo từng runtime hook family, vẫn dùng chung harness helper.
+- Mỗi source feature được tách phải có một test file tập trung.
+
+## Rule cho runtime composition
+
+- Registration function nhận dependency object rõ ràng, không import mutable state từ composition root.
+- Shared session state có một typed owner và được truyền vào hook/tool/command registrar.
+- Tool và command alias gọi cùng handler; alias không duplicate behavior.
+- UI formatting nằm trong runtime adapter. Policy service trả về structured decision.
+- Mọi file trong `packages/piagent-core/runtime/` phải có trong
+  `capabilities/runtime-integrity.js`; capability lock phải pin toàn bộ runtime
+  code thực thi trước khi release được phép pass.
+- Mỗi filesystem write phải khai báo path, mode, retention và source of truth.
+- Mỗi derived metric phải nêu input và có unit test tính tay một ví dụ.
+
+## Checklist khi thay đổi
+
+1. Đặt code đúng owning layer.
+2. Thêm hoặc update cặp EN/VI nếu behavior là normative.
+3. Chạy `npm run architecture:check` trước broad test.
+4. Chạy focused test của feature vừa sửa.
+5. Chạy `npm run verify` trước release.
+6. Khi semantic thay đổi, update hai language file trong cùng commit.
+
+## Definition of done cho architecture migration
+
+- Composition root tối đa 500 dòng.
+- `architecture/layers.json` không còn non-growth exception.
+- Core policy module không import runtime hay CLI code.
+- Mọi maintainer topic normative đều có cặp EN/VI.
+- Full verification, package distribution, benchmark schema và published docs gate đều xanh.

package/docs-site/architecture.html

@@ -27,7 +27,8 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.13 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.14 docs · VI</span>
+        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -95,34 +96,56 @@
               <p>Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được.</p>
             </div>
 <section class="section">
-
+  <div class="callout">
+    <strong>Chiều dependency được enforce bằng code.</strong>
+    <p><span class="inline-code">architecture/layers.json</span> là rule máy đọc; <span class="inline-code">npm run architecture:check</span> chặn dependency ngược và file vượt budget.</p>
+  </div>
   <div class="grid cols-3">
     <article class="card">
-      <h3 id="core-package">Core package</h3>
-      <p><span class="inline-code">packages/piagent-core</span> chứa extension guard, prompts, skills và subagent roles.</p>
+      <h3 id="composition">Composition</h3>
+      <p><span class="inline-code">piagent-guard.ts</span> chỉ giữ wiring, registration order và shared runtime state. File này không được tiếp tục chứa feature algorithm.</p>
     </article>
     <article class="card">
-      <h3 id="adapters">Adapters</h3>
-      <p><span class="inline-code">adapters/</span> chứa profile dùng lại: frontend, backend, fullstack, data, devops, docs.</p>
+      <h3 id="runtime-adapters">Runtime adapters</h3>
+      <p><span class="inline-code">packages/piagent-core/runtime</span> quản lý Pi hook, command, tool, session UI, usage, log compaction và workflow input routing.</p>
     </article>
     <article class="card">
-      <h3 id="capability-packs">Capability packs</h3>
-      <p><span class="inline-code">packs/</span> gom policy, lifecycle, recipes và eval scenarios theo manifest có lock.</p>
+      <h3 id="core-services">Core services</h3>
+      <p>Policy, task, context và state trả về structured decision. Core service không import runtime adapter hay Pi composition root.</p>
     </article>
     <article class="card">
-      <h3 id="policies">Policies</h3>
-      <p>Base policy định nghĩa protected paths, command rules, permission modes và human-action gates.</p>
+      <h3 id="integrations">Integrations</h3>
+      <p><span class="inline-code">mcp/</span>, <span class="inline-code">capabilities/</span> và <span class="inline-code">security/</span> có ownership riêng; không nhúng task workflow vào integration.</p>
     </article>
     <article class="card">
-      <h3 id="scripts">Scripts</h3>
-      <p>Setup, doctor, model scope, MCP, subagents, benchmark và trusted-run wrapper đều có CLI riêng.</p>
+      <h3 id="entrypoints">Entrypoints</h3>
+      <p><span class="inline-code">scripts/</span> parse CLI argument rồi gọi use case. Metric, policy và state transition không được duplicate trong CLI.</p>
     </article>
     <article class="card">
-      <h3 id="docs">Docs</h3>
-      <p><span class="inline-code">docs/</span> giữ manual dài. <span class="inline-code">docs-site/</span> là trang HTML gọn cho team.</p>
+      <h3 id="product-assets">Product assets</h3>
+      <p><span class="inline-code">prompts/</span>, <span class="inline-code">skills/</span>, <span class="inline-code">subagents/</span>, <span class="inline-code">adapters/</span>, <span class="inline-code">packs/</span> và <span class="inline-code">schemas/</span> là declarative assets.</p>
     </article>
   </div>
 </section>
+
+<section class="section">
+  <div class="section-head">
+    <p class="eyebrow">Ownership</p>
+    <h2 id="state-ownership">Một state chỉ có một source of truth</h2>
+    <p>Project profile và lock có thể commit. Task evidence, telemetry, trace, capture và session history là local state. Derived index phải có policy digest và rebuild được.</p>
+  </div>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>State</th><th>Owner</th><th>Vị trí</th><th>Commit</th></tr></thead>
+      <tbody>
+        <tr><td>Project profile + lock</td><td>Project</td><td><span class="inline-code">.pi/piagent-profile*.json</span></td><td>Có</td></tr>
+        <tr><td>Task, trace, telemetry, capture</td><td>Runtime</td><td><span class="inline-code">.pi/piagent-state/</span></td><td>Không</td></tr>
+        <tr><td>Session history</td><td>Pi</td><td>Pi session store</td><td>Không</td></tr>
+        <tr><td>Shared instructions</td><td>Project</td><td><span class="inline-code">AGENTS.md</span>, project docs</td><td>Có</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
             <nav class="pager" aria-label="Trang kế tiếp">
               <a class="pager-prev" href="/security">
                 <span class="pager-label">Trước</span>
@@ -139,6 +162,7 @@
               <div class="footer-links" aria-label="External links">
                 <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
                 <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>

package/docs-site/benchmark.html

@@ -27,7 +27,8 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.13 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.14 docs · VI</span>
+        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -324,6 +325,7 @@
               <div class="footer-links" aria-label="External links">
                 <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
                 <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>