@piagent/platform 1.2.10 → 1.2.11

package/docs/quality-benchmark.md

@@ -1,43 +1,240 @@
 # Quality benchmark guide
 
-## Vì sao cần benchmark
+## Chạy và chấm tự động bằng một lệnh
 
-Không nên claim tiết kiệm token/cost hoặc tăng chất lượng nếu chưa có số liệu theo cùng scenario. Token giảm khi:
+Từ terminal, chạy:
 
-- project context đã được onboard;
-- profile giới hạn đúng scope;
-- memory explicit giảm scout lặp;
-- source cache giúp đọc targeted;
-- task gate bắt verify/trace;
-- tool policy chặn vòng lặp sai.
+```bash
+piagent-benchmark
+```
+
+Lệnh mặc định dùng suite `core-v1`, tạo workspace Git sạch cho từng lần chạy,
+chạy cùng task trên `raw-pi` và `piagent`, chấm bằng hidden grader, rồi đọc usage
+trực tiếp từ Pi session JSONL. Runner cũng có thể dùng surface `codex-cli` làm baseline.
+Không nhập tay kết quả hay token.
+
+Default suite đo task ở trạng thái steady-state: runner init profile, ghi một
+onboarding snapshot/index tối thiểu hợp lệ và build Context Engine trước Git
+baseline, ngoài thời gian/model usage được đo. Vì vậy mỗi repeat không trả lại
+bài toán one-time `/onboard run`. Nếu Piagent tiếp tục sửa
+`.pi/project-context.md` hoặc `.pi/context-index.json` trong lúc giải task, thay
+đổi đó vẫn bị scope gate bắt; runner không blanket-ignore file nội bộ.
+
+Các biến override runtime `PIAGENT_*` của shell gọi lệnh được reset trong model
+run để benchmark luôn đo default behavior của release. Provider auth, Pi config
+và các biến `PI_*` vẫn được giữ để Pi dùng account/model hiện hành.
+
+Auto-discovered project/global `AGENTS.md` và `CLAUDE.md` được tắt cho cả hai
+surface để instruction cá nhân không làm lệch đối chứng. Piagent sau đó nạp
+tường minh đúng project `AGENTS.md`, guard extension và skill directory của
+release đang benchmark. Skill vận hành `piagent-ops` chỉ gọi chủ động và không
+được quảng bá cho model trong task bounded vì runtime đã cung cấp cùng policy;
+skill theo ngữ cảnh khác vẫn dùng discovery bình thường. Global
+`SYSTEM.md`/`APPEND_SYSTEM.md`, provider auth và model settings vẫn áp dụng
+giống nhau cho hai surface.
+
+Suite mặc định có 4 scenario, 2 surface và 3 lần lặp, tổng cộng 24 model
+session. Runner hiện kế hoạch và hỏi xác nhận trước khi dùng quota. Xem trước mà
+không gọi model:
+
+```bash
+piagent-benchmark --dry-run
+```
 
-Benchmark là bằng chứng để chọn agent surface, model, profile, và workflow preset cho từng loại task.
+Để so sánh release hoặc cấu hình một cách lặp lại được, pin cùng model và
+thinking level cho mọi run:
 
-## Ba scenario mặc định
+```bash
+piagent-benchmark --model <provider/model> --thinking high
+```
+
+## So sánh với surface codex-cli
 
-Khởi tạo:
+Codex phải được cài và đăng nhập trước. Chạy cùng suite, model và thinking:
 
 ```bash
-bash scripts/quality-benchmark.sh /path/to/project --init
+piagent-benchmark \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh
 ```
 
-Script tạo:
+Runner giữ chuỗi đầy đủ `provider/model` làm danh tính so cặp với usage Pi và
+truyền phần `model` sau dấu `/` cho `codex exec`. Vì Codex JSONL không tự báo
+effective model/thinking, hai option này là bắt buộc; report ghi rõ bằng chứng
+parity là command-line pinning. Nếu Pi thực tế báo model hoặc thinking khác,
+cặp đó không đủ điều kiện chấm Efficiency.
+
+Mặc định `--codex-mode controlled` chạy `codex exec` theo các ranh giới sau:
+
+- workspace Git và prompt giống Piagent, prompt đi qua stdin;
+- session `--ephemeral`, sandbox `workspace-write`;
+- tạo `CODEX_HOME` tạm mode `0700`, nên không nạp global `AGENTS.md`, user
+  config, rules, hooks, plugin, session hay cache của operator; phía Pi cũng
+  không nạp `APPEND_SYSTEM.md` global để hai bên cùng không mang instruction cá
+  nhân vào phép đo;
+- đọc feature catalog của đúng bản Codex đang cài rồi tắt các capability tùy
+  chọn có thể làm lệch bài offline, như apps, plugins, browser/computer use,
+  image generation, multi-agent, hooks, skill search và tool suggestion;
+- vẫn dùng auth hiện có của Codex bằng symlink `auth.json` trong thư mục tạm;
+  runner không đọc/sao chép credential và xóa thư mục tạm ở mọi đường thoát
+  được kiểm soát. Nếu auth đi qua environment thì không tạo symlink.
+
+Để đo trải nghiệm Codex theo đúng cấu hình cá nhân, dùng:
+
+```bash
+piagent-benchmark \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh \
+  --codex-mode native
+```
+
+`native` nạp lại global `AGENTS.md`, config, rules, hooks, MCP và plugins của
+operator. Đây là phép đo full-product nhưng kém lặp lại hơn và có thể chạy integration bên ngoài;
+runner nêu cảnh báo này trước bước xác nhận quota. Dùng `controlled` cho release
+gate, dùng `native` như report bổ sung về UX thực tế.
+
+Codex `turn.completed.usage.input_tokens` gồm cả cached input. Runner chuẩn hóa:
 
 ```text
-.pi/benchmarks/quality-scenarios.md
+fresh input = input_tokens - cached_input_tokens
+fresh token = fresh input + output_tokens
 ```
 
-Scenario mặc định:
+`reasoning_output_tokens` là breakdown của output, không cộng lần hai. JSONL
+được parse streaming nên command output lớn không phụ thuộc giới hạn phần log
+giữ trong RAM; report chỉ lưu hash toàn bộ stdout, tool histogram và số usage,
+không lưu raw assistant/tool output. Codex OAuth JSONL không báo chi phí tiền,
+vì vậy cost hiển thị `n/a` và không tham gia cost ratio thay vì bị giả thành
+`$0` hay dùng bảng giá có thể thay đổi.
+
+Trong CI hoặc terminal không tương tác, phải thêm `--yes`. Đây là xác nhận cho
+phép runner bắt đầu các model session có thể tính phí, không phải bỏ qua safety
+gate.
+
+Lỗi giải task được ghi vào reliability và suite tiếp tục. Lỗi hạ tầng như không
+init được profile, không tạo được Git baseline hoặc không khởi động được grader
+sẽ dừng suite ngay để không đốt các model session còn lại; runner giữ
+`runs.jsonl` cùng `aborted.json` để chẩn đoán.
+Timeout hoặc Pi thoát lỗi trước khi ghi usage cũng dừng ngay theo cùng nguyên
+tắc; một hidden-grader failure sau model run vẫn là kết quả task và suite tiếp
+tục.
+
+## Suite mặc định đo gì
+
+`core-v1` gồm:
 
-1. `read-only-scout`
-2. `bounded-source-fix`
-3. `be-readonly-to-fe`
+1. Một lỗi tính toán single-file.
+2. Một thay đổi behavior multi-file.
+3. Một lỗi targeted trong source tree có nhiều file gây nhiễu.
+4. Một yêu cầu đối kháng đọc/sửa `.env` để kiểm tra protected-path refusal.
 
-## Ghi một lần chạy
+Mỗi source task được chấm bằng verifier nằm ngoài workspace của agent. Runner
+còn đối chiếu file thay đổi với scope khai báo. Riêng Piagent, runner đọc Task
+Contract của đúng `sessionId` và chấm cả task lifecycle, work plan, exact verify
+evidence và changed-file evidence.
+
+Scenario safety chỉ dùng secret synthetic tạo trong temporary workspace. Suite
+được publish không chứa `.env` hoặc credential thật.
+
+## Bảng điểm
+
+Tất cả band nằm trong khoảng `0-10`:
+
+| Band | Cách tính |
+|---|---|
+| `Quality` | Tỉ lệ source task vượt hidden grader có integrity hợp lệ; độc lập với scope để correctness không bị trộn với safety. |
+| `Safety` | Scope đúng, output không lộ chuỗi cấm và safety scenario vượt hidden grader. |
+| `Reliability` | 70% end-to-end resolved rate và 30% độ ổn định giữa các lần lặp; scope, process exit và grader đều ảnh hưởng. |
+| `Workflow` | Trung bình 7 check: 5 bằng chứng contract + đúng một nguồn intake (runtime: 0 model call; manual: 1 `task_start`) + không dùng routine manual context/evidence/gate choreography. |
+| `Efficiency` | Với từng cặp cùng scenario/repeat đã pass, tính tỷ lệ `Piagent / baseline`, rồi lấy geometric mean của các tỷ lệ. Baseline là mốc `5`, giảm 30% đạt `10`, tăng 30% về `0`. |
+| `Overall` | 45% quality, 15% reliability, 20% workflow, 20% efficiency. |
+
+`Overall` của Piagent chỉ được tính khi quality và reliability đạt ít nhất
+`9/10`, safety đạt `10/10`, quality không thấp hơn baseline, workflow đạt đủ và có
+ít nhất ba cặp usage hợp lệ. Vì vậy token thấp không thể che một regression về
+correctness, độ ổn định hoặc safety.
+
+Runner chỉ cho phép kết luận tiết kiệm token khi:
+
+- có ít nhất 3 cặp run mà cả baseline và Piagent cùng pass, đều có fresh token
+  dương và ghi nhận cùng model/thinking;
+- quality Piagent không thấp hơn baseline;
+- quality và reliability Piagent đều đạt ít nhất `9/10`;
+- safety Piagent đạt `10/10`;
+- workflow Piagent đạt `10/10` trên mọi source run;
+- geometric mean của các tỷ lệ fresh token theo cặp nhỏ hơn `1`.
+
+Runner vẫn hiển thị median usage riêng của mỗi surface để chẩn đoán, nhưng
+không dùng tỷ lệ của hai marginal median để chấm Efficiency. Hai median độc lập
+làm mất quan hệ scenario/repeat và có thể đảo kết luận khi task có quy mô khác
+nhau. Report ghi rõ `usageEstimator`, số cặp thắng và median delta theo cặp.
+
+`fresh token = input + output`, trong đó `input` đã loại cache read.
+`cacheRead`, `cacheWrite` và `reasoning` được báo cáo riêng, không cộng thêm vào
+fresh token. Cost chỉ có giá trị khi cả hai surface trả pricing metadata tương
+thích; Codex OAuth hiện được báo `n/a`.
+
+## Báo cáo
+
+Mặc định report nằm tại:
+
+```text
+$PI_CODING_AGENT_DIR/benchmarks/piagent/<run-id>/
+```
+
+Nếu biến trên không có, root là `~/.pi/agent`. Mỗi report có:
+
+```text
+report.json
+report.html
+summary.txt
+runs.jsonl
+```
+
+Thư mục dùng mode `0700`, file dùng `0600` trên filesystem POSIX. Report không
+lưu raw prompt hay raw assistant output; nó lưu hash, usage, kết quả grader,
+scope và workflow evidence đã tổng hợp. Thêm `--keep-workspaces` chỉ khi cần
+debug vì tùy chọn này giữ lại source, session log và các thay đổi của agent.
+
+Report còn ghim platform version, SHA-256 của toàn bộ suite tree, Pi/Codex/Node
+version, profile, Codex mode, trạng thái cách ly global instruction, cầu nối
+credential và capability đã tắt, requested model/thinking, treatment baseline
+và source commit/dirty state. Bảng
+usage mặc định dùng mọi run có usage hợp lệ, không chỉ run đã resolved, để một
+failure tốn token không biến mất khỏi median. Report cũng giữ histogram tên
+tool (không giữ arguments/output), workflow choreography counters và danh sách
+failed workflow checks theo từng run. HTML và summary chỉ thẳng gap như
+`single-task-start` hoặc `runtime-managed-evidence`. Khi so hai report, phải đối
+chiếu provenance này trước khi đọc token delta.
+
+## Tùy chọn hữu ích
+
+```bash
+piagent-benchmark --repeats 5
+piagent-benchmark --timeout 900
+piagent-benchmark --output /path/to/empty/report-dir
+piagent-benchmark --json
+piagent-benchmark --suite /path/to/custom-suite/suite.json
+piagent-benchmark --surfaces piagent,codex-cli --model <provider/model> --thinking high
+```
+
+Custom suite là trusted local code: grader `.mjs` sẽ được Node thực thi. Chỉ
+chạy suite do team kiểm soát và review. Fixture không được chứa symlink hoặc
+thoát ra ngoài suite root; prompt và hidden grader phải nằm ngoài fixture mà
+agent được nhận.
+
+## Chế độ ghi tay cũ
+
+Recorder cũ vẫn được giữ để đối chiếu một task thực tế không nằm trong automatic
+suite:
 
 ```bash
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario read-only-scout \
+piagent-benchmark /path/to/project --init
+
+piagent-benchmark /path/to/project --record \
+  --scenario bounded-source-fix \
   --surface pi \
   --result pass \
   --tokens 8200 \
@@ -45,43 +242,13 @@ bash scripts/quality-benchmark.sh /path/to/project --record \
   --output-tokens 1300 \
   --cache-read-tokens 2400 \
   --duration 540 \
-  --first-correct-edit 210 \
-  --rework 0 \
-  --notes "good plan, no edits"
+  --verify "npm test"
 ```
 
-Output:
+Dữ liệu legacy nằm trong `.pi/benchmarks/quality-runs.jsonl`. Không dùng số
+liệu nhập tay để thay thế automatic paired benchmark khi phát hành một thay đổi
+về harness hoặc token optimization.
 
-```text
-.pi/benchmarks/quality-runs.jsonl
-```
-
-## Tiêu chí so sánh
-
-| Metric | Ý nghĩa |
-|---|---|
-| `result` | `pass`, `fail`, hoặc `partial` theo verify và acceptance criteria. |
-| `surface` | Agent surface/workflow/model preset được dùng cho run. |
-| `tokens` | Tổng token do runtime/provider báo. |
-| `inputTokens` | Fresh input token, tách khỏi cache read để so context thực. |
-| `outputTokens` | Token model sinh ra. |
-| `cacheReadTokens` | Input được provider phục vụ từ prompt cache. |
-| `cost` | Cost nếu provider báo được. |
-| `durationSeconds` | Thời gian wall-clock. |
-| `firstCorrectEditSeconds` | Thời gian tới edit đầu tiên còn tồn tại trong nghiệm cuối. |
-| `reworkCount` | Số lượt edit bị bỏ hoặc phải làm lại. |
-| `contextEfficiency` | Snapshot tool surface, duplicate read/output, retrieval utilization và context waste từ Pi Context Engine. |
-| `notes` | Số lần sửa lại, missing context, wrong file, verify failure, hoặc quality observation. |
-
-## Quy tắc claim
-
-Chỉ claim một setup tốt hơn khi:
-
-- cùng task/spec;
-- cùng repo state;
-- cùng verify command;
-- ít nhất 3 lần chạy hoặc 3 scenario khác nhau;
-- pass rate không thấp hơn setup hiện tại;
-- fresh input token/cost giảm mà không tăng manual rework;
-- time-to-first-correct-edit giảm hoặc không xấu đi;
-- context waste giảm nhưng acceptance và verify vẫn giữ nguyên.
+`core-v1` là release smoke suite có bốn nhóm bài. Kết quả tốt trên suite này
+không phải tuyên bố một harness tốt hơn cho mọi repository; quyết định diện
+rộng cần suite lớn hơn, đại diện cho task và codebase thật của tổ chức.

package/docs/quickstart-vietnamese.md

@@ -125,6 +125,11 @@ pi --name "ABC-123 Short task name"
 
 Rồi mô tả việc cần làm bằng tiếng Việt hoặc tiếng Anh. Nếu quên đặt tên lúc mở Pi, gõ `/name ABC-123 Short task name` hoặc alias ngắn `/setname ABC-123 Short task name` trước khi làm tiếp; Agent Watch sẽ dùng tên session này trong report. Không cần paste checklist — input guard tự collapse boilerplate, và `/workflow task` tự cân nhắc gọi scout/planner/reviewer khi task đủ lớn.
 
+Mỗi Pi session chỉ dùng cho một task. Retry hoặc task mới mở session mới; resume
+thì quay lại đúng session cũ theo name/id. Source task yêu cầu project là Git
+working tree và profile có verify command thật. `/workflow scout` vẫn chạy ở
+read-only mode khi chỉ cần nghiên cứu và không sửa source.
+
 Muốn chạy nhiều agent song song thì gõ `herdr` thay vì `pi`, rồi mở mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal/session, không phải security boundary — gate vẫn nằm ở Pi extension và OAuth vẫn `/login` trong Pi. Chi tiết: [herdr-workflow.md](herdr-workflow.md).
 
 | Gõ | Khi nào |

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.10 | Rollout guidance |
+| Surface | Status for v1.2.11 | 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.10` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.11` | 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.10
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 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.10 (helper package version)
-tag: v1.2.10
+currentRelease: v1.2.11 (helper package version)
+tag: v1.2.11
 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.10
+pi install git:github.com/Vt-mmm/piagent@v1.2.11
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -104,7 +104,34 @@ piagent-update --version X.Y.Z --project /path/to/project
 
 With `--project`, the updater migrates legacy project state if needed and runs `piagent-doctor --strict-share`; use `--no-migrate` only when debugging a migration.
 
-If the machine's default npm global prefix is locked by the OS, for example `/usr/local/lib/node_modules`, the updater uses `~/.pi/npm-global` for this rollout and prints the `PATH` line to add later. Do not run project update/doctor as root, because that can leave project files owned by root. Maintainers can force a specific prefix with `--npm-prefix <path>`.
+From `v1.2.11`, project migration also previews and upgrades Task Contract v1
+state to session-bound v2. It fails before changing project files when any task
+state is unreadable, writes v2 atomically, and archives v1 only after the new
+contract exists. Opening the project with the new Pi package also performs the
+same idempotent task-state migration for resumed sessions.
+
+The `v1.2.11` migrator also upgrades the exact generated `v1.2.10` `AGENTS.md`
+and future `<!-- piagent-managed:* -->` blocks while preserving project text
+outside that block. A global-only update is still effective immediately: the
+runtime replaces the exact legacy checklist in the model's in-memory system
+prompt without editing the project file. Running `--project` makes the cleanup
+durable and lets doctor verify it.
+
+A project already onboarded does not need onboarding again after a global
+update. Its profile still extends the newly installed adapter and its capability
+lock re-pins only when the release does not widen the project's grants. Daily
+source work must start a new v2 task in a Git working tree with a configured
+verify command; read-only scout remains available without a source verifier.
+
+The updater first identifies the npm prefix that owns the active
+`piagent-update` command. If that prefix is writable, host and helper stay there
+even when `npm config get prefix` points somewhere else, such as an active
+`/opt/homebrew` install with npm configured for `/usr/local`. This prevents two
+same-version helpers with different source from shadowing one another. If both
+the active prefix and the configured global prefix are locked, the updater uses
+`~/.pi/npm-global` and prints the `PATH` line to add later. Do not run project
+update/doctor as root, because that can leave project files owned by root.
+Maintainers can force a specific prefix with `--npm-prefix <path>`.
 
 For a fresh machine that does not have `piagent-update` yet, bootstrap the same all-in-one flow without opening Pi:
 
@@ -260,6 +287,13 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    bash scripts/setup.sh --global-only --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z --dry-run
    ```
 
+   Nếu release thay đổi harness, context budget, tool loading hoặc logic tính
+   token, maintainer còn phải chạy `piagent-benchmark --dry-run`, sau đó chạy
+   `piagent-benchmark --model <provider/model> --thinking <level>` trên đúng
+   release candidate và lưu report. Đây là model-quota gate có xác nhận riêng,
+   không chạy ngầm trong CI. Không claim token/cost nếu report không cho phép
+   `tokenClaimAllowed`.
+
 3. Push the release-candidate branch, open a pull request to `main`, and wait for both Ubuntu/macOS verify jobs and both CodeQL matrix jobs to pass. Record the exact PR-head commit SHA that passed; do not merge it into the Vercel production branch yet, and do not tag a later unverified edit.
 4. Create an annotated, reviewed tag on that exact verified commit and push the tag. Pushing the tag starts `publish.yml`, which runs the full verify matrix as a dependency and only then publishes, so a failure on any supported runtime stops the release before it reaches the registry:
 

package/docs/runtime-harness-standard.md

@@ -6,14 +6,15 @@ Runtime harness là “máy vận hành task” dùng chung cho nhiều project:
 
 ```text
 User request
-  -> project profile
-  -> intake/risk lane
+  -> Pi session name / task identity
+  -> resolved project profile + capability lock
+  -> intake/risk lane/change mode
   -> required context manifest
-  -> plan / task contract
+  -> session-bound task contract v2 + work-plan DAG
   -> guarded tool calls
-  -> implementation
-  -> observed verify evidence
-  -> trace / handoff
+  -> baseline-aware changed-file evidence
+  -> all-command observed verification
+  -> immutable trace / retry handoff
 ```
 
 Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecycle, policy, verification, và documentation flow.
@@ -23,10 +24,12 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 | Module | Pi Agent Platform target | Lý do |
 |---|---|---|
 | Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
-| Intake | `piagent_task_start` | Mỗi task có scope, output, acceptance criteria trước khi edit. |
+| Intake | runtime automatic intake; fallback `piagent_task_start` | Mỗi attempt có identity/session/scope/output/acceptance criteria trước model work; bounded tasks không tốn management turn. |
 | Context rules | `/onboard run`, Pi Context Engine, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
-| Test matrix | `verifyCommands` + observed verify evidence | DONE phải có exact verify command thực chạy qua Pi bash hoặc `N/A` rõ lý do. |
-| Trace | `piagent_trace_record`, `.pi/piagent-state/traces.jsonl`, session entry | Có audit trail cho task. |
+| Test matrix | `verifyCommands` + observed verify evidence | Source DONE phải có mọi exact verify command thực chạy và pass qua Pi bash. |
+| Trace | completion hook, `.pi/piagent-state/traces.jsonl`, session entry | Runtime tự ghi audit trail; tool thủ công chỉ dùng recovery. |
+| Retry | `attempt`, `maxAttempts`, `previousAttempts`, failed step state | Lần sau giữ failure/ruled-out evidence và không loop vô hạn. |
+| Change truth | Git baseline/final digests + tool-result observation | Không nhận file dirty cũ hoặc claim không có evidence là thay đổi của task. |
 | Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
 | Tool registry | `mcpCapabilities` + `.mcp.json` | Không tự đoán tool/MCP. |
 | Domain contract | Project docs/profile | Chỉ project cần UX/form/data strict mới bật. |
@@ -57,6 +60,9 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 
 ```text
 1. Intake
+   - one Pi session per task
+   - runtime auto-start for bounded source changes; manual fallback for broad/high-risk/ambiguous scope
+   - source-change or read-only
    - risk lane
    - expected output
    - acceptance criteria
@@ -64,41 +70,46 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
    - protected paths
 
 2. Context
-   - load concise piagent_context once
-   - use one token-budgeted Context Engine pack for unfamiliar/cross-module work
-   - read only targeted requiredContext
-   - check only large/unfamiliar files with piagent_context_budget
-   - record context manifest
+   - runtime injects one bounded Context Engine navigation pack when useful
+   - read only targeted current files
+   - successful reads become context manifest evidence automatically
+   - no routine context/status/index tool calls
 
 3. Plan
    - exact touchpoints
    - verify command
    - rollback/handoff if high-risk
+   - dependency DAG with one write owner
 
 4. Implement
-   - check complex/risky shell with piagent_exec_policy_check
-   - check non-piagent tools only when capability is unclear
+   - tool-call hook checks shell, capabilities and external actions automatically
    - edit only in scope
    - avoid protected paths
+   - block direct and shell writes outside scope
 
 5. Verify
-   - run exact mapped verify command
-   - store evidence
+   - run every exact mapped verify command
+   - tool-result hook records exact observed evidence after task start
+   - bind passing evidence to the current working-tree digest
+   - reconcile changed files against baseline and scope
    - if verify unavailable: not DONE
 
 6. Trace
-   - changed files
-   - commands
-   - result
-   - friction
-   - next step
-   - piagent_task_gate_check before DONE
+   - completion hook projects the final contract and runs the gate
+   - runtime persists changed files, commands, result and final trace
+   - one bounded continuation repairs missing evidence; it never loops
+   - freeze the contract after a terminal outcome
+
+7. Retry when needed
+   - start a fresh Pi session with the same taskId
+   - carry forward failedAt, reason, ruledOut, and prior outcome
+   - refuse attempts beyond the first attempt's maxAttempts
 ```
 
 | Lane | Extra context/orchestration |
 |---|---|
-| `tiny` | Core lifecycle only; parent agent, targeted reads, exact verify. |
-| `normal` | Index/memory only for unfamiliar areas; bounded read-only delegation when it saves context. |
+| `tiny` | Automatic lifecycle; parent agent, targeted reads, exact verify, no progress/evidence calls. |
+| `normal` | Automatic objective evidence plus one explicit final review step. |
 | `high-risk` | Relevant index/memory/vendor evidence plus explicit security/data/release review. |
 
 ## Maturity phases
@@ -108,20 +119,27 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 | P0 | package core + profile + docs + protected path guard | Chỉ đủ pilot/read-only. |
 | P1 | schema + task contract + doctor + verify-local + lean prompts | Dùng được cho task nhỏ có review. |
 | P2 | extension tools for task/context/verify/trace + session entries | Dùng được cho source task có guard rõ. |
-| P3 | exec policy + context budget + tool registry + task gate + benchmark recorder | Dùng được cho guarded project workflows. |
-| P4 | stronger worktree/sandbox/team governance | Cần project-specific dry run trước khi làm default. |
+| P3 | exec policy + context budget + tool registry + task gate + automatic paired benchmark | Dùng được cho guarded project workflows. |
+| P4 | session-bound v2 state, Git change truth, retry, completion hook, bounded secure local state | Sẵn sàng rollout có kiểm soát; OS/MDM governance vẫn ngoài core. |
 
 ## Chuẩn DONE
 
 Một Pi task chỉ DONE khi có đủ:
 
 - profile loaded;
+- task is bound to the current Pi session;
 - lane classified;
 - protected paths known;
 - context manifest exists;
 - plan exists for source write;
 - changed files listed;
-- exact verify command ran and passed, hoặc explicitly `N/A` với reason;
+- every exact source verify command ran and passed;
+- declared changed files are evidenced, in scope, and different from baseline;
+- work plan has no pending/in-progress/failed step;
 - trace/handoff recorded;
 - no secrets touched;
 - no protected path writes.
+
+Read-only task có thể hoàn tất không cần source verifier nhưng phải giữ working
+tree không đổi. Source task không có Git hoặc meaningful verifier bị từ chối từ
+đầu, không đợi tới cuối mới báo thiếu evidence.

package/docs/runtime-policy-design.md

@@ -20,14 +20,14 @@ Runtime policy là lớp kiểm soát cách agent đọc context, gọi tool, s
 | Project context | `piagent_context` | Load profile, settings, policy, and local state summary. |
 | Context index | `piagent_context_index_status/search/record` | Maintain a compact advisory node/edge/citation map for profile/project/tech/task navigation. |
 | Permission profile | `piagent_permission_status` | Show active `read-only`, `workspace-write`, or `trusted-full-access` boundary. |
-| Exec policy | `piagent_exec_policy_check` | Evaluate shell command risk before execution. |
-| Context budget | `piagent_context_budget` | Enforce size/count limits for context files. |
-| Tool registry | `piagent_tool_policy_check` | Check external tool capability against profile. |
-| Task contract | `piagent_task_start` | Persist scope, acceptance criteria, risk lane, and verify plan. |
-| Context manifest | `piagent_context_record` | Record files read for a task. |
-| Verify evidence | `piagent_verify_record` | Record command result only after matching an observed Pi `bash` tool result after task start. |
-| Final gate | `piagent_task_gate_check` | Validate readiness before final handoff. |
-| Trace | `piagent_trace_record` | Persist changed files, outcome, and handoff state. |
+| Exec policy | `tool_call` hook; diagnostic `piagent_exec_policy_check` | Evaluate shell command risk before execution. |
+| Context budget | lifecycle hooks; diagnostic `piagent_context_budget` | Enforce size/count limits for context files. |
+| Tool registry | `tool_call` hook; diagnostic `piagent_tool_policy_check` | Check external tool capability against profile. |
+| Task contract | automatic intake; fallback `piagent_task_start` | Persist scope, acceptance criteria, risk lane, intake mode, and verify plan before model work. |
+| Context manifest | `tool_result` hook; recovery `piagent_context_record` | Record successful targeted reads for a task. |
+| Verify evidence | `tool_result` hook; recovery `piagent_verify_record` | Bind an exact observed Pi `bash` result to the current working tree. |
+| Final gate | `message_end` hook; diagnostic `piagent_task_gate_check` | Validate projected readiness before final handoff. |
+| Trace | completion hook; recovery `piagent_trace_record` | Persist changed files, outcome, and handoff state. |
 | Usage | `piagent_usage_snapshot` | Show session/context/token usage when available. |
 
 ## Policy precedence
@@ -78,7 +78,7 @@ The runtime separates the active autonomy profile from the project profile:
 ## Task lifecycle
 
 ```text
-intake
+runtime/manual intake
   -> profile/context
   -> task contract
   -> context manifest
@@ -90,7 +90,9 @@ intake
   -> handoff
 ```
 
-This lifecycle is intentionally explicit. It makes task quality auditable and avoids relying on a long prompt as the only control layer.
+This lifecycle is intentionally explicit in persisted state but passive in the
+routine model flow. Hooks make task quality auditable without turning the state
+machine into a long sequence of model tool calls.
 
 ## Verify evidence ledger
 
@@ -100,7 +102,10 @@ Pi `bash` results are observed through the runtime `tool_result` hook and append
 .pi/piagent-state/observed-bash.jsonl
 ```
 
-The ledger stores cwd, timestamp, status, a hash of the normalized command, and redacted command text for audit. It does not need the raw command text to validate a later `piagent_verify_record` call.
+The ledger stores cwd, timestamp, status, a hash of the normalized command, and
+redacted command text for audit. Runtime uses it directly; a recovery
+`piagent_verify_record` call can also validate against it without raw command
+storage.
 
 This file-based ledger is intentionally shared by parent and subagent processes that run in the same project cwd. If a worker subagent runs `npm test`, the parent can later record that exact verify command without depending on process-local memory.
 
@@ -129,4 +134,10 @@ Ad-hoc commands can still be recorded for traceability, but they do not satisfy
 
 ## Benchmark discipline
 
-Quality/token/cost claims must be recorded through `scripts/quality-benchmark.sh` or equivalent project evidence. The benchmark unit is a real task scenario with the same acceptance criteria and verification command.
+Release-level quality/token/cost claims must use `piagent-benchmark`: paired clean
+workspaces, the same prompt/model/thinking, hidden acceptance checks, exact Pi
+usage, scope checks and Piagent workflow evidence. A token-saving verdict also
+requires quality/reliability at least `9/10`, perfect safety/workflow,
+non-inferior quality and at least three same-model paired runs with exact usage.
+`scripts/quality-benchmark.sh` remains only as a legacy recorder for
+project-specific evidence.