@piagent/platform 1.2.10 → 1.2.12

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,11 @@ 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, 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

@@ -133,7 +133,18 @@ Runtime behavior:
 - yêu cầu observed passing verify khớp exact `task.verifyCommands` khi task có source changes;
 - block `piagent_trace_record completed` nếu final gate đang enforce và proof chưa đủ.
 
-Agent vẫn phải gọi `piagent_task_gate_check` trước final handoff.
+Agent không phải gọi các tool evidence/trace/gate trong task thường. Hook
+`tool_result` tự ghi targeted reads, changed files và exact verifier; hook
+`message_end` dựng final contract, chạy gate rồi ghi terminal trace khi đủ proof.
+Các tool thủ công vẫn tồn tại cho diagnostics/recovery và high-risk/custom plan.
+
+Passing evidence còn phải khớp `workingTreeDigest` hiện tại. Bất kỳ mutation nào
+sau verify làm evidence cũ stale. Việc chạm một file rồi revert về đúng digest
+baseline chỉ được giữ trong audit history, không được tính là final source diff.
+
+Automatic/assisted plan được phép một `followUp` correction turn khi projected
+gate fail. Lượt này nhận đúng missing reasons, không tự lặp; rollback bằng
+`PIAGENT_AUTO_RECOVERY=off`.
 
 `piagent_verify_record` không còn tin `exitCode` tự khai báo. Lệnh verify phải khớp một bash tool result đã quan sát sau `task.createdAt`, và claimed `exitCode` phải khớp trạng thái `isError` của Pi. Observed result được ghi vào `.pi/piagent-state/observed-bash.jsonl` để parent/subagent process có thể share evidence trong cùng project cwd.
 
@@ -158,7 +169,7 @@ Guard state tự bảo vệ:
 - mọi text block trong `tool_result` và string leaf trong JSON-like `details` có thêm shared sensitive-data redaction; key như `password`, `token`, `credential` được dùng làm context phát hiện;
 - `npm run benchmark:redaction` gate contextual recall, benign preservation, structured objects/arrays, và large-output correctness bằng synthetic data; opaque entropy không có credential context được báo riêng và không gate release;
 - bash evidence chỉ giữ command text đã redact ở memory/disk; raw command hash vẫn dùng để exact-match verify evidence;
-- `piagent_task_start`, `piagent_verify_record`, và `tool_result` hook vẫn ghi state được qua internal extension path.
+- `piagent_task_start`, lifecycle hooks và các recovery tools vẫn ghi state được qua internal extension path.
 
 ## 5. Local verification
 
@@ -188,34 +199,48 @@ pi list --approve
 
 ## 6. Quality benchmark
 
-Script:
+Automatic paired benchmark:
 
 ```bash
-bash scripts/quality-benchmark.sh <project-path> --init
-bash scripts/quality-benchmark.sh <project-path> --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens 12345 \
-  --cost 0.12 \
-  --verify "npm test" \
-  --notes "verify passed; no manual correction"
+piagent-benchmark --dry-run
+piagent-benchmark
+piagent-benchmark --production --dry-run
 ```
 
 Output:
 
 ```text
-<project>/.pi/benchmarks/quality-scenarios.md
-<project>/.pi/benchmarks/quality-runs.jsonl
+~/.pi/agent/benchmarks/piagent/<run-id>/report.json
+~/.pi/agent/benchmarks/piagent/<run-id>/report.html
+~/.pi/agent/benchmarks/piagent/<run-id>/summary.txt
+~/.pi/agent/benchmarks/piagent/<run-id>/runs.jsonl
 ```
 
-Chỉ claim chất lượng/token/cost khi cùng scenario có:
+Runner dùng clean Git fixture, hidden grader và exact Pi session usage. Piagent
+fixture được init/onboard và build context trước measured run để benchmark task
+steady-state; mọi context/index mutation sau Git baseline vẫn bị scope gate bắt.
+Report tách hidden correctness khỏi scope/reliability, hiện usage của mọi run và
+chỉ lưu histogram tên tool. Chỉ claim chất lượng/token/cost khi các paired run có:
 
 - cùng task prompt/spec;
 - cùng acceptance criteria;
 - verify command rõ;
-- token/cost/duration được ghi lại;
-- quality notes và số vòng sửa lại.
+- token/cost/duration được runtime ghi lại;
+- 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
 

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.10, 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.12, 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/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. |