@piagent/platform 1.2.9 → 1.2.11

package/docs/task-implementation-contract.md

@@ -1,200 +1,136 @@
-# Task Implementation Contract
-
-## Mục tiêu
-
-Đây là contract tối thiểu để Pi implement task không khác gì một CLI agent nghiêm túc: có scope, context, guard, verify, trace.
-
-## Contract fields
-
-| Field | Required | Ý nghĩa |
-|---|---:|---|
-| `taskId` | yes | ID ổn định cho task. |
-| `summary` | yes | Một câu mô tả outcome. |
-| `riskLane` | yes | `tiny`, `normal`, hoặc `high-risk`. |
-| `expectedOutput` | yes | Artifact/behavior cụ thể. |
-| `acceptanceCriteria` | yes | Điều kiện pass/fail. |
-| `scope` | yes | File/module được phép đụng. |
-| `outOfScope` | yes | Cái không làm. |
-| `protectedPaths` | yes | Vùng cấm từ profile/policy. |
-| `requiredContext` | yes | Context bắt buộc đọc. |
-| `contextManifest` | yes | Bằng chứng context đã dùng. |
-| `memoryCitations` | no | Memory file dùng làm advisory context, nếu có. |
-| `mcpCapabilities` | no | Tool/MCP được phép. |
-| `verifyCommands` | yes | Command phải chạy trước DONE. |
-| `workPlan` | no | Task tree compact: step, role, mode, trạng thái, dependency. |
-| `reviewLenses` | no | Góc review rõ ràng, mặc định `correctness`, `tests`, `scope`. |
-| `orchestration` | no | Snapshot solo-first policy khi task bắt đầu: mode, subagent stance, Field Guide, model-role guidance. |
-| `verifyEvidence` | yes before done | Observed command result. Passing gate requires exact match with `verifyCommands`. |
-| `changedFiles` | yes before done | File đã sửa. |
-| `trace` | yes before done | Handoff/audit record. |
-
-## JSON example
-
-```json
-{
-  "taskId": "TASK-0001",
-  "summary": "Fix listing filter reset behavior",
-  "riskLane": "normal",
-  "expectedOutput": "Filter reset returns listing page to default query and preserves route owner.",
-  "acceptanceCriteria": [
-    "Reset button clears selected filters",
-    "URL query returns to canonical default",
-    "No protected paths are modified"
-  ],
-  "scope": [
-    "src/features/listings/**"
-  ],
-  "outOfScope": [
-    "backend API changes",
-    "database changes"
-  ],
-  "protectedPaths": [
-    "backend/**"
-  ],
-  "requiredContext": [
-    "AGENTS.md",
-    ".pi/project-context.md",
-    "docs/frontend/structure-guide.md"
-  ],
-  "contextManifest": [
-    {
-      "path": "AGENTS.md",
-      "reason": "root rules"
-    }
-  ],
-  "memoryCitations": [],
-  "mcpCapabilities": [
-    "filesystem-readonly",
-    "browser"
-  ],
-  "verifyCommands": [
-    "npm run test"
-  ],
-  "workPlan": [
-    {
-      "id": "plan",
-      "title": "Confirm scope and verify gate before editing.",
-      "role": "parent",
-      "mode": "read-only",
-      "status": "done"
-    },
-    {
-      "id": "implement",
-      "title": "Apply the bounded source change.",
-      "role": "piagent-worker",
-      "mode": "single-writer",
-      "status": "pending",
-      "dependsOn": [
-        "plan"
-      ]
-    }
-  ],
-  "reviewLenses": [
-    "correctness",
-    "tests",
-    "scope"
-  ],
-  "orchestration": {
-    "mode": "solo-first",
-    "subagents": "not-used",
-    "reason": "Task starts in solo-first mode; use bounded subagents only for independent scout, planning, or review work.",
-    "fieldGuidePath": ".pi/memory/MEMORY.md",
-    "modelRoles": {
-      "planner": "Use the strongest available model for decomposition, architecture, risk, and acceptance criteria.",
-      "worker": "Use the fastest reliable model for a bounded, already-planned single write set.",
-      "reviewer": "Use a model or thinking setting decorrelated from the worker when review quality matters.",
-      "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
-    }
-  },
-  "verifyEvidence": [
-    {
-      "command": "npm run test",
-      "exitCode": 0,
-      "summary": "Unit test suite passed.",
-      "observed": true,
-      "matchedProfileCommand": true
-    }
-  ],
-  "changedFiles": [],
-  "trace": {
-    "outcome": "pending"
-  }
-}
-```
+# Task Implementation Contract v2
+
+## Muc tieu
+
+Contract la state machine cuc bo giup Pi chung minh mot task da doc gi, duoc sua
+gi, da thay doi gi, verify bang lenh nao va ket thuc ra sao. File nam tai:
 
-## Prompt contract
+```text
+.pi/piagent-state/tasks/<taskRunId>.json
+.pi/piagent-state/session-tasks/<session-id-hash>.json
+```
 
-Pi task prompt phải bắt buộc:
+`taskId` la ten logic cua cong viec. `taskRunId` la identity duy nhat cua mot
+attempt. `sessionId` rang attempt vao dung Pi session; `sessionName` de resume va
+Agent Watch/report hien ten task ma operator da dat.
+
+## Field groups
+
+| Nhom | Field | Quy tac |
+|---|---|---|
+| Schema | `schemaVersion` | Luon la `2`. |
+| Identity | `taskRunId`, `taskId`, `sessionId`, `sessionName`, `intakeMode` | Run ID/Task ID normalized; mot session chi co mot task; intake la `runtime` hoac `model`. |
+| Mode | `changeMode` | `source-change` hoac `read-only`. |
+| Retry | `attempt`, `maxAttempts`, `previousAttempts` | Tran lay tu attempt dau, khong duoc nang o retry sau. |
+| Intent | `summary`, `riskLane`, `expectedOutput`, `acceptanceCriteria` | Chot truoc khi implementation. |
+| Scope | `scope`, `outOfScope`, `protectedPaths` | Direct write bi chan ngoai scope; final gate doi chieu Git. |
+| Context | `requiredContext`, `contextManifest`, `memoryCitations`, `mcpCapabilities` | Citation co path va reason. |
+| Verify | `verifyGroup`, `verifyCommands`, `verifyEvidence` | Moi command phai observed, exact-match va pass. |
+| Plan | `workPlan`, `reviewLenses`, `orchestration` | Toi da 12 step, dependency DAG, single writer. |
+| Changes | baseline/observed/final file lists va digests, `changedFiles` | Phan biet dirty truoc task voi thay doi trong task; ghi ca hai dau rename. |
+| Outcome | `trace`, `failedAt`, `failureReason`, `ruledOut` | Terminal contract immutable. |
+| Time | `createdAt`, `updatedAt` | Timestamp parseable, dung de sap xep/migration/report. |
+
+Template day du nam tai
+[`templates/project/.pi/task-contract.template.json`](../templates/project/.pi/task-contract.template.json).
+Schema chinh thuc nam tai
+[`schemas/task-contract.schema.json`](../schemas/task-contract.schema.json).
+
+## Runtime lifecycle
 
 ```text
-Use piagent_context first.
-Use piagent_orchestration_policy; default to solo-first, create a compact task tree, and choose review lenses before spawning subagents.
-Use piagent_context_index_status/search as advisory navigation when available; verify cited files before editing.
-Use piagent_memory_status and search memory when relevant; memory is advisory only.
-Read .pi/project-context.md; if it is pending, stop and request /onboard run.
-Create a Task Implementation Contract with piagent_task_start.
-Check large context with piagent_context_budget.
-Check complex/high-impact shell with piagent_exec_policy_check.
-Check non-piagent tools with piagent_tool_policy_check.
-Do not edit before scope + verify command are known.
-Before final, run the exact verify command from task.verifyCommands through Pi bash, record observed verify evidence, and trace.
-Call piagent_task_gate_check before DONE.
-If verify cannot run, final outcome is blocked/partial, not done.
+runtime automatic intake OR piagent_task_start fallback
+  -> ordinary targeted reads + project tool calls
+  -> runtime-observed context and changed files
+  -> exact bash verify commands
+  -> current-tree verify evidence from tool_result
+  -> completion hook projects trace + final gate
 ```
 
-## Enforcement levels
+Bounded default source tasks are created and completed through runtime hooks
+without model management calls. Broad/high-risk/custom source tasks use manual
+intake and explicit checkpoints when required.
+Read-only defaults use `scout`/`review`, never an implementation step. Manual
+context/verify/trace/gate tools are recovery surfaces for custom/high-risk work.
+
+Task start tu choi khi:
 
-| Level | Cách enforce | Độ tin cậy |
-|---|---|---:|
-| Prompt only | prompt nhắc model | Thấp |
-| Profile + prompt | profile có rule, prompt đọc profile | Trung bình |
-| Extension guard | tool_call block protected/destructive | Khá |
-| Runtime task tools | task_start/context_record/verify_record/trace | Cao |
-| Runtime quality tools | exec_policy/context_budget/tool_policy/task_gate | Cao |
-| Final gate | trace completion block khi `finalGate=enforce`; hard assistant stop-hook khi Pi API hỗ trợ | Cao nhất |
+- session da thuoc task khac hoac task terminal;
+- cung `taskId` dang pending o session khac;
+- task da completed;
+- retry vuot `maxAttempts`;
+- source task khong o trong Git working tree;
+- profile khong co meaningful verifier;
+- work plan trung ID, thieu dependency, tu tham chieu hoac co cycle.
 
-Hiện platform đang ở mức “P3-baseline runtime policy”:
+Truoc task start, governed project chi cho phep inspection. Guard chi coi shell la
+mutation khi command that su co kha nang ghi project (write redirection, mutating
+Git/package/file command, interpreter write, `sed -i`, `find -delete`...). Read,
+search va test khong bi gan nham thanh write.
 
-- `piagent_task_start`
-- `piagent_exec_policy_check`
-- `piagent_context_budget`
-- `piagent_context_index_status`
-- `piagent_context_index_search`
-- `piagent_context_index_record`
-- `piagent_tool_policy_check`
-- `piagent_context_record`
-- `piagent_verify_record`
-- `piagent_trace_record`
-- `piagent_task_gate_check`
-- local task/trace/observed-bash state trong `.pi/piagent-state/`
-- session trace qua Pi custom entry `piagent-task-trace`
+## Changed-file truth
 
-`piagent_trace_record` có thể block completion nếu profile bật `finalGate=enforce`. Nếu Pi runtime chưa expose hard final assistant stop hook, agent vẫn phải gọi `piagent_task_gate_check` và final phải nêu gate result.
+Luc start, runtime luu Git working-tree snapshot va digest tung file dirty. Luc
+gate/final trace, runtime chup lai snapshot:
 
-## Verify evidence rules
+```text
+expected change = file co final digest khac task-start baseline
+```
+
+Vi vay:
 
-`piagent_verify_record` is not a free-form self-report. It accepts evidence only when the same normalized command was observed through a Pi `bash` `tool_result` after `task.createdAt`.
+- file dirty truoc task khong tu dong bi nhan la do task;
+- file dirty truoc task nhung bi sua tiep se duoc tinh;
+- file da duoc sua roi revert ve baseline chi nam trong audit history, khong pass gate;
+- claim file khong co evidence bi tu choi;
+- thay doi ngoai `scope` bi tu choi;
+- delete/missing co digest rieng;
+- staged rename ghi ca old path va new path.
 
-Observed bash results are persisted to:
+## Verify truth
+
+Observed bash ledger la bounded owner-only JSONL. Evidence chi pass khi:
 
 ```text
-.pi/piagent-state/observed-bash.jsonl
+exitCode === 0
+observed === true
+matchedProfileCommand === true
+command nam chinh xac trong task.verifyCommands
 ```
 
-This lets parent agents validate verify commands executed by guarded subagent processes in the same cwd.
+Final gate doi evidence cho **tat ca** meaningful verify commands, khong chi mot
+command bat ky. Profile `generic` fail-closed cho source work den khi project khai
+verifier. Profile theo stack chi chay command co y nghia va khong dung `|| true`
+de che failure.
+
+## Retry va terminal immutability
+
+Step co the `pending`, `in-progress`, `done`, `skipped`, `failed`. Reopen mot
+failed step can note moi; step done/skipped khong duoc mo lai. Khi trace da
+terminal, cac tool progress/context/memory/verify/trace va project mutations deu
+bi chan cho session do.
 
-Final-gate pass requires:
+Retry chay o session moi. `previousAttempts` giu outcome, phase failure, reason,
+ruled-out hypothesis va timestamp de agent khong lap lai cach da that bai.
 
-- `observed=true`;
-- `matchedProfileCommand=true`;
-- `exitCode=0`.
+## Migration v1 -> v2
 
-Exact command identity matters. If the task profile says `npm test`, record `npm test`. `npm  test`, `npm test 2>&1`, `npm test || true`, `true`, and `echo ok` are different commands and will not satisfy the passing gate unless explicitly present in `task.verifyCommands`.
+Reader v2 fail-closed voi field la, timestamp hong, nested plan sai, taskRunId
+khong khop filename hoac state unreadable. Migrator v1 chi copy whitelist field
+da cong bo, them identity/session/retry/baseline defaults, ghi v2 atomically roi
+archive file v1. Update preflight tu choi truoc moi project write neu state can
+operator recovery.
 
-## Named implementation recipes
+Project da onboard khong can onboard lai sau global update. Capability lock giu
+nguyen grant cua project va chi re-pin core khi release moi khong mo rong quyen.
 
-- `/workflow platform-improve`: dùng cho task cải tiến setup, docs, prompt, MCP, model, memory, runtime policy, hoặc subagent workflow của platform.
-- `/workflow be-to-fe`: dùng cho task scout BE contract read-only rồi implement FE.
-- `/memory`: dùng cho task kiểm tra/ghi nhớ explicit project memory.
+## Enforcement
 
-Hai recipe này vẫn phải tạo/giữ Task Implementation Contract khi có source writes.
+| Lop | Enforcement |
+|---|---|
+| Prompt/workflow | Huong dan dung tool theo thu tu. |
+| Tool-call guard | Protected path, scope, read-only, destructive/external confirmation. |
+| Tool-result observer | Changed-file va bash evidence tu su kien that. |
+| Persisted contract | Session binding, retry, plan, context, verify, trace. |
+| Completion hook | Chan completion claim khi gate chua pass. |
+| Local-state boundary | Owner-only, atomic write, no ancestor symlink, bounded retention. |

package/docs/task-lifecycle-vietnamese.md

@@ -1,139 +1,143 @@
-# Vòng đời một task: research → plan → execute → verify → loop
+# Vong doi task trong Pi Agent Platform
 
-## Mục tiêu
+## Muc tieu
 
-Tài liệu này mô tả một task chạy qua platform từ đầu tới cuối, và nói thẳng harness hiện tại đỡ được khâu nào, chưa đỡ được khâu nào. Mọi nhận định đều dẫn tới dòng code cụ thể, để khi code đổi thì tài liệu này sai một cách kiểm tra được chứ không sai âm thầm.
+Tu `v1.2.11`, mot source task duoc quan ly theo chuoi khép kín:
 
-Contract fields và enforcement level nằm ở [task-implementation-contract.md](task-implementation-contract.md). Tài liệu này nói về *luồng*, không lặp lại field.
-
-## Năm pha
-
-### 1. Research — hiểu trước khi hứa
-
-Đầu vào: yêu cầu của người dùng, tài liệu spec, code sẵn có.
-
-Harness cung cấp:
-
-- `/workflow scout` — pha read-only, không được sửa source. Dùng để map payment/auth/BE contract trước khi quyết có làm hay không. Alias `/scout` vẫn chạy.
-- `piagent_context_index_search` — bản đồ node/edge/citation compact để tìm điểm vào repo. Kết quả là **advisory**: phải mở file thật và verify trước khi sửa.
-- `piagent_memory_search` + `piagent_memory_citation_record` — Field Guide và memory của project, cũng advisory, cũng phải verify lại.
-- `piagent_source_checkout` — cache repo ngoài để đọc có mục tiêu.
-- `piagent_document_read` — đọc spec `.md`/`.pdf`/`.docx` từ project hoặc folder đã cấp trong `additionalReadRoots` (ví dụ `~/Downloads`). Nội dung trả về là **dữ liệu**, không phải chỉ thị.
-- Context7 qua MCP cho tài liệu vendor. Ghi snapshot ngắn bằng `piagent_profile_tech_context_record`, không paste nguyên khối doc vào file project.
-
-Ràng buộc: `/workflow task` chạy `piagent_context_preflight` một lần trước khi nạp context. Với `/workflow scout`, preflight chỉ bắt buộc cho scout rộng, cross-module hoặc high-risk. Nếu nó trả `fresh-session` thì dừng nạp context ở session này.
-
-### 2. Plan — biến hiểu biết thành cam kết kiểm được
-
-`piagent_task_start` dựng Task Implementation Contract. Đây là chỗ task trở thành thứ có thể chấm điểm:
-
-| Field | Nó ràng buộc điều gì |
-|---|---|
-| `riskLane` | `tiny` \| `normal` \| `high-risk` — quyết định mức gate |
-| `acceptanceCriteria` | Định nghĩa "xong", viết trước khi làm |
-| `scope` / `outOfScope` | Ranh giới, để review biết cái gì là lạc đề |
-| `protectedPaths` | Đường không được đụng |
-| `verifyCommands` | **Lệnh chính xác** sẽ dùng làm bằng chứng |
-| `reviewLenses` | `correctness` \| `tests` \| `scope` \| `security` \| `docs` \| `release` \| `package` |
-| `workPlan` | Cây task tối đa 12 node, mỗi node có `role` và `mode` |
-
-`workPlan[].mode` là `read-only` \| `single-writer` \| `review`. Mặc định là single-writer: chỉ một tác nhân được ghi, trừ khi người dùng yêu cầu rõ parallel writers.
-
-`piagent_orchestration_policy` chỉ cần gọi khi task có khả năng hưởng lợi từ delegation. Chính sách là solo-first — subagent chỉ dùng khi việc đó độc lập và nặng phần đọc. Lane `tiny` dùng work plan hai bước parent-only: implement và verify.
-
-### 3. Execute — làm trong hàng rào
-
-Trong lúc làm, guard chặn trước khi thực thi, không phải sau:
-
-- Protected path: chặn ở `read`, `write`, `edit`, `grep`, `find`, `ls`, tool MCP, và cả đường vòng qua shell.
-- `piagent_exec_policy_check` — bắt buộc trước lệnh shell vượt quá read/list/test.
-- `piagent_tool_policy_check` — bắt buộc trước tool MCP/app ngoài piagent.
-- `piagent_context_budget` — kiểm trước khi nạp file lớn hoặc lạ.
-- `piagent_context_record` — ghi lại đọc file nào, vì lý do gì.
-
-### 4. Verify — chỗ mạnh nhất của harness
-
-Đây là phần được thiết kế kỹ nhất, và đáng để hiểu chính xác.
-
-Bằng chứng verify **không phải** thứ agent tự khai. Guard nghe `tool_result` của Pi và ghi vào sổ `.pi/piagent-state/observed-bash.jsonl` ([`piagent-guard.ts:1378`](../packages/piagent-core/extensions/piagent-guard.ts)). `piagent_verify_record` chỉ nhận bằng chứng khớp được với một quan sát thật, sau thời điểm task bắt đầu.
-
-`evaluateTaskGate` ([`piagent-guard.ts:3125`](../packages/piagent-core/extensions/piagent-guard.ts)) đòi ba điều kiện cộng dồn để một bằng chứng được tính là **pass**:
-
-```
-evidence.exitCode === 0
-&& evidence.observed === true            // đã quan sát được, không phải khai báo
-&& evidence.matchedProfileCommand === true  // khớp đúng verifyCommands của task
+```text
+session name -> task contract v2 -> scoped work plan -> observed changes
+-> exact verification -> immutable outcome -> retry evidence
 ```
 
-Thiếu bất kỳ điều nào thì bằng chứng vẫn được ghi, nhưng chỉ ở mức advisory và gate không tính. Cụ thể:
-
-- `observed !== true` → cảnh báo "Unobserved verify evidence is ignored by the passing verify gate."
-- `observed === true` nhưng lệnh không khớp `verifyCommands` → "advisory only".
-
-Nghĩa là `true`, `echo ok`, `npm test || true` không mua được chữ "done". Đó là chủ ý: một cổng có thể lách được thì tệ hơn không có cổng, vì nó vẫn hiện màu xanh.
-
-`piagent_task_gate_check` trả `pass` hoặc `fail` kèm danh sách `missing`. Gate fail thì outcome là `blocked`/`partial`, **không phải** `done`.
-
-### 5. Fail → loop lại
-
-Đây là chỗ đứt. Xem mục [Chỗ đứt, nói chính xác](#chỗ-đứt-nói-chính-xác).
-
-## Pi hiện tại xử lý tới đâu
+Runtime guard thi hanh chuoi nay. Prompt chi huong dan agent, khong phai lop
+enforcement chinh.
 
-| Pha | Trạng thái | Căn cứ |
-|---|---|---|
-| Research | **Đủ** | `/workflow scout`, context index, memory, Context7, source checkout |
-| Plan | **Đủ** | `piagent_task_start` + 19 field contract + `workPlan` |
-| Execute | **Đủ** | Chặn trước thực thi ở mọi đường: tool, MCP, shell |
-| Verify | **Mạnh** | Bằng chứng phải quan sát được và khớp lệnh, không tự khai được |
-| Fail → loop | **Nửa vời** | Phát hiện được, từ chối nhận done được, nhưng không mang được state qua lần sau |
+## Luong lam viec hang ngay
 
-### Chỗ đứt, nói chính xác
+1. Mo project bang Pi va dat ten session theo task noi bo.
+2. Neu quen dat luc mo, chay `/name <task/session name>` hoac `/setname`.
+3. Chay `/workflow task <yeu cau>` de implement, hoac `/workflow scout <yeu cau>`
+   de chi doc.
+4. Runtime tu tao Task Implementation Contract cho task nho, ro scope va gan voi
+   dung Pi session truoc model turn dau tien.
+5. Agent lam viec ngay bang read/edit/bash thuong va chay exact verifier runtime
+   cung cap. Chi task rong, high-risk hoac scope mo ho moi can goi
+   `piagent_task_start` mot lan. Runtime tu ghi context, changed files, verify,
+   trace va gate.
+6. Neu dong terminal, resume dung session cu bang `pi --continue`, `pi --resume`
+   hoac `pi --session <id-or-file>`. Task dang mo duoc map lai theo session id va
+   custom trace cua Pi; session name van dung cho Agent Watch/report.
 
-Harness **phát hiện** thất bại tốt:
+Mot Pi session chi thuoc mot task, ke ca sau khi task da completed/failed. Task
+moi hoac retry phai dung session moi. Quy tac nay ngan hai cong viec tron prompt,
+usage va changed-file evidence vao mot report.
 
-- `trace.outcome` có `failed`, `blocked`, `partial` bên cạnh `completed`.
-- `task.md` yêu cầu verify không chạy được thì dừng và báo blocker chính xác, không được gọi là done.
-- Gate trả `missing` liệt kê đúng thứ còn thiếu.
+## Nam pha
 
-Nhưng nó **không mang được gì sang lần thử sau**:
+### 1. Research
 
-1. **Contract không có bộ đếm lần thử.** Không có `attempt`, không có `previousAttempts`. Lần thử thứ hai bắt đầu như thể chưa từng có lần một.
-2. **`workPlan[].status` không có giá trị `failed`.** Enum chỉ là `pending` \| `in-progress` \| `done` \| `skipped` ([`schemas/task-contract.schema.json`](../schemas/task-contract.schema.json)). Một node đã thử và hỏng chỉ có thể ghi là `skipped` — mất nghĩa.
-3. **Không có chỗ ghi giả thuyết đã loại.** Verify fail vì lý do gì, đã thử cách nào, tại sao không được — không field nào giữ. Lần sau agent rất dễ thử lại đúng cách đã hỏng.
-4. **Không có trần số vòng.** Không có gì chặn loop vô hạn ngoài sự kiên nhẫn của người dùng.
+- `/workflow scout` tao luong read-only khi chua can sua source.
+- Pi Context Engine tim file/symbol/test bang FTS, import graph va Git signals.
+- Memory, Context7, source checkout va document reader la advisory evidence;
+  agent van phai doc file hien tai truoc khi sua.
+- Auto-context chi inject mot bounded pack cho moi prompt trong tung session.
+  Goi pack lai voi cung query se tra reuse marker, khong nhan doi payload/token.
 
-`/review-loop` có tồn tại và đúng là loop, nhưng nó đến từ add-on `pi-subagents` chứ không phải platform này, và nó lặp vòng review→fix, không phải vòng research→plan→execute→verify.
+### 2. Plan
 
-### Đề xuất để khép vòng
+Automatic intake hoac fallback `piagent_task_start` tao contract schema v2 gom:
 
-Thêm vào contract, không đổi thứ đang có:
-
-```jsonc
-{
-  "attempt": 2,                    // lần thử hiện tại
-  "maxAttempts": 3,                // trần, gate fail cứng khi vượt
-  "previousAttempts": [
-    {
-      "attempt": 1,
-      "failedAt": "verify",        // research | plan | execute | verify
-      "reason": "npm test — 3 test đỏ ở auth/session",
-      "ruledOut": "Không phải do token expiry; đã kiểm bằng fixture cố định giờ."
-    }
-  ]
-}
-```
-
-Và mở `workPlan[].status` thêm giá trị `failed`.
-
-Chi phí: một field mảng trong schema, một nhánh trong `evaluateTaskGate`, một bước trong `task.md`. Đổi lại, lần thử thứ hai đọc được lần thứ nhất đã loại trừ gì — đó là toàn bộ giá trị của việc loop thay vì làm lại.
-
-Đây là đề xuất, chưa implement. Cần chốt trước khi làm.
-
-## Liên quan
-
-- [task-implementation-contract.md](task-implementation-contract.md) — field và enforcement level
-- [workflow-recipes.md](workflow-recipes.md) — công thức cho từng loại việc
-- [runtime-policy-design.md](runtime-policy-design.md) — thiết kế lớp policy
-- [security-threat-model.md](security-threat-model.md) — giả định, vector, và rủi ro còn lại
-- [command-reference-vietnamese.md](command-reference-vietnamese.md) — giải thích từng lệnh
+| Nhom | Field chinh |
+|---|---|
+| Identity | `taskRunId`, `taskId`, `sessionId`, `sessionName`, `intakeMode` |
+| Retry | `attempt`, `maxAttempts`, `previousAttempts` |
+| Boundary | `changeMode`, `scope`, `outOfScope`, `protectedPaths` |
+| Quality | `acceptanceCriteria`, `verifyGroup`, `verifyCommands`, `reviewLenses` |
+| Execution | `workPlan`, `orchestration` |
+| Evidence | context, memory, baseline/observed/final file digests, verify, trace |
+
+Source task bat buoc nam trong Git working tree. Khong co Git thi runtime tu
+choi source-change vi khong the chung minh file nao da doi; read-only scout van
+hoat dong.
+
+Work plan toi da 12 step, dependency khong duoc thieu, tu tham chieu hoac tao
+cycle. Source task `tiny` tu dong hoan tat lifecycle; source task `normal` tu
+dong ghi objective evidence va giu mot explicit review step. Read-only task dung
+plan `scout`/`review`, khong con step `implement` mau thuan. Task high-risk/custom
+van giu checkpoint thu cong. Chi dung subagent cho scout, planning hoac review
+doc lap. Mot write set chi co mot owner.
+
+### 3. Execute
+
+Truoc khi co task contract, project da onboard chi cho inspection co gioi han;
+write/edit va shell command that su ghi file bi chan. Sau khi task bat dau:
+
+- direct tool va MCP write phai nam trong `scope`;
+- read-only task chan moi project/external mutation;
+- protected path, secret redaction, destructive command va external confirmation
+  van manh hon task gate;
+- tool result ghi nhan file da quan sat thay doi;
+- file da dirty truoc task chi tinh la thay doi cua task neu digest sau task khac
+  baseline;
+- rename ghi nhan ca source va destination.
+
+### 4. Verify va complete
+
+Moi lenh trong `task.verifyCommands` phai duoc Pi `bash` chay that sau thoi diem
+task bat dau. Hook `tool_result` tu ghi evidence khi command identity khop plan;
+tool `piagent_verify_record` chi con la recovery surface va van phai khop ledger
+`.pi/piagent-state/observed-bash.jsonl`.
+
+Gate completed yeu cau dong thoi:
+
+- context manifest theo policy;
+- moi verify command co observed result `exitCode=0` va exact match;
+- work plan khong con `pending`, `in-progress` hoac `failed`;
+- declared changed files khop final digest sau baseline; file da revert khong tinh;
+- khong co file ngoai `scope`;
+- final trace la `completed`.
+
+`true`, `echo ok`, `npm test || true` hoac command gan giong khong thay the lenh
+verify da chot. Hard completion hook tu project final state, check gate va ghi
+completed trace. Evidence verify chi hop le cho working-tree digest hien tai;
+sua tiep sau verify buoc phai chay lai. Neu automatic/assisted task dung som,
+runtime gui dung mot follow-up correction turn voi missing reasons that, sau do
+khong loop.
+
+Sau terminal outcome (`completed`, `blocked`, `partial`, `failed`), contract la
+immutable. Agent khong the chen them context/verify/change evidence de viet lai
+lich su.
+
+### 5. Fail va retry
+
+`workPlan[].status` co `failed`. Final failure ghi `failedAt`, `failureReason`,
+`ruledOut` va friction. Session moi dung cung `taskId` tao attempt tiep theo va
+mang theo toi da 10 attempt summaries.
+
+`maxAttempts` duoc khoa tu attempt dau (mac dinh 3, toi da 10). Sua tay attempt
+sau khong the nang tran. Completed task khong duoc mo lai bang cung `taskId`;
+cong viec moi phai co ID moi.
+
+## Migration va local state
+
+Session start va `piagent-update --project <path>` deu nhan biet contract v1.
+Migration:
+
+- preview truoc khi ghi;
+- tu choi toan bo neu co state unreadable/corrupt;
+- tao contract v2 roi archive v1, co the chay lai sau interruption;
+- chi map legacy task vao session resume khi custom Pi trace chung minh dung task;
+- khong yeu cau onboard lai project.
+
+State, telemetry va capture nam trong `.pi/piagent-state/`, mode owner-only. Moi
+writer dung chung local-state boundary, tu choi `.pi`/ancestor symlink thoat
+project. JSONL duoc rotate co lock lien process; capture gioi han 500 file,
+128 MiB va 30 ngay.
+
+## Lien quan
+
+- [Task Implementation Contract](task-implementation-contract.md)
+- [Runtime harness standard](runtime-harness-standard.md)
+- [Pi Context Engine](context-engine.md)
+- [Command reference](command-reference-vietnamese.md)
+- [Usage observability](usage-observability.md)

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.9
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 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.9
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -79,7 +79,12 @@ Khi cần kiểm tra một project sau rollout, chạy riêng:
 piagent-update --version X.Y.Z --project /path/to/project
 ```
 
-`--project` là bước phụ: tự migrate layout cũ nếu có rồi chạy doctor strict-share. `--check` chỉ báo version, không đụng gì.
+`--project` là bước phụ: tự migrate layout cũ, Task Contract và managed block
+trong `AGENTS.md` nếu có rồi chạy doctor strict-share. Text riêng của project
+ngoài managed block được giữ nguyên. Nếu chỉ update global, runtime mới vẫn thay
+checklist template cũ trong system prompt ở memory nên task dùng logic mới ngay;
+chạy `--project` để file trên disk được dọn bền vững. `--check` chỉ báo version,
+không đụng gì.
 
 Nếu npm global mặc định của máy bị khóa quyền ở `/usr/local`, updater tự chuyển sang `~/.pi/npm-global` cho user hiện tại và in dòng `PATH` cần thêm. Không chạy doctor bằng `sudo`.
 
@@ -360,9 +365,12 @@ Chạy trên project:
 ```bash
 bash /path/to/piagent/scripts/profile-doctor.sh /path/to/project
 bash /path/to/piagent/scripts/team-doctor.sh /path/to/project --strict-share
-bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --init
+piagent-benchmark --dry-run
 ```
 
+Maintainer chạy `piagent-benchmark` khi cần đo release/model bằng automatic paired
+suite. Lệnh dùng model quota và sẽ hỏi xác nhận trước khi bắt đầu.
+
 Nếu doctor cảnh báo `project onboarding snapshot is still pending`, mở Pi trong project và chạy `/onboard run`.
 
 ## Không commit