@manhd_d/ai-harness 0.14.0 → 0.15.0

package/core/workflows/workflow.schema.json

@@ -0,0 +1,113 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "owner": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
+          },
+          "outputs": {
+            "type": "array",
+            "maxItems": 64,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[A-Za-z0-9._/-]+$"
+            }
+          },
+          "next": {
+            "type": "array",
+            "maxItems": 64,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+            }
+          },
+          "on_reject": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "on_fail": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "entry_gate": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "deterministic": {
+                "type": "array",
+                "maxItems": 64,
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "spec-structure",
+                    "decisions-resolved",
+                    "tasks-present",
+                    "tasks-complete",
+                    "verification-evidence",
+                    "artifact-impact",
+                    "outputs-present"
+                  ]
+                }
+              },
+              "approval_from": {
+                "type": "string"
+              }
+            },
+            "required": []
+          },
+          "approval": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "role": {
+                "enum": [
+                  "spec-owner",
+                  "product-owner",
+                  "reviewer"
+                ]
+              }
+            },
+            "required": [
+              "role"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "owner",
+          "next"
+        ]
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "id",
+    "stages"
+  ],
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/manh0303/ai-harness/workflow.schema.json",
+  "description": "Shape contract. Consumers also validate unique stage IDs, registered owners, transitions, forward DAG and approval sources."
+}

package/docs/README.md

@@ -48,3 +48,11 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 
 - [Start theo input hiện có](start.md)
 - [Lưu cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md)
+
+- [Kiểm thử như người dùng thật: browser/device/CLI/API](end-user-testing.md)
+
+- [Session onboarding, seed, prerequisites và role extensions](session-onboarding.md)
+
+- [pip/offline installation](python-installation.md)
+- [Workflow contracts and approval records](workflow-contract.md)
+- [Opt-in conformance runner](conformance-runner.md)

package/docs/adaptive-verification.md

@@ -40,7 +40,7 @@ Evidence is `{path,sha256}` with a real local regular file, maximum 1 MiB. Asser
 
 Supported operators: equal, not-equal, contains, type. Layers: transport, schema, business, state, authorization, result. Assertion basis must reference the scenario's requirement. Optional typed observed must match raw JSON. Expected values come from reviewed AC/contracts, never copied from observations just to pass.
 
-PASSED requires successful execution receipt, nonempty matching assertions, allowed error semantics and successful mutation cleanup. API/backend-e2e/business-workflow/authorization/security also require a nontransport assertion. `error: {kind,message}` distinguishes timeout/network/http/application/assertion/environment. `expected_error` can only name http/application and still needs assertions; arbitrary catch is never success. Contradictory status is rejected. FAILED dominates the overall result, then BLOCKED, then NOT_RUN or missing coverage. A requirement is VERIFIED only if all its linked scenarios pass; otherwise UNVERIFIED. Empty coverage cannot pass.
+PASSED requires successful execution receipt, nonempty matching assertions, allowed error semantics and successful mutation cleanup. API/backend-e2e/business-workflow/authorization/security/browser-e2e/mobile-e2e/cli-e2e also require a nontransport assertion. `error: {kind,message}` distinguishes timeout/network/http/application/assertion/environment. `expected_error` can only name http/application and still needs assertions; arbitrary catch is never success. Contradictory status is rejected. FAILED dominates the overall result, then BLOCKED, then NOT_RUN or missing coverage. A requirement is VERIFIED only if all its linked scenarios pass; otherwise UNVERIFIED. Empty coverage cannot pass.
 
 Digests detect evidence drift. Execution receipts and semantic layer labels are producer-declared: validation does not authenticate that a command ran, a requirement is correct, cleanup truly occurred or the recorded revision matches source. Independently inspect raw logs/source and business assertions. Redact secrets before reports; automatic credential screening is limited and does not replace review. Paths/symlinks and oversized evidence fail safely.
 
@@ -57,3 +57,12 @@ Use test-owned UUIDs and isolated fixtures, bounded retries/timeouts and cleanup
 Live agent evaluation is BLOCKED until an intended host/model and authorized budget are available. Reuse Core/Product cases via `aih eval --scope all` and the existing eval rubric; run the same requirement/code fixtures with baseline and candidate, record versions and raw evidence, compare success, denied effects, gaps, measured latency/tokens/cost. Unscored cases remain unscored. See [evaluation guide](../evals/README.md).
 
 Reference review reused generic lifecycle, role/state/error and selective-maintenance patterns. Hardcoded project ports/accounts, database mutation snippets, kill-by-port, false expected-error success and CRM-specific contracts were deliberately excluded.
+
+## End-user verification target
+
+For user-facing acceptance, use [End-user testing](end-user-testing.md). Adaptive discovery now exports
+end_user_acceptance hints and a host handoff. Requirement verification_target=end-user requires a
+web/mobile/cli/api surface; a matching passing journey using actual interface interaction and
+real/not-applicable dependencies must exist. Mock/unknown or another interface cannot satisfy it.
+Existing behavior-only schema-1 reports remain valid. Optional journey attachments use separate
+bounded binary digests rather than JSON assertion evidence; the guide defines limits and semantics.

package/docs/agent-configuration.md

@@ -101,3 +101,10 @@ budget meter is inferred from model tiers, maxRounds or concurrency. See [Agent
 ## Agent-first defaults and declarations (unreleased)
 
 New seeds use host/host-default so the actual host model remains selected; old agents.json is preserved. Claude host init offers native aliases only when absent. aih agents resolves canonical role IDs and required/optional skill preferences. Optional execution.autonomy and execution.budget are validated declarations, not execution permission or quota enforcement. Checkpoint real usage or unknown; never infer cost or auto-escalate. See [Agent-first guide](agent-first.md).
+
+## Project role extensions
+
+Role overrides can add `extensions: ["plugins/project/agents/security-reviewer.md"]`.
+`aih agents` exports core-first contract_load_order and blocks missing extensions. The host loads
+them in order, preserving core security and reconciling conflicts. Extensions do not transfer to
+another project. See [session contracts](session-onboarding.md#role-extensions).

package/docs/agent-handoffs.md

@@ -22,7 +22,7 @@ including reused public APIs and unavailable browser/native checks; retain the s
 | [documentation](../core/agents/documentation.md) | Verified sources and decisions | Source-linked document diff and quality evidence | Invent approval or unperformed verification |
 | [planner](../core/agents/planner.md) | Scope, approved requirements, repo map | OpenSpec design/tasks/test outline | Implement ngoài scope |
 | [implementer](../core/agents/implementer.md) | Spec, tasks, repo, adapter | Code slice và actual test evidence | Merge/deploy |
-| [test-engineer](../core/agents/test-engineer.md) | AC, diff, contracts | Test scenarios, executed results/gaps | Tuyên bố pass khi chưa chạy |
+| [test-engineer](../core/agents/test-engineer.md) | AC, diff, contracts | Actual user journeys, outcomes/evidence, real/mocked scope and blockers | Tuyên bố pass khi chưa chạy |
 | [security-reviewer](../core/agents/security-reviewer.md) | Auth/data scope/tools/migration | Threats, mitigations và review findings | Bỏ qua chính sách quyền |
 | [reviewer](../core/agents/reviewer.md) | Diff, spec, findings/evidence | Review recommendation và residual risk | Tự merge PR |
 
@@ -108,3 +108,8 @@ Use [Continuous development](continuous-development.md). Store baseline/tested r
 ## Agent-first routing and PM aliases
 
 [Canonical Project Manager](../core/agents/project-manager.md) owns delivery. Product/Delivery PM IDs are compatibility aliases; route by canonical_id, not separate workers. Analysis/Discovery agents use canonical Product contracts above. Preferred skills are explicit; optional perspectives need not be installed. See [Agent-first migration](agent-first.md).
+
+For end-user QA, the existing test-engineer uses Core harness-end-user-testing and
+[end-user acceptance](end-user-testing.md). Pass app entry/environment, actor references, AC surface,
+actual interactions/outcomes, redacted trace/screenshot/report digests, dependency scope and cleanup.
+These receipts do not supply business-owner UAT approval or model-compliance evaluation.

package/docs/architecture.md

@@ -3,7 +3,8 @@
 Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
 
 AI Harness is a versioned instruction and workflow distribution framework. Its executable part is a
-local installer and integrity checker. It is not an LLM gateway, an orchestration server or a sandbox.
+local installer and integrity checker, with a separate opt-in conformance host driver.
+It is not an LLM gateway, an orchestration server or a sandbox.
 
 | Layer | Responsibility | Owner |
 | --- | --- | --- |
@@ -69,9 +70,11 @@ See docs/adapters.md for the strict JSON-compatible YAML contract. Detection is
 checks are advisory and never executed. Installed capabilities are read from the locked snapshot, not
 from the latest global CLI source. Core TDD/debug/review are not duplicated in adapters.
 
-## npm distribution
+## npm and Python distribution
 The package exposes bin/aih.js as `aih`. It uses native JavaScript ES modules and Node.js built-ins:
-there is no Python bridge, transpilation step, runtime dependency, network client or install hook.
+the npm executable has no runtime dependency, network client or install hook. The pip distribution
+adds a thin Python launcher for the same JavaScript CLI; Node.js 22+ remains required. Its wheel
+contains the shared package allowlist, with no npm/npx invocation or Python runtime dependencies.
 Source paths resolve relative to the package, not cwd. The target defaults to cwd. Local node_modules
 installation is an explicit exception to overlap rejection; payload destinations never include node_modules.
 The npm files allowlist ships runtime assets including the hidden OpenSpec template. A smoke test packs
@@ -166,3 +169,40 @@ saves a before-backup through the same installation guard/rollback machinery. Tr
 project/agent preferences and removes repository autonomy. No credentials, machine paths, locked
 payload, custom skills or checkpoint/document contents are exported. Full repo recovery remains Git
 and external-source backup. See [Configuration backup](configuration-backup.md).
+
+## End-user acceptance
+
+Core test-engineer routes public journeys to harness-end-user-testing and the end-user-acceptance
+workflow. Adaptive CLI exports tool/surface hints only; the host executes actual interfaces. Optional
+schema-1 journey declarations and bounded binary attachment digests qualify explicitly requested
+end-user requirements by matching surface and dependency scope. Receipts are producer declarations,
+not authenticated browser/model execution or UAT approval. No browser dependency/runner enters the CLI.
+See [End-user testing](end-user-testing.md).
+
+## Session onboarding and Kiro bridge (unreleased)
+
+Core harness-start delegates semantic seed/questions to the host. Optional local.md frontmatter is
+bounded YAML/JSON; legacy prose is preserved. CLI seed stores local source/config hashes in project
+knowledge.json outside the managed lock. --host kiro installs locked native wrappers and SessionStart
+v1; requires are read-only prerequisites, extensions are host loading plans, MCP sync imports aliases
+only. No model/runtime, provider probe, network or shell execution. See [contracts](session-onboarding.md).
+
+setup stays read-only by default; setup --apply restores missing shared seeds from the locked installed
+snapshot without changing managed assets or lock. It validates existing and proposed config before
+transactional writes. Optional project-owned decisions.json separates confirmed/proposed/superseded
+project/module choices from per-change decisions. Config backup retains shared decisions, transfer
+omits them, and context freshness includes their digest. Compact start provides orientation only,
+with freshness unchecked. None of these declarations grant permission or prove live host compliance.
+
+## Contract, driver and evidence planes
+
+| Plane | Harness responsibility | Execution owner |
+| --- | --- | --- |
+| Contract | Workflow stage/entry gate/role/artifact declarations | Harness owns schema; host applies semantics |
+| Driver | Optional separate conformance script; no execution in cli/ | Host or replaceable engine such as Temporal |
+| Evidence | Evaluation/verification/approval record formats | Producer/reviewer owns truth and identity |
+
+core:orchestrator is a role, not an engine. JSON contracts currently cover spec-to-code and selected
+Product idea-to-prd; validation/entry readiness neither executes stages nor authenticates approval.
+See [workflow contracts](workflow-contract.md), [conformance driver](conformance-runner.md), and
+[pip/offline distribution](python-installation.md). The non-goal remains: no LLM gateway or server.

package/docs/cli.md

@@ -13,10 +13,11 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
 | verify | --scope adapters/core/capabilities/all or --adaptive or --report file | Advisory checks, metadata plan or evidence consistency; executed false, no subprocesses |
 | eval | --scope adapters/core/capabilities/all; --report FILE | Emit unscored template or aggregate reviewed report; no model calls |
 | init | --detect OR --adapters a,b; --capabilities a,b; --agent-preset recommended/economy/custom; --source; --dry-run; --allow-major | Install a snapshot and seed project agent preferences; exact rerun without explicit preset is idempotent |
-| update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
+| update | --host kiro (optional); --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
 | check | none | Compare installed files/block with lock and selection; no writes |
-| doctor | none | check plus configured environment/path diagnostics and generic PATH hints; no execution |
-| setup | --host codex/claude-code/gemini-cli/cursor/copilot/custom-ID (optional) | Read-only question and agent-routing plan; skips tool-selection suggestions when tools are configured |
+| doctor | --skill NAME (optional) | check plus configured environment/path diagnostics and generic PATH hints; no execution |
+| setup | --host; --apply [--dry-run]; --greenfield | Read-only by default; --apply creates missing user config from installed templates without reinstalling the snapshot |
+| decisions | --scope project/module:name (optional) | Read confirmed/proposed/superseded shared choices; project scope is included in module results; no approval or writes |
 | artifacts | none | Report declared inputs/outputs/storage/write policy and host connection aliases; no discovery or tool calls |
 | ready ID | --stage implement/review | Structural readiness; blocked returns exit 1, ready returns exit 0; no business approval |
 | new-change ID | none | Create an unapproved OpenSpec draft using installed templates |
@@ -170,7 +171,7 @@ aih agents shows canonical IDs, skill preferences and model declarations. init -
 | --- | --- |
 | `aih start` | Terminal: intake ngắn; không TTY: read-only plan; trả host_prompt |
 | `aih start --goal docs --task "Implement requirements" --input docs/requirements --output docs/specs` | Lưu task và seed nguồn/output còn thiếu |
-| `aih backup [--output backups/config.json]` | Export 8 file cấu hình dùng chung; không ghi đè archive |
+| `aih backup [--output backups/config.json]` | Export tối đa 9 file cấu hình dùng chung, gồm decisions.json; không ghi đè archive |
 | `aih restore --from config.json --dry-run` | Kiểm tra schema/digest và xem file/conflict trước ghi |
 | `aih restore --from config.json [--replace]` | Phục hồi cùng dự án, tự backup trước thay file khác nội dung |
 | `aih restore --from config.json --transfer` | Chuyển module/model; bỏ repo autonomy và nguồn/task/domain/command cũ |
@@ -180,3 +181,37 @@ Tất cả nhận --target. Đường dẫn --from/--output tính từ project r
 không đổi target hoặc chờ stdin. Fresh repo restore trước init; installed repo update/check sau khi
 selection đổi. Đọc [Start](start.md) và [Configuration backup](configuration-backup.md) cho giới hạn,
 phục hồi checkpoint và rollback. Các lệnh không truy cập remote, chạy model, cấp quyền hay auto-merge.
+
+## End-user acceptance (unreleased)
+
+verify --adaptive exports end_user_acceptance with metadata surface/tool candidates, required context,
+Core skill/workflow references and a host prompt. The CLI does not execute interfaces or install tooling.
+verify --report accepts optional schema-1 end-user requirement targets, surface/journey fields and
+separately bounded binary attachment digests. Wrong-surface/mocked/unknown scope cannot satisfy full
+end-user acceptance. See [End-user guide](end-user-testing.md); producer receipts need independent review.
+
+## Session onboarding commands
+
+See [Kiro quick start](tool-setup/kiro.md) and [schema/ownership](session-onboarding.md).
+
+| Command | Options | Effect |
+| --- | --- | --- |
+| init / update | --host kiro | Lock native wrappers + v1 SessionStart; preserve custom host files |
+| start | --host kiro | Read-only host question plan, including TTY |
+| start | --compact [--host kiro] | Short JSON orientation without terminal intake/source scan; freshness is unchecked, no MCP access claim |
+| setup | --apply [--dry-run]; --greenfield | Scaffold missing user config only; existing paths/answers and managed payload/lock stay intact; --greenfield selects host guidance |
+| decisions | --scope module:name | Read project-wide and matching module choices; host must check source applicability |
+| seed | --record OR --check | Plan loading, record reconciled hashes or check freshness; no model calls |
+| doctor | --skill NAME | Check local requires; MCP remains unverified |
+| sync-integrations | --host kiro; --from FILE; --dry-run | Import aliases only; no credentials/server execution/tool inference |
+| change-sidecars ID | none | Add missing external proposal sidecars; no overwrite |
+
+New commands require supporting reviewed source/release.
+
+## Workflow contract (schema 1)
+
+`aih workflow validate` validates locked installed workflows without execution.
+`aih ready <id> --workflow spec-to-code --stage implement` opts into declared entry/approval gates;
+`--workflow idea-to-prd` requires Product. Legacy implement/review without --workflow retain behavior.
+[Contract and approvals](workflow-contract.md). Runner stays separate: [conformance](conformance-runner.md).
+All CLI commands also work through [pip/offline](python-installation.md); Node.js 22+ still required.

package/docs/configuration-backup.md

@@ -17,6 +17,7 @@ chỉ dùng với bản đã phát hành có các lệnh đó, hoặc checkout/p
 | `.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 |
@@ -45,7 +46,7 @@ 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 8 file dùng chung ở bảng (nếu hiện có), kèm schema version,
+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.
@@ -115,8 +116,15 @@ aih start
 ```
 
 Transfer mang **project.json + agents.json**: adapter/capability và model/reasoning/execution preferences.
-Khai báo autonomy gắn repo cũ bị loại bỏ. Task, domain facts, nguồn input/output, connection aliases,
+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

@@ -33,12 +33,19 @@ Với project đã cài, đổi lựa chọn trong `.harness/project.json` rồi
 
 ## 2. Start và mở AI làm việc
 
-Chạy `npx --yes @manhd_d/ai-harness start`: trả lời mục tiêu/input/output còn thiếu, rồi gửi
-`host_prompt` từ kết quả vào AI tool đang mở project. [Luồng start](start.md). Nếu đã biết task, có thể gửi thẳng:
+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).
@@ -86,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