@manhd_d/ai-harness 0.6.0 → 0.7.0

package/docs/getting-started.md

@@ -1,148 +1,110 @@
-# Getting started — cài và sử dụng AI Harness
+# Bắt đầu với AI Harness
 
-AI Harness phân phối **rules, role contracts, skills và workflows** tới repository ứng dụng. Lệnh `aih` là CLI chạy offline, không phải AI agent runner: nó không tạo ứng dụng, đọc Confluence, tạo Figma, chạy test, gọi LLM, merge PR hay deploy.
+**Cài một lần → ghi context dự án → giao việc cho AI → kiểm tra kết quả.**
 
-**Đọc theo thứ tự:** [Full SDLC](end-to-end-workflow.md) → [Skill matrix](skill-matrix.md) → [Agent handoffs](agent-handoffs.md) → [Ví dụ theo stack](#ví-dụ-thực-hành).
+Cần Node.js **22+**, Git và một repository ứng dụng đã tồn tại. AI IDE/assistant phải đọc được file trong repository; cách tự nạp `AGENTS.md` và skills phụ thuộc AI host. CLI `aih` quản lý hướng dẫn, không chạy LLM hay tạo ứng dụng.
 
-## 1. Chuẩn bị
+## 1. Cài vào project
 
-- Node.js >=22, Git và npm (cần quyền repository private chỉ khi cài từ source).
-- Một **repository ứng dụng đã tồn tại** và AI IDE/assistant có thể đọc file trong repository đó.
-- Chỉ kết nối GitHub, Confluence, Figma hay nền tảng khác trong AI host khi cần, theo quyền đã phê duyệt.
-- **OpenSpec CLI là tùy chọn**: `aih new-change` tạo bản nháp offline, còn `openspec validate` cần OpenSpec CLI cài riêng. Xem [OpenSpec](openspec.md).
-- Bản nguồn hiện tại là candidate; chưa mặc định có một bản `@manhd_d/ai-harness` được phát hành trên npm registry. Xem [npm release](npm-release.md).
-
-## 2. Cài một lần từ source đã review
-
-~~~bash
-git clone git@github.com:manh0303/ai-harness.git
-cd ai-harness
-# Nếu thử PR Astro chưa merge, chọn branch đã review:
-git switch feat/astro-lightweight-adapter
-# Sau khi merge, ưu tiên commit/tag chính thức đã review.
-npm test
-npm run validate
-npm run test:package
-npm pack
-npm install -g ./manhd_d-ai-harness-0.6.0.tgz
-aih --version
-~~~
-
-Nếu package đã được publish công khai thì có thể cài bằng `npm install -g @manhd_d/ai-harness`; **đừng coi lệnh cài registry là dùng được trước khi xác minh việc phát hành**. Cài bộ `aih` không tự cài OpenSpec hay dependency Spring/React/Python cho ứng dụng.
-
-## 3. Cài Harness vào repository ứng dụng
-
-Ví dụ service Spring Boot có nhu cầu làm tài liệu sản phẩm và triển khai Kubernetes:
-
-~~~bash
-cd /path/to/existing-spring-service
-aih resolve --adapters java-spring,kubernetes --capabilities product,devops
-aih init --adapters java-spring,kubernetes --capabilities product,devops --dry-run
-aih init --adapters java-spring,kubernetes --capabilities product,devops
+```bash
+npm install -g @manhd_d/ai-harness
+cd /path/to/existing-project
+aih init --adapters java-spring
 aih check
-aih skills
-~~~
+```
 
-- `aih resolve`: kiểm tra dependency/compatibility và cảnh báo recommendation; **không cài module**.
-- `aih init --dry-run`: xem diff dự kiến, **không cài đặt lâu dài**.
-- `aih init`: cài snapshot đã chọn trong `.harness/`, tạo AGENTS block, ghi lock và expose skills trong `.agents/skills/`.
-- `aih check`: kiểm tra integrity của file do Harness quản lý, **không kiểm thử source code ứng dụng**.
-- `aih skills`: liệt kê metadata. `aih skill <tên>`: đọc **một** skill đã cài, không tự kích hoạt agent.
+Chọn module theo nhu cầu, không cần cài cả bộ:
 
-**Các lựa chọn phổ biến:**
-
-| Dự án | Lựa chọn |
+| Nhu cầu | Tham số cho `aih init` |
 | --- | --- |
-| API Spring | `--adapters java-spring` |
-| Web React/Next.js | `--adapters react-nextjs --capabilities uiux` |
-| Astro web tools (static-first) | `--adapters astro` (tùy chọn `--capabilities product,uiux`) |
-| Astro/React + advertising | `--adapters astro --capabilities monetization` (hoặc `react-nextjs`) |
-| React Native/Expo | `--adapters react-native --capabilities product,uiux` |
-| Python AI/RAG | `--adapters ai-python --capabilities product` |
-| Full-stack một repo | `--adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops` |
-| Chỉ BA/PO | `--capabilities product` |
-| Core-only | Không truyền adapters/capabilities |
+| Spring Boot API | `--adapters java-spring` |
+| React/Next.js + UI | `--adapters react-nextjs --capabilities uiux` |
+| Astro tool nhỏ | `--adapters astro` |
+| Website có quảng cáo | `--adapters astro --capabilities monetization` |
+| Viết tài liệu từ ý tưởng hoặc tài liệu BA | `--capabilities product` |
+| Spring + tài liệu + Kubernetes | `--adapters java-spring,kubernetes --capabilities product,devops` |
 
-`aih detect` kiểm tra heuristic các file trực tiếp ở target, không tìm đệ quy monorepo. Với mỗi microservice/repository độc lập, cài riêng và chỉ chọn những module thực sự cần.
+`aih list` xem toàn bộ module. `aih init --dry-run` xem trước thay đổi với cùng tham số đã chọn. Với project đã cài, đổi module trong `.harness/project.json` rồi dùng `aih update`, không chạy lại `init` với lựa chọn khác.
 
-## Astro cho web tools nhỏ
+## 2. Ghi context và bắt đầu giao việc
 
-Nếu xây nhiều tiện ích như QR, JSON hoặc image tools: dùng [Astro micro-tools walkthrough](examples/astro-micro-tools.md) với lệnh `aih init --adapters astro` và skill islands, SEO, performance, Cloudflare. `astro` được nhận diện từ dependencies. React Islands không bắt buộc; MFE/Workers không được cài tự động.
+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ó.
 
-## Website công cụ miễn phí có quảng cáo
+Điền `.harness/local.md` bằng thông tin thực của project:
 
-Nếu mục tiêu là traffic SEO và doanh thu AdSense, chọn optional `monetization` **không phụ thuộc Astro**; website có thể dùng Next.js. Xem [Monetization guide](monetization.md), [walkthrough Astro + AdSense](examples/astro-adsense-microtools.md) và `aih skill harness-monetization-adsense-integration`. Các hướng dẫn chỉ giúp chuẩn bị, không tự tạo tài khoản AdSense hoặc kết nối Analytics.
+- Mục tiêu, phạm vi và quy tắc nghiệp vụ quan trọng.
+- Stack/phiên bản, database, cấu trúc service/module.
+- Lệnh build/test đã xác nhận chạy được.
+- Đường dẫn tài liệu BA, conventions và những ràng buộc cần giữ.
 
-## Hai hướng dẫn theo loại dự án
+Mở project trong AI IDE và giao yêu cầu, ví dụ:
 
-- [Idea-driven — có ý tưởng và muốn AI cùng thảo luận, nghiên cứu, viết tài liệu](examples/idea-driven-project.md).
-- [Document-driven — có BRD/PRD/SRS từ BA, cần AI đưa vào phát triển phần mềm](examples/document-driven-project.md).
+> Đọc AGENTS.md và .harness/local.md, chỉ nạp skill liên quan. Thêm API tìm kiếm khách hàng theo yêu cầu này: … Làm rõ điểm chưa chắc chắn, đề xuất acceptance scenarios; sau khi thống nhất scope, triển khai, chạy test phù hợp và báo cáo kết quả thực chạy.
 
-**Lưu ý:** khi PR chứa tính năng chưa merge, cần checkout đúng branch/commit đã review trước khi `npm pack`; cài từ `main` không mặc định có các tính năng chỉ có trong PR.
+Bạn không cần gọi từng role/skill thủ công. Nếu host không tự phát hiện hướng dẫn, yêu cầu assistant đọc các đường dẫn trên. `aih skills` xem danh sách; `aih skill <tên>` đọc một skill khi cần.
 
-## 4. Bắt đầu một thay đổi có traceability
+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ý.
 
-Hai workflow tài liệu: `idea-driven` khi bắt đầu từ ý tưởng thô, `document-driven` khi đã có BRD/PRD/SRS/Confluence do BA cung cấp. Cả hai dùng chung pipeline, approval và OpenSpec. Xem [Documentation workflows](documentation-workflows.md).
+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
 
-~~~bash
-# Chỉ dùng được khi đã chọn capability product:
-aih new-doc brd
-aih new-doc prd
-aih new-doc backlog
-aih new-doc acceptance-criteria
-aih new-doc traceability
-aih new-doc idea       # docs/discovery/
-aih new-doc research   # docs/discovery/
-aih new-doc prd-lite   # docs/product/
-aih new-doc srs        # docs/product/
-aih new-doc use-cases  # docs/product/
+Với capability `product`:
 
-# Tạo change bản nháp OpenSpec — không cần cài OpenSpec CLI:
-aih new-change add-customer-api
+```bash
+aih new-doc prd-lite
+```
 
-# Đọc từng skill cần thiết:
-aih skill harness-product-prd-generation
-aih skill harness-spec
-aih skill harness-tdd
-~~~
+Lệnh tạo template `docs/product/prd-lite.md`; bạn và AI điền nội dung, nguồn và acceptance criteria. Chọn [Idea-driven](examples/idea-driven-project.md) nếu bắt đầu từ ý tưởng; chọn [Document-driven](examples/document-driven-project.md) nếu đã có tài liệu BA/Confluence.
 
-Các lệnh `new-doc` chỉ copy template trống sang `docs/product/`; AI host/BA/PO phải điền theo nguồn đáng tin cậy và duyệt. `new-change` chỉ tạo proposal/design/tasks/spec có TODO; **không phải spec đã được approve**. Trước khi yêu cầu IDE implement, hướng assistant đọc `AGENTS.md` và `.harness/local.md` của dự án.
+Khi một tính năng cần proposal/design/tasks/spec riêng:
 
-**Prompt mẫu gửi cho assistant:**
+```bash
+aih new-change add-customer-search
+```
 
-> Hãy đọc AGENTS.md, .harness/local.md và các skill phù hợp đã cài. Phân tích yêu cầu theo source ID, nêu các điểm chưa rõ, soạn OpenSpec change và test scenarios. Chỉ implement khi scope được duyệt; báo cáo tests thực chạy và tạo PR để tôi review, không tự merge hoặc deploy.
+Đâ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.
 
-## 5. Verify / evaluate và release
+`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).
 
-~~~bash
-aih verify --scope all
-aih eval --scope all
-aih check
-~~~
+## 4. Kiểm tra đúng thứ
+
+| Lệnh | Ý nghĩa |
+| --- | --- |
+| `aih check` | Kiểm tra integrity của file Harness; không kiểm thử ứng dụng |
+| `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 |
 
-- `verify`: checklist advisory, `executed: false`. Dùng bằng chứng chạy build/test **bên ngoài CLI**.
-- `eval`: dataset và report để con người chạy bài test với một AI runtime được cấp quyền rồi chấm; **không gọi model, không tự chấm**.
-- `--scope all`: Core + capability + adapter và scenario ghép module phù hợp. Không có scope thì mặc định chỉ là adapter.
-- Production approval phải chỉ rõ artifact, environment và người phê duyệt; CI xanh không cấp quyền deploy.
+Một lần `aih check` thành công không có nghĩa tính năng đã đúng. Ghi lệnh test thực chạy, kết quả và phần chưa kiểm chứng trong PR. Xem [đánh giá hành vi AI](../evals/README.md) nếu muốn đo hiệu quả Harness.
 
-Đọc các [approval gates trong Full SDLC](end-to-end-workflow.md) và [DevOps runbook](../capabilities/devops/workflows/pr-to-production.md).
+## 5. Cập nhật: CLI trước, project sau
 
-## 6. Update bộ Harness đã cài
+Trên branch riêng, commit trạng thái hiện tại trước. Với cách cài global ở trên:
 
-~~~bash
-# Trên branch của consumer, commit trạng thái hiện tại trước.
-# Thay đổi adapters/capabilities trong .harness/project.json nếu cần.
+```bash
+npm install -g @manhd_d/ai-harness@latest
+aih --version
+aih check
 aih update --dry-run
 aih update
 aih check
-~~~
+```
+
+`aih --version` là phiên bản CLI; `aih check` trả phiên bản snapshot trong project. `aih update` lấy bundle từ CLI đang cài (hoặc `--source`), **không tự tải npm**. Review diff, chạy test ứng dụng và commit snapshot/lock cùng nhau. Nếu báo drift, giữ lại thay đổi trong Git, chuyển tùy chỉnh sang `.harness/local.md` và khôi phục managed files trước khi update.
 
-Không chỉnh file snapshot dưới `.harness/core|adapters|capabilities` hoặc skill do Harness quản lý; nội dung riêng của dự án thuộc `.harness/local.md`. Nếu có drift, khôi phục từ Git và review diff; không sửa lock hash để che lỗi.
+Nếu cài local trong project, dùng `npm install --save-dev @manhd_d/ai-harness@latest` và `npx aih` thay cho `aih`.
 
-## Ví dụ thực hành
+## Đọc thêm theo nhu cầu
 
-- [Spring Boot REST API với Kafka/DB/Kubernetes](examples/spring-boot-api.md)
-- [Full-stack Spring + Next.js + Figma](examples/fullstack-web.md)
-- [React Native/Expo có offline-sync](examples/react-native-app.md)
-- [Python AI/RAG với kiểm soát truy cập](examples/ai-rag-service.md)
+- [CLI reference](cli.md) · [Full SDLC](end-to-end-workflow.md) · [Skill matrix](skill-matrix.md) · [Agent handoffs](agent-handoffs.md).
+- [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.

package/docs/npm-release.md

@@ -1,70 +1,57 @@
-# npm installation and release
+# npm publishing — automated releases
 
-The public npm package is `@manhd_d/ai-harness` (executable: `aih`). The private GitHub repository stays `manh0303/ai-harness`. Different npm and GitHub usernames are expected.
+The public distribution is `@manhd_d/ai-harness` (CLI command `aih`). The GitHub source stays **private** at `manh0303/ai-harness`. First version `0.6.0` was published manually by its owner.
 
-**Changing this configuration and merging a PR does not publish a package.** Public npm publication makes every file inside the npm tarball publicly accessible, regardless of GitHub repository visibility.
+## One-time npm Trusted Publisher setup
 
-## First publication: manual, maintainer-controlled
+In [npm package settings](https://www.npmjs.com/package/@manhd_d/ai-harness) → Trusted Publisher select **GitHub Actions** with:
 
-1. Confirm the verified npm account is `manhd_d`, with 2FA enabled, and the publishing machine uses the official npm registry.
-2. Merge the reviewed PR. Check out the approved `main` commit. Review `npm pack --dry-run` for secrets before sharing the archive.
-3. Run:
+| Field | Value |
+| --- | --- |
+| Organization or user | `manh0303` |
+| Repository | `ai-harness` |
+| Workflow filename | `npm-publish.yml` |
+| Environment | Leave empty |
+| Allowed actions | **Allow npm publish** (required) |
 
-```bash
-git switch main
-git pull --ff-only
-npm login
-npm whoami
-npm config get registry
-npm ci --ignore-scripts --no-audit --no-fund
-npm test
-npm run validate
-npm run check:release
-npm run test:package
-npm pack --dry-run
-npm publish --access public
-npm view @manhd_d/ai-harness version
-```
+Use **npm CLI >= 11.5.1** and Node 22.14+ for OIDC; this workflow runs Node 24 and installs npm 11. No `NPM_TOKEN` or OTP is required in GitHub Actions. Keep npm 2FA on for account security. Because the GitHub repository is private, npm provenance attestations are unavailable and the workflow disables provenance while retaining OIDC.
 
-`npm whoami` must return `manhd_d`. The expected first package version is `0.6.0`, if the maintainer has approved that release and the version is not already published. Publishing may require browser/2FA confirmation. Never commit npm credentials or tokens.
+**Repository setting required:** GitHub → `manh0303/ai-harness` → Settings → Actions → General → Workflow permissions → ensure **Allow GitHub Actions to create and approve pull requests** is enabled. This grants Release Please permission to open Release PRs (which are still reviewed by a human). GitHub does not validate the npm Trusted Publisher mapping when it is saved; the first OIDC release run proves it works.
 
-A successful publish is independently verifiable with `npm view`. You can add an annotated git tag `v0.6.0` to the exact commit afterwards, but **do not create/publish a GitHub Release for a version already published manually**.
+## End-to-end workflow
 
-## Later releases: npm Trusted Publishing via GitHub Actions
+1. Feature/fix PRs use Conventional Commits or squash titles: `feat: ...` (minor), `fix: ...` (patch), `feat!: ...` / `BREAKING CHANGE` (breaking). Do **not** bump `package.json`, `package-lock.json`, `harness.yaml` or the Release Please manifest on feature branches.
+2. CI runs tests; **you review and merge** the feature PR into `main`.
+3. `.github/workflows/npm-publish.yml` runs CI on `main` then Release Please. It opens/updates a separate **Release PR**, proposing version/changelog changes. It also explicitly dispatches `harness.yml` for the generated Release PR branch; the `GITHUB_TOKEN` does not trigger arbitrary downstream workflows.
+4. **You review and merge the Release PR** once satisfied. That `main` push triggers the same workflow. After tests pass, Release Please creates a `vX.Y.Z` Git tag and GitHub Release.
+5. The **same** `npm-publish.yml` run checks out that tag, checks ancestry on `main`, verifies scope/manifest/changelog, runs tests and an actual npm tarball smoke test, then executes `npm publish --access public` with GitHub OIDC.
+6. Confirm the new version with `npm view @manhd_d/ai-harness version`. npm processing can take a few minutes. Consumers run `npm install -g @manhd_d/ai-harness@latest`, then `aih update --dry-run`, `aih update` and `aih check` inside each project.
 
-After the first successful manual publication, go to [npm](https://www.npmjs.com) → package `@manhd_d/ai-harness` → Settings → Trusted publishing and configure a GitHub Actions publisher:
+**Why one workflow?** Release Please uses `GITHUB_TOKEN`. GitHub usually suppresses new workflow runs in response to events created by `GITHUB_TOKEN`, including its `release.published` event. Publishing in the same `push main` workflow avoids silently skipping npm publication. For a **manually published** GitHub Release, the same file also supports `release.published` as a fallback, with matching version and main-ancestry guards. Do not create a manual GitHub Release for a version already present on npm; npm versions cannot be overwritten.
 
-| Field | Value |
-| --- | --- |
-| GitHub user/organization | `manh0303` |
-| Repository | `ai-harness` |
-| Workflow file | `npm-publish.yml` |
-| Environment | Leave empty (workflow does not use an environment) |
+## Bootstrap from manually published v0.6.0
 
-Select direct **npm publish** permissions if npm offers a stage-only option. Configure the trusted publisher shortly before the next release if npm applies an initial activation deadline. No long-lived `NPM_TOKEN` is required.
+`.release-please-manifest.json` starts at `{".":"0.6.0"}` and `release-please-config.json` pins `bootstrap-sha` to the main commit from which v0.6.0 was published. This prevents replaying all historical changes or treating an older branch's releases as new. For the root npm package Release Please uses:
 
-For each subsequent version: use a dedicated release PR to update `package.json`, `package-lock.json`, `harness.yaml` and `CHANGELOG.md` together, run CI, review and merge. Create a tag `vX.Y.Z` at the tested main commit and **publish the corresponding GitHub Release**. Only this Release publication triggers `.github/workflows/npm-publish.yml`. The workflow checks that the commit is reachable from main, that the tag matches the package version, and that tests and tarball smoke checks pass before attempting OIDC-based publication.
+- `release-type: node` to update `package.json`, `package-lock.json`, and `CHANGELOG.md`.
+- `include-v-in-tag: true` and `include-component-in-tag: false` to create tags like `v0.6.1`.
+- **`extra-files` type `json` for `harness.yaml`**, because despite its .yaml name, this file must stay valid JSON and is parsed with `JSON.parse`; a YAML updater would break the CLI.
 
-A private GitHub source repository does not support npm provenance attestation even though the public package can use OIDC. Do not enable npm provenance for this private repository. See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+`scripts/check-release.js` blocks mismatched versions across the three distribution metadata files and Release Please manifest, and accepts old and Release Please-generated changelog version headings. Feature PRs should not edit `bootstrap-sha`; it becomes irrelevant after the first automated release.
 
-## Local installation before npm publication
+## Security and recovery
 
-```bash
-npm pack
-npm install -g ./manhd_d-ai-harness-0.6.0.tgz
-aih --version
-```
+No workflow automatically merges a PR. The release job uses only `contents: read` and `id-token: write`; the Release Please job has separately scoped permissions to open PRs/create releases. GitHub-hosted runners are required for npm OIDC. If a Release PR appears without CI checks, use the explicitly dispatched CI run linked from Actions. Never merge an unreviewed release PR.
 
-## Installation after verified npm publication
+If the Release Please job fails to create a PR, check repository Actions workflow permissions and the workflow logs. If npm returns E403, check Trusted Publisher's **workflow filename exactly `npm-publish.yml`**, allowed action `npm publish`, and that the connection is active. Do not add bypass-2FA tokens as a workaround. An expired/unverified publisher binding may require recreating it in npm settings.
 
-```bash
-npm install -g @manhd_d/ai-harness
-aih --version
-cd /path/to/existing-project
-aih init --adapters java-spring
-aih check
-```
+If GitHub Release exists but npm publish failed, **do not bump the version blindly or create another GitHub Release for the same tag**. Diagnose the failed job. Re-running the workflow is appropriate only when npm still has no published version and the error is resolved. A documented manual recovery is possible after verifying the tag and credentials.
 
-Existing consumers can update the CLI with `npm update -g @manhd_d/ai-harness`. Use `aih update --dry-run`, `aih update`, `aih check` to update a consumer project's snapshot on a branch. CLI installation does not install OpenSpec, an AI runtime or application dependencies.
+If the failure is in code/tests stored in the release tag, fixing `main` does not fix that immutable
+tag. Do not move or overwrite it. Merge the repair, let Release Please prepare a new patch Release PR,
+verify CI on its exact head, then review/merge it. Re-running the old tag will reproduce the old defect.
+For example, v0.6.1 failed before publication because two migration tests expected 0.6.0.
+Main now compares against the source version; the regression suite also exercises the next patch
+version. Publish the reviewed follow-up release rather than changing v0.6.1.
 
-Read [Getting started](getting-started.md) and [Release policy](release-policy.md).
+Official docs: [Release Please](https://github.com/googleapis/release-please-action), [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/), [GitHub Actions event triggering](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).

package/docs/project-configuration.md

@@ -0,0 +1,82 @@
+# Cấu hình từng project và từng máy
+
+| File | Nội dung | Git |
+| --- | --- | --- |
+| `.harness/project.json` | Adapter/capability | 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ụ.
+
+## 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/release-policy.md

@@ -7,7 +7,7 @@ Distribution version is `harness.yaml` + `package.json` + `package-lock.json`. O
 2. Each module maintainer changes `module_version` only for real contract changes, describing compatibility impact in the PR.
 3. One **release PR** assigns the next distribution version, updates all three metadata files, and moves Unreleased notes into a version heading.
 4. Check CI on Linux/Windows and Node 22/24; run behavioral agent evaluations when instructions change, not just synthetic unit tests.
-5. A human merges the release PR and separately approves npm publication: first version is manually published; subsequent versions require a human-published matching GitHub Release. No publishing merely on merge or tag.
+5. A human reviews/merges the feature PR, then reviews/merges the auto-generated Release Please PR. The second approval authorizes the workflow to tag/release and publish npm through OIDC, after tests. No publishing from feature PRs, and no publish-on-tag alone.
 
 ## Compatibility
 - Existing schema-1 config and locks remain valid. Optional module contract fields are additive.

package/docs/versioning.md

@@ -1,7 +1,7 @@
 # Versioning and migration
 
 Framework version is in harness.yaml and package.json; keep both and package-lock.json synchronized. Use three-part SemVer releases and Git tags vX.Y.Z after review.
-0.6.0 is a DevOps/Kubernetes candidate (0.5.0 added the Product documentation capability), not a claim of a registry publication or Git tag. Do not publish from a feature PR.
+0.6.0 was initially published manually to npm. Future versions are prepared by Release Please after human PR review; do not publish directly from a feature PR.
 
 - Patch: compatible corrections to instructions or installer defects.
 - Minor: backward-compatible adapter, skill or CLI additions.
@@ -16,13 +16,28 @@ It does not fetch releases or silently follow main. Pass a reviewed local checko
 See [release policy](release-policy.md) for independently versioned module contracts and single release-PR version ownership.
 
 ## Release procedure
+
+**Current automation (after v0.6.0):** Release Please maintains the root distribution version, changelog and JSON-formatted harness.yaml. The human review/merge of its generated Release PR is the explicit publishing approval. See [npm release](npm-release.md).
 1. Update harness.yaml, CHANGELOG and migration notes. Review policy/behavior changes as code.
 2. Run structural validation and CLI tests on the supported Node.js 22/24 and OS matrix, including actual npm package smoke tests.
 3. Run the behavioral evaluation suite with the intended agent/model if prompts materially changed.
 4. Inspect the install/update diff in a sample consumer; document source commit and limitations.
-5. Merge by human decision. First npm publication is manual. Subsequent releases use an approved GitHub Release triggering npm Trusted Publishing; merge or tag alone never publishes.
+5. Merge feature PR by human decision. Release Please opens a separate version/changelog PR; after human review and merge, the release workflow creates the tag and GitHub Release and publishes npm from the same workflow through OIDC. Merge of feature PR alone does not publish.
+
+## Project setup and readiness additions (unreleased)
+
+The project/lock schema remains 1. Update adds optional project-owned environment.json plus the
+scoped machine.json ignore rule and new managed workflows/templates. Existing local.md, environment,
+machine data and old OpenSpec changes survive. No machine paths are created or committed automatically.
+Doctor only enforces declared required environment entries; empty or absent configuration remains valid.
+Existing changes need decision/evidence sidecars only when using the new ready command.
 
 ## Consumer update
+For global npm installs, first run `npm install -g @manhd_d/ai-harness@latest`.
+For local installs, update the local dependency and use `npx aih`.
+`aih --version` identifies the CLI; `aih check` identifies the installed project snapshot.
+`aih update` applies the installed CLI bundle (or explicit `--source`), without fetching releases.
+
 Create a branch, commit current state, obtain the reviewed source commit/tag and inspect CHANGELOG.
 Run update --dry-run; resolve conflicts by moving custom rules into .harness/local.md and restoring
 managed files from the last installation commit. Apply update and run check plus application tests.
@@ -82,8 +97,8 @@ Do not treat raw Confluence data, drafts or AI review as approved business decis
 
 ## 0.5 → 0.6 migration
 
-No new configuration/lock schema version: 0.5 Product templates, `aih new-doc`, UI/UX and all earlier adapter selections stay compatible. New DevOps and Kubernetes modules are opt-in. On a consumer branch, pin a reviewed 0.6 source/package, add `"devops"` to `.harness/project.json` capabilities and/or `"kubernetes"` to adapters, then run `aih update --dry-run`, `aih update` and `aih check`. Unmodified installed payload updates safely; any drift still blocks update. Application DevOps workflows remain instruction-only and do not deploy production workloads; a separate repository-level npm workflow publishes only after a human-approved GitHub Release.
+No new configuration/lock schema version: 0.5 Product templates, `aih new-doc`, UI/UX and all earlier adapter selections stay compatible. New DevOps and Kubernetes modules are opt-in. On a consumer branch, pin a reviewed 0.6 source/package, add `"devops"` to `.harness/project.json` capabilities and/or `"kubernetes"` to adapters, then run `aih update --dry-run`, `aih update` and `aih check`. Unmodified installed payload updates safely; any drift still blocks update. Application DevOps workflows remain instruction-only and do not deploy production workloads; a separate repository-level npm workflow publishes only after a human-approved Release Please PR creates a tagged GitHub Release.
 
 ## Foundation hardening (unreleased after 0.6)
 
-Module contracts gain optional version and dependency fields without changing config/lock schema 1. Existing consumer snapshots retain default adapter-only verify/eval. After a reviewed update, `--scope all` enables locked Core/capability/composition evaluation, and `--scope core` works in core-only projects. Feature branches retain distribution version 0.6.0; release PR chooses the next number. Use tagged releases for other consumers rather than interpreting an unreleased commit as a published update.
+Module contracts gain optional version and dependency fields without changing config/lock schema 1. Existing consumer snapshots retain default adapter-only verify/eval. After a reviewed update, `--scope all` enables locked Core/capability/composition evaluation, and `--scope core` works in core-only projects. Feature branches keep the latest release version; Release Please's generated PR chooses and synchronizes the next number. Use tagged releases for other consumers rather than interpreting an unreleased commit as a published update.

package/evals/README.md

@@ -1,5 +1,8 @@
 # Behavioral evaluation
 
+For controlled with/without-Harness trials, use [Real-task comparison](real-task-comparison.md).
+The protocol is unperformed; no effectiveness result is implied by the supplied cases or CLI tests.
+
 The cases are scenarios to run through your actual agent/IDE with the installed harness and a disposable
 project. They are not mocked model transcripts and are not automatically run by CI.
 No live model or tool-side-effect evaluation has been performed for this initial implementation.

package/evals/real-task-comparison.md

@@ -0,0 +1,49 @@
+# Real-task comparison protocol (unperformed)
+
+Purpose: measure whether the installed Harness improves actual delivery, not whether its CLI passes.
+No results are supplied here. Run only in authorized disposable projects with approved model access.
+
+Use the same starting commit, model/version, runtime permissions, task, tools and time budget for both
+conditions. Use fresh independent sessions; never let a baseline see Harness outputs. Alternate order.
+Do not relax runtime security for the baseline. Preserve all runs, including failed or interrupted runs.
+
+| Task | Observable acceptance |
+| --- | --- |
+| Spring API from a short BA requirement | Correct contract/auth, duplicate behavior clarified, meaningful tests run |
+| Transaction/notification defect | Reproduce failure, preserve transaction boundaries, regression test passes |
+| Internal Maven onboarding | Ask only missing setup details, use supplied tool path, no invented successful build |
+
+Run each task at least three times per condition. Review blind to condition when feasible.
+Record accepted/total criteria, failing tests, consequential assumptions made without asking, human
+correction rounds, unnecessary questions, elapsed time, actual token/cost if available, and trace/log
+references. Use null for unavailable metrics. Do not convert missing evidence to zero cost or success.
+
+Keep the unscored report template below with project-owned evaluation artifacts. Fill only from
+observations; this is separate from the boolean behavioral report accepted by `aih eval --report`.
+
+```json
+{
+  "status": "unperformed",
+  "model": null,
+  "runtime": null,
+  "harness_commit": null,
+  "starting_commit": null,
+  "task_id": null,
+  "condition": null,
+  "run_id": null,
+  "accepted_criteria": null,
+  "total_criteria": null,
+  "tests": null,
+  "unasked_consequential_assumptions": null,
+  "human_correction_rounds": null,
+  "unnecessary_questions": null,
+  "elapsed_seconds": null,
+  "tokens": null,
+  "cost": null,
+  "evidence": []
+}
+```
+
+Report per-task outcomes and variation across repeats. Distinguish instruction-following gains from
+model capability and runtime differences. Do not claim a general productivity gain from one anecdote.
+Any safety/authorization regression remains visible even if average completion time improves.

package/harness.yaml

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "name": "ai-harness",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "adapters": [
     "java-spring",
     "react-nextjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhd_d/ai-harness",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Reusable AI development rules, skills and workflows with a safe local installer",
   "type": "module",
   "bin": {

package/templates/AGENTS.md

@@ -1,9 +1,14 @@
 <!-- ai-harness:start -->
 ## AI Harness {{version}}
 
-1. Read `.harness/core/rules/foundations.md` and `.harness/core/policies/security.md`.
+1. Read `.harness/core/rules/foundations.md`, `.harness/core/rules/context.md` and `.harness/core/policies/security.md`.
 2. Read `.harness/core/policies/permissions.md` and `.harness/core/workflows/spec-to-code.md`.
-3. Read `.harness/local.md` for project facts and reviewed exceptions.
+3. Read `.harness/local.md` and `.harness/environment.json` (if present) for project facts and commands.
+   For first-run or missing environment facts, use `.harness/core/workflows/project-setup.md`.
+   Machine paths may come from ignored `.harness/machine.json`; do not copy private values into shared files.
+   Before consequential implementation, follow `.harness/core/workflows/clarification.md`:
+   inspect existing answers, ask 1–3 A/B/C questions with grounded recommendations only where needed,
+   record decisions, then continue within existing authorization.
 4. Load only the adapter and skills needed for the current task:
 {{adapters}}
 5. For optional capabilities, read only their selected workflow and relevant skill descriptions:

package/templates/environment.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "tools": {},
+  "files": {},
+  "commands": {}
+}

package/templates/openspec/decisions.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "reviewed": false,
+  "decisions": []
+}