@manhd_d/ai-harness 0.6.2 → 0.8.0

package/docs/documentation-workflows.md

@@ -69,3 +69,10 @@ Risks/unknowns: threshold and privacy requirements pending decision
 Permissions: read/write authorized project branch only; no external publish or merge
 Human reviewer: developer or named BA/PO
 ```
+
+## Product → solution → delivery
+
+For new/material journeys, reuse existing BA documents and continue with [Solution workflow](solution-workflow.md).
+PO defines a usable MVP and evidence-backed outcomes, SA evaluates quality/architecture/contracts,
+PM sequences dependent value slices. Accepted decisions and requirement IDs feed OpenSpec and adapters.
+Depth scales to the task; no mandatory full document set for small fixes. Use [tool setup](tool-setup/README.md).

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

@@ -1,6 +1,6 @@
 # Full SDLC — Idea → Product → UI/UX → Spec → Code → Test → PR → Release → Operate
 
-Tài liệu này là **bản đồ điều phối** toàn bộ Core + Product + UI/UX + technology adapters + DevOps. Mỗi module vẫn có workflow riêng; chỉ **kích hoạt module đã cài và thật sự liên quan**, không bắt buộc dùng đủ tất cả cho một change. Bắt đầu với [Getting started](getting-started.md); xem [ma trận 53 skills](skill-matrix.md) và [role handoffs](agent-handoffs.md).
+Tài liệu này là **bản đồ điều phối** toàn bộ Core + Product + Architecture + Delivery + UI/UX + technology adapters + DevOps. Mỗi module vẫn có workflow riêng; chỉ **kích hoạt module đã cài và thật sự liên quan**, không bắt buộc dùng đủ tất cả cho một change. Bắt đầu với [Getting started](getting-started.md); xem [ma trận 64 skills](skill-matrix.md) và [role handoffs](agent-handoffs.md).
 
 > **Ranh giới thực thi:** `aih` cài/gợi ý rules, templates, skills và check/eval **advisory**. AI host/IDE và các công cụ bên ngoài thực hiện phân tích, code, test và tương tác hệ thống trong phạm vi được cấp quyền. Không có `aih run` hay `aih deploy`; các hành động ghi Figma, production hoặc merge phải có phê duyệt.
 
@@ -41,6 +41,8 @@ Lệnh trên là **ví dụ một repo chứa BE/FE/manifests**; nếu frontend/
 | **1. Intake** | Ý tưởng, ticket, Confluence/PDF được phép đọc, version/source, scope | Product: `knowledge-analysis`, `business-analysis`; BA | Source register, FACT/INFERENCE/UNKNOWN, AS-IS/TO-BE, quyết định còn thiếu |
 | **2. Business & Product** | Nguồn có traceability, mục tiêu, rules, NFR | Product: `brd-generation`, `prd-generation`, `user-stories`, `acceptance-criteria`, `backlog-prioritization`, `document-review`, `traceability`; PM/PO/requirements reviewer | PRD-lite hoặc BRD/PRD/SRS/UC khi cần, story IDs, AC, backlog; **Gate A: stakeholder duyệt**, không gắn nhãn Approved bởi AI |
 | **3. UX/UI (nếu cần)** | Approved PRD/stories/AC; Figma file và quyền (nếu dùng) | UI/UX: `requirements-analysis` (chỉ khi cần), `user-flow`, `screen-planning`, `design-system`, `figma-design`, `design-review` | User flows, screen specs, component/tokens, Figma node IDs; **Gate B trước ghi Figma**, gate sau design review |
+| **3a. Solution architecture (when material)** | Reviewed MVP/AC, existing decisions and constraints | Architecture skills/SA and reviewer | Source-linked context, NFR scenarios, module/data/contracts, ADRs and critical failure flows |
+| **3b. Delivery planning (when material)** | Accepted scope/design, known estimates/dependencies | Delivery skills/Project Manager | Value slices, owners, risks, checkpoints and actual estimate authority |
 | **4. Technical spec** | Approved requirements, API constraints, architecture, DB/event contracts | Core: `harness-spec`, planner; tech adapter phù hợp; OpenSpec | `openspec/changes/<change-id>/` (proposal, design, tasks, delta specs), measurable AC; **Gate C: duyệt thay đổi có ảnh hưởng** |
 | **5. Implementation** | Change được duyệt, kiến trúc, repo, tests | Core: `harness-tdd`, `harness-debugging` khi sửa lỗi; Spring/React/Native/AI adapter theo stack; implementer | Minimal code diff, unit/integration/contract tests, migration plans, không thay đổi unrelated files |
 | **6. Verify & code review** | Diff, specs, test logs thực chạy | Core: `harness-review`, `harness-ai-evaluation` nếu AI; test-engineer/security-reviewer; `aih verify/eval --scope all` (chỉ plan) | Evidence của test chạy thực tế, scope chưa test, security findings, trace requirement → test; **Gate D: human PR review** |
@@ -114,3 +116,10 @@ aih check
 **Checklist hoàn thành một change:** scope và approved AC rõ; diff có trace; tests thực chạy với kết quả chính xác; security/permissions đã review; CI xanh; PR được human quyết định; deployment (nếu có) có artifact/environment approval; OpenSpec archive/sync **chỉ sau khi các PR liên quan đã merge**, thông qua upstream CLI/human được quyền.
 
 Xem [handoff contracts](agent-handoffs.md), [OpenSpec integration](openspec.md), [DevOps PR-to-production](../capabilities/devops/workflows/pr-to-production.md) và các [ví dụ theo stack](getting-started.md#ví-dụ-thực-hành).
+
+For new/material journeys use [Solution workflow](solution-workflow.md); for existing clear fixes keep
+a compact source/impact note. Set up the host with [Coding tools](tool-setup/README.md).
+
+Before assigning roles, apply [Agent configuration](agent-configuration.md) and Core routing workflow.
+Use one session for simple work, hybrid only for independent authorized work with host support, and
+carry short source/evidence handoffs. User preferences do not grant runtime permissions or model access.

package/docs/getting-started.md

@@ -28,6 +28,10 @@ Chọn module theo nhu cầu, không cần cài cả bộ:
 
 ## 2. Ghi context và bắt đầu giao việc
 
+Chạy `aih setup` rồi nhờ AI đọc workflow `project-setup`. Đây là gợi ý cho AI host, không phải wizard
+nhập liệu của CLI. AI đọc repo trước, chỉ hỏi 1–3 câu A/B/C cho điểm còn thiếu, có đề xuất và lý do.
+Không cần xác nhận lại thông tin hoặc quyền triển khai đã có.
+
 Điền `.harness/local.md` bằng thông tin thực của project:
 
 - Mục tiêu, phạm vi và quy tắc nghiệp vụ quan trọng.
@@ -43,6 +47,10 @@ Bạn không cần gọi từng role/skill thủ công. Nếu host không tự p
 
 Review diff và kết quả test, rồi commit `AGENTS.md`, `.harness/`, `.agents/skills/` và tài liệu thay đổi cùng project. Sửa quy tắc riêng trong `.harness/local.md`; giữ nguyên snapshot do Harness quản lý.
 
+Lệnh/tool chung thuộc `.harness/environment.json`; đường dẫn máy riêng thuộc file ignored
+`.harness/machine.json`. `aih doctor` kiểm tra tham chiếu biến và sự hiện diện công cụ, không chạy chúng.
+Xem [cấu hình Maven nội bộ](project-configuration.md).
+
 ## 3. Tài liệu và spec khi cần
 
 Với capability `product`:
@@ -59,7 +67,9 @@ Khi một tính năng cần proposal/design/tasks/spec riêng:
 aih new-change add-customer-search
 ```
 
-Đây là bản nháp trong `openspec/changes/add-customer-search/`, chưa phải spec được duyệt. Sửa nhỏ, ít rủi ro có thể bỏ qua full spec với lý do rõ ràng; không bắt mọi task tạo đủ BRD/PRD/SRS.
+Đây là bản nháp trong `openspec/changes/add-customer-search/`, chưa phải spec được duyệt.
+AI ghi câu trả lời thực tế trong `decisions.json`; kiểm tra bằng `aih ready add-customer-search --stage implement`.
+Sau code, ghi bằng chứng trong `verification.json` và chạy với `--stage review`. Xem [Change readiness](change-readiness.md). Sửa nhỏ, ít rủi ro có thể bỏ qua full spec với lý do rõ ràng; không bắt mọi task tạo đủ BRD/PRD/SRS.
 
 `aih new-change` không cần OpenSpec CLI. Chỉ cài OpenSpec riêng khi cần validator/archive của công cụ đó; xem [OpenSpec](openspec.md).
 
@@ -68,7 +78,7 @@ aih new-change add-customer-search
 | Lệnh | Ý nghĩa |
 | --- | --- |
 | `aih check` | Kiểm tra integrity của file Harness; không kiểm thử ứng dụng |
-| `aih doctor` | Thêm kiểm tra sự hiện diện của công cụ; không xác nhận công cụ chạy được |
+| `aih doctor` | Kiểm tra công cụ và environment đã cấu hình; không chạy build/test |
 | `aih verify --scope all` | Xuất checklist, `executed: false`; không chạy build/test |
 | `aih eval --scope all` | Xuất tình huống và báo cáo chưa chấm; không gọi model |
 | Lệnh test của project | Do bạn, AI host hoặc CI thực chạy để xác minh code |
@@ -98,3 +108,20 @@ Nếu cài local trong project, dùng `npm install --save-dev @manhd_d/ai-harnes
 - [Spring Boot API](examples/spring-boot-api.md) · [Full-stack](examples/fullstack-web.md) · [React Native](examples/react-native-app.md) · [Python AI/RAG](examples/ai-rag-service.md).
 - [Astro micro-tools](examples/astro-micro-tools.md) · [Astro + AdSense](examples/astro-adsense-microtools.md).
 - [Release guide](npm-release.md): dành cho maintainer; merge source không đồng nghĩa npm đã có bản mới.
+
+## Coding conventions
+
+Trước code, áp dụng [Project conventions](project-conventions.md): xác định new/maintain/mixed theo module, đọc chuẩn hiện có, tìm common và ghi lý do tạo mới. AI lưu nguồn và quyết định trong `.harness/local.md`; không hỏi lại thông tin đã rõ.
+
+## BA/PO/SA/PM and coding tools
+
+For a material new project choose `--capabilities product,architecture,delivery` with the actual adapter.
+Read [Solution workflow](solution-workflow.md) and the [setup guide for your coding tool](tool-setup/README.md).
+Skills/templates are selective context; use existing approved documents and compact notes when sufficient.
+
+## Agent model and execution preferences
+
+New installs seed `.harness/agents.json`: Sol recommended, hybrid/two concurrent agents only when
+supported; Luna low documentation, no automatic Astra escalation. Edit provider/model/reasoning and
+execution for your actual host. Use `aih setup --host codex` and [Agent configuration](agent-configuration.md).
+For a new economy consumer use `aih init --agent-preset economy`; never overwrite an existing config.

package/docs/harness-maintenance.md

@@ -0,0 +1,80 @@
+# Nâng cấp AI Harness không bỏ sót thành phần
+
+Đây là đầu mối dành cho người và AI sửa **repository AI Harness**, không phải quy trình phát triển
+ứng dụng của consumer. Đọc tài liệu này trước khi sửa Harness. Giữ thông tin chuyên biệt ở tài liệu
+gốc được liên kết bên dưới; không sao chép quy tắc thành nhiều bản có thể mâu thuẫn.
+
+## Bản đồ trách nhiệm và liên kết
+
+| Thành phần | Nguồn chính | Nơi được sử dụng / kiểm chứng |
+| --- | --- | --- |
+| Core | [Rules](../core/rules/), [policies](../core/policies/) | [AGENTS template](../templates/AGENTS.md) → [workflows](../core/workflows/) → [roles](../core/agents/), [skills](../core/skills/) → [checks](../core/checks/verification.json), [evals](../core/evals/cases.json) |
+| Adapter | [Registry](../harness.yaml), [adapter contract](adapters.md), [adapter assets](../adapters/) | Manifest `rules/skills/verification/evaluation` → [bundle/install](../cli/harness.js) → [installed verify/eval](../cli/adapters.js) |
+| Capability / skill | [Capability assets](../capabilities/), [schema/loader](../cli/capabilities.js) | Workflow/role bàn giao → exposed skill → [skill matrix](skill-matrix.md), [handoffs](agent-handoffs.md), [composition evals](../core/evals/composition.json) |
+| CLI / config | [CLI reference](cli.md), [implementation](../cli/), [templates](../templates/) | [Architecture/ownership](architecture.md), [project configuration](project-configuration.md), [tests](../tests/), [package smoke](../scripts/smoke-package.js) |
+| 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) |
+| 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
+→ cách review/kiểm chứng → hướng dẫn sử dụng**. Thành phần không áp dụng bước nào phải ghi rõ lý do;
+không tạo thêm file chỉ để đủ hình thức.
+
+## Quy trình cho mỗi lần nâng cấp
+
+1. Xác nhận Git root, base commit và đọc [AGENTS](../AGENTS.md), kiến trúc, quy định versioning cùng
+   thay đổi liên quan. Khảo sát implementation và test tương tự trước khi thiết kế mới.
+2. Với thay đổi có ý nghĩa về hành vi/chính sách, tạo OpenSpec proposal/design/tasks/specs theo
+   [quy trình hiện có](../core/workflows/spec-to-code.md). Ghi phân tích ảnh hưởng vào `design.md`
+   hoặc sao chép [mẫu impact](templates/harness-change-impact.md) vào change. Sửa typo/đường dẫn nhỏ
+   có thể ghi ngay trong PR; không bắt một bộ OpenSpec đầy đủ.
+3. Duyệt từng hàng của ma trận bên dưới. Ban đầu dùng `pending` cho mục cần sửa; khi hoàn tất chuyển
+   `done` kèm đường dẫn/bằng chứng. `not-applicable` cần lý do cụ thể. Không bỏ trống hàng và không coi
+   “đã nghĩ đến” là “đã cập nhật”. Hỏi lại chỉ khi có lựa chọn quan trọng chưa được quyết định.
+4. Triển khai theo phạm vi; đồng bộ nơi khai báo, đường dẫn consumer sau cài đặt, nơi gọi và tài liệu.
+   Khi đổi tên/xóa, tìm mọi tham chiếu cũ và xem xét snapshot cũ, không chỉ source mới.
+5. Chạy các kiểm tra bắt buộc, kiểm tra diff cài mới/update khi payload hoặc ownership thay đổi,
+   và ghi kết quả thực tế. Báo riêng kiểm tra bị chặn, kết quả manual và live-agent eval chưa chạy.
+6. Điền [PR template](../.github/pull_request_template.md), liên kết impact/OpenSpec và evidence.
+   Còn `pending` thì nêu rõ và dùng draft nếu phần triển khai chưa xong; không báo hoàn tất.
+7. Human review/merge; [Release Please](release-policy.md) quản lý version phân phối và PR phát hành
+   riêng. Không auto-merge, tự tag hoặc publish từ feature PR. Archive chỉ sau khi PR liên quan đã merge.
+
+## Ma trận ảnh hưởng bắt buộc rà soát
+
+Mỗi lần nâng cấp rà soát **tất cả hàng**, nhưng chỉ sửa phần bị ảnh hưởng. Một thay đổi có thể chạm
+nhiều nhóm. Liên kết evidence vào impact record thay vì chép lại cùng nội dung trong PR.
+
+| ID | Khi có thay đổi | Những nơi phải đối chiếu |
+| --- | --- | --- |
+| core | Rule/policy dùng chung | Điểm đọc trong AGENTS template, workflow/role/skill liên quan, precedence, checks và behavioral evals |
+| adapter | Adapter / convention | Registry, adapter manifest và schema; rules index; skills; checks/evals; detection nếu liên quan; module_version khi contract đổi |
+| capability-skill | Capability hoặc skill | Manifest, input/output/constraints, workflow kích hoạt, bàn giao, đường dẫn installed/exposed, skill matrix và composition |
+| cli-config | CLI, config, template | Validation, help/reference, project-owned vs managed files, install/update/dry-run/conflict, tương thích snapshot cũ, migration và package allowlist |
+| workflow | Quy trình / bàn giao | Điều kiện vào, output, owner/bước nhận tiếp, role/skill, acceptance/readiness, SDLC/examples liên quan |
+| documentation | Hướng dẫn sử dụng | README/getting-started, tài liệu chuyên biệt và đường dẫn; không quảng cáo khả năng chưa có hoặc kết quả chưa đo |
+| verification | Kiểm chứng | Tests đúng rủi ro, validate, package smoke, CI matrix; eval scenarios khi hướng dẫn hành vi đổi; actual logs/manual limitations |
+| release-migration | Phát hành / tương thích | Changelog Unreleased, migration/rollback khi cần, module contract version; version phân phối chỉ do release PR quản lý |
+
+Ví dụ thêm convention Java: manifest khai báo `rules/conventions.md` → bundle cài file vào
+`.harness/adapters/java-spring/` → rules index dẫn AI đọc → Core code/review áp dụng → checklist/eval
+kiểm tra → guide hướng dẫn. Nếu chỉ có file convention mà thiếu đường đọc, thay đổi chưa đầy đủ.
+
+## Điều kiện hoàn thành và giới hạn tự động hóa
+
+- Chạy `npm test`, `npm run validate`, `npm run test:package`. CI chạy các gate theo
+  [Harness CI](../.github/workflows/harness.yml); khi liên quan release chạy cả `npm run check:release`.
+- Tests về [maintenance links](../tests/maintenance.test.js) kiểm tra các điểm vào tài liệu, đường đọc
+  Core và rule index của mọi adapter được đăng ký. Các [documentation tests](../tests/documentation.test.js)
+  kiểm tra skill matrix/handoffs; validate kiểm tra đường dẫn Markdown; package smoke dùng tarball thật.
+- Khi đổi payload: xác minh asset được chọn/không được chọn, lock và conflict, project-owned content
+  không bị ghi đè, đường dẫn exposed skill hợp lệ. Dùng test hiện có và chỉ thêm test cho rủi ro mới.
+- Khi đổi instructions: cập nhật kịch bản [behavioral evaluation](../evals/README.md) nếu hành vi kỳ vọng
+  thay đổi; giữ unscored nếu chưa chạy host thật. Passing CLI tests không chứng minh AI tuân thủ.
+- CI kiểm tra cấu trúc và liên kết đã khai báo, **không tự kết luận impact analysis đầy đủ hoặc các tài
+  liệu nhất quán về nghĩa**. PR checklist là hợp đồng review, không phải parser cưỡng chế PR body.
+  Người/AI review đối chiếu diff với ma trận, lý do not-applicable và bằng chứng thực tế.
+
+Thêm nhóm thành phần mới thì cập nhật bản đồ và ma trận tại đây, mẫu impact và PR template nếu cần;
+chỉ mở rộng kiểm tra tự động cho các liên kết có thể xác minh đáng tin cậy. Không tạo registry thứ hai
+cho adapter/skill: `harness.yaml` và module manifests vẫn là nguồn đăng ký chính.

package/docs/monetization.md

@@ -28,7 +28,7 @@ For React/Next.js, substitute `--adapters react-nextjs`. Add `product,uiux` only
 6. If approved to publish, use the actual Google-provided ad integration and owner-authorized publisher details. `ads.txt` at the root domain is **highly recommended, not universally mandatory**; never invent an account/seller ID.
 7. Human reviews actual changed pages, ad/no-fill/adblocked/consent UX and production release scope before deploy. `aih` cannot publish ads or deploy.
 
-Project-owned artifacts: `docs/monetization/site-monetization-plan.md`, `ad-placement-review.md`, `privacy-consent-checklist.md`. The templates are installed at `.harness/capabilities/monetization/templates/` and must be copied into consumer docs by your authorized editor **without overwrite**; `aih new-doc` creates **Product-only** templates.
+Project-owned artifacts: `docs/monetization/site-monetization-plan.md`, `ad-placement-review.md`, `privacy-consent-checklist.md`. The templates are installed at `.harness/capabilities/monetization/templates/` and can be scaffolded with `aih new-doc <type> --capability monetization` **without overwrite**; the default new-doc owner remains Product.
 
 ## Workflow B — traffic → financial learning
 

package/docs/project-configuration.md

@@ -0,0 +1,86 @@
+# Cấu hình từng project và từng máy
+
+| File | Nội dung | Git |
+| --- | --- | --- |
+| `.harness/project.json` | Adapter/capability | Commit |
+| `.harness/agents.json` | Provider/model/reasoning theo role, execution preferences và host mappings | Commit |
+| `.harness/local.md` | Nghiệp vụ, kiến trúc, nguồn và quyết định chung | Commit |
+| `.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
+`.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ụ.
+
+[Agent configuration](agent-configuration.md) mô tả preset và cấu hình model. `aih setup --host codex`
+chỉ đưa ra kế hoạch khai báo; update bảo toàn `agents.json` và không ghi config native của AI host.
+
+## Ví dụ Maven nội bộ
+
+Cấu hình chung:
+
+```json
+{
+  "schema_version": 1,
+  "tools": {
+    "maven": { "executable": "mvn", "required": true }
+  },
+  "files": {
+    "maven-settings": { "path": "${PROJECT_MAVEN_SETTINGS}", "required": true }
+  },
+  "commands": {
+    "test": { "tool": "maven", "args": ["-s", "${PROJECT_MAVEN_SETTINGS}", "verify"] }
+  }
+}
+```
+
+Máy Windows của bạn có thể đặt `.harness/machine.json`:
+
+```json
+{
+  "schema_version": 1,
+  "tools": {
+    "maven": { "executable": "D:\\tools\\apache-maven\\bin\\mvn.cmd" }
+  }
+}
+```
+
+Đặt biến môi trường trong terminal của AI host, ví dụ PowerShell:
+
+```powershell
+$env:PROJECT_MAVEN_SETTINGS = "C:\Users\YourName\.m2\settings-company.xml"
+aih doctor
+```
+
+`doctor` báo trạng thái như `present`, `missing-env`, `missing` hoặc `platform-mismatch`; không in
+đường dẫn/giá trị biến/arguments. Với công cụ bắt buộc bị thiếu, exit code là 1. PATH hints chung
+không thay thế executable đã cấu hình. Thiếu công cụ `required: false` chỉ là chẩn đoán.
+
+AI host đọc command và sử dụng cách quoting đúng terminal; ví dụ PowerShell dùng toán tử `&` cho
+executable có khoảng trắng. Không nối arguments thành shell text một cách mù quáng. Harness không
+tự chạy lệnh, đổi JAVA_HOME, sửa settings.xml hay tải dependency.
+
+## Quy tắc cấu hình
+
+- Schema 1 yêu cầu các map `tools`, `files`, `commands` (có thể rỗng); ID dùng lowercase-hyphen.
+- Tool: `executable` và `required` tùy chọn, mặc định true. File: `path` và `required` tương tự.
+- Command: `tool` phải trỏ tới tool đã khai báo, `args` là mảng string.
+- Machine chỉ có `schema_version`, `tools`/`files` tùy chọn; chỉ override `executable`/`path` của
+  ID đã có. Không đổi commands, required flags hay policy.
+- Đường dẫn machine ưu tiên đường dẫn project; project ưu tiên gợi ý adapter. Không fallback khi
+  đường dẫn được chọn không dùng được. Paths tương đối tính từ project root; executable không
+  chứa separator được tìm trên PATH. Paths tuyệt đối phải phù hợp OS của host.
+- Chỉ cú pháp ${ENV_NAME} tham chiếu biến môi trường hiện tại. Không tự đọc .env, không mở rộng
+  `~` hay shell substitution. Command arguments chỉ được kiểm tra tham chiếu biến; giá trị trong
+  files không tự thay thế arguments. Nếu settings dùng trong args, dùng cùng biến môi trường như ví dụ.
+- `files` dành cho file (settings, config), không phải thư mục JDK. Dùng biến JAVA_HOME của host
+  hoặc khai báo executable Java trực tiếp. Doctor không xác nhận Java/Maven version.
+- `aih check` kiểm tra snapshot; `aih doctor` kiểm tra thêm environment. Dự án cũ chưa có
+  environment vẫn dùng được; không bắt buộc migrate chỉ để chạy check.
+
+## Hỏi trước, lưu lại
+
+Chạy `aih setup` rồi nhờ AI đọc workflow `project-setup`. Host đọc repo và câu trả lời cũ trước khi
+hỏi 1–3 câu A/B/C có đề xuất dựa trên bằng chứng. Các gợi ý JSON của CLI có thể được bỏ qua nếu
+local.md đã trả lời. Setup không phải wizard nhập liệu và không tự ghi lựa chọn.

package/docs/project-conventions.md

@@ -0,0 +1,67 @@
+# Coding conventions: dự án mới và maintain
+
+Harness yêu cầu AI đọc cấu trúc và tìm phần tái sử dụng trước khi code. Core áp dụng cho mọi stack;
+Java/Spring, React/Next.js và React Native có thêm bộ convention mặc định. Đây là hướng dẫn cho AI
+host, không phải công cụ tự phân tích hoặc cưỡng chế kiến trúc ứng dụng.
+
+| Phạm vi | Cách làm |
+| --- | --- |
+| New | Đề xuất cấu trúc tối thiểu và convention theo adapter; chốt lựa chọn có ảnh hưởng trước khi dựng |
+| Maintain | Theo quy định và pattern nhất quán của module đang sửa; giữ public contract và dùng common phù hợp |
+| Mixed | Module mới kế thừa quy định chung của repo; chỉ quyết định mới cho phần nội bộ chưa có chuẩn |
+
+Một tính năng mới trong module cũ vẫn là maintain. Có `pom.xml` hay `package.json` chưa đủ để kết luận
+mode; `aih detect` chỉ đưa gợi ý stack. AI kiểm tra scope và quyết định đã có, không hỏi lại toàn bộ.
+
+## Quy trình sử dụng
+
+1. Chạy `aih setup`; AI đọc `AGENTS.md`, `.harness/local.md`, build/lint/format và code tương tự.
+2. Nếu thiếu lựa chọn quan trọng, AI hỏi A/B/C có trade-off và gợi ý dựa trên bằng chứng. Quyết định
+   thông thường đã được scope/convention bao phủ không cần hỏi lại.
+3. Lưu các nguồn và quyết định bền vững vào `.harness/local.md`, hoặc liên kết tới tài liệu đang có.
+4. Trước mỗi task, AI ghi ngắn: đã đọc đâu, tái sử dụng symbol nào, code mới đặt đâu, vì sao cần tạo mới.
+   Đặt ghi chú trong change/PR hiện tại; sửa nhỏ không bắt tạo thêm một bộ tài liệu.
+5. Review diff và chạy các kiểm tra của dự án. `aih verify --scope all` xuất checklist gồm Core,
+   còn `aih eval --scope all` xuất các tình huống để đánh giá AI thực tế; không lệnh nào tự chạy model.
+
+## Thứ tự ưu tiên
+
+Trong phạm vi quyền và an toàn hiện có: quy định riêng đã thống nhất → cấu hình và pattern nhất quán
+trong module → mặc định adapter cho chỗ còn thiếu. Nếu tài liệu và code mâu thuẫn, AI nêu nguồn và
+hỏi khi ảnh hưởng đáng kể. Không lấy một file legacy làm chuẩn, không sao chép lỗi bảo mật để đồng bộ.
+
+Ví dụ nội dung ngắn trong `.harness/local.md` (thay bằng đường dẫn thật đã kiểm tra):
+
+```markdown
+## Development conventions
+- Scope: maintain module customer; new feature follows that module's layout.
+- Sources: link the actual team guide, formatter config and comparable endpoint/tests.
+- Boundaries: describe the allowed dependency direction and supported shared APIs.
+- Reuse: link the actual error contract, pagination, mapper/client/components that apply.
+- Checks: link declared project commands and existing architecture tests.
+- Exceptions: record reason, scope and decision source; leave unknowns explicit.
+```
+
+## Nội dung theo stack
+
+| Adapter | Chuẩn và điểm tái sử dụng |
+| --- | --- |
+| [Java/Spring](../adapters/java-spring/rules/conventions.md) | Package/naming, injection, DTO, transaction, error/logging, mapper, pagination, test |
+| [React/Next.js](../adapters/react-nextjs/rules/conventions.md) | Feature/routes, naming, typed contracts, client/hooks/state, forms, design tokens, UI states |
+| [React Native](../adapters/react-native/rules/conventions.md) | Screen/navigation, state, API/device boundaries, theme, secure storage, permission, platform checks |
+
+Không tự tạo thêm `ApiResponse`, HTTP client, theme hoặc permission manager nếu dự án đã có bản phù hợp.
+Không ép tái sử dụng bằng cách gọi nội bộ module khác, tạo vòng dependency hoặc đưa nghiệp vụ riêng vào
+common. Dependency, base class hoặc abstraction mới cần nhu cầu thật và lý do; thay đổi kiến trúc ngoài
+scope cần quyết định của người dùng. Không cài lint/framework mới chỉ vì adapter đề cập tên công cụ.
+
+## Update và giới hạn kiểm chứng
+
+Sau khi phiên bản chứa thay đổi được phát hành, nâng CLI rồi chạy `aih update --dry-run`, `aih update`,
+`aih check` trên nhánh consumer. Có thể kiểm thử trước bằng `--source /path/to/reviewed/ai-harness`.
+Update giữ nguyên `.harness/local.md`, environment và các tài liệu dự án; host bổ sung thông tin còn
+thiếu vào file cũ thay vì ghi đè. Không có schema mới, auto-scaffold ứng dụng hay migration kiến trúc.
+
+`aih check` xác minh snapshot Harness; `aih verify` chỉ lập kế hoạch. Lint, test, build và kiểm tra ranh
+giới thực tế do AI host/CI chạy. Khi chưa có kiểm tra kiến trúc tự động, báo kết quả review thủ công
+và giới hạn. Các bài test CLI không chứng minh AI luôn tuân thủ convention; xem [đánh giá](../evals/README.md).

package/docs/research/solution-workflow-sources.md

@@ -0,0 +1,30 @@
+# Source review: product and solution delivery
+
+Reviewed 2026-10-12. These are method references, not installed engines or vendored upstream assets.
+Harness skills/templates were independently authored. Existing MIT distribution and no-runtime-dependency
+contract continue; upstream trademarks/endorsement are not implied.
+
+| Primary source / reviewed revision | Verified license | Method considered | Harness decision |
+| --- | --- | --- | --- |
+| [BMAD stable v6.12.2 README](https://github.com/bmad-code-org/BMAD-METHOD/blob/v6.12.2/README.md), [release](https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.12.2) | [MIT](https://github.com/bmad-code-org/BMAD-METHOD/blob/v6.12.2/LICENSE) | Proportional planning, durable context and explicit decisions/handoffs | Core solution-framing and optional Product/Architecture/Delivery workflows; no installer/runtime adoption |
+| [PM-Skills README](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/README.md), [create-prd skill](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/pm-execution/skills/create-prd/SKILL.md) | [MIT](https://github.com/phuryn/pm-skills/blob/c68487d721e419ec87af1ae6412a842978eab785/LICENSE) | Task-oriented skills, lean decision-ready output and source-grounded questions | Add independent templates/examples/quality/handoff sections; retain Harness authorization and ambiguity rules |
+| [arc42 overview](https://arc42.org/overview/), [license](https://arc42.org/license/) | CC BY-SA 4.0 for template structure/text; own project content remains owned by its author | Communicate context, boundaries, quality and operating reality at the necessary depth | Original compact overview/NFR/project-map/solution templates; no copied 12-section template or explanatory text |
+| [MADR 4.0.0](https://github.com/adr/madr/tree/4.0.0), [docs](https://adr.github.io/madr/), [license](https://github.com/adr/madr/blob/4.0.0/LICENSE) | MIT OR CC0-1.0 | Trace decisions, alternatives and consequences near code | Original ADR draft with authority/status, revision, rollback and reconsideration triggers |
+
+arc42 creators: Gernot Starke and Peter Hruschka. This reference acknowledges their documentation
+method; it does not claim endorsement or import their licensed template into MIT assets.
+
+BMAD main described v7 as preview alpha at review time. The stable v6.12.2 tag was the research baseline;
+no alpha workflow or future release promise is a dependency. PM-Skills refers specifically to phuryn's
+repo and the pinned revision above, not every similarly named marketplace.
+
+## Fit and limits
+Harness keeps OpenSpec as the change record and a single manifest-driven instruction distribution.
+Core applies a compact overview/impact check; capabilities add depth when selected. Product Manager
+owns product value; Project Manager owns delivery coordination; role names do not make approvals.
+No workflow engine, upstream prompt bundle, provider credentials or public account data was copied.
+
+Research proves source/format availability, not Harness model effectiveness. Behavioral cases remain
+unscored until real host runs and reviewed traces exist. Native host configuration references below
+were checked against official docs; installed-client behavior still requires the smoke procedure in
+[tool setup](../tool-setup/README.md). Recheck sources before changing host discovery recommendations.

package/docs/skill-matrix.md

@@ -1,12 +1,14 @@
-# Skill matrix — 53 skills, 11 nhóm module
+# Skill matrix — 64 skills, 13 nhóm module
 
-Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (5 Core, 30 capability, 18 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 53 skill vào prompt.
+Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (5 Core, 41 capability, 18 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 64 skill vào prompt.
 
 **Cách dùng:** `aih skills` xem skills đã cài, sau đó `aih skill harness-...` lấy nội dung. Danh mục này mô tả chức năng; **không** có nghĩa `aih` thực thi skills hoặc agent. Tech adapters và capabilities chỉ xuất hiện trong consumer khi được chọn; Core dùng chung.
 
 | Stage | Chọn module | Vai trò/output mong đợi |
 | --- | --- | --- |
 | Discovery → Product | `product` | Source register, BRD/PRD, AC, backlog, traceability |
+| Product → Solution | `architecture` | Context, NFR, module/data/contracts, ADR, architecture review |
+| Solution → Delivery | `delivery` | Value slices, dependencies, owned risks and scope-change assessment |
 | UX → Figma | `uiux` | Flows, screen specs, tokens, design review |
 | Spec → Code → Review | Core + adapter theo stack | OpenSpec, tests, changes, review evidence |
 | Release → Operate | `devops`, `kubernetes` khi phù hợp | CI, container, manifests, rollout và SLO plan |
@@ -22,7 +24,7 @@
 | [`harness-spec`](../core/skills/harness-spec/SKILL.md) | Technical design | Soạn OpenSpec proposal/design/tasks/delta specs | OpenSpec change và các quyết định còn thiếu |
 | [`harness-tdd`](../core/skills/harness-tdd/SKILL.md) | Implementation | Red → green → refactor trên slice nhỏ | Code + test evidence |
 
-## Product capability (13)
+## Product capability (15)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
@@ -35,11 +37,12 @@
 | [`harness-product-prd-generation`](../capabilities/product/skills/harness-product-prd-generation/SKILL.md) | Product | Soạn PRD với scope, outcome và metrics | `docs/product/prd.md` |
 | [`harness-product-traceability`](../capabilities/product/skills/harness-product-traceability/SKILL.md) | Change impact | Liên kết nguồn → stories → UI → spec | `docs/product/traceability.md` |
 | [`harness-product-user-stories`](../capabilities/product/skills/harness-product-user-stories/SKILL.md) | Backlog | Phân rã epics/stories theo yêu cầu duyệt | `docs/product/backlog.md` |
-
 | [`harness-product-idea-discovery`](../capabilities/product/skills/harness-product-idea-discovery/SKILL.md) | Idea-driven | Cùng developer làm rõ ý tưởng, phương án, MVP và quyết định | `docs/discovery/idea.md` |
 | [`harness-product-product-research`](../capabilities/product/skills/harness-product-product-research/SKILL.md) | Research | Tìm và phân loại bằng chứng đáng tin cậy, trade-offs | `docs/discovery/research.md` |
 | [`harness-product-srs-generation`](../capabilities/product/skills/harness-product-srs-generation/SKILL.md) | Software requirements | Đặc tả FR/NFR, giao diện, luồng lỗi có trace ID | `docs/product/srs.md` |
 | [`harness-product-use-case-generation`](../capabilities/product/skills/harness-product-use-case-generation/SKILL.md) | Detailed flows | Viết UC chính/phụ/lỗi liên kết FR/US/AC | `docs/product/use-cases.md` |
+| [`harness-product-mvp-definition`](../capabilities/product/skills/harness-product-mvp-definition/SKILL.md) | MVP scope | Explicit product decisions and traceability | Usable journey, in/out scope and minimum quality |
+| [`harness-product-product-outcomes`](../capabilities/product/skills/harness-product-product-outcomes/SKILL.md) | Success measures | Explicit product decisions and traceability | Evidence-backed metrics and experiments |
 
 ## Monetization capability (5)
 
@@ -132,3 +135,24 @@
 - `harness-ai-evaluation` đánh giá **hành vi AI thực tế**; `aih eval` chỉ xuất và tổng hợp report do reviewer điền.
 
 Đối chiếu [Agent handoffs](agent-handoffs.md), [adapters](adapters.md) và [full workflow](end-to-end-workflow.md). Khi thêm skill mới, hãy cập nhật một hàng trong bảng; test tài liệu sẽ báo thiếu/trùng.
+
+## Architecture capability (6)
+
+| Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
+| --- | --- | --- | --- |
+| [`harness-architecture-project-context`](../capabilities/architecture/skills/harness-architecture-project-context/SKILL.md) | project-context | Map verified system context, module ownership and source-linked architecture for new or existing projects. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-quality-attributes`](../capabilities/architecture/skills/harness-architecture-quality-attributes/SKILL.md) | quality-attributes | Translate NFRs into measurable quality scenarios and verification plans with evidence-backed targets. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-solution-design`](../capabilities/architecture/skills/harness-architecture-solution-design/SKILL.md) | solution-design | Compare architectures and local design patterns against MVP, NFRs and existing project boundaries. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-decision-records`](../capabilities/architecture/skills/harness-architecture-decision-records/SKILL.md) | decision-records | Record traceable architecture decisions with alternatives, consequences and reconsideration triggers. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-change-impact`](../capabilities/architecture/skills/harness-architecture-change-impact/SKILL.md) | change-impact | Assess change impact and architecture drift using a source-linked living project map. | Project-owned docs/architecture or compact task note |
+| [`harness-architecture-review`](../capabilities/architecture/skills/harness-architecture-review/SKILL.md) | review | Review solution and implemented boundaries against MVP, NFRs, ADRs and actual verification evidence. | Project-owned docs/architecture or compact task note |
+
+## Delivery capability (3)
+
+| Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
+| --- | --- | --- | --- |
+| [`harness-delivery-planning`](../capabilities/delivery/skills/harness-delivery-planning/SKILL.md) | planning | Plan value-bearing delivery slices and dependencies from reviewed scope and team-supplied estimates. | Project-owned docs/delivery or compact task note |
+| [`harness-delivery-risk-management`](../capabilities/delivery/skills/harness-delivery-risk-management/SKILL.md) | risk-management | Maintain owned delivery risks, assumptions, blockers and dependencies with response triggers. | Project-owned docs/delivery or compact task note |
+| [`harness-delivery-scope-change`](../capabilities/delivery/skills/harness-delivery-scope-change/SKILL.md) | scope-change | Evaluate scope changes across product value, architecture, dependencies and delivery before re-planning. | Project-owned docs/delivery or compact task note |
+
+Product → Architecture → Delivery → Core/adapter uses [Solution workflow](solution-workflow.md); source revisions, requirement/AC/NFR/ADR IDs and actual decisions travel together. See [host setup](tool-setup/README.md).

package/docs/solution-workflow.md

@@ -0,0 +1,67 @@
+# BA → PO → SA → PM → Dev/QA
+
+Product contains BA/PO analysis and documents; optional Architecture adds Solution Architect context,
+NFRs/ADRs/design/review; optional Delivery adds Project Manager planning/risks/scope changes.
+Roles are instructions for a host and can be performed sequentially. User/stakeholder decisions keep
+actual authority. No new workflow engine is installed; OpenSpec owns change proposal/design/tasks/specs.
+
+## Choose proportional depth
+| Work | Minimum sufficient context | Optional deeper outputs |
+| --- | --- | --- |
+| Small clear fix | Existing source/decisions, affected boundary/reuse and regression note | Only new consequential decisions |
+| New small product | Actor/problem, usable MVP journey/AC, minimum NFR, minimal solution and slices | Short overview and a significant ADR |
+| Material/enterprise change | Source versions, MVP/requirements, module/data/contracts, NFR/failure impact | Project map, ADRs, risk register, rollout plan |
+
+```bash
+aih init --adapters java-spring --capabilities product,architecture,delivery
+aih setup
+aih skills
+aih new-doc mvp
+aih new-doc overview --capability architecture
+aih new-doc nfr --capability architecture
+aih new-doc delivery-plan --capability delivery
+aih new-change customer-search
+aih verify --scope all
+aih eval --scope all
+```
+
+Blank templates only. Use existing approved BA/Confluence documents instead of re-creating them.
+For an existing Harness install, edit selected capabilities in project.json and use reviewed update
+--dry-run/update/check. `resolve` validates and warns; it does not install soft recommendations.
+
+## Responsibilities and handoff
+| Role / module | Owns | Receives / passes |
+| --- | --- | --- |
+| BA / Product | Problem, business rules, source authority and requirement gaps | Idea/docs → versioned FR/US/AC/NFR and contradictions |
+| PO / Product | MVP value, in/out scope, acceptance and priorities | BA → reviewed journey, outcomes and actual scope decisions |
+| SA / Architecture | Context, quality scenarios, solution trade-offs, public boundaries | Scope → NFR/ADR/contracts/failure flows and verification |
+| PM / Delivery | Sequencing, dependencies, estimates/risks and status | Accepted scope/design → value slices, owners, blockers and checkpoints |
+| Dev/QA / Core + adapters | Implementation and actual tests | OpenSpec/decisions → minimal code, test evidence and findings |
+| DevOps / optional capability | Operational release/recovery detail | Agreed constraints → reviewed rollout/rollback/telemetry |
+
+Carry source revision, requirement/AC/NFR/ADR IDs, output paths, decisions/status, unresolved questions,
+actual verification and next owner. Scope changes return to PO; technical conflicts to SA; delivery
+risks to PM. UX and implementation feedback can revise the plan; this is not a one-way document conveyor.
+
+## MVP and architecture judgment
+MVP must let a target actor complete a useful journey. A customer-search MVP can defer bulk import
+but must include resource authorization, data integrity and agreed duplicate behavior.
+Compare architectures on actual constraints; styles may combine. Ports and Adapters concerns boundaries;
+Factory concerns object construction. Add Strategy/Adapter/State only for concrete variation or state
+requirements. Direct code is a valid minimal choice. Do not promise enterprise scale from a diagram.
+
+Record important decisions with evidence and owner status, not inferred approval. NFR targets/load,
+cost and delivery estimates remain unknown when evidence is absent. Keep the living project-map
+linked to actual source; refresh touched entries when code/requirements change instead of loading all docs.
+
+## Templates and reading paths
+- [Product handoff](../capabilities/product/workflows/product-to-solution.md): MVP/outcomes, existing BA skills.
+- [Architecture entry](../capabilities/architecture/workflows/discovery-to-design.md), [change review](../capabilities/architecture/workflows/change-review.md).
+- [Delivery planning](../capabilities/delivery/workflows/planning.md), [execution/change](../capabilities/delivery/workflows/execution-change.md).
+- [Core framing](../core/workflows/solution-framing.md), [skill matrix](skill-matrix.md), [agent handoffs](agent-handoffs.md).
+- [Research/provenance](research/solution-workflow-sources.md), [coding tool setup](tool-setup/README.md).
+
+`aih new-doc adr --capability architecture` produces one draft; move the populated file to a stable
+project-owned `docs/architecture/decisions/adr-NNN.md` path and link it before making the next ADR.
+`aih new-doc delivery-plan` keeps its historical Product path; explicitly select Delivery for the richer
+plan. Do not duplicate/migrate an accepted plan automatically.

package/docs/templates/harness-change-impact.md

@@ -0,0 +1,30 @@
+# Harness change impact
+
+Maintainer-only template. Copy into the active OpenSpec design/change or use the table in a small PR.
+Do not install this as a mandatory consumer application template.
+
+- Change / objective: record the actual request and scope.
+- Base commit / affected modules: record verified values.
+- Decision sources: link existing decisions; list consequential unresolved questions.
+
+Use `pending`, `done`, or `not-applicable`. Every row needs paths/evidence or a specific reason.
+Keep pending work visible; no blanket not-applicable statement for the whole change.
+
+| Area | Status | Affected paths and evidence / reason not applicable |
+| --- | --- | --- |
+| core | pending | Assess rule, entry point, policy and related behavior |
+| adapter | pending | Assess registry, manifest, index, assets and module version |
+| capability-skill | pending | Assess declaration, exposure, workflow and handoff |
+| cli-config | pending | Assess schema, ownership, install/update and package contents |
+| workflow | pending | Assess inputs, outputs, gates and receiving stage |
+| documentation | pending | Assess usage guides, examples and links |
+| verification | pending | Record actual commands/results; separate manual/live-agent evidence |
+| release-migration | pending | Assess Unreleased notes, compatibility, rollback and version ownership |
+
+## Link chain
+Record declaration → distribution → discovery → use → review/check → documentation for affected
+behavior. Explain any stage that does not apply. For a removal/rename, list old references reconciled.
+
+## Validation and remaining work
+Record commands actually run, outcomes, skipped checks with reasons, pending items and next owner.
+Do not claim model compliance from file/link tests. Keep shared instructions in their canonical docs.