@manhd_d/ai-harness 0.0.0-stage → 0.6.2

package/docs/architecture.md

@@ -0,0 +1,107 @@
+# Architecture and scope
+
+AI Harness is a versioned instruction and workflow distribution framework. Its executable part is a
+local installer and integrity checker. It is not an LLM gateway, an orchestration server or a sandbox.
+
+| Layer | Responsibility | Owner |
+| --- | --- | --- |
+| core/rules | Evidence, context loading, code/change discipline | Harness maintainers |
+| core/policies | Permission and security contracts | Maintainers plus runtime admins |
+| core/skills | Repeatable task procedures | Harness maintainers |
+| core/agents | Role inputs, outputs and authority limits | Harness maintainers |
+| core/workflows | Stage order and review evidence | Harness maintainers |
+| adapters | Technology-specific defaults and suggested checks | Adapter maintainers |
+| capabilities | Optional cross-stack product, UI/UX, DevOps and ad monetization workflows | Capability maintainers |
+| integrations | GitHub, GitLab and MCP setup contracts/templates | Project/runtime owners |
+| templates | AGENTS entry point and OpenSpec draft structure | Harness maintainers |
+| CLI + lock | Deterministic installation and update conflicts | Executable framework |
+| project overrides | Domain facts, actual versions, approved exceptions | Consumer project |
+
+## Installation design
+The consumer receives a vendored .harness snapshot and .agents/skills/harness-* files. AGENTS.md gets
+one marked block. The CLI leaves text outside that block intact. The generated .harness/lock.json records
+schema version, release version, selected adapters, each owned content hash and an aggregate hash.
+The hashes detect accidental drift; they are not signatures and cannot detect a coordinated malicious
+edit to both payload and lock. Review source commit provenance and consumer lock diffs in Git.
+
+Project-owned seeds: .harness/project.json, .harness/local.md and openspec/config.yaml. Updates preserve
+their contents. Existing openspec specs/changes are never rewritten. Only previously owned, unchanged
+files can be deleted when a new bundle removes them. Unknown user files are never swept away.
+Identical pre-existing payload may be adopted; conflicting payload aborts the entire preflight.
+
+init/update take an exclusive installation marker, preflight changes, and write files atomically one at
+a time. Ordinary write failures roll back bytes already changed. This is not a crash-safe multi-file
+filesystem transaction: a power loss, process kill or rollback I/O failure can leave partial state.
+Commit consumer state before updates; after interruption inspect the marker, run check and restore from Git.
+Empty directories may remain after rollback/removal. Symlinked roots/paths are intentionally unsupported.
+Concurrent hostile filesystem mutation is outside the threat model; run in a trusted local workspace.
+
+## Agent/runtime boundary
+Roles are Markdown handoff contracts. The host decides tool execution and delegation. A role document
+does not create another agent or supply an API key. Use the same framework in an IDE assistant or your
+own model-backed runtime; actual permissions, cost limits and network allowlists live in that runtime.
+
+## Advertising monetization capability
+
+`capabilities/monetization/` is an optional, stack-neutral guide for legitimate publisher readiness, safe ad UX, SEO and revenue analysis. It does not install provider SDKs, access Google accounts, claim consent compliance or guarantee approval/revenue. Templates are vendored into the selected consumer under `.harness/capabilities/monetization/templates/`; `aih new-doc` still only scaffolds Product documents. Owners copy monetization templates to project-owned `docs/monetization/` using authorized filesystem tools. Review [Monetization guide](monetization.md).
+
+## Astro static-first adapter
+
+Astro là technology adapter độc lập (`adapters/astro/`), không phải capability chung, dùng chung Core/Product/UIUX/DevOps khi được chọn. Sáu skills tập trung website tool tĩnh, islands, SEO, performance, Cloudflare và đường nâng cấp Micro Frontend. `aih detect` nhận diện `astro` trong root `package.json` và bỏ nhận diện React/Next chỉ đến từ `react-dom` khi dùng Astro Islands (trừ khi có `next`). Không thêm Astro runtime vào Harness và không tự chạy build/deployment. Xem [Astro walkthrough](examples/astro-micro-tools.md).
+
+## Extending adapters
+Add adapters/<id>/adapter.yaml (schema 2), rules.md, rules/, namespaced skills/, checks/verification.yaml
+and evals/cases.json. Register the id in harness.yaml; add detection, installation and evaluation cases.
+See docs/adapters.md for the strict JSON-compatible YAML contract. Detection is opt-in and read-only;
+checks are advisory and never executed. Installed capabilities are read from the locked snapshot, not
+from the latest global CLI source. Core TDD/debug/review are not duplicated in adapters.
+
+## npm distribution
+The package exposes bin/aih.js as `aih`. It uses native JavaScript ES modules and Node.js built-ins:
+there is no Python bridge, transpilation step, runtime dependency, network client or install hook.
+Source paths resolve relative to the package, not cwd. The target defaults to cwd. Local node_modules
+installation is an explicit exception to overlap rejection; payload destinations never include node_modules.
+The npm files allowlist ships runtime assets including the hidden OpenSpec template. A smoke test packs
+and installs a real tarball globally and locally without registry access. Development tests and fixtures
+are excluded from distribution. Only the development smoke script launches npm subprocesses.
+
+## Optional capabilities (0.4.0)
+
+Capabilities differ from technology adapters: they represent reusable workflows such as UI/UX,
+not runtime stack defaults. A registered capability contains `capability.json` schema 1,
+namespaced `SKILL.md` files and workflow contracts, installed only when selected. CLI copies
+the selected capability under `.harness/capabilities/<id>/` and exposes its skills to
+`.agents/skills/`. The existing Core and technology adapter contracts remain unchanged.
+
+`aih skills` exposes metadata-only catalog and `aih skill <name>` retrieves a single locked
+skill after drift validation. The agent host controls actual skill activation and remote MCP.
+For package size, source npm distribution currently bundles all capabilities, but consumer
+snapshot and AI context are selective; split distributable packages only when size warrants it.
+
+## Product documentation capability (0.5.0)
+
+An optional `product` capability owns business-analysis and product-documentation
+role contracts and templates. Capability schema-1 now supports optional unique safe
+`agents` and `templates` Markdown path lists (required fields remain unchanged).
+Role files must include Inputs, Outputs, Permissions and limits, Handoff sections.
+The existing `uiux` manifest without these optional fields remains valid.
+Selected capability artifacts are hashed and installed with the existing lock safety.
+
+`aih new-doc <type>` reads a locked, drift-free Product template, creates
+`docs/product/<type>.md` as project-owned data, and refuses overwrite/symlinked
+destinations. It never fills confidential content, fetches Confluence or auto-approves.
+The approved PRD/BRD/stories/AC serve as source of truth for UI/UX and OpenSpec.
+
+## DevOps and Kubernetes composition (0.6.0)
+
+DevOps is an optional stack-neutral capability for release procedures and SRE; the Kubernetes adapter owns workload/Helm details. Product role/template support from 0.5 remains unchanged. Both are installed only when selected, vendored and hash-locked alongside existing modules. Integrations/runtime permissions are independently administered; no instructions can grant cloud access, override Core approval gates or trigger production changes. `aih verify`/`aih eval` use adapter-only defaults; opt in to Core and capability scenarios with `--scope all`, without executing runtime checks.
+
+## Foundation hardening (in source; candidate not published)
+
+`cli/composition.js` validates a selected module graph before copying managed content. Optional `module_version`, hard `requires`, soft `recommends`, `conflicts` and `compatible_adapters` use namespaced refs like `adapter:kubernetes`. Cycles, unknown refs, missing required or explicitly incompatible modules fail before writes; recommendations only warn. Config and lock schemas remain 1, and module metadata is pinned inside installed snapshots.
+
+`aih verify/eval --scope all` reads Core, selected adapters/capabilities and matching cross-module scenarios from locked files. Default without scope is still adapter-only for compatibility. Checklists are advisory, evaluations human-scored, and no local/remote commands or models run. See [release policy](release-policy.md).
+
+## Documented end-to-end usage
+
+The cross-module route is described in [Getting started](getting-started.md), [Full SDLC](end-to-end-workflow.md), [Skill matrix](skill-matrix.md) and [Agent handoffs](agent-handoffs.md). All roles/skills remain instruction contracts. The four [stack walkthroughs](examples/spring-boot-api.md) illustrate permitted integrations, not a runnable scaffold or orchestration engine.

package/docs/cli.md

@@ -0,0 +1,109 @@
+# CLI contract
+
+Invocation: `aih COMMAND [--target /existing/project]`.
+Node.js 22+; built-in modules only; no network, subprocesses, remote provider calls or dependency installs.
+Output is JSON on stdout on success; errors use stderr. Drift reports from check and failed evaluation reports use stdout with exit 1.
+Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift failure; 2 is a CLI usage error. Help and version are plain text; no arguments displays help.
+
+| Command | Options | Effect |
+| --- | --- | --- |
+| list | --source | List validated adapters and namespaced skills |
+| detect | --source | Read target build files and return heuristic matches with evidence |
+| resolve | --source; --adapters a,b; --capabilities a,b | Validate module selection and compatibility; read-only |
+| verify | --scope adapters/core/capabilities/all | Read installed advisory checks; executed false, no subprocesses |
+| eval | --scope adapters/core/capabilities/all; --report FILE | Emit unscored template or aggregate reviewed report; no model calls |
+| init | --detect OR --adapters a,b; --capabilities a,b; --source; --dry-run; --allow-major | Install a snapshot; exact rerun is idempotent |
+| update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
+| check | none | Compare installed files/block with lock and selection; no writes |
+| doctor | none | check plus executable presence on PATH; no execution |
+| new-change ID | none | Create an unapproved OpenSpec draft using installed templates |
+| new-doc TYPE | none | Copy a selected locked Product template to `docs/discovery/` (idea, research) or `docs/product/` (other types) without overwriting |
+| skills | none | List installed skill metadata only |
+| skill NAME | none | Read one installed, locked skill |
+
+All commands default --target to the current directory. --source defaults to the installed package.
+For a global install, upgrade the CLI with `npm install -g @manhd_d/ai-harness@latest` before
+`aih update --dry-run` and `aih update`. Update never fetches npm. `aih --version` reports the CLI
+version; `aih check` reports the project snapshot version. For a local install, update the local
+dependency and use `npx aih`. Application tests must be executed separately.
+--help/-h and --version/-v are available. Unknown, duplicate and inapplicable flags fail.
+Source and target cannot contain one another, except source inside target/node_modules for local npm installs. Symlinks in roots, source
+payload or destination paths are rejected. IDs are lowercase hyphenated slugs; archive is reserved.
+Astro projects are detected from `astro` in package.json dependencies; `react-dom` used only for Astro islands is not a standalone React/Next.js detection when `next` is absent. Explicit `--adapters astro,react-nextjs` remains valid. `aih init --adapters astro` installs static-first rules/skills but no Astro packages or Cloudflare deployment.
+Selection changes belong in .harness/project.json; unknown or duplicate adapters fail validation.
+
+## Optional monetization capability
+
+`aih init --capabilities monetization` installs five stack-independent advertising/revenue skills and 2 Markdown workflows with 4 templates. Combine with `--adapters astro` or `react-nextjs`; `product` and `uiux` are optional. `aih verify --scope capabilities` gives an unexecuted manual publisher policy/consent checklist. `aih new-doc` is **Product-only**; the editor may copy installed monetization Markdown templates to user-owned `docs/monetization/` with explicit no-overwrite review. No Google account access, ads publishing or metrics APIs are provided. See [Monetization guide](monetization.md).
+
+## Ownership and conflict behavior
+AGENTS.md ownership covers only text between the unique start/end markers, inclusive. Any modification
+inside the block is drift; text before/after is user-owned. A malformed marker pair fails safely.
+The snapshot and exposed harness skills are fully owned files. init refuses different unmanaged content;
+identical content can be adopted. Existing OpenSpec config is project-owned and preserved, not validated
+by this CLI. Run the upstream OpenSpec validator for spec/config correctness.
+check detects changed/missing locked files and mismatched adapter selection. It does not verify all
+application code, external tools, remote origin or model behavior. The lock is not a cryptographic signature.
+
+## Recovering failures
+For conflicts, preserve custom work in Git, move project-specific rules to local.md and restore managed
+files from the last install commit. Re-run dry-run. Do not manually regenerate hashes to suppress drift.
+For an interrupted install inspect .harness-install.lock, confirm no installer is running, remove the
+stale marker and restore a known-good installation from Git. Then check and retry on a branch.
+There is no uninstall command; revert the installation commit. No command merges or publishes changes.
+
+## Capability commands
+list/detect read the CLI package or explicit --source. verify/eval require a valid installed snapshot and
+read its pinned metadata, rules and cases. Every referenced capability file must be covered by the lock.
+Detection reads only declared paths directly in --target, capped at 1 MiB per file; malformed package JSON
+and symlink probes fail. It does not infer framework versions or recurse into workspaces/node_modules.
+init --detect refuses empty detection; it cannot be combined with --adapters or used on update.
+verify labels file presence as candidate/not-detected, and manual checks as review-required. This is not
+proof that a script exists, a command is safe, or a native toolchain is available. Commands are never run.
+eval without --report emits {dataset, report}; save/edit only the report object as the submission.
+Missing metadata, null/nonboolean scores, missing/duplicate/unknown cases or stale hashes fail validation.
+Any false criterion returns status fail and exit 1, including a list of critical failures where relevant.
+
+## Selective capabilities and progressive skill loading (0.4.0)
+
+- `aih init --capabilities uiux` is optional and independent of `--adapters`.
+- `aih list` returns a `capabilities` array alongside adapter metadata.
+- `aih skills` lists **installed** names/descriptions and paths only (no full skill bodies).
+- `aih skill harness-uiux-figma-design` returns only that single installed, locked skill text.
+- Invalid, duplicate and unknown capability IDs fail before installing. Custom capabilities must have a registered and valid source manifest.
+- For existing installs, edit the `capabilities` array in `.harness/project.json`, then use `aih update --dry-run` followed by `aih update`. Init refuses an already installed conflicting selection.
+- Selecting a capability copies only its managed snapshot and exposed skills into the consumer. npm package transport itself still contains all bundled capabilities.
+- Neither `skills` nor `skill` contacts the network or runs model/tool integrations. Both require a drift-free installed snapshot.
+
+## Product docs and safe template scaffolding (0.5.0)
+
+- `aih init --capabilities product` or `aih init --capabilities product,uiux` installs
+  Product workflows, role contracts, document templates and skill pointers.
+- `aih list` returns capability agents/templates metadata alongside skills/workflows.
+- `aih new-doc brd`, `aih new-doc prd`, `aih new-doc backlog`, etc. safely
+  copy **one** locked template from `.harness/capabilities/product/templates/` to
+  the project-owned `docs/product/<type>.md`. An existing file is never overwritten.
+- `aih skills` lists descriptions only; `aih skill harness-product-brd-generation`
+  loads specific task guidance when needed.
+- For installed projects, change `.harness/project.json` selection and run update/check.
+- Documents must be populated by an authorized AI host using source references;
+  no command retrieves Confluence, calls an LLM or claims stakeholder approval.
+
+## Module composition (foundation hardening)
+
+`aih resolve --adapters java-spring,kubernetes --capabilities product,uiux,devops` is read-only and validates dependencies, conflicts, version metadata, and declared compatibility before install. Optional recommendations only warn. Init/update use the same resolver.
+
+## Unified eval scopes
+
+`aih verify --scope all` and `aih eval --scope all` include the Core and installed capability/adapter contracts plus matching cross-module scenarios. `adapters` is the unchanged default for backward compatibility. `capabilities` and `core` isolate those cases. Older installed snapshots without Core evaluation assets must be upgraded first. The CLI emits advisory checks and a human-scored report; it never executes provider commands or AI evaluations.
+
+## Human workflows and examples
+
+See [Getting started](getting-started.md) for CLI boundaries, [Full SDLC](end-to-end-workflow.md) for review gates, [Skill matrix](skill-matrix.md) for valid skill IDs and [Agent handoffs](agent-handoffs.md) for role responsibilities. The four [examples](examples/fullstack-web.md) distinguish advisory `aih` commands from external build, AI and deployment tools.
+
+
+## Product document templates — discovery and specifications
+
+With the optional `product` capability selected, `aih new-doc idea` and `aih new-doc research` safely create `docs/discovery/<type>.md` in the consumer repository. Other names including `prd-lite`, `srs` and `use-cases` create `docs/product/<type>.md`.
+
+All types must be declared templates in the installed, hash-locked Product manifest. Commands refuse unknown names, traversal, overwrite, collisions and installation drift. These are **blank templates only**, not AI-generated content. Read [Documentation workflows](documentation-workflows.md) for the two intake paths and approvals.

package/docs/documentation-workflows.md

@@ -0,0 +1,71 @@
+# Documentation workflows — developer idea or existing BA documentation
+
+AI Harness intentionally supports **two entry points feeding one engineering pipeline**. The Product capability supplies role contracts, skills and drafts to an authorized AI host; the `aih` CLI never performs conversations, web research, ingestion, writes to Confluence or automatic approval.
+
+## Bắt đầu nhanh — ví dụ đầy đủ
+
+- [Walkthrough A: Từ ý tưởng developer đến spec và PR](examples/idea-driven-project.md): lệnh CLI, prompt thảo luận/research, cách review và chuyển sang OpenSpec.
+- [Walkthrough B: Dự án có BRD/PRD/SRS của BA](examples/document-driven-project.md): đọc đúng nguồn, kiểm tra gap, tránh viết lại tài liệu chính thức và tạo OpenSpec theo approved AC.
+
+Để thử tài liệu chưa merge, cài CLI từ **branch PR #10 đã review** thay vì mặc định `main` (xem [Getting started](getting-started.md)).
+
+## Mode A — Idea-driven (developer → BA/PM/PO)
+
+1. Install with `aih init --capabilities product` (add optional UI/UX/adapters only if needed).
+2. Use `aih skill harness-product-idea-discovery` to instruct the AI host to preserve the original idea, clarify user problem and discuss MVP options iteratively.
+3. Use `aih skill harness-product-product-research` and permitted search tools to support market/competitive/feasibility decisions. Record citations and dates; mark unavailable research as pending.
+4. Draft the **minimum necessary** documentation:
+   - Solo developer/small scope: `aih new-doc idea`, `aih new-doc research` (optional), `aih new-doc prd-lite`.
+   - Larger/product or enterprise scope: `aih new-doc brd`, `aih new-doc prd`, `aih new-doc srs`, `aih new-doc use-cases`, backlog, AC and traceability as needed.
+5. AI proposes and reviews; **developer or explicitly authorized owner** records accepted decisions and approval. Continue discussion when important UNKNOWNs affect scope.
+6. Feed approved requirement IDs and acceptance criteria into `aih new-change <id>` plus the appropriate adapter; a human reviews specs and PRs.
+
+This is not an automatic document-writing command: each `new-doc` simply copies a pinned template into the **consumer** repository. An AI assistant with filesystem permissions must populate the draft; the human reviews.
+
+## Mode B — Document-driven (existing BA sources → engineering)
+
+1. Register official BRD, PRD, SRS, Confluence page URLs/revisions, owners and permission scopes in `docs/product/source-register.md`.
+2. Use the `document-driven` workflow in the installed Product capability to inspect authorized input and build requirements / AC traceability. If an official SRS already exists, do **not** generate a competing one by default.
+3. Create only missing artifacts or project-specific derived docs; identify contradictions/staleness and obtain explicit owner decisions.
+4. Approved source-linked requirements → UI/UX if applicable → OpenSpec change → implementation/testing/PR review. Carry source/version and FR/US/AC IDs through each handoff.
+5. When upstream BA documents change, run change-impact analysis and propose diffs; do not rewrite approved BA sources or code without review.
+
+## Storage and ownership
+
+| Artifact | Canonical location | Notes |
+| --- | --- | --- |
+| Harness roles, skills, workflows, templates | `ai-harness/capabilities/product/` | Versioned framework source; not real customer requirements |
+| Original developer idea and evidence summary | Consumer `docs/discovery/` | Project-owned, Git versioned; `idea.md`, `research.md` |
+| Project product artifacts | Consumer `docs/product/` | BRD/PRD/PRD-lite/SRS/UC/backlog/AC/traceability |
+| Source enterprise Confluence/BA documents | Existing authorized external system | Canonical source; keep URLs/revisions and permission scope, avoid copying confidential content |
+| Technical change specifications | Consumer `openspec/` | OpenSpec design/tasks/delta specs linked to approved requirement IDs |
+| UI designs | Figma or approved system of record | Store screen-to-URL/node ID mapping, not copies of entire design |
+| Large binary documentation | Authorized object storage | Store references rather than large sensitive binaries in Git |
+
+A product spanning many services should ideally have a single product-owned documentation home, with service-local OpenSpec/architecture and links back to approved requirements. If multiple repositories are used, explicitly designate the system of record and prevent parallel editing of copies.
+
+## Metadata and quality
+
+Every derived artifact should identify owner, status (`draft`, `pending-review`, `approved`), version/source revision, review history and stable IDs. Facts from external sources require anchors; AI inferences, proposals and unverified assumptions are labeled separately. Unavailable evidence or approvals remain UNKNOWN/pending; do not invent them.
+
+Review checks: source freshness and access authorization; conflicting statements; missing FR/NFR to story/AC mapping; unsupported quantitative NFR; duplicate IDs; orphaned stories/screens/OpenSpec; missing review decisions; no claims of unexecuted validation. The current `aih verify` emits advisory checks, not executed document verification.
+
+## Confluence export/publishing contract (future host integration)
+
+Confluence is a **publication platform**, not a file type interchangeable with SRS/PRD. For Confluence imports, record space/page ID, URL, version, access class and section links, and reconcile against local derived docs. For exports, prepare Markdown/Confluence-friendly pages and a mapping from stable document ID → Confluence page ID/version. Require explicit target-page selection, write permission, diff preview and human approval before creating/updating pages. Use version checks and refuse unknown concurrent changes; avoid duplicate pages and unapproved overwrites. The CLI does not integrate with Atlassian APIs.
+
+Future permission-scoped indexing/RAG may improve retrieval for very large corpora, but Git/Confluence remains canonical. Do not require an embeddings database to use either mode.
+
+## Example handoff
+
+```text
+Mode: idea-driven (or document-driven)
+Source: IDEA-001 (or SRC-001 revision 5)
+Status: pending-review (until human approval)
+Requirements: FR-001, NFR-001, US-001, AC-US-001-01
+Artifacts: docs/product/prd.md; docs/product/srs.md (if applicable)
+Proposed OpenSpec change: add-expense-categorization
+Risks/unknowns: threshold and privacy requirements pending decision
+Permissions: read/write authorized project branch only; no external publish or merge
+Human reviewer: developer or named BA/PO
+```

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

@@ -0,0 +1,116 @@
+# Full SDLC — Idea → Product → UI/UX → Spec → Code → Test → PR → Release → Operate
+
+Tài liệu này là **bản đồ điều phối** toàn bộ Core + Product + UI/UX + technology adapters + DevOps. Mỗi module vẫn có workflow riêng; chỉ **kích hoạt module đã cài và thật sự liên quan**, không bắt buộc dùng đủ tất cả cho một change. Bắt đầu với [Getting started](getting-started.md); xem [ma trận 53 skills](skill-matrix.md) và [role handoffs](agent-handoffs.md).
+
+> **Ranh giới thực thi:** `aih` cài/gợi ý rules, templates, skills và check/eval **advisory**. AI host/IDE và các công cụ bên ngoài thực hiện phân tích, code, test và tương tác hệ thống trong phạm vi được cấp quyền. Không có `aih run` hay `aih deploy`; các hành động ghi Figma, production hoặc merge phải có phê duyệt.
+
+## Monetization: tùy chọn business/marketing
+
+Website miễn phí kiếm tiền quảng cáo có thể cài `--capabilities monetization` cùng Astro/React/Next.js. Sau khi xây các tool hữu ích và được phê duyệt về product, workflow của `monetization` xử lý SEO, publisher policy, consent, ad placement, hiệu quả quảng cáo và Page RPM; qua human approval trước mọi thay đổi ad/deploy. Đọc [Monetization](monetization.md) và [Astro + AdSense walkthrough](examples/astro-adsense-microtools.md). Không được giả định AdSense đã duyệt hoặc tự phát sinh traffic/clicks.
+
+## Astro micro-tools: một stack tùy chọn
+
+Website tiện ích nhỏ có thể chọn riêng adapter `astro` để theo hướng static-first và chỉ thêm React Islands, API/Cloudflare Workers hoặc tách Micro Frontend khi có nhu cầu thật. Product/UX vẫn là optional capabilities như các stack khác. Đọc [Astro walkthrough](examples/astro-micro-tools.md). Không cần backend hay Kubernetes cho tool xử lý hoàn toàn trong trình duyệt.
+
+## Hai chế độ bắt đầu
+
+- **Idea-driven:** developer trình bày ý tưởng → thảo luận và nghiên cứu có nguồn → PRD-lite hoặc BRD/PRD/SRS/use cases tùy độ phức tạp → human approval → OpenSpec.
+- **Document-driven:** BA/PO đã có BRD/PRD/SRS/Confluence → lập source register với URL/revision/quyền, gap/traceability → chỉ tạo artifact còn thiếu → human approval → OpenSpec.
+
+Cả hai chế độ đều dùng chung các stage phía dưới và không bắt buộc cài mọi capability. Xem [Documentation workflows](documentation-workflows.md).
+
+## 0. Chọn module và xác định ownership
+
+~~~bash
+cd /path/to/existing-repository
+aih resolve --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops
+aih init --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops --dry-run
+aih init --adapters java-spring,react-nextjs,kubernetes --capabilities product,uiux,devops
+aih check
+aih skills
+~~~
+
+Lệnh trên là **ví dụ một repo chứa BE/FE/manifests**; nếu frontend/backend thuộc nhiều repo, `aih init` được chạy tại từng repo và chỉ chọn module phù hợp. `aih resolve` không tự bổ sung module được recommend. Không dùng `--detect` như công cụ quét toàn monorepo.
+
+**Project input:** `AGENTS.md`, `.harness/local.md`, source repo, scope và branch, quyền truy cập nguồn; tạo `change-id` và xác định nguồn của từng artifact.
+
+## 1. Các stage, outputs và human gates
+
+| Stage | Input và việc phải làm | Module / skills & roles | Output / điều kiện bàn giao |
+| --- | --- | --- | --- |
+| **1. Intake** | Ý tưởng, ticket, Confluence/PDF được phép đọc, version/source, scope | Product: `knowledge-analysis`, `business-analysis`; BA | Source register, FACT/INFERENCE/UNKNOWN, AS-IS/TO-BE, quyết định còn thiếu |
+| **2. Business & Product** | Nguồn có traceability, mục tiêu, rules, NFR | Product: `brd-generation`, `prd-generation`, `user-stories`, `acceptance-criteria`, `backlog-prioritization`, `document-review`, `traceability`; PM/PO/requirements reviewer | PRD-lite hoặc BRD/PRD/SRS/UC khi cần, story IDs, AC, backlog; **Gate A: stakeholder duyệt**, không gắn nhãn Approved bởi AI |
+| **3. UX/UI (nếu cần)** | Approved PRD/stories/AC; Figma file và quyền (nếu dùng) | UI/UX: `requirements-analysis` (chỉ khi cần), `user-flow`, `screen-planning`, `design-system`, `figma-design`, `design-review` | User flows, screen specs, component/tokens, Figma node IDs; **Gate B trước ghi Figma**, gate sau design review |
+| **4. Technical spec** | Approved requirements, API constraints, architecture, DB/event contracts | Core: `harness-spec`, planner; tech adapter phù hợp; OpenSpec | `openspec/changes/<change-id>/` (proposal, design, tasks, delta specs), measurable AC; **Gate C: duyệt thay đổi có ảnh hưởng** |
+| **5. Implementation** | Change được duyệt, kiến trúc, repo, tests | Core: `harness-tdd`, `harness-debugging` khi sửa lỗi; Spring/React/Native/AI adapter theo stack; implementer | Minimal code diff, unit/integration/contract tests, migration plans, không thay đổi unrelated files |
+| **6. Verify & code review** | Diff, specs, test logs thực chạy | Core: `harness-review`, `harness-ai-evaluation` nếu AI; test-engineer/security-reviewer; `aih verify/eval --scope all` (chỉ plan) | Evidence của test chạy thực tế, scope chưa test, security findings, trace requirement → test; **Gate D: human PR review** |
+| **7. Delivery** | PR đã review/CI và artifact định danh | DevOps: `ci-cd`, `docker`, `deployment`, `infrastructure`; Kubernetes: workload/Helm/rollout skills | Build provenance, deploy/rollback runbook, staging evidence; **Gate E: approve artifact + production environment** |
+| **Optional: Monetization** | Website/tool hoạt động hợp lệ, có traffic, quyền publisher | `monetization`: `adsense-integration`, `ad-placement-ux`, `seo-growth`, `analytics-revenue`, `publisher-compliance` | Plan ads.txt/consent, ads UX and revenue scenarios; **Gate: owner approves provider/production changes** |
+| **8. Operations** | Authorized release, metrics/logs/traces và runbooks | DevOps: `observability`, `incident-response`; Kubernetes khi liên quan | SLO signals, incident timeline/postmortem, follow-up changes; không tự động thay đổi production |
+
+**Nhớ:** bảng stage sử dụng tên kỹ năng viết gọn; sử dụng [skill-matrix.md](skill-matrix.md) để lấy **ID chính xác** và command `aih skill <name>`. Technical architecture hiện là trách nhiệm của Core + adapter, chưa có capability Architecture chuyên biệt.
+
+## 2. Luồng thực tế qua các handoff
+
+1. **Discover**: BA/PM ghi `SRC-001` từ nguồn có phiên bản và kiểm tra quyền, tạo `BR-001`, `FR-001`, `NFR-001` trong BRD. Không lấy tài liệu ngoài phạm vi để làm prompt.
+2. **Product gate**: PO xác nhận `US-001`, `AC-US-001-01` và trace tới `FR-001`; bản nháp chỉ chuyển sang Ready sau khi người có thẩm quyền chấp thuận.
+3. **Design gate**: UI/UX ánh xạ `US-001` đến screen `SCR-001`, mô tả loading/error/empty/accessibility. Figma chỉ được ghi khi được phê duyệt đúng file/node; giữ node-ID để review.
+4. **Spec gate**: planner và `harness-spec` tạo change (ví dụ `add-customer-api`) mang lại `FR-001`/`AC-US-001-01`, API semantics và test plan. Nếu dùng OpenSpec CLI riêng, chạy `openspec validate add-customer-api --strict` sau khi hoàn thiện TODO.
+5. **Implementation & QA**: từng nhiệm vụ dùng `harness-tdd` và skill adapter phù hợp, bảo vệ tenancy/auth, test failures và DB migration; reviewer kiểm tra diff theo approved AC.
+6. **PR**: branch riêng, PR có change ID, source/spec links, tests thực chạy, tests còn thiếu, plan rollback; không tự merge.
+7. **Release**: DevOps dùng artifact immutable + explicit human production gate; người vận hành hoặc runtime đã cấp quyền mới có thể deploy. Sau đó thu thập latency/errors/traffic/saturation và cập nhật postmortem nếu cần.
+
+**Traceability mẫu (đây là ví dụ, không phải dữ liệu thật):**
+
+~~~text
+SRC-001 (Confluence page, revision)
+  → BR-001 / FR-001 → PRD-001
+  → US-001 / AC-US-001-01
+  → SCR-001 / Figma node (nếu có UI)
+  → openspec/changes/add-customer-api/
+  → source/tests/commit SHA
+  → PR / CI evidence
+  → artifact digest / approved release / observed SLO
+~~~
+
+Project tự sở hữu các file `docs/product/` và cập nhật `traceability.md`. Không có automation nào tự cập nhật trace ID giữa Figma, Jira, code và release.
+
+## 3. Thực thi từ AI IDE theo stage (prompts mẫu)
+
+**Business phase:**
+
+> Đọc AGENTS.md, tài liệu nguồn được phép truy cập và capability Product đã cài. Sử dụng knowledge-analysis → BRD/PRD → stories/AC/traceability. Ghi nguồn và revision cho mọi fact, tách suy luận và quyết định. Tạo draft trong docs/product/ và yêu cầu BA/PO review, không tự approve.
+
+**Design phase (tùy chọn):**
+
+> Dùng các requirement ID đã được phê duyệt, lập UX flow và screen inventory với trạng thái lỗi/rỗng/loading. Chờ duyệt trước mọi thay đổi Figma; chỉ thao tác trên file được cấp quyền. Ghi screen-to-node mapping.
+
+**Implement phase:**
+
+> Dựa trên approved OpenSpec change, chọn chính xác Core/adapter skill cần dùng; thực hiện test-first slice nhỏ, không đụng file ngoài scope. Báo kết quả tests đã chạy, cập nhật requirement-to-test evidence, mở PR để review, không tự merge.
+
+**Release phase:**
+
+> Lập CI/CD, container, deployment và rollback plan với các signal có thể đo. Chỉ đề xuất thao tác production; không deploy/rollback nếu chưa có phê duyệt riêng cho artifact và environment.
+
+## 4. Khi thay đổi không cần cả vòng đời
+
+- **Bugfix nhỏ:** đọc [bugfix workflow](../core/workflows/bugfix.md), tái hiện lỗi → regression test → patch → PR. Không tự tạo BRD/PRD mới khi không cần.
+- **Refactor/upgrade:** theo [upgrade workflow](../core/workflows/upgrade.md), inventory tương thích, baseline và rollback, giữ public contracts.
+- **Backend-only:** bỏ UI/UX; dùng Product nếu cần xác nhận nghiệp vụ, Java/AI adapter khi implement.
+- **Mobile-only:** dùng React Native adapter và UI/UX; không cài Kubernetes cho app di động chỉ vì cần release.
+- **No code yet:** Product + UI/UX có thể dừng sau design gate, không tạo PR implementation giả.
+
+## 5. Verify, eval và hồ sơ release
+
+~~~bash
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+`aih verify` **không chạy** lint/build/test; `aih eval` tạo report chưa chấm, không chạy model. Chạy các lệnh build/test từ repo bằng công cụ tương ứng, đính kèm evidence và run scenarios với mô hình thật nếu có nhu cầu. Chỉ khi đã ghi điểm có căn cứ mới dùng `aih eval --scope all --report /path/to/report.json` để tổng hợp.
+
+**Checklist hoàn thành một change:** scope và approved AC rõ; diff có trace; tests thực chạy với kết quả chính xác; security/permissions đã review; CI xanh; PR được human quyết định; deployment (nếu có) có artifact/environment approval; OpenSpec archive/sync **chỉ sau khi các PR liên quan đã merge**, thông qua upstream CLI/human được quyền.
+
+Xem [handoff contracts](agent-handoffs.md), [OpenSpec integration](openspec.md), [DevOps PR-to-production](../capabilities/devops/workflows/pr-to-production.md) và các [ví dụ theo stack](getting-started.md#ví-dụ-thực-hành).

package/docs/examples/ai-rag-service.md

@@ -0,0 +1,60 @@
+# Walkthrough 4 — Python AI/RAG service có kiểm soát truy cập
+
+**Tình huống giả định:** API hỏi đáp tri thức doanh nghiệp (Confluence/PDF) với quyền theo tenant/nhóm, citations, tool calling có giới hạn và AI quality gates. Nếu tài liệu ít, **không cần RAG**; trước tiên đo chất lượng retrieval và quyết định phương án phù hợp.
+
+## 1. Init theo phạm vi
+
+~~~bash
+cd /path/to/existing-python-ai-service
+aih resolve --adapters ai-python --capabilities product,devops
+aih init --adapters ai-python --capabilities product,devops --dry-run
+aih init --adapters ai-python --capabilities product,devops
+aih check
+aih skills
+~~~
+
+Nếu AI application triển khai trên Kubernetes, cân nhắc thêm adapter `kubernetes`. Các framework Python, vector DB và API key **không** được `aih` cài/cấp. Dùng `java-spring` thêm nếu service thực tế viết bằng Spring Boot thay vì Python; `ai-python` không phải bắt buộc cho mọi AI application.
+
+## 2. Business/data intake và security gate
+
+- BA/PO ghi nguồn tài liệu, owner, tenant/scope, revision, retention, consent và loại dữ liệu nhạy cảm; output là `source-register` và các `FR/NFR/AC` được duyệt.
+- Design nêu rõ boundary: caller identity → authorized retrieval filter → chunk/citation → grounded answer, deny-by-default và audit metadata tối thiểu.
+- Test scenarios: tenant A tìm thấy document B có độ giống cao vẫn **không lộ nội dung B**, missing access claim, prompt injection trong retrieved text, stale sources, no-evidence abstention, latency/cost budgets.
+- Không upload tài liệu bí mật vào eval fixtures; dùng synthetic corpus với auth giả lập.
+
+## 3. Spec & implementation
+
+~~~bash
+aih new-change authorized-knowledge-search
+aih skill harness-spec
+aih skill harness-tdd
+aih skill harness-ai-python-rag-access
+aih skill harness-ai-python-tool-safety
+aih skill harness-ai-evaluation
+~~~
+
+- `rag-access`: filter ACL **trước khi tài liệu được trả về model**, kết quả có source chunk/revision, giữ cross-tenant isolation; không dựa vào prompt "đừng tiết lộ".
+- `tool-safety`: schema, allowlist, scoped credentials, bounded timeout/token/cost, human approval cho mutation, test denied actions.
+- `harness-ai-evaluation`: versioned datasets, recall/groundedness/citation accuracy, denied leakage, regressions, latency/cost. Define measurement trước khi thử provider.
+- Với project có nhiều trang tài liệu mới cần index hoặc phân vùng semantic search, tách pipeline ingestion/retention và ACL ở storage/retriever. Mô tả nguồn nào thực sự truy cập được.
+
+## 4. Tests và LLM evaluation
+
+~~~bash
+# Thực hiện ở môi trường disposable sau khi xác nhận tool/test deps của repo:
+# python -m pytest  # chỉ khi dependency pytest đã cài và repo sử dụng nó
+aih verify --scope all
+aih eval --scope all
+aih check
+~~~
+
+`aih eval --scope all` cung cấp cases/report chưa chấm; chạy model/tập dữ liệu kiểm thử **bên ngoài CLI**, ghi trace đã redact và reviewer điền report. Báo real pass/fail; **không dùng synthetic score của unit test như bằng chứng model đạt chất lượng**. Kịch bản cross-module DevOps xuất hiện nếu chọn và phù hợp.
+
+## 5. PR → deployment/operations
+
+- PR chứa OpenSpec change, ACL tests, retrieved citation evidence, eval threshold results, cost/latency assumptions, prompt-injection defense và failures.
+- `harness-devops-ci-cd` / `harness-devops-deployment` lên kế hoạch artifact/staging/rollback. `harness-devops-observability` nêu access-deny counters, retrieval failures, token/cost, latency, errors, SLO.
+- Secrets thuộc secret manager/runtime, không hardcode vào prompts, report hoặc Git. Production deploy chỉ khi có authorization riêng.
+- Sau rollout, theo dõi drift source revision, tenant leak alerts và versioned dataset regressions.
+
+**Handoff:** approved data-use rules → retrieval design → OpenSpec → ACL-enforced RAG and tool wrappers → human-reviewed model evidence → PR → controlled deployment/monitoring.

package/docs/examples/astro-adsense-microtools.md

@@ -0,0 +1,80 @@
+# Walkthrough — Astro micro-tools with AdSense monetization
+
+Scenario: a free website with QR Generator, JSON Formatter and Image Compressor, aiming for **legitimate search traffic + advertising**. No guarantee of publisher approval, SEO ranking or earnings. Build useful tools first; ad placement is a secondary concern.
+
+## 1. Prerequisites and selection
+
+Node.js 22+, Git, an existing Astro app, and an `aih` CLI bundle including the optional monetization capability. If you need an Astro starter use the upstream Astro CLI separately; Harness installs only rules/skills.
+
+```bash
+cd /path/to/astro-utilities
+aih resolve --adapters astro --capabilities product,uiux,monetization
+aih init --adapters astro --capabilities product,uiux,monetization --dry-run
+aih init --adapters astro --capabilities product,uiux,monetization
+aih check
+aih skills
+aih skill harness-astro-project-architecture
+aih skill harness-monetization-adsense-integration
+aih skill harness-monetization-seo-growth
+```
+
+Product/UIUX are optional; the smallest setup is `aih init --adapters astro --capabilities monetization`. An existing installation must update `.harness/project.json` and use `aih update` instead.
+
+## 2. Start with product and SEO, no ad code
+
+Example route layout:
+
+```text
+src/pages/index.astro
+src/pages/tools/qr-generator.astro
+src/pages/tools/json-formatter.astro
+src/pages/tools/image-compressor.astro
+src/lib/qr/
+src/lib/json/
+src/lib/image/
+docs/monetization/
+```
+
+First ask the AI host to inspect the project and plan tool-specific pages with useful original content, accessible forms/error handling and local processing. Example prompt:
+
+> Read AGENTS.md plus harness-astro-project-architecture and harness-monetization-seo-growth. Plan three public micro-tools focused on real search intent, good mobile UX and static/browser-only processing. Separate verified keyword data, inference and unknowns. Do not add backend, database, web scraping, advertising scripts, ad account credentials or mock visitor counts. Propose routes, validation and meaningful descriptions; request my approval before code changes.
+
+If Product is selected, use `aih new-doc prd-lite` for the product scope if needed. The monetization documents are **not** supported by `aih new-doc`; review and copy named installed templates into project-owned `docs/monetization/` once with a permitted filesystem tool.
+
+## 3. Publisher readiness and policy review
+
+Check the actual AdSense account/site approval status, original site content, user trust pages, privacy disclosures, intended visitors and third-party rights. Use `harness-monetization-publisher-compliance`. Do not publish provider tags or claim Google approval without account access/owner authorization.
+
+Example prompt:
+
+> Read installed monetization skills and workflow site-to-adsense. Create or complete docs/monetization/site-monetization-plan.md and privacy-consent-checklist.md from supplied evidence. Read current Google policies if web is enabled, recording URLs and check dates. Confirm which visitors need a certified CMP and flag gaps. Do not assume I already have an AdSense account or a publisher ID, and do not publish anything externally.
+
+## 4. Review slots and add authorized ads only after approval
+
+Draft mobile/desktop page designs with safe ad placement around, **not inside**, Generate/Download flows. Avoid accidental taps, misleading download-like labels and layout shift; confirm tool works when ads are blocked/not filled or required consent is absent.
+
+Before production, confirm provider approval/permissions, account-supplied `ads.txt` content, deploy root path `/ads.txt`, correct CMP choice and actual deployment environment. Use `aih skill harness-monetization-ad-placement-ux`. For `ads.txt`, copy **only** a real seller line from the publisher account; Google highly recommends but does not universally require ads.txt.
+
+Review actual responsive pages, consent choices, script loading, privacy and accessibility. Test production build using **scripts that exist** in the Astro project. `aih verify --scope all` is only advisory and no cloud/Google writes occur through CLI.
+
+## 5. Measure and improve when real data exists
+
+After launch and account authorization, use analytics/Search Console exports and provider earnings for the **same time window**; compare legitimate organic traffic by tool, Page RPM, cost of hosting/API and qualitative task completion. If access is absent, label metrics UNKNOWN and use explicit assumptions rather than fabricated earnings.
+
+Example prompt:
+
+> Read harness-monetization-analytics-revenue. Using only authorized metric exports with source dates, prepare docs/monetization/analytics-report.md. Separate actual earnings from scenarios; calculate Page RPM only if earnings and page views share a window, list hosting/API costs and propose one measurable SEO/UX improvement with a stop rule. No growth hacks that generate clicks or fake ad impressions.
+
+```bash
+aih verify --scope all
+aih eval --scope all
+aih check
+```
+
+`aih eval` emits an unscored evaluation dataset; it does not test Google compliance or call a model. Human review, real site/browser tests and publisher console observations are separate activities.
+
+## 6. Scaling decisions
+
+Keep a single Astro website with many routes until independent teams/deployments or very different runtimes require an MFE split. Monetization is stack-independent and follows your site/business across Astro/React changes. Never use MFE, Kubernetes or backend services simply because the website earns ad revenue.
+
+Review [Monetization guide](../monetization.md), [Astro micro-tools](astro-micro-tools.md) and [Monetization capability](../../capabilities/monetization/README.md) for reusable procedures.