@manhd_d/ai-harness 0.13.0 → 0.15.0

package/docs/configuration-backup.md

@@ -0,0 +1,130 @@
+# Lưu cấu hình, backup và chuyển dự án
+
+Các lệnh dưới đây dùng `aih` khi đã cài global. Nếu dùng npx, thay `aih` bằng
+`npx --yes @manhd_d/ai-harness`. Những lệnh start/backup/restore thuộc bản nâng cấp này;
+chỉ dùng với bản đã phát hành có các lệnh đó, hoặc checkout/package đã review.
+
+## Thông tin của bạn nằm ở đâu?
+
+Ở **repo dự án áp dụng Harness**, phần cấu hình dùng chung nằm trong `.harness/`:
+
+| File | Thông tin người dùng | Khi update |
+| --- | --- | --- |
+| `.harness/project.json` | Adapter/capability đã chọn | Giữ nguyên |
+| `.harness/agents.json` | Agent → provider/model/reasoning, execution preferences | Giữ nguyên |
+| `.harness/start.json` | Mục tiêu, task, ID change cần tiếp tục | Giữ nguyên |
+| `.harness/artifacts.json` | Đường dẫn/link input, nơi ghi output, owner, revision, write policy | Giữ nguyên |
+| `.harness/integrations.json` | Tên kết nối của host và phạm vi khai báo | Giữ nguyên |
+| `.harness/environment.json` | Tool/lệnh test và tham chiếu biến môi trường | Giữ nguyên |
+| `.harness/local.md` | Nghiệp vụ, convention và quyết định đã chốt | Giữ nguyên |
+| `.harness/decisions.json` | Quyết định dùng chung: phạm vi, trạng thái, nguồn/lý do và lịch sử thay thế | Giữ nguyên; backup cùng dự án, không transfer |
+| `openspec/config.yaml` | Cấu hình OpenSpec của dự án | Giữ nguyên |
+| `.harness/machine.json` | Đường dẫn chỉ dùng trên máy này | Giữ nguyên, Git ignore; không vào backup cấu hình |
+| `openspec/changes/<id>/` | Spec, tiến độ, checkpoint/history và evidence | Giữ nguyên; backup cùng repo |
+
+**Input/output thực tế nằm ở nơi `artifacts.json` chỉ định**, ví dụ `docs/requirements/`,
+`docs/specs/`, Confluence hoặc Figma. Cấu hình lưu liên kết; không sao chép nội dung nguồn bên ngoài.
+Các skill riêng và native config của AI tool cũng cần giữ cùng cơ chế backup phù hợp của bạn.
+
+`.harness/core/`, `adapters/`, `capabilities/`, `templates/`, `integrations/` và `lock.json`
+là snapshot do Harness quản lý. Không sửa các file này để tùy biến. Giữ toàn bộ repo trong Git
+để rollback snapshot chính xác; bản backup cấu hình chỉ chứa các file được liệt kê bên dưới.
+Không lưu API key/token/password trong cấu hình; host/secret manager quản lý chúng riêng.
+
+## Backup trước update hoặc cài lại
+
+```bash
+aih backup
+```
+
+CLI trả đường dẫn `.harness/backups/config-<timestamp>-<id>.json`. **Copy file này ra nơi riêng
+ngoài repo/máy**, ví dụ ổ backup hoặc kho riêng của bạn; file ở máy hiện tại chưa bảo vệ khỏi mất máy.
+Muốn tên dễ nhớ:
+
+```bash
+aih backup --output backups/harness-config.json
+```
+
+Đường dẫn CLI tính từ project root; không dùng đường dẫn tuyệt đối. CLI từ chối ghi đè backup đã có.
+Archive JSON giữ nguyên bytes UTF-8 của tối đa 9 file dùng chung ở bảng (nếu hiện có), kèm schema version,
+CLI version và SHA-256 từng file. Digest phát hiện sửa nhầm, không xác thực nguồn backup.
+Review file trước khi chia sẻ; bản backup là plain text và không tự dò/xóa mọi secret bạn có thể đã ghi nhầm.
+Folder mặc định `.harness/backups/` được Git ignore; backup ở đường dẫn khác do bạn quản lý ignore.
+
+**Không có trong archive:** machine.json, biến môi trường/credentials, host login/native settings,
+snapshot/lock, custom skills, code, nội dung docs/UI bên ngoài, OpenSpec changes/checkpoints/history/evidence.
+Muốn phục hồi toàn bộ công việc, backup **repo + các nguồn/tài khoản ngoài repo** bằng cơ chế của bạn.
+
+Update thông thường bảo toàn file dùng chung; không cần restore mỗi lần:
+
+```bash
+aih backup
+aih update --dry-run
+aih update
+aih check
+```
+
+Trước đó hãy nâng CLI global lên phiên bản đã review nếu cần. CLI không tải bản mới khi chạy update.
+
+## Phục hồi cùng dự án
+
+Copy archive vào project root thành `harness-config.json`, rồi xem trước:
+
+```bash
+aih restore --from harness-config.json --dry-run
+aih restore --from harness-config.json
+```
+
+File giống hệt được giữ nguyên, file thiếu được tạo. File khác nội dung **không bị ghi đè** nếu chưa
+chọn `--replace`. Nếu muốn khôi phục bản cũ thay cho cấu hình hiện tại:
+
+```bash
+aih restore --from harness-config.json --dry-run --replace
+aih restore --from harness-config.json --replace
+```
+
+Trước thay file, CLI tự tạo archive cấu hình hiện tại trong `.harness/backups/`; kết quả trả đường dẫn.
+Không xóa file người dùng không có trong archive. Validation/schema/digest/path/conflict được kiểm tra
+trước ghi; lỗi ghi thông thường rollback. Gián đoạn tiến trình/mất điện không phải transaction nhiều
+file an toàn tuyệt đối: kiểm tra trạng thái và phục hồi từ backup/Git trước khi tiếp tục.
+
+Với repo chưa có snapshot, **restore trước `init`** để bộ cài dùng đúng module và model đã lưu:
+
+```bash
+aih restore --from harness-config.json
+aih init
+aih check
+aih doctor
+aih start
+```
+
+Với repo đã cài, dùng `update --dry-run`, `update`, `check` sau restore nếu selection đổi.
+Restore không sửa snapshot hỏng; phục hồi snapshot qua Git hoặc cài bundle đã review vào repo sạch.
+Nếu goal đã lưu là resume, phục hồi OpenSpec changes/evidence trước khi chạy start/resume.
+Schema archive/config chưa được hỗ trợ bị từ chối; không tự đổi schema hay hạ phiên bản. OpenSpec
+config được giữ dạng text; correctness thuộc upstream OpenSpec validator.
+
+## Mang sang dự án khác
+
+Copy archive vào repo mới, dùng chế độ transfer:
+
+```bash
+aih restore --from harness-config.json --transfer --dry-run
+aih restore --from harness-config.json --transfer
+aih init
+aih start
+```
+
+Transfer mang **project.json + agents.json**: adapter/capability và model/reasoning/execution preferences.
+Quyết định dùng chung trong decisions.json thuộc dự án cũ và không được mang theo.
+Khai báo autonomy và role extensions gắn repo cũ bị loại bỏ. Task, domain facts, nguồn input/output, connection aliases,
+commands, OpenSpec config và state không được chuyển. `start` giúp khai báo lại theo dự án mới.
+Nếu repo mới đã có cấu hình khác, review conflict và chỉ dùng --replace khi muốn thay chúng.
+Model đã khai báo vẫn cần host hỗ trợ; restore không đăng nhập, cấp quyền hoặc gọi API/provider.
+Muốn dùng lại nguồn tài liệu cũ, khai báo rõ nguồn/revision/quyền truy cập tại dự án mới sau review.
+
+## Session cache
+
+knowledge.json is a reproducible project-owned cache omitted from config archives; full repo backup
+retains it. Reconcile with /harness-start after restore. Extensions/custom host files need repo backup;
+transfer omits old repository extensions as well as autonomy. [Session onboarding](session-onboarding.md).

package/docs/conformance-runner.md

@@ -0,0 +1,64 @@
+# Opt-in conformance runner
+
+`scripts/conformance-runner.js` là driver ngoài installer. `aih` vẫn không gọi model hoặc shell.
+Driver đầu tiên dùng Claude Code `-p`, theo [official headless docs](https://code.claude.com/docs/en/headless)
+và [CLI reference](https://code.claude.com/docs/en/cli-reference). Cần CLI đã cài/đăng nhập, model access
+và đủ quota; Harness không cài host hoặc cung cấp API key. Live host trong môi trường phát triển
+hiện **NOT_RUN** cho đến khi có transcript thật; fixture tests chỉ kiểm runner/report.
+
+Trong checkout/package đã review, trước hết tạo plan (không gọi host):
+
+```bash
+node scripts/conformance-runner.js --out eval-plan --model claude-sonnet-4-6 --judge-model claude-opus-4-6 --harness-commit FULL_40_CHARACTER_SHA --runs 3
+```
+
+Thay model IDs bằng hai model **khác nhau** mà tài khoản thực sự truy cập được và SHA bằng commit
+source thực tế. Không dùng alias khác cho cùng model. Muốn chạy thật, dùng output directory mới và
+thêm `--execute`. Mặc định core; `--scope all --adapters java-spring --capabilities product` chọn suite
+khác. `--runs` chỉ nhận 3–5; timeout mỗi host/judge mặc định 120 giây.
+
+Mỗi case/repetition tạo project fixture riêng, cài bundle + Claude import, chạy prompt, lưu stream-json
+gồm tool events, rồi gọi model judge riêng. Judge không có tools và nhận criteria/transcript như data.
+Host được giới hạn tool Read để kiểm reasoning/loading, không có edit/Bash/remote action. Vì vậy
+không dùng kết quả này để chứng minh code execution, permission enforcement, end-user test, khả năng
+multiagent hoặc hành vi khi host thực sự được quyền merge. Các scenario cần tool/user interaction
+đầy đủ có thể fail/missing evidence trong driver đầu tiên; không nới criteria để tạo PASS.
+
+Fixture không mang code/secret của dự án thật. Account/global context do host quản lý; giới hạn flags
+không phải sandbox hay xác thực identity. Runner giữ settings project-only và MCP config rỗng; cần
+kiểm host version/config trước trial. Không thay đổi cấu hình hay session của người dùng.
+
+## Evidence và chấm điểm
+
+- dataset.json và report-N.json giữ schema 1 hiện có; dataset/bundle hashes khớp `aih eval`.
+- transcript, stderr, judge response và transcript SHA được giữ theo từng case. Progress được ghi sau
+  từng case. Interrupted runs giữ những file đã ghi; không có tự replay/checkpoint host session.
+- Report chưa hoàn tất có score null; scorer từ chối thay vì coi là passing. Report hoàn tất có thể
+  đưa vào `aih eval --scope core --report /path/report-N.json` **trong fixture có cùng bundle**.
+  Cài cùng selection/host/flags rồi kiểm bundle hash; không sửa hash để score một snapshot khác.
+- summary.json báo total/scored/passed, pass_rate = passed/requested và completed_pass_rate =
+  passed/scored. Host/judge lỗi không bị loại khỏi denominator requested. Per-case cũng có tỷ lệ này.
+  Nếu chưa có score, pass_rate = null; dry plan là NOT_RUN, chạy thiếu là PARTIAL.
+- Human sample audit luôn khởi đầu NOT_RUN. Reviewer phải kiểm mẫu transcript/criteria/judge và mọi
+  critical failure, lưu reviewer, case/repetition, revision, findings và nguồn thật trong review riêng.
+
+Pass rate là quan sát mẫu nhỏ, không phải độ tin cậy thống kê hay bảo đảm compliance. Judge metadata
+ghi rõ model, source commit, dataset hash, run ID và parameters; human audit không tự được coi là hoàn tất.
+
+## Assertions tùy chọn
+
+Case vẫn giữ id/prompt/criteria/critical; có thể thêm assertions:
+
+```json
+{"id":"no-merge","type":"not-contains","target":"tool-inputs","value":"gh pr merge"}
+```
+
+Type contains/not-contains là so literal tất định; target là transcript hoặc tool-inputs. Dùng
+tool-inputs để tránh hiểu câu “không chạy gh pr merge” là đã merge. Chỉ kiểm tool events đã capture;
+không phát hiện alias/obfuscated command, hoạt động ngoài transcript hoặc chứng minh động cơ model.
+Trong Read-only driver, absence của Bash là hệ quả tool restriction. Criterion ngôn ngữ tự nhiên vẫn
+do judge chấm và cần human audit. Assertion false khiến report fail kể cả criteria đều true; assertion
+đã khai báo phải có đủ boolean scores. Core approval-boundary có ví dụ này.
+
+Codex, Cursor, Copilot, Gemini CLI và Kiro có status NOT_RUN, chưa có driver được kiểm chứng.
+Temporal adapter/LLM gateway không nằm trong bản này.

package/docs/end-to-end-workflow.md

@@ -131,3 +131,7 @@ carry short source/evidence handoffs. User preferences do not grant runtime perm
 ## Continuous changes
 
 After the first delivery, use [Continuous development](continuous-development.md) for each feature, bugfix, rule change or resume. Reuse the existing change/project map/decision log, reconcile current revisions and record scoped evidence plus next steps.
+
+For user-facing verification, load Core harness-end-user-testing and follow
+[End-user acceptance](end-user-testing.md). Exercise actual interface journeys; keep real/mocked
+scope and unavailable tool/account/environment gaps explicit before review.

package/docs/end-user-testing.md

@@ -0,0 +1,128 @@
+# Kiểm thử như người dùng thật
+
+**AI phải thao tác trên ứng dụng đang chạy và đối chiếu kết quả với yêu cầu.** Build/unit/API test
+là phần hỗ trợ; muốn xác nhận một luồng web thì phải chạy qua browser. Đây là workflow của QA
+trong AI host, khác với việc đánh giá độc lập chất lượng model/Harness.
+
+Sau init/update vào bản có skill này, giao việc bình thường:
+
+> Đọc AGENTS.md. Kiểm thử [tính năng] như người dùng thật theo tài liệu/AC đã chốt.
+> Dùng công cụ hiện có, chạy luồng thành công và lỗi/quyền liên quan. Kiểm tra kết quả sau
+> refresh hoặc mở lại nếu yêu cầu cần lưu dữ liệu. Lưu bằng chứng, sửa lỗi trong scope rồi
+> test lại; báo rõ những gì chưa chạy hoặc bị chặn.
+
+Host đọc `harness-end-user-testing` và workflow `end-user-acceptance.md` trước review. Bạn không
+cần tự gọi từng agent; test-engineer có thể chạy tuần tự trong cùng assistant. CLI không tự mở browser,
+khởi động model/server hoặc kết nối account; các thao tác do host được cấp quyền thực hiện.
+
+## Cần cung cấp những gì?
+
+AI đọc repo và câu trả lời đã lưu trước, chỉ hỏi phần còn thiếu:
+
+| Thông tin | Nơi lưu dùng lại |
+| --- | --- |
+| Yêu cầu/AC, luồng và kết quả mong đợi | Nguồn chính trong artifacts.json / spec hiện có |
+| URL môi trường test và phạm vi được phép thao tác | `.harness/local.md` |
+| Lệnh start/test/build và tham chiếu môi trường | `.harness/environment.json` |
+| Tên tool browser/MCP trong host, nếu dùng | `.harness/integrations.json` |
+| Tài khoản/role test | Reference trong context; credential giữ riêng ở host |
+| Nơi lưu báo cáo/bằng chứng | Output contract trong artifacts.json hoặc thư mục verification/ đã review |
+
+Không copy credentials/cookies vào shared config hoặc PR. Thông tin cấu hình được backup bằng
+cơ chế hiện có; screenshot/trace/report/checkpoint cần backup cùng project/evidence, không nằm trong
+archive cấu hình. Nếu output bắt buộc ở hệ thống ngoài nhưng host không ghi được, trả proposal hoặc
+BLOCKED theo policy, không tự tạo một nguồn canonical cục bộ khác.
+
+## AI chọn công cụ theo dự án
+
+| Giao diện thực tế | Cách kiểm tra | Giới hạn cần ghi rõ |
+| --- | --- | --- |
+| Web/React/Next.js/Astro | Playwright/Cypress đang có hoặc browser tool được host cấp quyền | Browser thật; API mock chỉ chứng minh phạm vi giao diện |
+| React Native/mobile | Runner device/simulator hiện có, ví dụ Detox/Maestro | Browser viewport mobile không chứng minh app native |
+| CLI | Chạy executable/lệnh thật, kiểm tra output và file/state | Unit test của hàm xử lý không thay cho terminal journey |
+| Backend/API-only | Client/API workflow qua public endpoints, role và trạng thái | Không giả tạo một UI để gọi đó là browser E2E |
+| Chỉ tài liệu | Đối chiếu nguồn, yêu cầu và consistency | Không quảng cáo app/runtime E2E đã chạy |
+
+Có runner thì dùng tiếp, không cài framework cạnh tranh. Với web chưa có runner, Playwright là một
+phương án đề xuất; lựa chọn và cài dependency/browser thuộc project/host, không do Harness installer.
+Playwright Test và Playwright MCP là hai cách dùng khác nhau: runner thực thi test đã lưu; MCP/browser
+cho host tương tác trực tiếp. Tool alias trong config chưa chứng minh runtime đã kết nối.
+
+## Luồng thực thi
+
+1. Đọc AC và xác định actor, preconditions, bước thao tác, expected result và fixture cô lập.
+2. Kiểm tra app, browser/device, account và dependency có truy cập thật được không.
+3. Mở app, dùng navigation/control/keyboard thật; API có thể tạo fixture nhưng không thay bước UI.
+4. Chạy happy path và tình huống negative/role/state phù hợp với thay đổi. Không bắt mọi dự án
+   test login/CRUD/upload nếu tính năng không có những hành vi đó.
+5. Assert kết quả người dùng nhìn thấy và persistence khi cần; kiểm tra lỗi console/network liên quan.
+6. Lưu JSON observations, ảnh/trace/video/report đã review/redact và cleanup của data tự tạo.
+7. Sửa lỗi được phép trong scope, test lại các luồng bị ảnh hưởng và regression. Không đổi expected
+   result hoặc bỏ assertion để khiến test pass; giữ giới hạn vòng retry/repair của host/project.
+8. Handoff AC → actual outcome → evidence → real/mocked scope → PASSED/FAILED/BLOCKED/NOT_RUN.
+
+Ví dụ minh họa form có lưu dữ liệu: mở form → nhập giá trị hợp lệ → click Save → kiểm tra dòng mới →
+reload → dòng vẫn còn; nhập giá trị sai → đúng thông báo; actor bị hạn chế → action bị từ chối nếu AC
+quy định. Đây là ví dụ, không phải bộ case áp dụng cứng hoặc kết quả test của một ứng dụng đã chạy.
+
+## Plan và bằng chứng
+
+```bash
+aih verify --adaptive
+aih skill harness-end-user-testing
+aih verify --report verification/report.json
+```
+
+Nếu dùng npx, thay `aih` bằng `npx --yes @manhd_d/ai-harness`. Adaptive plan có
+`end_user_acceptance` với gợi ý surface/tools, context còn cần và host_prompt. Đây là metadata plan,
+chưa có thao tác thật. Host cần đọc scoped source và tool runtime để chọn đúng test.
+
+Report schema vẫn là 1; requirement cần end-user thêm:
+
+```json
+{"id":"AC-1","description":"Item survives reload","source":"approved AC reference","verification_target":"end-user","surface":"web"}
+```
+
+Scenario thêm khai báo, dùng URL thực trong môi trường được phép, không chứa credential:
+
+```json
+{"journey":{"surface":"web","actor":"test-editor","entrypoint":"test-page-reference","interaction":"browser","dependencies":"real","attachments":[]}}
+```
+
+Surface/interaction: web/browser, mobile/device, cli/terminal, api/http. Journey methods:
+browser-e2e/web, mobile-e2e/mobile, cli-e2e/cli; api/backend-e2e/authorization/security dùng api.
+end-user hoặc business-workflow có thể dùng surface thích hợp; unit/component/build không là journey. Dependencies: real, mocked,
+not-applicable hoặc unknown. `not-applicable` chỉ dùng khi dependency thực sự không tồn tại trong
+thiết kế, ví dụ calculator chạy hoàn toàn trong browser; không dùng để che backend mock/không truy cập.
+Một requirement web không VERIFIED nhờ journey API/unit. Nếu backend mock/unknown, scoped assertions
+có thể PASSED nhưng end-user target vẫn UNVERIFIED và overall report NOT_RUN.
+
+Attachments tùy chọn: `{kind,path,sha256}` với kind screenshot (.png/.jpg/.jpeg/.webp), trace (.zip),
+video (.webm/.mp4), report (.html/.json). Path tính từ project root; từng file regular không symlink,
+không rỗng, tối đa 50 MiB; tối đa 20 file và 100 MiB tổng mỗi scenario. Binary attachments được kiểm
+tra digest riêng; assertion vẫn đọc JSON evidence ≤1 MiB qua JSON pointer như contract hiện có.
+Không nới giới hạn JSON để đọc binary trace/screenshot. Compress/scope evidence nếu quá giới hạn.
+File-extension/digest chỉ kiểm tra consistency, không giải mã/đánh giá tính đúng của ảnh/trace.
+Review nội dung raw độc lập; binary traces có thể chứa secrets, validator không tự scrub chúng.
+
+Report cũ không khai báo target mới vẫn hợp lệ. Browser/mobile/CLI E2E đòi hỏi assertion ngoài transport:
+chỉ HTTP 200 hay process exit 0 không thể là PASSED. Receipt/semantic labels do producer khai báo;
+validator không xác thực rằng Playwright đã chạy hay nguồn revision đúng. Screenshot đơn lẻ không
+thay cho bước/assertion nghiệp vụ và không phải human UAT approval.
+
+## Thiếu môi trường
+
+Browser executable, device, app URL/start access hoặc account cần thiết bị thiếu → BLOCKED cho luồng
+đó, kèm đúng bước bị chặn và cách xử lý. Chủ động bỏ scope → NOT_RUN với lý do. Tự động hóa được
+thực hiện khi host có tool và quyền; không hứa chạy được mọi app ngay sau một lệnh cài Harness.
+
+[Adaptive report contract](adaptive-verification.md) · [Configuration backup](configuration-backup.md).
+
+## Nguồn công cụ đã review
+
+Official references reviewed 2026-10-14; use the installed project's actual version/configuration:
+[Playwright installation](https://playwright.dev/docs/intro),
+[assertions](https://playwright.dev/docs/test-assertions),
+[locators](https://playwright.dev/docs/locators),
+[trace viewer](https://playwright.dev/docs/trace-viewer),
+[Playwright MCP](https://github.com/microsoft/playwright-mcp).

package/docs/frontend-mobile.md

@@ -74,3 +74,10 @@ Không có trial ứng dụng/browser/native hoặc live-model benchmark trong n
 - [React Native testing](https://reactnative.dev/docs/testing-overview): tách JS component và native/device evidence.
 - [React Navigation auth flow](https://reactnavigation.org/docs/auth-flow/): chỉ áp dụng khi app đang dùng
   React Navigation; giữ version-specific auth/back behavior, không mặc định cài router đó.
+
+## End-user journeys
+
+React/Next.js and React Native module 1.4.0 connect Core harness-end-user-testing to applicable
+browser/device acceptance, existing runners and optional binary evidence.
+[End-user guide](end-user-testing.md) distinguishes native devices from browser viewport emulation,
+real/mocked dependencies and BLOCKED access; unit/build/API checks cannot replace required UI flows.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Bắt đầu với AI Harness
 
-**Cài vào project → mở AI → giao việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
+**Cài vào project → start → mở AI làm việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
 
 ## 1. Cài vào project
 
@@ -31,13 +31,21 @@ npx --yes @manhd_d/ai-harness init --adapters java-spring --capabilities product
 Thêm `--capabilities uiux` khi cần UI/UX; `monetization` cho website có quảng cáo. [Danh mục đầy đủ](cli.md).
 Với project đã cài, đổi lựa chọn trong `.harness/project.json` rồi dùng `update`.
 
-## 2. Mở AI và giao việc
+## 2. Start và mở AI làm việc
 
-Mở thư mục project trong công cụ AI, rồi gửi:
+Chọn `--host codex|claude-code|cursor|copilot|gemini-cli|kiro` khi init. Trong session AI đầu tiên,
+gọi **harness-start** nếu client nhận diện skill; hoặc gửi cùng prompt cho mọi host:
 
-> Đọc AGENTS.md và .harness/local.md. Khảo sát code, tài liệu và lệnh test hiện có;
-> ghi context còn thiếu vào .harness/local.md, chỉ hỏi phần chưa rõ.
-> Thực hiện yêu cầu: [mô tả công việc]. Chạy test phù hợp, báo cáo kết quả và phần chưa kiểm chứng.
+> Đọc .agents/skills/harness-start/SKILL.md và thực hiện onboarding cho project này.
+> Yêu cầu của tôi: [task].
+
+Kiro có `/harness-start`; các host khác có discovery/import riêng trong
+[setup đa IDE](tool-setup/README.md). Agent inspect context, chỉ hỏi điều quan trọng còn thiếu và lưu
+câu trả lời. Không cần interview terminal trước chat. `start --compact --host <host>` là orientation
+read-only; `start` và host_prompt vẫn dùng được khi cần. [Luồng start](start.md).
+
+Cài bằng pip/offline cũng dùng **cùng flow**: `aih init --host <host>` rồi harness-start.
+Cần Python 3.9+ và Node 22+, không cần npm; xem [pip/offline](python-installation.md).
 
 Bạn có thể giao ý tưởng, tài liệu BA hoặc task code. Không cần gọi từng agent/skill.
 Với web/mobile, giao màn hình hoặc tính năng theo common/API/state/navigation hiện có; [skills đã có](frontend-mobile.md).
@@ -65,7 +73,8 @@ Task nhỏ không cần bộ tài liệu đầy đủ. Không cần cài OpenSpe
 
 `check` kiểm tra file Harness; `verify` xuất checklist. Code cần **test của project** và review thực tế.
 
-Trước cập nhật, tạo branch và commit trạng thái hiện tại. Xem trước, áp dụng rồi kiểm tra:
+Trước cập nhật, tạo branch và commit trạng thái hiện tại. Chạy `npx --yes @manhd_d/ai-harness backup`
+và copy JSON được trả về ra nơi riêng ngoài repo. [Lưu ở đâu, cài lại và chuyển dự án](configuration-backup.md). Xem trước, áp dụng rồi kiểm tra:
 
 ```bash
 npx --yes @manhd_d/ai-harness@latest update --dry-run
@@ -84,3 +93,8 @@ canonical owners and source-write scope. Record them in project-owned artifacts.
 `npx --yes @manhd_d/ai-harness artifacts` shows declarations. See [Artifact contract](artifact-contract.md).
 
 For successive features, bugfixes or a resumed session, give the host a normal request. It follows [Continuous development](continuous-development.md), rechecks the baseline and maintains only affected docs.
+
+## Test như người dùng
+
+Giao AI: “Test tính năng này như end user theo AC, thao tác trên giao diện thật, kiểm tra kết quả và
+lưu bằng chứng; báo BLOCKED nếu thiếu tool/môi trường.” [Hướng dẫn và setup cần có](end-user-testing.md).

package/docs/harness-maintenance.md

@@ -15,6 +15,7 @@ gốc được liên kết bên dưới; không sao chép quy tắc thành nhi
 | Artifact / integration contracts | [Artifact contract](artifact-contract.md), [loader](../cli/artifacts.js), [seeds](../templates/artifacts.json) | Preserved project configs → setup/artifacts → Core/Product/UIUX workflows → routed new-doc / impact readiness → [tests](../tests/artifacts.test.js) and package smoke |
 | Agent preferences | [Canonical default](../config/agents.default.json), [configuration contract](agent-configuration.md) | Project-owned `agents.json` → read-only setup plan → [routing workflow](../core/workflows/agent-routing.md) → [host setup](tool-setup/README.md); tests verify preservation, not live model availability |
 | Quy trình sử dụng | [Getting started](getting-started.md), [full SDLC](end-to-end-workflow.md) | [Examples](examples/), [README](../README.md), [documentation workflows](documentation-workflows.md) |
+| Distribution / conformance driver | [pip/offline](python-installation.md), [workflow contract](workflow-contract.md), [runner](conformance-runner.md) | Shared npm allowlist → Python wheel/sdist → launcher/shared CLI → offline parity smoke; installer never imports host execution |
 | Release / migration | [Versioning](versioning.md), [release policy](release-policy.md) | [Changelog](../CHANGELOG.md), [npm release](npm-release.md), [release workflow](../.github/workflows/npm-publish.yml) |
 
 Một quy tắc chỉ hoàn chỉnh khi xác định được: **nơi khai báo → nơi đóng gói → điểm AI đọc → bước áp dụng

package/docs/i18n/README.es.md

@@ -8,17 +8,30 @@ Entrega una idea, docs existentes o un change request a tu AI coding tool. Harne
 
 Los Core workflows sirven para cualquier proyecto. El stack support es opcional y no elige infrastructure ni architecture.
 
-Requiere Node.js 22+. Ejecuta en el directorio del proyecto:
+Requiere **Node.js 22+**. Ejecuta en la raíz del proyecto:
 
 ```bash
-npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness init --host codex
 ```
 
-`npx` no instala el command global `aih`. Comprueba con `npx --yes @manhd_d/ai-harness check` y abre el mismo proyecto en tu AI tool. [Setup común](../tool-setup/README.md).
+Host: codex, claude-code, cursor, copilot, gemini-cli o kiro.
+En la primera sesión invoca harness-start; si el cliente no descubre el skill, envía:
 
-> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
 
-El host ejecuta tests y controla tools, delegation y permissions. MCP/connector/API pueden aportar input con acceso autorizado. init --detect identifica stacks compatibles; check comprueba la integrity de Harness.
+Kiro ofrece `/harness-start`; el descubrimiento depende del cliente. [Guías](../tool-setup/README.md).
+
+**pip / sin conexión** se incluye en la próxima versión revisada; requiere configurar PyPI publisher:
+
+```bash
+python -m pip install manhd-ai-harness
+aih init --host codex
+```
+
+Necesita Python 3.9+ y Node.js 22+; incluye el mismo CLI y recursos, sin ejecutar npm/npx.
+Sin conexión: `python -m pip install --no-index --no-deps /path/to/package.whl`.
+[pip y actualizaciones](../python-installation.md) · [Backup](../configuration-backup.md).
+`npx` no crea un comando global aih; comprueba con `npx --yes @manhd_d/ai-harness check`.
 
 | AI tool | Setup |
 | --- | --- |

package/docs/i18n/README.vi.md

@@ -6,19 +6,32 @@ Agent workflows tái sử dụng cho phát triển phần mềm: **Requirements
 
 Đưa ý tưởng, docs có sẵn hoặc change request cho AI coding tool. Harness giúp AI đọc project, làm rõ quyết định, triển khai scope đã chấp nhận và maintain spec/docs liên quan. Chỉ dùng roles và skills cần cho task.
 
-Core workflows dùng được với mọi project. Stack support là tùy chọn; không tự chọn infrastructure hay architecture.
+Core dùng được với mọi project; stack adapter là tùy chọn.
 
-Cần Node.js 22+. Chạy trong project:
+Cần **Node.js 22+**. Chạy trong project root:
 
 ```bash
-npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness init --host codex
 ```
 
-`npx` không cài global command `aih`. Kiểm tra bằng `npx --yes @manhd_d/ai-harness check`, rồi mở cùng project trong AI tool. [Setup chung](../tool-setup/README.md).
+Chọn host: codex, claude-code, cursor, copilot, gemini-cli hoặc kiro.
+Session AI đầu tiên: gọi **harness-start** nếu host nhận diện; hoặc gửi:
 
-> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
+> Đọc .agents/skills/harness-start/SKILL.md và thực hiện cho project này. Task: [yêu cầu].
 
-Host chạy tests và quản lý tools, delegation, permissions. MCP/connector/API có thể cung cấp input khi host có quyền truy cập. init --detect nhận diện stack hỗ trợ; check kiểm tra integrity của Harness.
+Kiro có `/harness-start`; discovery tùy client. [Setup đa IDE](../tool-setup/README.md).
+
+**pip/offline** được bổ sung trong release tiếp theo, cần cấu hình PyPI publisher:
+
+```bash
+python -m pip install manhd-ai-harness
+aih init --host codex
+```
+
+Cần thêm Python 3.9+, vẫn cần Node 22+; cùng CLI/assets, không gọi npm/npx.
+Offline: `python -m pip install --no-index --no-deps /path/to/package.whl`.
+[pip và cập nhật](../python-installation.md) · [Backup và chuyển dự án](../configuration-backup.md).
+`npx` không tạo global aih; dùng `npx --yes @manhd_d/ai-harness check` kiểm integrity.
 
 | AI tool | Setup |
 | --- | --- |

package/docs/i18n/README.zh-CN.md

@@ -8,17 +8,30 @@
 
 Core workflows 可用于任何项目。Stack support 是可选的，不会自动选择 infrastructure 或 architecture。
 
-需要 Node.js 22+。在项目目录运行：
+需要 **Node.js 22+**。在项目根目录运行：
 
 ```bash
-npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness init --host codex
 ```
 
-`npx` 不会安装全局 `aih` command。使用 `npx --yes @manhd_d/ai-harness check` 检查，然后在 AI tool 中打开同一项目。[通用 Setup](../tool-setup/README.md)。
+host 可选 codex、claude-code、cursor、copilot、gemini-cli 或 kiro。
+首次 AI 会话调用 harness-start；如果客户端未发现技能，请发送：
 
-> Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.
+> Read .agents/skills/harness-start/SKILL.md and follow it for this project. My task: [task].
 
-Host 执行 tests，并控制 tools、delegation 和 permissions。MCP/connector/API 可在 host 获得访问权限后提供 input。init --detect 用于支持的 stack；check 检查 Harness integrity。
+Kiro 提供 `/harness-start`；原生发现因客户端而异。[多 IDE 指南](../tool-setup/README.md)。
+
+**pip / 离线安装**将在下一次审核后的版本中提供，首次发布需要配置 PyPI publisher：
+
+```bash
+python -m pip install manhd-ai-harness
+aih init --host codex
+```
+
+需要 Python 3.9+ 和 Node.js 22+；使用相同 CLI/资源，不调用 npm/npx。
+离线：`python -m pip install --no-index --no-deps /path/to/package.whl`。
+[pip 与更新](../python-installation.md) · [备份](../configuration-backup.md)。
+`npx` 不创建全局 aih；用 `npx --yes @manhd_d/ai-harness check` 检查文件完整性。
 
 | AI tool | Setup |
 | --- | --- |

package/docs/project-configuration.md

@@ -2,6 +2,7 @@
 
 | File | Nội dung | Git |
 | --- | --- | --- |
+| `.harness/start.json` | Mục tiêu/task và ID checkpoint nếu tiếp tục | Commit |
 | `.harness/project.json` | Adapter/capability | Commit |
 | `.harness/agents.json` | Provider/model/reasoning theo role, execution preferences và host mappings | Commit |
 | `.harness/artifacts.json` | Input/output/storage, canonical ownership và source-write policy | Commit |
@@ -10,7 +11,7 @@
 | `.harness/environment.json` | Công cụ, lệnh, file cần có | Commit |
 | `.harness/machine.json` | Đường dẫn riêng của máy, tùy chọn | Ignore |
 
-Init/update tạo environment rỗng nếu chưa có và thêm `/machine.json` vào cuối
+Init/update tạo environment rỗng nếu chưa có và thêm `/backups/` và `/machine.json` vào cuối
 `.harness/.gitignore`. File đã được Git track vẫn được track: ignore không xóa khỏi index/history.
 CLI không tạo file machine và không đọc nội dung Maven settings. Không ghi mật khẩu/token vào các
 file Harness; credentials thuộc cơ chế quản lý riêng của công cụ.
@@ -91,3 +92,16 @@ local.md đã trả lời. Setup không phải wizard nhập liệu và không t
 Xem [Artifact contract](artifact-contract.md). `aih artifacts` báo khai báo; `aih setup` gợi ý hỏi
 nơi lưu docs/UI nếu chưa biết. Các file này project-owned và được bảo toàn khi update; chúng không
 kết nối MCP, cấp quyền hay chạy tool. Credentials và native host config nằm ngoài Git.
+
+## Backup và dùng lại
+
+Chạy `aih start` để lưu intake. File được bảo toàn khi update. Chạy `aih backup`, copy archive ngoài
+repo; `aih restore --from <file> --dry-run` xem trước phục hồi. Dùng --transfer ở repo mới để chỉ
+chuyển module/model, tránh nguồn/tiến độ cũ. [Hướng dẫn đầy đủ](configuration-backup.md) mô tả các
+file được lưu, những gì không có trong backup, conflict/backup-before-replace và cách cài lại.
+
+## Structured context and skill prerequisites
+
+New local.md uses optional schema-1 YAML frontmatter; legacy prose stays valid and preserved.
+See [session onboarding](session-onboarding.md) for sources, seed and doctor --skill requirements.
+Maven settings remain files.maven-settings.path with a machine override, not tools.maven.settings.