@manhd_d/ai-harness 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased — Project setup, clarification and readiness
+- Add optional shared environment configuration and ignored machine path overrides, with redacted doctor diagnostics.
+- Add read-only setup suggestions, host-led A/B/C clarification and next-step guidance.
+- Scaffold decision/evidence sidecars and add structural implement/review readiness checks.
+- Add behavior scenarios and a real-task comparison protocol; live-model evaluation remains unperformed.
+
+## Unreleased — Simpler onboarding and release regression coverage
+- Start with npm install, minimal module selection and project context; clarify advisory commands and the two-step CLI/snapshot update.
+- Link progressive context rules from the generated AGENTS entry point; retain project ownership and runtime boundaries.
+- Exercise legacy migrations against both the current and next patch version; document recovery from a failed immutable release tag.
+
+## Unreleased — Release validation compatibility
+- Accept Release Please's linked version headings for version 0.6.1 in both validation commands while retaining strict matching of the current distribution version.
+
+## Unreleased — Release migration tests
+- Fix legacy upgrade tests to assert the current Harness source version rather than hardcoding 0.6.0, allowing Release Please version PRs to pass CI without weakening migration checks.
+
 ## Unreleased — npm 12 pack metadata compatibility
 - Make package smoke tests support both npm 10/11 array-form and npm 12 package-keyed JSON output from `npm pack --json`.
 - Validate archive metadata before accessing `files`, with explicit diagnostics instead of an undefined-property crash.
@@ -42,6 +59,30 @@
 - Check release metadata consistency and establish single-release-PR version discipline; retain v0.6.0 until a dedicated release PR.
 
 
+## [0.7.0](https://github.com/manh0303/ai-harness/compare/v0.6.2...v0.7.0) (2026-10-12)
+
+
+### Features
+
+* add project environment setup and clarification readiness ([384cf13](https://github.com/manh0303/ai-harness/commit/384cf13b8a96791c26f9e0769bd8e0ccb734c20b))
+
+## [0.6.2](https://github.com/manh0303/ai-harness/compare/v0.6.1...v0.6.2) (2026-10-11)
+
+
+### Bug Fixes
+
+* **release:** support linked Release Please changelog headings ([8084940](https://github.com/manh0303/ai-harness/commit/80849408a349305ef5cdfb0c0eb0206ea8242eb8))
+* simplify onboarding and guard release version migrations ([43efbb2](https://github.com/manh0303/ai-harness/commit/43efbb24e26d190b7a2b8dd2fbd5a9a5ee5368a1))
+* **test:** unblock Release Please version bump CI ([63ba179](https://github.com/manh0303/ai-harness/commit/63ba17974cafad40e6ff5b483c126afdfc49df44))
+
+## [0.6.1](https://github.com/manh0303/ai-harness/compare/v0.6.0...v0.6.1) (2026-10-11)
+
+
+### Bug Fixes
+
+* **release:** automate npm publishing with Release Please and OIDC ([d39f284](https://github.com/manh0303/ai-harness/commit/d39f2843bd2700d9be8f70981135b8502b691303))
+* **release:** automate npm releases with Release Please and OIDC ([0b293c5](https://github.com/manh0303/ai-harness/commit/0b293c520601cf2f21ed10d0dd3973f659647cc0))
+
 ## 0.6.0 — DevOps capability and Kubernetes adapter candidate
 - Add `devops` capability with six namespaced CI/CD, Docker, deployment, infrastructure, observability and incident-response skills plus two review-gated workflows.
 - Add `kubernetes` adapter with Helm/workload/rollout skills, advisory verification checks and two safety evaluation scenarios.

package/README.md

@@ -1,329 +1,76 @@
-# ai-harness
+# AI Harness
 
-Framework tái sử dụng để hướng dẫn AI làm việc theo **Spec → Code → Test → Review** trong nhiều dự án.
-Core dùng chung; adapter chứa quy chuẩn công nghệ; CLI cài một bản có version vào từng repository.
+**Bộ quy tắc, skills và workflows tái sử dụng để AI hỗ trợ phát triển phần mềm theo quy trình _Spec → Code → Test → Review_.**
 
-**Trạng thái:** 0.6.0 candidate; 6 adapters, 4 optional capabilities, 53 skills và CLI Node.js 22+ với lệnh `aih`, không cần Python hay thư viện runtime ngoài.
-Gói `@manhd_d/ai-harness` chưa phát hành lên npm registry; hiện cài từ repository private hoặc tarball.
-Harness không tự gọi LLM, không tự sinh ứng dụng, không tạo agent runtime, không tự merge/deploy.
-Các role/skill hướng dẫn assistant đang dùng; quyền thực tế do IDE/runtime, Git và CI kiểm soát.
+AI Harness cài context vào từng repository qua CLI `aih`. Có thể kết hợp các technology adapters và capabilities theo nhu cầu; không phụ thuộc một IDE hay mô hình AI cụ thể.
 
-## Hướng dẫn quy trình phát triển phần mềm (full SDLC)
+> Yêu cầu **Node.js 22+**. CLI không tự chạy LLM, viết code, phê duyệt tài liệu, merge PR hoặc deploy.
 
-Nếu lần đầu sử dụng, đọc theo thứ tự: **Cài → Product/BA/PO → UI/UX → OpenSpec → Code → Test/Review → CI/CD → Vận hành**.
-
-- **[Getting started](docs/getting-started.md)** — cài CLI, chọn module, tạo change và kiểm tra.
-- **[Hai luồng tài liệu](docs/documentation-workflows.md)** — idea-driven và document-driven, lưu trữ, version và handoff.
-- **[Full SDLC: Idea → Production](docs/end-to-end-workflow.md)** — input/output, approval gate, cách phối hợp capabilities/adapters.
-- **[Ma trận 53 skills](docs/skill-matrix.md)** — tra cứu skills theo stage/công nghệ và ID thật.
-- **[Agent handoffs](docs/agent-handoffs.md)** — roles, trách nhiệm, ownership, evidence và bàn giao.
-- **Walkthrough:** [Spring Boot API](docs/examples/spring-boot-api.md) · [Full-stack Next.js + Spring](docs/examples/fullstack-web.md) · [React Native](docs/examples/react-native-app.md) · [Python AI/RAG](docs/examples/ai-rag-service.md) · [Astro micro-tools](docs/examples/astro-micro-tools.md) · [Astro + AdSense](docs/examples/astro-adsense-microtools.md).
-
-Harness cung cấp hướng dẫn cho AI runtime, **không** tự điều phối AI agent, tạo code, chạy test, merge hay deploy.
-
-## Bắt đầu
-
-**Để thử adapter Astro trước khi PR được merge**, checkout branch `feat/astro-lightweight-adapter` trước `npm pack`. Sau merge, ưu tiên commit/tag chính thức đã review. CLI vẫn báo 0.6.0 vì adapter mới chưa được phát hành qua release PR riêng.
-
-Cài từ source đã review bằng tài khoản có quyền repository private:
+## Cài đặt và dùng nhanh
 
 ```bash
-git clone git@github.com:manh0303/ai-harness.git
-cd ai-harness
-# Nếu thử các tính năng chưa merge trong PR #10:
-git switch feat/astro-lightweight-adapter
-# Sau khi merge, ưu tiên tag/commit đã review thay vì feature branch.
-npm pack
-npm install -g ./manhd_d-ai-harness-0.6.0.tgz
+npm install -g @manhd_d/ai-harness
 
-cd /path/to/my-backend
-aih init --adapters java-spring --dry-run
+# Chạy trong một project đã tồn tại
 aih init --adapters java-spring
 aih check
-aih new-change add-order
-```
-
-Sau khi cài, dùng `aih` từ bất kỳ repository ứng dụng nào. Đích mặc định là thư mục hiện tại;
-`--target /path/to/project` vẫn được hỗ trợ. Thư mục đích phải tồn tại.
-`aih --help` xem lệnh, `aih --version` xem phiên bản công cụ.
-
-Khi chủ sở hữu đã phát hành npm package công khai, cách cài sẽ là
-`npm install -g @manhd_d/ai-harness@0.6.0`. **Lệnh registry này chưa dùng được chỉ vì PR đã merge.**
-Có thể cài tarball vào devDependencies rồi dùng `npx --no-install aih init` nếu không muốn cài global.
-Xem [hướng dẫn đóng gói/phát hành](docs/npm-release.md).
-
-Đây là cài **quy trình và context**, không scaffold source code Spring/React và không sửa build file.
-
-## Hai chế độ tài liệu — Idea-driven / Document-driven
-
-**Idea-driven:** Từ ý tưởng của developer → thảo luận → nghiên cứu có nguồn → PRD-lite hoặc BRD/PRD/SRS/use cases → duyệt → OpenSpec. **Document-driven:** Từ BRD/PRD/SRS/Confluence đã có của BA → kiểm tra source version, gap và traceability → technical spec và code. Không tự ghi đè tài liệu BA đã duyệt. Hai chế độ có thể sử dụng luân phiên trong cùng một dự án.
-
-Xem hai hướng dẫn thực hành: [Bắt đầu từ ý tưởng](docs/examples/idea-driven-project.md) · [Dự án đã có tài liệu BA](docs/examples/document-driven-project.md). Xem thêm [Documentation workflows](docs/documentation-workflows.md) và [Confluence integration contract](integrations/confluence/README.md). `aih` only creates templates and ships instructions; AI host handles research/content, and external publishing requires independently authorized tooling.
-
-```bash
-aih init --capabilities product
-aih new-doc idea       # docs/discovery/idea.md
-aih new-doc research   # docs/discovery/research.md
-aih new-doc prd-lite   # docs/product/prd-lite.md
-aih new-doc srs        # docs/product/srs.md
-aih new-doc use-cases  # docs/product/use-cases.md
-```
-
-## Product documentation capability — BA / PM / PO
-
-Capability `product` cung cấp 5 role contracts, 13 skills, 5 workflows và 16 templates
-để chuyển ý tưởng hoặc nguồn Confluence được cấp quyền thành BRD, PRD, user stories,
-acceptance criteria và requirement traceability. Mọi tài liệu hoàn thiện là dữ liệu
-**do dự án sở hữu**, nằm trong `docs/discovery/` (ý tưởng, nghiên cứu) hoặc `docs/product/` (yêu cầu) của repository ứng dụng.
-
-```bash
-# Khởi tạo dự án mới chỉ cần Product
-aih init --capabilities product
-# Kết hợp Product + UI/UX + React
-aih init --capabilities product,uiux --adapters react-nextjs
-# Tạo file mẫu để AI điền bằng tài liệu được cấp phép, không tự điền nội dung
-aih new-doc brd
-aih new-doc prd
-aih new-doc backlog
-aih new-doc acceptance-criteria
-aih new-doc traceability
-aih skills
-aih skill harness-product-prd-generation
-aih check
-```
-
-Dự án đã cài đặt cần sửa `.harness/project.json`, bổ sung `product` vào
-`capabilities` rồi chạy `aih update --dry-run`, `aih update`, `aih check`.
-CLI chỉ tạo **bản mẫu** khi dùng `new-doc`. Việc phân tích và điền nội dung cần
-AI runtime có quyền đọc nguồn, kiểm tra bằng chứng và được BA/PM/PO phê duyệt.
-Xem [Product capability](capabilities/product/README.md).
-
-## Astro cho micro-tools, React Islands và Cloudflare
-
-Chọn [adapter Astro](adapters/astro/README.md) nếu bạn làm trang công cụ nhỏ, SEO landing page hoặc portfolio nhiều utilities. **Static-first:** TypeScript/browser xử lý trước; React Islands chỉ cho UI tương tác; Cloudflare Workers/API và MFE chỉ khi có nhu cầu thực. Astro Islands không phải các micro frontend deploy độc lập. Xem [walkthrough đầy đủ](docs/examples/astro-micro-tools.md).
-
-```bash
-cd /path/to/existing-astro-project
-aih resolve --adapters astro --capabilities product,uiux
-aih init --adapters astro --capabilities product,uiux --dry-run
-aih init --adapters astro --capabilities product,uiux
-aih check
-aih skills
-aih skill harness-astro-project-architecture
-aih skill harness-astro-islands
-aih skill harness-astro-cloudflare
-aih verify --scope all  # advisory; không tự chạy build/deploy
-```
-
-Không bắt buộc Product/UIUX; nếu chỉ cần code, dùng `aih init --adapters astro`. Trong dự án đã cài Harness: sửa `.harness/project.json` và chạy `aih update --dry-run`, `aih update`, `aih check`. `aih detect` nhận diện `astro` từ `package.json`; `react-dom` vì React Islands không tự khiến CLI cài `react-nextjs` trừ khi dự án còn dùng `next`. CLI chỉ cài rules/skills, **không** tạo Astro app, cài React hay deploy lên Cloudflare.
-
-## Monetization — kiếm tiền hợp lệ từ quảng cáo
-
-Capability `monetization` độc lập với Astro, React/Next.js và các adapter khác. Với website micro-tools miễn phí, ưu tiên **giá trị sản phẩm → SEO → kiểm tra AdSense/consent → ad placement an toàn → đo traffic và Page RPM thực tế**. Năm skills giúp phân tích các bước; không tự tạo tài khoản, xin duyệt site, nhúng ad code hoặc kéo doanh thu từ Google.
-
-```bash
-# Website Astro có mục tiêu doanh thu quảng cáo
-aih resolve --adapters astro --capabilities monetization
-aih init --adapters astro --capabilities monetization --dry-run
-aih init --adapters astro --capabilities monetization
-aih check
-aih skill harness-monetization-adsense-integration
-aih skill harness-monetization-ad-placement-ux
-aih skill harness-monetization-analytics-revenue
-aih verify --scope capabilities  # manual checklist, không chạy provider checks
-```
-
-Nếu cần Product + UI/UX thì chọn `--capabilities product,uiux,monetization`. Dự án đã cài Harness phải sửa `.harness/project.json`, rồi `aih update --dry-run`, `aih update`, `aih check`. Templates monetization nằm trong `.harness/capabilities/monetization/templates/`; tự copy vào `docs/monetization/` khi được quyền — `aih new-doc` chỉ dùng cho Product.
-
-Hướng dẫn: [Monetization](docs/monetization.md) · [Astro + AdSense walkthrough](docs/examples/astro-adsense-microtools.md) · [Capability README](capabilities/monetization/README.md). Không hứa AdSense sẽ phê duyệt hay đảm bảo thu nhập; quảng cáo phải tuân thủ chính sách và không được nhầm với nút tool.
-
-## Optional UI/UX capability
-
-UI/UX là **capability** độc lập với technology adapter. Chọn khi cần chuyển ý tưởng, PRD hoặc
-Confluence thành requirement, UX flow, screen inventory rồi tạo Figma bằng agent đã kết nối.
-Không tự động gọi LLM, đọc Confluence hay viết Figma. Phải cấp quyền MCP cho host và duyệt trước
-khi chỉnh sửa file Figma hoặc màn hình đã được duyệt.
-
-```bash
-# Dự án chỉ cần design, không cần adapter công nghệ
-aih init --capabilities uiux
-
-# Dự án vừa React vừa thiết kế UI/UX
-aih init --adapters react-nextjs --capabilities uiux
-
-# Sau khi cài, xem metadata kỹ năng trước, chỉ nạp nội dung khi cần
-aih skills
-aih skill harness-uiux-figma-design
-
-# Bổ sung UI/UX vào một project đã cài: sửa mảng capabilities
-# trong .harness/project.json, sau đó:
-aih update --dry-run
-aih update
-aih check
+aih setup
 ```
 
-`aih list` liệt kê cả adapters và capabilities; `aih skills` chỉ trả tên + mô tả,
-`aih skill <name>` mới trả nội dung đầy đủ của skill đã cài và được lock. Không có network
-download độc lập: npm tarball vẫn chứa mọi capability, nhưng dự án chỉ nhận capability đã chọn.
-Xem [tài liệu capability](capabilities/uiux/README.md) và [quy trình docs-to-figma](capabilities/uiux/workflows/docs-to-figma.md).
-
-## DevOps capability + Kubernetes adapter
-
-`devops` cung cấp 6 skills cho CI/CD, Docker, release, infrastructure review,
-observability và incident response, cùng 2 workflows có cổng phê duyệt.
-`kubernetes` là adapter riêng cho manifest, Helm và rollout safety.
-
-```bash
-aih init --adapters java-spring,kubernetes --capabilities devops
-# Kết hợp cả Product + UI/UX + DevOps
-aih init --adapters java-spring,kubernetes --capabilities product,uiux,devops
-aih skills
-aih skill harness-devops-deployment
-aih verify                  # chỉ gợi ý kiểm tra, không chạy
-aih check
-```
-
-Các lệnh không gọi cloud API, không triển khai production hay cấp quyền kết nối.
-Xem [DevOps capability](capabilities/devops/README.md) và [quy tắc adapters](docs/adapters.md).
-
-## Module composition & evaluation (unreleased)
+Tiếp theo, ghi stack, nghiệp vụ và lệnh test vào `.harness/local.md`; mở project trong AI IDE và yêu cầu assistant đọc `AGENTS.md` trước khi làm việc. Bạn giao task bình thường, AI đọc skill liên quan và báo cáo test thực chạy.
 
-Module manifests có `module_version` và các metadata phụ thuộc, khuyến nghị, xung đột. Kiểm tra trước khi cài:
+Thêm `--capabilities product` khi cần tài liệu BA; `aih new-doc prd-lite` tạo template, `aih new-change <id>` tạo spec nháp khi cần. Không bắt mọi task tạo đủ tài liệu. Xem [Getting started](docs/getting-started.md) và [CLI reference](docs/cli.md).
 
-```bash
-aih resolve --adapters java-spring,kubernetes --capabilities product,uiux,devops
-aih verify --scope all     # checklist tư vấn, không chạy
-aih eval --scope all       # báo cáo chưa chấm, không gọi model
-```
+**Phân biệt:** `aih check` kiểm tra file Harness; `aih verify` xuất checklist; build/test ứng dụng do AI host hoặc CI thực chạy. CLI không bảo đảm AI sẽ tuân thủ hướng dẫn; xem [đánh giá hành vi](evals/README.md).
 
-Chế độ mặc định không có `--scope` vẫn chỉ gồm adapters. Foundation Hardening đã có trong source; đây vẫn là source candidate, chưa chứng minh npm registry có bản phát hành. Xem [release policy](docs/release-policy.md).
+`aih setup` đưa gợi ý câu hỏi cho AI host; AI hỏi phần còn mơ hồ bằng A/B/C có đề xuất và lưu câu trả lời.
+Cấu hình Maven/JDK riêng từng máy: [Project configuration](docs/project-configuration.md).
+Trước code/review tính năng có spec: [Change readiness](docs/change-readiness.md).
 
-## Chọn adapter
+## Thành phần
 
-| Dự án | `--adapters` |
+| Nhóm | Hỗ trợ |
 | --- | --- |
-| Java / Spring Boot | `java-spring` |
-| React hoặc Next.js | `react-nextjs` |
-| Astro micro-tools / static SEO | `astro` |
-| React Native / Expo | `react-native` |
-| Python AI, agent hoặc RAG | `ai-python` |
-| Kubernetes / Helm workloads | `kubernetes` |
-| Full-stack trong cùng repository | `java-spring,react-nextjs` |
-| Chỉ core rules và workflow | Bỏ tùy chọn `--adapters` |
-
-AI bằng Java có thể dùng `java-spring` cùng skill `harness-ai-evaluation`; không bắt buộc chuyển sang Python.
-Với multi-repo, cài vào từng repo có thực hiện công việc. Ghi danh sách repo và thứ tự merge trong change.
+| **Core** | Rules, agent roles, skills, workflows, review & verification |
+| **Adapters** | Java Spring Boot, React/Next.js, React Native, Python AI/RAG, Kubernetes, Astro |
+| **Capabilities** | Product/BA/PO, UI/UX & Figma, DevOps, Monetization/AdSense |
+| **OpenSpec** | Template cho proposal, design, tasks và spec có review |
 
-## Nhận diện stack và dùng adapter
+Bạn chỉ chọn module cần dùng, ví dụ `aih init --adapters astro --capabilities monetization` cho website công cụ nhỏ có quảng cáo. Xem [Astro adapter](adapters/astro/README.md) và [Monetization capability](capabilities/monetization/README.md).
 
-```bash
-aih list
-aih detect
-aih init --detect --dry-run
-aih init --detect
-aih verify
-aih eval
-```
+## Hai luồng làm việc
 
-`detect` báo adapter đề xuất kèm bằng chứng; chỉ đọc file ngay trong thư mục đích, không quét đệ quy
-monorepo. Dùng `--target apps/backend` cho từng module. Spring cần dấu hiệu Spring Boot trong Maven/Gradle;
-React Native được phân biệt với web; AI/Python dựa trên tên thư viện trong pyproject/requirements.
-Đây là heuristic: có thể bỏ sót dependency gián tiếp hoặc khớp comment. Review kết quả trước khi cài.
-`init --detect` là lựa chọn chủ động; không tìm thấy stack thì dừng. `init` không có flag vẫn cài core-only.
-Có thể dùng `--adapters` để chọn chính xác. Update giữ lựa chọn trong project.json, không tự nhận diện lại.
+- **Idea-driven:** Ý tưởng → thảo luận/nghiên cứu → BRD/PRD/SRS → UI/UX → spec → code.
+- **Document-driven:** BRD/PRD/SRS/Confluence đã có → phân tích gap → technical spec → code.
 
-Mỗi adapter có `adapter.yaml`, `rules/`, `skills/`, `checks/verification.yaml` và `evals/cases.json`.
-Skills của adapter đã chọn được cài vào `.agents/skills/harness-<adapter>-*`; Core giữ TDD/debug/review dùng chung.
-`aih verify` chỉ xuất checklist và lệnh gợi ý, **không chạy test/build**. `aih eval` xuất tình huống và mẫu
-báo cáo chưa chấm; `aih eval --report report.json` tổng hợp điểm có bằng chứng, **không gọi model**.
-Xem [hướng dẫn adapter và đánh giá](docs/adapters.md) trước khi điền báo cáo.
+Chi tiết: [Documentation workflows](docs/documentation-workflows.md) · [Confluence integration](integrations/confluence/README.md).
 
-## Dự án nhận những gì?
+## Tài liệu
 
-| Đường dẫn | Cách quản lý |
+| Mục đích | Hướng dẫn |
 | --- | --- |
-| `AGENTS.md` | Thêm/cập nhật một block có marker; giữ nguyên nội dung bên ngoài |
-| `.harness/core/`, `adapters/`, `integrations/`, `templates/` | Snapshot framework, được lock bằng hash |
-| `.agents/skills/harness-*/` | Skill dùng trong project; cách kích hoạt tùy assistant |
-| `.harness/lock.json` | Version, adapters và SHA-256 của nội dung được quản lý |
-| `.harness/project.json` | Dự án sở hữu; chọn adapter |
-| `.harness/local.md` | Dự án sở hữu; domain, build command, convention riêng |
-| `openspec/config.yaml` | Chỉ tạo nếu chưa có; giữ cấu hình hiện tại |
-| `openspec/changes/<id>/` | Chỉ tạo khi gọi `new-change`; còn TODO cần hoàn thiện |
-
-Commit các file đã cài vào repository ứng dụng để cả team dùng đúng một phiên bản. Không commit secrets.
-Hãy hướng assistant đọc `AGENTS.md`; việc tự phát hiện file/skill phụ thuộc công cụ bạn sử dụng.
-CLI không cấu hình tài khoản, plugin cá nhân hoặc MCP server của assistant.
-
-## Tùy biến và cập nhật
-
-Cài phiên bản công cụ mới trước, rồi chạy `aih update` trong từng dự án để cập nhật snapshot.
-Lockfile từ CLI Python 0.1 vẫn được hỗ trợ; xem [migration](docs/versioning.md).
-
-Thêm quy ước vào `.harness/local.md` hoặc phần ngoài marker trong `AGENTS.md`.
-Muốn đổi stack: chỉnh mảng `adapters` trong `.harness/project.json`, rồi chạy update.
-
-```bash
-aih update --dry-run
-aih update
-aih check
-aih doctor
-```
-
-Source mặc định là package đã cài chứa CLI; có thể dùng `--source /path/to/reviewed-checkout` với init/update.
-Cập nhật dừng khi file managed bị sửa, không có chế độ force. Đưa tùy biến sang local.md rồi restore
-file managed từ commit cài trước đó. Major upgrade cần `--allow-major`; downgrade dùng Git revert.
-Dry-run không để lại thay đổi file, nhưng tạo/xóa marker khóa trong lúc lập kế hoạch nên cần quyền ghi.
-Doctor chỉ kiểm tra tool có trên PATH; không xác nhận version hay build chạy thành công.
-
-## OpenSpec
-
-Framework tạo cấu trúc tương thích workflow `spec-driven` và không cài OpenSpec thay bạn.
-`new-change` tạo proposal/design/tasks/delta spec bằng template đã pin trong project; đây là bản nháp.
-Hoàn thiện TODO, review yêu cầu, rồi dùng OpenSpec CLI do dự án cài và pin phiên bản:
-
-```bash
-# Chạy tại repository ứng dụng sau khi cài OpenSpec theo hướng dẫn upstream.
-openspec validate add-order --strict
-```
+| Bắt đầu | [Getting started](docs/getting-started.md) |
+| Phát triển end-to-end | [Full SDLC](docs/end-to-end-workflow.md) · [Agent handoffs](docs/agent-handoffs.md) |
+| Tra cứu kỹ năng | [Skill matrix](docs/skill-matrix.md) · [CLI reference](docs/cli.md) |
+| Tài liệu sản phẩm | [Idea-driven example](docs/examples/idea-driven-project.md) · [Document-driven example](docs/examples/document-driven-project.md) |
+| Ví dụ backend/full-stack | [Spring Boot API](docs/examples/spring-boot-api.md) · [Spring + Next.js](docs/examples/fullstack-web.md) |
+| Ví dụ mobile/AI | [React Native](docs/examples/react-native-app.md) · [Python AI/RAG](docs/examples/ai-rag-service.md) |
+| Micro-tools/website | [Astro micro-tools](docs/examples/astro-micro-tools.md) · [Astro + AdSense](docs/examples/astro-adsense-microtools.md) · [Monetization](docs/monetization.md) |
+| Phát hành npm | [Release guide](docs/npm-release.md) · [Changelog](CHANGELOG.md) |
 
-Xem [docs/openspec.md](docs/openspec.md). Chỉ archive sau khi mọi PR liên quan đã merge.
-
-## Kiểm thử
+## Kiểm tra và cập nhật
 
 ```bash
+# Trong repository AI Harness (maintainer)
 npm test
 npm run validate
 npm run test:package
-```
-
-Test CLI chạy offline trên thư mục tạm: cài/update, preservation, drift, collision, traversal/symlink,
-adapter selection, version guard, reproducibility, rollback và tạo change. CI cấu hình Node.js 22/24 trên Linux và Windows.
-[evals/README.md](evals/README.md) có bộ tình huống và công cụ tổng hợp đánh giá hành vi AI riêng.
-Test CLI pass không có nghĩa đã chạy Spring/Next/native build hay live evaluation của LLM.
 
-## License
-
-Dự án được cấp phép theo [MIT License](LICENSE) — cho phép sử dụng, sửa đổi và phân phối (kể cả thương mại) theo các điều kiện trong giấy phép. Repository vẫn **private** và package npm đã cấu hình `public`; việc thêm license không tự thay đổi quyền truy cập hoặc phát hành package.
-
-## Tài liệu
-
-- [Getting started](docs/getting-started.md)
-- [Documentation workflows](docs/documentation-workflows.md)
-- [Walkthrough Idea-driven](docs/examples/idea-driven-project.md)
-- [Walkthrough Document-driven](docs/examples/document-driven-project.md)
-- [Astro micro-tool walkthrough](docs/examples/astro-micro-tools.md)
-- [Website advertising monetization](docs/monetization.md)
-- [Astro + AdSense walkthrough](docs/examples/astro-adsense-microtools.md)
-- [Full SDLC](docs/end-to-end-workflow.md)
-- [Skill matrix](docs/skill-matrix.md)
-- [Agent handoffs](docs/agent-handoffs.md)
-- [Kiến trúc và ranh giới trách nhiệm](docs/architecture.md)
-- [Versioning và migration](docs/versioning.md)
-- [CLI contract](docs/cli.md)
-- [Phân tích workspace tham khảo](docs/reference-analysis.md)
-- [Hướng dẫn đóng góp](CONTRIBUTING.md)
-- [Thay đổi phiên bản](CHANGELOG.md)
+# Nâng CLI global, rồi cập nhật snapshot trong project
+npm install -g @manhd_d/ai-harness@latest
+aih update --dry-run
+aih update
+aih check
+```
 
-`harness.yaml` cố ý dùng JSON-compatible YAML 1.2 để CLI đọc bằng `JSON.parse`. Không dùng cú pháp YAML
-khác cho file này. `openspec/config.yaml` vẫn là YAML thông thường do OpenSpec đọc.
+**License:** [MIT](LICENSE). GitHub source có thể private; package `@manhd_d/ai-harness` được phát hành công khai qua npm.

package/cli/environment.js

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, isObject, SLUG, HarnessError } from './files.js';
+
+export const ENVIRONMENT = '.harness/environment.json';
+export const MACHINE = '.harness/machine.json';
+export const emptyEnvironment = () => ({ schema_version: 1, tools: {}, files: {}, commands: {} });
+const validText = s => typeof s === 'string' && s.trim().length > 0 && !/[\0\r\n]/.test(s);
+const own = (o, k) => Object.hasOwn(o, k);
+function requireThat(ok, message) { if (!ok) throw new HarnessError(message); }
+
+export function readConfig(root, name) {
+  const p = safe(root, name), info = stat(p);
+  if (!info) return null;
+  requireThat(info.size <= 1024 * 1024, 'Configuration exceeds 1 MiB: ' + name);
+  // Never include parser input (possibly private machine paths) in diagnostics.
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { throw new HarnessError('Invalid JSON: ' + name); }
+}
+function keys(value, allowed, label) {
+  requireThat(isObject(value) && Object.keys(value).every(k => allowed.includes(k)), 'Invalid fields: ' + label);
+}
+export function loadEnvironment(root) {
+  const shared = readConfig(root, ENVIRONMENT);
+  const machine = readConfig(root, MACHINE);
+  if (shared === null) {
+    requireThat(machine === null, 'Machine configuration requires environment.json');
+    return { configured: false, shared: emptyEnvironment(), machine: null };
+  }
+  keys(shared, ['schema_version', 'tools', 'files', 'commands'], ENVIRONMENT);
+  requireThat(shared.schema_version === 1, 'Unsupported environment schema');
+  for (const group of ['tools', 'files', 'commands']) {
+    requireThat(isObject(shared[group]), 'Missing environment map: ' + group);
+    for (const [id, value] of Object.entries(shared[group])) {
+      requireThat(SLUG.test(id), 'Invalid environment identifier');
+      const label = group + '/' + id;
+      if (group === 'commands') {
+        keys(value, ['tool', 'args'], label);
+        requireThat(validText(value.tool) && own(shared.tools, value.tool), 'Unknown command tool: ' + id);
+        requireThat(Array.isArray(value.args) && value.args.every(a => typeof a === 'string' && !/[\0\r\n]/.test(a)), 'Invalid arguments: ' + id);
+      } else {
+        const field = group === 'tools' ? 'executable' : 'path';
+        keys(value, [field, 'required'], label);
+        requireThat(validText(value[field]), 'Missing path: ' + label);
+        requireThat(value.required === undefined || typeof value.required === 'boolean', 'Invalid required flag: ' + label);
+      }
+    }
+  }
+  if (machine !== null) {
+    keys(machine, ['schema_version', 'tools', 'files'], MACHINE);
+    requireThat(machine.schema_version === 1, 'Unsupported machine schema');
+    for (const group of ['tools', 'files']) {
+      if (machine[group] === undefined) continue;
+      requireThat(isObject(machine[group]), 'Invalid machine map: ' + group);
+      const field = group === 'tools' ? 'executable' : 'path';
+      for (const [id, value] of Object.entries(machine[group])) {
+        requireThat(SLUG.test(id) && own(shared[group], id), 'Machine override must reference a declared ' + group + ' entry');
+        keys(value, [field], 'machine ' + group + '/' + id);
+        requireThat(validText(value[field]), 'Invalid machine override: ' + group + '/' + id);
+      }
+    }
+  }
+  return { configured: true, shared, machine };
+}
+
+function expand(value, env) {
+  const missing = [];
+  const resolved = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => {
+    if (!own(env, key) || !validText(env[key])) { missing.push(key); return ''; }
+    return env[key];
+  });
+  return { resolved, missing: [...new Set(missing)], invalid: /\$\{/.test(resolved) };
+}
+function pathStatus(value, root, executable, env) {
+  if ((process.platform !== 'win32' && /^[A-Za-z]:[\\/]|^\\\\/.test(value)) ||
+      (process.platform === 'win32' && value.startsWith('/'))) return 'platform-mismatch';
+  if (value.startsWith('~')) return 'unsupported-path'; // No implicit shell expansion.
+  const bare = !path.isAbsolute(value) && !/[\\/]/.test(value);
+  const candidates = executable && bare
+    ? (env.PATH || '').split(path.delimiter).filter(Boolean).filter(path.isAbsolute).map(dir => path.join(dir, value))
+    : [path.resolve(root, value)];
+  const extensions = executable && process.platform === 'win32' && !path.extname(value)
+    ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(e => /^\.[A-Za-z0-9]+$/.test(e)) : [''];
+  let notExecutable = false;
+  for (const candidate of candidates) for (const ext of extensions) {
+    try {
+      const p = candidate + ext;
+      if (!fs.statSync(p).isFile()) continue;
+      fs.accessSync(p, executable && process.platform !== 'win32' ? fs.constants.X_OK : fs.constants.F_OK);
+      return 'present';
+    } catch (e) { if (e.code === 'EACCES') notExecutable = true; }
+  }
+  return notExecutable ? 'not-accessible' : 'missing';
+}
+
+export function environmentReport(root, env = process.env) {
+  const { configured, shared, machine } = loadEnvironment(root);
+  const entries = [];
+  for (const group of ['tools', 'files']) for (const [id, value] of Object.entries(shared[group])) {
+    const field = group === 'tools' ? 'executable' : 'path';
+    const override = machine?.[group]?.[id];
+    const expanded = expand(override ? override[field] : value[field], env);
+    entries.push({ group, id, source: override ? 'machine' : 'project', required: value.required !== false,
+      status: expanded.missing.length ? 'missing-env' : expanded.invalid ? 'invalid-reference'
+        : pathStatus(expanded.resolved, root, group === 'tools', env),
+      missing_variables: expanded.missing });
+  }
+  // Arguments are references only; do not execute or print resolved values.
+  for (const [id, command] of Object.entries(shared.commands)) {
+    const args = command.args.map(a => expand(a, env));
+    const missing = [...new Set(args.flatMap(a => a.missing))];
+    entries.push({ group: 'commands', id, source: 'project', required: shared.tools[command.tool].required !== false,
+      status: missing.length ? 'missing-env' : args.some(a => a.invalid) ? 'invalid-reference' : 'declared',
+      missing_variables: missing });
+  }
+  const problems = entries.filter(e => e.required && !['present', 'declared'].includes(e.status))
+    .map(e => e.group + '/' + e.id + ': ' + e.status);
+  return { configured, machine_present: machine !== null, entries, problems,
+    note: 'Presence/reference checks only. No commands executed; values and arguments are omitted. Never store credentials here.' };
+}
+
+export function setupPlan(root, adapters, env = process.env) {
+  const environment = environmentReport(root, env);
+  const configuredTools = environment.entries.some(e => e.group === 'tools');
+  const questions = [];
+  if (adapters.includes('java-spring') && !configuredTools) {
+    const wrapper = process.platform === 'win32' ? 'mvnw.cmd' : 'mvnw';
+    const hasWrapper = Boolean(stat(safe(root, wrapper)));
+    const gradle = ['gradlew', 'gradlew.bat', 'build.gradle', 'build.gradle.kts'].some(p => Boolean(stat(safe(root, p))));
+    if (gradle) {
+      questions.push({ id: 'build-tool', question: 'Which build tool does this project use?',
+        options: [{ label: 'A', value: 'gradle', description: 'Use the existing Gradle setup.' },
+          { label: 'B', value: 'maven', description: 'Use Maven only if project conventions require it.' }],
+        recommendation: 'A', reason: 'Gradle files exist; confirm the project convention.', allow_free_text: true });
+    } else questions.push({ id: 'maven-mode', question: 'How should Maven be invoked?',
+      options: [{ label: 'A', value: 'wrapper', description: 'Use the repository Maven Wrapper.' },
+        { label: 'B', value: 'path', description: 'Use Maven available on PATH.' },
+        { label: 'C', value: 'custom', description: 'Use an internal Maven executable and optional settings file.' }],
+      recommendation: hasWrapper ? 'A' : null,
+      reason: hasWrapper ? 'A wrapper exists for this OS; review it before execution.' : 'No wrapper found for this OS; ask which Maven the team uses.',
+      allow_free_text: true });
+  }
+  if (!environment.configured || !environment.entries.length) questions.push({
+    id: 'project-context', question: 'Where are the authoritative project requirements and conventions?',
+    options: [{ label: 'A', value: 'repository', description: 'Use existing repository documentation and build files.' },
+      { label: 'B', value: 'external', description: 'Use authorized BA/Confluence sources with revisions.' },
+      { label: 'C', value: 'idea', description: 'Start from the user idea and clarify the scope.' }],
+    recommendation: null, reason: 'The host must inspect existing local.md and sources before recommending.',
+    allow_free_text: true
+  });
+  return { status: environment.problems.length ? 'blocked' : 'planned', environment, questions,
+    next_steps: ['Read AGENTS.md, .harness/local.md and the installed project-setup workflow.',
+      'Skip answered questions; ask at most 1–3 consequential questions with evidence-based recommendations.',
+      'Record shared decisions in local.md/environment.json; put only machine paths in ignored machine.json.',
+      'Run aih doctor, then use the reviewed project commands through your AI host.'],
+    note: 'Read-only host-facing suggestions, not an interactive terminal wizard or approval.' };
+}