@manhd_d/ai-harness 0.0.0-stage → 0.6.0

package/docs/examples/idea-driven-project.md

@@ -0,0 +1,71 @@
+# Walkthrough A — từ ý tưởng của developer tới tài liệu và code
+
+Đây là **ví dụ thực hành** của chế độ **Idea-driven**, không gắn với một dự án CRM hay công nghệ cụ thể. `aih` chỉ cài hướng dẫn/skills và tạo **template trống**; AI host như Codex, IDE assistant hoặc ChatGPT Work có quyền repo mới có thể phân tích và ghi nội dung. Trong Chat thông thường, bạn vẫn có thể thảo luận ý tưởng, nhưng việc ghi file cần công cụ và quyền truy cập phù hợp.
+
+## 1. Chuẩn bị dự án và cài Harness
+
+Yêu cầu: Node.js 22+, Git, CLI `aih` đã cài từ bản nguồn được review, và một thư mục dự án tồn tại. Xem [Getting started](../getting-started.md) để cài CLI từ source; bản tính năng này nằm trong PR cho tới khi merge.
+
+```bash
+mkdir expense-app
+cd expense-app
+git init
+aih init --capabilities product
+aih new-doc idea
+aih new-doc decision-log
+aih check
+aih skills
+aih skill harness-product-idea-discovery
+aih skill harness-product-product-research
+```
+
+Nếu dự án đã cài Harness, sửa `.harness/project.json` để thêm `product` vào `capabilities`, rồi dùng `aih update --dry-run && aih update && aih check` trên branch riêng; **không** chạy lại init với lựa chọn không tương thích.
+
+## 2. Giao AI thảo luận thay vì bắt đầu code
+
+Dán prompt này vào AI host có quyền đọc repository (hoặc thảo luận trước trong Chat):
+
+> Đọc AGENTS.md và skill harness-product-idea-discovery đã cài. Ý tưởng ban đầu của tôi: “Ứng dụng quản lý chi tiêu cá nhân cho phép nhập giao dịch, AI đề xuất phân loại, có báo cáo theo tháng”. Hãy giữ nguyên ý tưởng gốc, đóng vai BA/PM/PO và thảo luận từng nhóm vấn đề quan trọng với tôi. Đề xuất user personas, MVP, non-goals và trade-off; không tự cho rằng các đề xuất là quyết định của tôi. Phân biệt FACT / INFERENCE / DECISION / UNKNOWN. Chưa code hay tự duyệt scope.
+
+Sau mỗi vòng thảo luận, AI host cập nhật các file đã tạo trước đó: `docs/discovery/idea.md` và `docs/product/decision-log.md` (nếu được cấp quyền). Bạn là người chốt mục tiêu và MVP, không cần có BA/PM/PO riêng cho dự án cá nhân.
+
+## 3. Tạo draft tài liệu có cấu trúc
+
+```bash
+aih new-doc research
+aih new-doc prd-lite
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih check
+```
+
+`idea.md` và `decision-log.md` đã tạo tại bước 1; không chạy lại. Các lệnh chỉ chạy **một lần trên mỗi file** và sẽ từ chối ghi đè. Khi đã có file, AI host điền nội dung vào đúng file dựa trên thảo luận, không chạy lại `new-doc`.
+
+Prompt mẫu:
+
+> Đọc AGENTS.md và skill harness-product-product-research đã cài. Nếu có công cụ web được cấp phép, hãy tìm các sản phẩm tương tự và ghi nguồn, ngày kiểm tra, điểm mạnh/yếu vào docs/discovery/research.md; nếu không có công cụ thì đánh dấu chưa nghiên cứu, không bịa nguồn. Từ các quyết định tôi đã duyệt, hoàn thiện docs/product/prd-lite.md, acceptance-criteria.md và traceability.md. Chỉ ghi draft/pending-review đối với thông tin chưa phê duyệt, rồi gửi diff để tôi review.
+
+Khi cần chi tiết hơn (đa actor, nghiệp vụ phức tạp, nhiều tích hợp), tạo thêm `aih new-doc brd`, `aih new-doc prd`, `aih new-doc srs`, `aih new-doc use-cases` theo **mức độ cần thiết**, không bắt mọi dự án phải có tất cả.
+
+## 4. Human approval và OpenSpec
+
+Sau khi duyệt scope, cập nhật trạng thái/decision record thật của owner. Chỉ khi requirements và AC cho một thay đổi đã được duyệt, mới chuyển sang OpenSpec:
+
+```bash
+aih new-change add-expense-categorization
+# Chỉ là các file proposal/design/tasks/spec dạng TODO, chưa được phê duyệt.
+```
+
+Prompt handoff:
+
+> Đọc approved scope trong docs/product/ và requirement IDs; dùng core harness-spec để hoàn thiện openspec/changes/add-expense-categorization/, bao gồm test scenarios, rủi ro bảo mật dữ liệu, xử lý lỗi và những điểm còn thiếu. Không tự triển khai nếu scope chưa được duyệt. Sau khi tôi review, dùng adapter phù hợp để implement/test và tạo PR, không tự merge.
+
+Nếu dùng OpenSpec upstream, cài/pin CLI riêng và chạy `openspec validate add-expense-categorization --strict` sau khi điền nội dung. Harness không tự cài hay chạy OpenSpec CLI.
+
+## 5. Lưu trữ và thay đổi về sau
+
+- `docs/discovery/` lưu ý tưởng và research đã ghi nguồn; `docs/product/` lưu tài liệu yêu cầu của **project**, không lưu trong source `ai-harness`.
+- `openspec/` lưu technical change và trace ID. Review tài liệu, code và CI trên PR, sau đó con người quyết định merge.
+- Khi ý tưởng thay đổi, dùng `workflows/change-impact-analysis.md` và yêu cầu AI tạo diff; không tự ghi đè tài liệu approved.
+
+**Giới hạn:** `aih verify --scope all` / `aih eval --scope all` chỉ cho checklist/eval advisory; không chứng minh đã thực sự chạy test, nghiên cứu hoặc review.

package/docs/examples/react-native-app.md

@@ -0,0 +1,57 @@
+# Walkthrough 3 — React Native/Expo: permission, offline và release
+
+**Tình huống giả định:** thêm màn hình lưu nháp khi offline và đồng bộ lại khi có mạng trong ứng dụng React Native/Expo đã tồn tại. Đây là hướng dẫn công việc, **không** scaffold app, không dùng Kubernetes cho ứng dụng di động.
+
+## 1. Init
+
+~~~bash
+cd /path/to/existing-react-native-app
+aih resolve --adapters react-native --capabilities product,uiux
+aih init --adapters react-native --capabilities product,uiux --dry-run
+aih init --adapters react-native --capabilities product,uiux
+aih check
+aih skills
+~~~
+
+Nếu chỉ sửa một lỗi offline đã có ticket/AC duyệt, có thể bỏ Product và UI/UX không cần thiết, giữ Core + React Native. `aih detect` có thể nhận React Native/Expo tại thư mục target chứa `package.json`, không tự quét monorepo.
+
+## 2. Requirements & UX
+
+- BA/PO mô tả business rule: trạng thái draft, server authoritative fields, replay/dedupe, login/logout giữa chừng, đa thiết bị, mất mạng và dữ liệu nhạy cảm.
+- Tạo draft Product theo [getting started](../getting-started.md); duyệt story/AC trước khi design.
+- `harness-uiux-user-flow` và `harness-uiux-screen-planning` mô tả offline banner, pending queue, syncing, conflict, retry, auth expired và error accessibility.
+- Figma chỉ ghi khi có MCP quyền hợp lệ và gate. Khi không có Figma, Markdown screen specs vẫn là bàn giao hợp lệ.
+
+## 3. Spec và code
+
+~~~bash
+aih new-change offline-draft-sync
+aih skill harness-spec
+aih skill harness-tdd
+aih skill harness-react-native-offline-sync
+aih skill harness-react-native-device-permissions
+~~~
+
+- `offline-sync`: định nghĩa local persistence encryption/retention, idempotency key, queue/retry backoff, conflict resolution và đồng bộ lại khi token hết hạn.
+- `device-permissions`: chỉ cần nếu feature có camera/location/notification/deep link; kiểm tra iOS và Android riêng, fallback khi từ chối permission.
+- Spec chứa test matrix: airplane mode, offline restart, duplicate request, conflict, revoke session, low storage và app update.
+- Không log token/customer payload, không giả định AsyncStorage/SecureStore đã được chọn; dùng stack đang có.
+
+**Verification** — tùy project scripts/toolchain, không được Harness thực thi:
+
+~~~bash
+# Chỉ chạy sau khi xác nhận có scripts tương ứng trong package.json
+npm test
+# Expo / device build và kiểm thử emulator/thiết bị cần setup riêng
+~~~
+
+Ngoài unit tests, report thiết bị/OS và test thật trên iOS/Android, permissions denied, offline transitions và accessibility evidence.
+
+## 4. PR và phát hành
+
+- `harness-review` và `security-reviewer` kiểm tra mã hóa/scope lưu local, auth và routing.
+- `aih verify --scope all` chỉ tạo checklist; đính kèm kết quả build/device tests thực chạy.
+- Nếu dùng `devops`, đây là **release planning** chung, không phải auto publish App Store/Play Store. Approval theo signing credentials/store policy nằm ngoài `aih`.
+- Nếu app phụ thuộc backend API, xác nhận contract tương thích và liên kết PR khác repo; không stage backend từ repo mobile.
+
+**Handoff:** approved user stories/AC → offline flows → OpenSpec → persistence/sync implementation → device test evidence → reviewed PR → authorized mobile release.

package/docs/examples/spring-boot-api.md

@@ -0,0 +1,100 @@
+# Walkthrough 1 — Spring Boot API từ yêu cầu tới release
+
+**Tình huống giả định:** thêm REST API tra cứu khách hàng theo tenant vào một **repo Spring Boot hiện có**, có PostgreSQL/Oracle tùy dự án, có thể thêm Kafka Outbox và Kubernetes **nếu thật sự có**. Không có source thực tế trong walkthrough này; endpoint, SQL và lệnh test là **đề xuất cần đối chiếu với project**.
+
+**Modules:** Core + `java-spring` + `product`, bổ sung `devops,kubernetes` chỉ khi sở hữu pipeline/manifests. Xem [full SDLC](../end-to-end-workflow.md), [skills](../skill-matrix.md).
+
+## 1. Setup & input
+
+~~~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
+aih check
+aih skills
+~~~
+
+Trong service không triển khai trên Kubernetes thì **bỏ `kubernetes`**; không dùng `aih detect` thay cho việc xác nhận stack. `aih init` chỉ chép Harness, không scaffold Spring Boot.
+
+Input: source revision, business owner, endpoint contract đang có, auth/tenant rules, schema migration policy, test/build tool, environment/approver. Ghi fact và unknown trong `.harness/local.md` hoặc change riêng, không thay Core managed files.
+
+## 2. BA/PO → reviewed requirements
+
+~~~bash
+aih new-doc brd
+aih new-doc prd
+aih new-doc backlog
+aih new-doc acceptance-criteria
+aih new-doc traceability
+aih skill harness-product-business-analysis
+aih skill harness-product-prd-generation
+aih skill harness-product-acceptance-criteria
+~~~
+
+AI IDE đọc nguồn được cấp quyền, đề xuất `FR-001`: tenant chỉ xem dữ liệu của mình; `AC-US-001-01`: tenant khác trả 403/404 tùy contract đã duyệt. **Chưa có xác nhận của PO thì đây vẫn là draft.** Reviewer dùng `harness-product-document-review` để phát hiện lỗ hổng; BA/PO là người xác nhận.
+
+## 3. OpenSpec & technical review
+
+~~~bash
+aih new-change add-customer-lookup
+aih skill harness-spec
+~~~
+
+Từ approved `FR/AC`, hoàn thiện `openspec/changes/add-customer-lookup/{proposal,design,tasks}.md` và delta specs. Nội dung cần có: API status/body, JWT/LDAP principal→tenant, authorization ở service/data access, error mapping, pagination, audit, DB indexes và backward compatibility. Không suy đoán dialect hoặc thông số tải.
+
+Nếu OpenSpec CLI được cài **riêng** và version tương thích với project:
+
+~~~bash
+openspec validate add-customer-lookup --strict
+~~~
+
+Lệnh `new-change` **chỉ tạo draft**, không validate/approve spec. Gate: reviewer duyệt API/security/data boundaries.
+
+## 4. Code theo adapter skills
+
+~~~bash
+aih skill harness-java-spring-spring-api
+aih skill harness-tdd
+aih skill harness-java-spring-database-migration
+aih skill harness-java-spring-kafka-outbox
+~~~
+
+- `spring-api`: controller/service/repository theo pattern hiện có, tenant-scope server-side, DTO và HTTP contract.
+- `database-migration`: chỉ dùng **khi đổi schema**; thiết kế expand → compatible deploy → contract, rollback/data-loss risk.
+- `kafka-outbox`: chỉ dùng **khi có event publication**; transactional write, duplicate consumer delivery, retry/dead-letter.
+- `harness-tdd`: negative auth test, missing resource, validation, successful request, regression. Không tạo implementation Kafka/DB nếu requirement không cần.
+
+Lệnh verify ứng dụng **tùy repo** — dưới đây chỉ là ví dụ nếu có Maven wrapper:
+
+~~~bash
+# Kiểm tra wrapper và profile của repo trước khi chạy
+./mvnw test
+# ./mvnw verify  # nếu project cấu hình integration tests phù hợp
+~~~
+
+`aih verify --scope all` xuất checklist **không chạy Maven**. Nếu không chạy được integration test do thiếu DB, báo blocker; không ghi Pass.
+
+## 5. PR → staging → production
+
+~~~bash
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+Reviewer sử dụng `harness-review` + `security-reviewer`; PR gắn change ID, approved AC, diff, actual test logs, migration sequence, unrun checks, release/rollback plan. Không tự merge.
+
+Nếu có pipeline/manifests: `harness-devops-ci-cd` → `harness-devops-docker` → `harness-kubernetes-workload-review`, `harness-kubernetes-helm-release` (nếu Helm) → `harness-devops-deployment` / `harness-kubernetes-rollout-safety`. Chỉ người/runtime được phép và có approval theo artifact/environment mới deploy; sau rollout kiểm chứng readiness + actual error/latency data.
+
+## Expected handoff (mẫu, không phải kết quả đã chạy)
+
+| Stage | Output cần bàn giao |
+| --- | --- |
+| Product | `docs/product/brd.md`, `prd.md`, `backlog.md`, `acceptance-criteria.md`, `traceability.md` approved |
+| Spec | `openspec/changes/add-customer-lookup/` reviewed |
+| Code | Endpoint + auth/contract tests + migration/event tests nếu có |
+| Review | PR, CI/test evidence, risk list, human decision |
+| Release | Image digest, environment approval, rollback steps, measured health |
+
+**Sau khi PR đã merge:** upstream OpenSpec archive/sync nếu dự án sử dụng OpenSpec; không archive khi change vẫn chưa merge.

package/docs/getting-started.md

@@ -0,0 +1,148 @@
+# Getting started — cài và sử dụng 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 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).
+
+## 1. Chuẩn bị
+
+- 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
+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.
+
+**Các lựa chọn phổ biến:**
+
+| Dự án | Lựa chọn |
+| --- | --- |
+| 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 |
+
+`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.
+
+## Astro cho web tools nhỏ
+
+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.
+
+## Website công cụ miễn phí có quảng cáo
+
+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.
+
+## Hai hướng dẫn theo loại dự án
+
+- [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).
+
+**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.
+
+## 4. Bắt đầu một thay đổi có traceability
+
+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).
+
+
+~~~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/
+
+# Tạo change bản nháp OpenSpec — không cần cài OpenSpec CLI:
+aih new-change add-customer-api
+
+# Đọc từng skill cần thiết:
+aih skill harness-product-prd-generation
+aih skill harness-spec
+aih skill harness-tdd
+~~~
+
+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.
+
+**Prompt mẫu gửi cho assistant:**
+
+> 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.
+
+## 5. Verify / evaluate và release
+
+~~~bash
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+- `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.
+
+Đọc các [approval gates trong Full SDLC](end-to-end-workflow.md) và [DevOps runbook](../capabilities/devops/workflows/pr-to-production.md).
+
+## 6. Update bộ Harness đã cài
+
+~~~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.
+aih update --dry-run
+aih update
+aih check
+~~~
+
+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.
+
+## Ví dụ thực hành
+
+- [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)

package/docs/monetization.md

@@ -0,0 +1,53 @@
+# Website monetization — ads as a business layer, not a framework dependency
+
+The optional `monetization` capability is reusable for Astro, React/Next.js or a static website. It guides research, policy-safe ad UX and unit economics; it does **not** connect to Google accounts, add scripts, fetch ad statistics, generate clicks or promise income. The user needs a legitimate publisher-owned domain and valuable original tools/content.
+
+## Choose modules
+
+```bash
+# Minimal website with advertising business workflow
+aih resolve --adapters astro --capabilities monetization
+aih init --adapters astro --capabilities monetization --dry-run
+aih init --adapters astro --capabilities monetization
+aih check
+aih skills
+aih skill harness-monetization-adsense-integration
+aih skill harness-monetization-ad-placement-ux
+aih verify --scope capabilities  # review checklist only, never a browser/policy scan
+```
+
+For React/Next.js, substitute `--adapters react-nextjs`. Add `product,uiux` only when discovery/design workflow is useful: `aih init --adapters astro --capabilities product,uiux,monetization`. For a project already initialized with Harness, update the `.harness/project.json` capabilities array on a branch and run `aih update --dry-run`, `aih update`, `aih check` (do **not** re-init). No extra runtime dependencies or AdSense credentials are needed to install this instructional module.
+
+## Workflow A — website → AdSense application → approved integration
+
+1. Build a working **useful tool** first: QR, format conversion, image, PDF or other legitimate user need. Avoid scraped, duplicated or thin generated pages. Prefer local browser processing to minimize operating cost and protect user input.
+2. Prepare unique public tool URLs, descriptive content, privacy disclosures, appropriate contact/about/trust information and accessible mobile UX. Review applicable original-content/network rules.
+3. Register/verify publisher-owned site in the actual AdSense account **outside Harness**. Eligibility and approval are Google decisions. If status is unknown, record UNKNOWN, not approved.
+4. Review ad positions: keep actual tool input/output actions easy to find. Ads cannot impersonate navigation or Download/Generate buttons. Reserve stable slot area to reduce unexpected shift.
+5. Determine site audience and legal/privacy/consent needs. For relevant personalized ads to EEA/UK/Swiss traffic Google requires a certified CMP integrated with the IAB TCF; decide approved solution with owner and applicable advisers.
+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.
+
+## Workflow B — traffic → financial learning
+
+Use `harness-monetization-seo-growth` and `harness-monetization-analytics-revenue` to measure legitimate traffic quality, Page RPM, ad earnings and real hosting/API costs.
+
+```text
+Page RPM = (estimated earnings / page views) × 1000
+Modeled earnings = (assumed page views / 1000) × assumed Page RPM
+Modeled contribution = modeled earnings − explicitly scoped costs
+```
+
+Do not confuse Page RPM with ad-impression RPM, or `estimated earnings` with payments received. If no actual AdSense/analytics access exists, pageviews, RPM and income are UNKNOWN; show parameterized scenarios rather than inventing country-specific payouts. Report observed vs forecast numbers in `docs/monetization/analytics-report.md`. Review using owner-approved experiments without traffic manipulation or invalid clicks.
+
+## Policy sources — recheck before every actual release
+
+- [Google AdSense placement policies](https://support.google.com/adsense/answer/1346295?hl=en) — avoid accidental clicks, disguised ads/controls
+- [Avoiding invalid traffic](https://support.google.com/adsense/answer/2660562?hl=en) — no click exchanges, self-clicks, forced/fake activity
+- [Google ads.txt guide](https://support.google.com/adsense/answer/12171612?hl=en) — highly recommended; serve authorized records at root
+- [Google publisher CMP/TCF requirements](https://support.google.com/adsense/answer/13554116?hl=en) — EEA, UK, Switzerland
+- [Google Page RPM definition](https://support.google.com/adsense/answer/190515?hl=en) — metric, not guaranteed yield
+
+Provider policies, privacy laws, pricing and revenue rates change. An AI-generated checklist does not establish legal compliance or Google site approval. Check exact pages, audiences, networks and dates.

package/docs/npm-release.md

@@ -0,0 +1,70 @@
+# npm installation and release
+
+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.
+
+**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.
+
+## First publication: manual, maintainer-controlled
+
+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:
+
+```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
+```
+
+`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.
+
+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**.
+
+## Later releases: npm Trusted Publishing via GitHub Actions
+
+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:
+
+| Field | Value |
+| --- | --- |
+| GitHub user/organization | `manh0303` |
+| Repository | `ai-harness` |
+| Workflow file | `npm-publish.yml` |
+| Environment | Leave empty (workflow does not use an environment) |
+
+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.
+
+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.
+
+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/).
+
+## Local installation before npm publication
+
+```bash
+npm pack
+npm install -g ./manhd_d-ai-harness-0.6.0.tgz
+aih --version
+```
+
+## Installation after verified npm publication
+
+```bash
+npm install -g @manhd_d/ai-harness
+aih --version
+cd /path/to/existing-project
+aih init --adapters java-spring
+aih check
+```
+
+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.
+
+Read [Getting started](getting-started.md) and [Release policy](release-policy.md).

package/docs/openspec.md

@@ -0,0 +1,23 @@
+# OpenSpec integration
+
+The initial integration uses the upstream `spec-driven` schema, project context and artifact rules.
+It does not fork OpenSpec, bundle its CLI or implement its archive/sync engine.
+Install and pin OpenSpec with the package manager and runtime requirements appropriate to your project.
+Consult upstream installation instructions; no floating `latest` dependency is injected into consumers.
+
+The harness new-change command creates `.openspec.yaml`, proposal.md, design.md, tasks.md and
+specs/<change-id>/spec.md. Replace draft TODOs and use capability names that match your actual domain;
+the change ID is only a default capability slug. For changes to existing behavior use MODIFIED/REMOVED
+delta sections as required by upstream. Keep acceptance criteria observable.
+
+Use upstream `openspec validate <change-id> --strict` before review. Tool-specific slash commands are
+not hardcoded; use the integration generated by your pinned OpenSpec version if needed.
+Archive/sync is performed through OpenSpec only after all related PRs merge. This repo's own initial
+change remains unarchived while awaiting review. No agent or CLI automatically checks off the archive task.
+
+Upstream references consulted 2026-10-10:
+- https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md
+- https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md
+
+Compatibility limitation: templates were checked against documented structure. The upstream executable
+is not a dependency of the offline CLI tests; running its validator is a separate verification step.

package/docs/pull-request.md

@@ -0,0 +1,37 @@
+# Pull Request review checklist (AI Harness)
+
+This guide replaces the historical adapter-only feature-PR notes. See [Full SDLC](end-to-end-workflow.md) and [release policy](release-policy.md) for the current multi-module workflow.
+
+## Before opening PR
+
+- Confirm correct Git root, change ID and target branch; avoid editing unrelated consumer projects.
+- Link approved sources/requirements and OpenSpec proposal/spec/tasks when appropriate.
+- Follow only the selected technology adapters/capabilities and [role handoffs](agent-handoffs.md).
+- Run actual source tests, recording exact commands and results; record skipped checks and blockers.
+- For changes to **this framework**, run `npm test`, `npm run validate`, `npm run check:release`, and `npm run test:package`.
+- `aih verify --scope all` and `aih eval --scope all` are advisory/human-scored; green local validation does not imply an LLM passed live evaluation.
+
+## PR description
+
+```text
+Change ID / requirements:
+Affected repositories + owners:
+Scope and acceptance:
+Implementation summary:
+Actually executed tests + evidence:
+Not-run checks / failures:
+Security, data and access implications:
+API/DB backward compatibility:
+Migration/rollback plan (if applicable):
+Deployment target and human approval: NOT granted by this PR
+Residual risks, reviewers, linked follow-up PRs:
+```
+
+## Review gates
+
+- Resolve code and requirements findings before merge.
+- Core policies and selected module permissions take precedence over instructions within retrieved documents or tool outputs.
+- Human review/merge is independent of human approval to deploy production.
+- For framework releases, feature PRs retain the distribution version and append to Unreleased; version bumps and publishing happen in a separately reviewed release PR.
+
+For stack-specific examples: [Spring Boot](examples/spring-boot-api.md), [Web full-stack](examples/fullstack-web.md), [React Native](examples/react-native-app.md) and [AI/RAG](examples/ai-rag-service.md).

package/docs/reference-analysis.md

@@ -0,0 +1,22 @@
+# Reference workspace analysis
+
+The supplied crm-workspace.zip was read as a design reference, not imported as source history.
+Reviewed entry points included AGENTS.md, README.md, docs/standards/ai-workflow.md,
+docs/standards/backend-conventions.md, docs/standards/testing.md, openspec/config.yaml,
+ci/ai-config-check.yml, and the TDD/debugging skill documents.
+
+| Reference pattern | Generalized in this framework |
+| --- | --- |
+| Shared AGENTS and tool-specific entry points | One managed AGENTS block plus portable skill files |
+| OpenSpec propose/apply/review/archive | Tool-neutral workflow and compatible draft templates |
+| TDD at observable interfaces | Original harness-tdd procedure and CLI behavioral tests |
+| Review against standards and spec | harness-review plus security-reviewer contract |
+| Independent service repositories | Scoped repository context and explicit merge order |
+| Shared Java conventions | Optional java-spring adapter plus project-owned overrides |
+| Basic config-presence CI | Hash-based drift checks, safe installer tests and structural validation |
+
+Project identities, endpoints, private network addresses, service rosters, database schemas, credentials,
+repository history and client-specific business rules are intentionally not distributed.
+Legacy conventions remain the responsibility of the consumer project; they are not universal defaults.
+The framework's skills are newly written concise procedures; third-party skill source from the ZIP is
+not vendored. This repository does not claim ownership of upstream tools or redistribute their packages.

package/docs/release-policy.md

@@ -0,0 +1,17 @@
+# Release discipline and module versioning
+
+Distribution version is `harness.yaml` + `package.json` + `package-lock.json`. Optional `module_version` belongs to each adapter/capability, allowing independent contracts inside a single npm package.
+
+## Prevent concurrent version conflicts
+1. Feature PRs **do not bump** distribution version, tag or publish. Describe changes in the Unreleased changelog.
+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.
+
+## Compatibility
+- Existing schema-1 config and locks remain valid. Optional module contract fields are additive.
+- `aih verify` / `aih eval` default to adapter-only. `--scope all` includes Core, capabilities and matching cross-module cases.
+- New installs and reviewed updates validate required module dependencies. `aih resolve` never silently installs recommendations.
+- Reports are bundle/dataset bound; human-scored reports do not prove AI behavior or tool execution.
+- No module may bypass Core permission rules, and the CLI grants no runtime privilege.