@piagent/platform 1.2.11 → 1.2.13

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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 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.11`. 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.13`. 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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 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.11 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.13 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -602,14 +602,29 @@ Không claim tiết kiệm token/cost nếu chưa có số liệu cùng scenario
 ```bash
 piagent-benchmark --dry-run
 piagent-benchmark
+piagent-benchmark --production --dry-run
 ```
 
 Lệnh mặc định tự chạy 4 scenario trên Raw Pi và Piagent, mỗi bên 3 lần; token,
 cost, model và thinking được đọc từ Pi session thay vì nhập tay. Runner chỉ cho
-phép kết luận tiết kiệm token khi quality/reliability đạt ít nhất `9/10`,
-safety/workflow đạt `10/10`, quality không giảm, có ít nhất ba cặp cùng model
-với exact usage và geometric mean của tỷ lệ fresh token `Piagent / Raw Pi`
-theo từng cặp thực sự nhỏ hơn `1`.
+phép kết luận tiết kiệm token khi quality/reliability đạt ít nhất `9/10`, safety
+đạt `10/10`, workflow đạt ngưỡng của suite (`10/10` cho smoke, ít nhất `9/10`
+cho production), quality không giảm, có ít nhất ba cặp cùng model với exact
+usage và geometric mean của tỷ lệ fresh token `Piagent / Raw Pi` theo từng cặp
+thực sự nhỏ hơn `1`.
+
+Lệnh không flag là smoke suite 24 session. Khi chốt thay đổi lớn về harness,
+model hoặc token policy, dùng `--production`: 18 scenario family, ba generated
+variant, hai surface, tổng 108 session; production gate chấm riêng sáu domain,
+profile/lifecycle/difficulty và cận trên 95% của paired token ratio. Seed/oracle
+động không đi vào agent workspace; root seed chỉ nằm trong private report để
+tái lập bằng `--seed`.
+
+Production runner mặc định retry tối đa hai lần, cách nhau 60 giây, chỉ khi process chết trước
+khi ghi usage. Timeout hoặc task đã tiêu token rồi fail vẫn là reliability failure thật,
+không được retry. Report hiện số retry và giữ chi tiết local trong
+`infrastructure-attempts.jsonl`. Dùng `--scenarios <id,id> --repeats 1` để debug
+rubric; subset không thể vượt production release gate.
 
 So sánh trực tiếp với surface `codex-cli` đã đăng nhập:
 
@@ -621,7 +636,7 @@ piagent-benchmark \
 ```
 
 Chế độ mặc định là `controlled`: Codex chạy ephemeral, chỉ được ghi trong
-workspace benchmark, dùng `CODEX_HOME` tạm để loại global `AGENTS.md`,
+workspace benchmark, dùng `CODEX_HOME` tạm mới cho từng session/retry để loại global `AGENTS.md`,
 config/rules/hooks/plugins/session cá nhân và tắt capability tùy chọn có thể
 làm lệch task offline. Credential hiện có chỉ được nối bằng symlink `auth.json`,
 không bị runner đọc hay sao chép. `--codex-mode native` đo cấu hình Codex thật
@@ -956,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.11` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.11` | Install pinned release cho reproducible team setup. |
+| `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. |
 | `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. |
@@ -990,8 +1005,9 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 | `piagent-subagents --preset safe` | Setup subagents baseline. |
 | `bash scripts/verify-local.sh` | Verify platform repo. |
 | `bash scripts/team-doctor.sh /path/to/project --strict-share` | Doctor project/team setup khi chạy từ source checkout. |
-| `piagent-benchmark` | Tự chạy, chấm và xuất paired benchmark report. |
+| `piagent-benchmark` | Chạy và chấm paired smoke benchmark 24 session. |
 | `piagent-benchmark --dry-run` | Xem execution plan, không dùng model quota. |
+| `piagent-benchmark --production --dry-run` | Xem production plan 108 session, không dùng model quota. |
 | `piagent-benchmark --surfaces piagent,codex-cli --model <provider/model> --thinking high` | So sánh Piagent với surface `codex-cli` ở controlled mode. |
 | `piagent-benchmark /path/to/project --record ...` | Legacy: ghi tay một scenario project-specific. |
 
@@ -1067,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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 command -v piagent-install
 ```
 

package/docs/quality-benchmark.md

@@ -41,6 +41,25 @@ không gọi model:
 piagent-benchmark --dry-run
 ```
 
+Đây là smoke suite để phát hiện regression nhanh, không phải production claim.
+Release cần bằng chứng diện rộng dùng track riêng:
+
+```bash
+piagent-benchmark --production --dry-run \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh
+
+piagent-benchmark --production \
+  --surfaces piagent,codex-cli \
+  --model openai-codex/gpt-5.6-sol \
+  --thinking xhigh
+```
+
+`production-v1` có 18 scenario family, 3 generated variant cho mỗi family và 2
+surface, tổng cộng 108 model session. Bộ này cố ý tốn quota hơn: dùng để chốt
+release/harness hoặc model policy, không chạy sau mỗi thay đổi nhỏ.
+
 Để 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:
 
@@ -69,7 +88,8 @@ Mặc định `--codex-mode controlled` chạy `codex exec` theo các ranh giớ
 
 - 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
+- tạo `CODEX_HOME` tạm mode `0700` mới cho từng model session/retry, 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;
@@ -113,13 +133,20 @@ Trong CI hoặc terminal không tương tác, phải thêm `--yes`. Đây là x
 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.
+Lỗi giải task, kể cả timeout, được ghi vào reliability và suite tiếp tục; runner
+không retry timeout hoặc process đã ghi usage vì làm vậy sẽ chọn lọc kết quả đẹp.
+Riêng process chết trước khi có bất kỳ provider usage nào được xem là lỗi hạ
+tầng. Schema-v2/production mặc định retry tối đa hai lần trên workspace sạch với
+cùng variant seed và backoff 60 giây; `--infrastructure-retries 0..3` cùng
+`--retry-delay 0..120` cho phép override. Lần hỏng
+được ghi riêng trong `infrastructure-attempts.jsonl`, còn report chỉ chấm lần
+đo hợp lệ cuối và công khai số retry.
+
+Lỗi deterministic như không init được profile, không tạo được Git baseline,
+grader không chạy được, hoặc process tiếp tục chết hết retry budget sẽ dừng
+suite để không đốt các model session còn lại. Runner giữ `runs.jsonl` cùng
+`aborted.json` để chẩn đoán. Hidden-grader failure sau model run luôn là kết quả
+task thật và suite tiếp tục.
 
 ## Suite mặc định đo gì
 
@@ -138,23 +165,158 @@ 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.
 
+## Production suite đo gì
+
+`production-v1` phủ sáu domain, mỗi domain ba family:
+
+| Domain | Năng lực được đo |
+|---|---|
+| `backend` | tenant authorization, integer-money rounding, cache isolation |
+| `frontend` | stale async response, Unicode search, pagination boundary |
+| `data` | quoted CSV, stable deduplication, backward-compatible migration |
+| `platform` | falsey config precedence, CLI `--` parsing, workspace dependency order |
+| `reliability` | bounded retry, expiry boundary, read-only incident diagnosis |
+| `security` | protected secret refusal, repository prompt injection, destructive audit-history refusal |
+
+Ma trận có đủ `small`, `medium`, `large`; profile `backend-api`,
+`web-frontend`, `fullstack`, `node-typescript`, `docs`; và cả `steady-state`
+lẫn `cold-start`. Cold-start vẫn init đúng Piagent release/profile nhưng không
+ghi sẵn onboarding/context snapshot. Steady-state chuẩn bị onboarding và Context
+Engine trước vùng model usage được đo.
+
+Trong cold-start, thay đổi ở đúng runtime-owned `.pi/project-context.md`,
+`.pi/context-index.json` và Context Engine database được tách
+thành `scope.runtimeManagedChanges`, không giả thành source edit của task. Mọi
+path khác vẫn đi qua scope gate; safety scenario bảo vệ audit state chạy ở
+steady-state nên không được hưởng ngoại lệ này.
+
+Mỗi scenario dùng generator tin cậy nằm ngoài agent workspace. Runner dẫn xuất
+cùng variant seed cho hai surface của một scenario/repeat, lưu oracle mode
+`0600` ngoài workspace, rồi chỉ đưa fixture đã biến đổi cho agent. Hidden grader
+đọc oracle sau khi model kết thúc. Report chỉ giữ seed/oracle digest, số marker
+đã thấy và hash marker thiếu; không lưu secret hoặc required-output marker thô.
+
+Mặc định seed mới được tạo cho mỗi benchmark. Tái lập chính xác một run bằng:
+
+```bash
+piagent-benchmark --production --seed <seed-from-private-report> ...
+```
+
+Root seed nằm trong `report.json` riêng tư để điều tra/reproduce. Không đăng
+report production công khai khi chưa loại trường này, vì suite công khai có thể
+dùng seed để tái tạo synthetic secret.
+
+## Kết quả production chuẩn của v1.2.12
+
+Snapshot dưới đây là release evidence đầu tiên của `production-v1`. Candidate
+được chạy từ 22:33 ngày 02/08/2026 đến 00:22 ngày 03/08/2026 theo múi giờ
+Asia/Ho_Chi_Minh, sau đó cùng logic được đóng gói thành `v1.2.12`.
+
+| Thuộc tính | Giá trị |
+|---|---|
+| Run | `production-v1-20260802T153320Z-11f3d0` |
+| Model | `openai-codex/gpt-5.6-sol` cho Piagent, `gpt-5.6-sol` cho `codex-cli` |
+| Thinking | `xhigh` cho cả hai surface |
+| Ma trận | 18 scenario family x 3 repeat x 2 surface = 108 session |
+| Baseline | `codex-cli` controlled mode, home tạm riêng mỗi session |
+| Runtime | Pi `0.82.0`, `codex-cli 0.146.0-alpha.9.2`, Node `24.11.1` |
+| Suite digest | `90a44ac4f5d4ec11772eac00f4f984d78c6962d116581ca29ab6b8760c8f9171` |
+| Hạ tầng | 108 attempt, 0 retry |
+
+### Điểm và kết quả task
+
+| Surface | Resolved | Hidden task grade | Scope | Quality | Safety | Reliability | Workflow | Efficiency | Overall |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| `codex-cli` | 54/54 | 48/48 | 54/54 | 10.00 | 10.00 | 10.00 | n/a | 5.00 baseline | n/a |
+| Piagent | **54/54** | **48/48** | **54/54** | **10.00** | **10.00** | **10.00** | **9.58** | **10.00** | **9.92** |
+
+Piagent đạt `10.00` ở cả sáu category: `backend`, `frontend`, `data`,
+`platform`, `reliability` và `security`. Quality, safety, reliability,
+workflow, category, repeat-count, efficiency-evidence và confidence gate đều
+pass.
+
+Workflow chưa tròn 10 vì mỗi check `session-bound-task`,
+`terminal-completion`, `completed-work-plan` và `single-task-start` hụt ở ba
+run. Các run này vẫn giải đúng task, đúng scope và qua safety gate; report giữ
+gap để Overall không che mất chất lượng vận hành.
+
+### Token và tool usage
+
+Median trên toàn bộ 54 run của mỗi surface:
+
+| Usage | Piagent | `codex-cli` |
+|---|---:|---:|
+| Input đã loại cache | 6,801 | 13,885 |
+| Output | 913 | 2,299 |
+| Cache read | 7,680 | 78,208 |
+| Reasoning, là breakdown của output | 414 | 592 |
+| Fresh token | **7,368** | **18,476** |
+| Tool calls | **5** | **8** |
+| Cost mỗi run | `$0.059141` | `n/a` từ Codex OAuth JSONL |
+
+Biểu đồ median fresh token, lấy `codex-cli` làm thanh 100%:
+
+```text
+Piagent      7,368 | ########             | 39.88% median baseline
+codex-cli   18,476 | #################### | 100.00%
+```
+
+Biểu đồ này chỉ giúp nhìn quy mô median. Efficiency chính thức không chia hai
+median độc lập; runner dùng matched pair theo đúng scenario/repeat:
+
+```text
+Fresh-token pair wins
+Piagent    47 | #################  | 87.04%
+codex-cli   7 | ###                | 12.96%
+Ties         0
+```
+
+- 54/54 cặp có usage và model/thinking tương thích.
+- Piagent thắng 47 cặp, `codex-cli` thắng 7 cặp, không có cặp hòa.
+- Median paired delta là `-7,870` fresh token.
+- Paired geometric mean ratio là `0.4889`, tương ứng giảm `51.11%`.
+- 95% confidence interval của ratio là `0.3809..0.6276`, với 18 scenario
+  family là 18 đơn vị mẫu độc lập.
+- Tổng fresh token của 54 Piagent run là `529,932`; `codex-cli` là `1,006,150`.
+- Tổng chi phí Piagent ghi nhận là `$5.321041`; Codex JSONL không cung cấp cost
+  nên report không suy diễn bảng giá.
+
+Cận trên confidence interval vẫn thấp hơn baseline `1.0`, vì vậy verdict là
+`piagent-more-efficient` và `token-saving claim allowed: yes`.
+
+### Provenance và giới hạn
+
+Full model run diễn ra trước commit bump metadata, nên environment gốc ghi
+platform `v1.2.11`, source working tree dirty. Candidate được test chính là logic
+sau đó phát hành trong `v1.2.12`; 1,253 deterministic test, typecheck, verify,
+audit và CI Linux/macOS được chạy lại sau khi đóng gói. Không chạy lại 108 model
+session chỉ để đổi version metadata.
+
+Raw report không được commit vì giữ root seed có thể tái tạo synthetic secret.
+Snapshot này cố ý chỉ công khai summary, suite digest và provenance không nhạy
+cảm. Đây là benchmark synthetic do maintainer xây dựng, không phải external
+benchmark chứng minh Piagent tốt hơn trên mọi repository/model. Claim triển khai
+toàn công ty vẫn cần đối chiếu held-out suite riêng và task thực tế. Bản trực
+quan của snapshot nằm tại [piagent.io.vn/benchmark](https://piagent.io.vn/benchmark).
+
 ## 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. |
+| `Quality` | Tỉ lệ source/read-only task vượt hidden grader, required-output evidence và grader integrity; độ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. |
+| `Reliability` | 70% end-to-end resolved rate và 30% tỉ lệ scenario family pass toàn bộ variant. Fail lặp lại không được tính là "ổn định"; scope, output evidence, process exit và grader đều ảnh hưởng. |
+| `Workflow` | Source task chấm 7 check contract/choreography; read-only task dùng contract tương ứng và yêu cầu khai báo đúng không có file thay đổi. |
 | `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.
+`9/10`, safety đạt `10/10`, quality không thấp hơn baseline, workflow đạt ngưỡng
+do suite khai báo và có ít nhất ba cặp usage hợp lệ. Smoke suite giữ workflow ở
+`10/10`; production suite dùng `9/10` và vẫn liệt kê từng check bị hụt. 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:
 
@@ -163,7 +325,8 @@ Runner chỉ cho phép kết luận tiết kiệm token khi:
 - 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;
+- workflow Piagent đạt ngưỡng của suite (`10/10` cho smoke, ít nhất `9/10` cho
+  production); report vẫn phải công khai mọi workflow check bị hụt;
 - 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
@@ -191,6 +354,7 @@ report.json
 report.html
 summary.txt
 runs.jsonl
+infrastructure-attempts.jsonl  # chỉ có khi từng xảy ra retry
 ```
 
 Thư mục dùng mode `0700`, file dùng `0600` trên filesystem POSIX. Report không
@@ -209,6 +373,29 @@ 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.
 
+Production report còn có band theo category, profile, lifecycle và difficulty;
+Wilson 95% interval cho resolved/quality rate; và 95% interval cho fresh-token
+ratio. Token interval lấy mỗi scenario family làm một mẫu độc lập: trước tiên
+lấy geometric mean qua repeat của family, sau đó tính interval trên log-ratio
+giữa các family. Vì vậy ba repeat của cùng một bài không bị giả thành ba loại
+task độc lập.
+
+`production-v1` chỉ pass release gate khi quality/reliability/workflow và mọi
+category đạt ít nhất `9`, safety đạt `10`, đủ cả 18 paired family, quality không
+thấp hơn baseline, và cận trên 95% của fresh-token ratio không vượt `1.0`.
+Point estimate tiết kiệm nhưng confidence interval còn chạm/vượt baseline sẽ
+không được phép claim tiết kiệm token.
+
+`--repeats 1` có thể dùng làm pilot 36 session, nhưng production release gate
+ghi `repeat-count` failure cho tới khi chạy đủ tối thiểu ba repeat. Override
+không thể hạ chuẩn rồi vẫn nhận production verdict.
+
+Một family chỉ được tính là complete efficiency evidence khi cả ba repeat đều
+resolved ở cả hai surface và có usage/model/thinking tương thích. Nếu một repeat
+fail, các cặp còn lại vẫn hiện để chẩn đoán nhưng family đó bị loại khỏi
+confidence gate; không có survivorship shortcut bằng cách chỉ tính lần chạy
+thành công.
+
 ## Tùy chọn hữu ích
 
 ```bash
@@ -217,14 +404,29 @@ 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 --production --seed <reproducible-seed>
+piagent-benchmark --production --scenarios invoice-rounding,workspace-order --repeats 1
+piagent-benchmark --production --infrastructure-retries 2
+piagent-benchmark --production --infrastructure-retries 2 --retry-delay 60
 piagent-benchmark --surfaces piagent,codex-cli --model <provider/model> --thinking high
 ```
 
+`--scenarios` chỉ dùng để chẩn đoán một family/rubric; report vẫn giữ release
+threshold gốc nên subset không thể nhận production verdict. Pilot toàn ma trận
+dùng `--repeats 1`, còn release gate chính thức vẫn bắt đủ ba repeat.
+
 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.
 
+Built-in production suite công khai nên chống hard-code bằng generated oracle,
+nhưng không thể tự chứng minh không có benchmark contamination. Claim nội bộ
+mạnh nhất nên chạy thêm một schema-v2 suite private do công ty giữ ngoài repo,
+đổi task theo chu kỳ và truyền bằng `--suite /private/path/suite.json`. Báo cáo
+phải ghi rõ `suite.assurance.visibility`; không gộp kết quả public và private
+thành một điểm nếu provenance khác nhau.
+
 ## 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
@@ -249,6 +451,8 @@ Dữ liệu legacy nằm trong `.pi/benchmarks/quality-runs.jsonl`. Không dùng
 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.
 
-`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.
+`core-v1` là smoke suite có bốn nhóm bài. `production-v1` là release benchmark
+diện rộng và nghiêm ngặt hơn, nhưng vẫn là synthetic/public methodology chứ
+không phải chứng minh Piagent tốt hơn trên mọi repository. Quyết định triển khai
+toàn công ty cần đối chiếu thêm private held-out suite và task/report thực tế của
+tổ chức.

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.11 | Rollout guidance |
+| Surface | Status for v1.2.13 | 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.11` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.13` | 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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 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.11 (helper package version)
-tag: v1.2.11
+currentRelease: v1.2.13 (helper package version)
+tag: v1.2.13
 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.11
+pi install git:github.com/Vt-mmm/piagent@v1.2.13
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -288,11 +288,15 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    ```
 
    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`.
+   token, maintainer trước tiên chạy smoke suite bằng `piagent-benchmark`, sau
+   đó chạy production suite với `--production --surfaces piagent,codex-cli --model <provider/model> --thinking <level>` trên đúng release candidate và lưu
+   report. Production gate dùng 108 model session, generated held-out variant,
+   category bands và 95% token-ratio confidence nên 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` hoặc `productionGate.passed` khác `true`.
+   Zero-usage process failure có thể retry tối đa hai lần với backoff và phải xuất hiện trong
+   infrastructure ledger; timeout hay task failure không được retry để né điểm
+   reliability.
 
 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-policy-design.md

@@ -137,7 +137,8 @@ Ad-hoc commands can still be recorded for traceability, but they do not satisfy
 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,
+requires quality/reliability at least `9/10`, perfect safety, the suite's
+workflow threshold (`10/10` for smoke and at least `9/10` for production),
 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.

package/docs/runtime-quality-baseline.md

@@ -204,6 +204,7 @@ Automatic paired benchmark:
 ```bash
 piagent-benchmark --dry-run
 piagent-benchmark
+piagent-benchmark --production --dry-run
 ```
 
 Output:
@@ -225,12 +226,22 @@ chỉ lưu histogram tên tool. Chỉ claim chất lượng/token/cost khi các
 - cùng acceptance criteria;
 - verify command rõ;
 - token/cost/duration được runtime ghi lại;
-- quality/reliability đạt ít nhất `9/10`, safety/workflow đạt `10/10`, quality
-  không giảm và ít nhất ba cặp cùng model có exact usage.
+- quality/reliability đạt ít nhất `9/10`, safety đạt `10/10`, workflow đạt ngưỡng
+  của suite (`10/10` cho smoke, ít nhất `9/10` cho production), quality không
+  giảm và ít nhất ba cặp cùng model có exact usage.
 
 `piagent-benchmark <project> --record ...` vẫn route tới recorder cũ cho task
 project-specific, nhưng không thay thế automatic release benchmark.
 
+`core-v1` là smoke gate 24 session. Release/model claim diện rộng dùng
+`production-v1`: 18 scenario family x 3 generated variant x 2 surface = 108
+session, phủ sáu domain, nhiều profile và cold/steady lifecycle. Production gate
+chấm thêm từng category và cận trên 95% của paired token ratio; repeat được
+cluster theo scenario family nên không bị tính như bằng chứng độc lập. Runner
+chỉ retry lỗi process trước khi có usage, ghi retry vào ledger riêng; timeout và
+task failure vẫn được chấm reliability. Chi tiết và quy trình private held-out
+suite nằm trong `docs/quality-benchmark.md`.
+
 ## Runtime policy trong profile
 
 Project có thể override:

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.11, 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.13, 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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 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.11
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs-site/architecture.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.11 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.13 docs</span>
         <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" />
@@ -74,6 +74,7 @@
             <a class="nav-link" href="/security">Security model</a>
             <a class="nav-link current" href="/architecture" aria-current="page">Architecture</a>
             <a class="nav-link" href="/context-engine">Context Engine</a>
+            <a class="nav-link" href="/benchmark">Benchmark</a>
             <a class="nav-link" href="/runtime">Runtime tools</a>
             <a class="nav-link" href="/team">Team usage</a>
           </div>