@manhd_d/ai-harness 0.6.2 → 0.8.0

package/core/rules/project-conventions.md

@@ -0,0 +1,61 @@
+# Project conventions and architecture fit
+
+Apply this rule before implementation and during review, including small bugfixes. Keep discovery
+proportional to the task; a short task note is enough for a small change. This is an instruction
+contract for the AI host, not an automatic architecture checker.
+
+## Choose the mode per affected module
+- **New (greenfield):** no established implementation in scope. Propose the smallest suitable layout,
+  name/style/error/test conventions and dependency boundaries using the relevant adapter defaults.
+  Resolve consequential choices through the clarification workflow before scaffolding; use established
+  authorization for routine choices. Do not generate speculative layers, base classes or empty folders.
+- **Maintain (brownfield):** preserve the target module's architecture, public contracts, dependency
+  direction, naming, package manager and configured tools. A new feature in an existing module is still
+  maintenance. Do not modernize or reformat unrelated code as a side effect.
+- **Mixed:** a new module inside an existing repository adopts repository-wide contracts and shared
+  infrastructure; agree only its genuinely new internal choices. Map mode and boundaries per module.
+
+Do not infer mode from an empty source folder, the presence of a package manifest, or adapter detection
+alone. Inspect the requested scope, neighboring modules and established decisions first.
+
+## Resolve the applicable standard
+Within platform/security constraints and the user's authorized scope, use this order:
+1. Explicit reviewed project/module decisions (AGENTS, local.md, ADRs and approved conventions).
+2. Applicable formatter/linter/build configuration and consistent patterns in the target module.
+3. Adapter defaults for unresolved gaps only.
+
+Inspect configuration and representative implementation together. One legacy file is not a convention.
+If documentation, configuration or modules disagree, identify the paths and scope of the conflict;
+ask only when it materially affects the task. Never copy fail-open authorization, secret logging or
+another known unsafe pattern merely for consistency. Explain a safe, bounded correction; obtain a
+decision when the fix changes a public contract or exceeds the authorized scope.
+
+## Find before creating
+Before adding a file, dependency or abstraction:
+1. Read local instructions, build/lint/format settings, relevant module boundaries and one or two
+   comparable implementations plus their tests where available.
+2. Search the affected module and authorized shared packages for the needed behavior: common APIs,
+   errors, mapping, pagination, clients, components, hooks, state, storage and test helpers.
+3. Record a compact task note: inspected paths, selected pattern, reusable symbol/path, intended new
+   code location and any gap. If nothing fits, record the search scope and why a new piece is needed.
+4. Reuse only through supported public boundaries when behavior and ownership match. Do not reach
+   into another module's internals, create dependency cycles or push domain-specific logic into common.
+5. Prefer a local implementation over an unrelated shared abstraction. A small amount of similar code
+   is acceptable when its meaning or lifecycle differs. Never invent reuse evidence.
+
+Keep durable decisions and source paths in `.harness/local.md`, or link existing authoritative docs
+there. Keep task-specific reuse evidence in the change/PR. Do not duplicate whole guides or create a
+new document for every trivial edit. Update stale facts when the scope or source changes.
+
+## Control the diff and verify
+New dependencies, generic wrappers, base classes, global state and cross-module APIs need a concrete
+requirement and a brief rationale. Ask before material architecture/contract changes outside agreed
+scope; do not seek repeated approval for ordinary authorized implementation. No speculative framework,
+unused export, dead code, commented-out implementation or unrelated cleanup in the delivered diff.
+
+Review placement, naming, reuse, dependency direction, duplicate behavior and unnecessary abstraction.
+Run applicable configured format/lint/type/build/tests and existing architecture checks through the
+host; do not invent commands or install tools just to satisfy this rule. If a boundary has no automated
+check, report the manual review and its limits; propose a focused check only when warranted.
+Report actual results, skipped checks and new-component rationale. `aih check`, `aih verify` and
+structural readiness cannot prove application convention compliance or model behavior.

package/core/skills/harness-review/SKILL.md

@@ -14,6 +14,8 @@ Base/head diff, change spec, selected adapters and test evidence.
 4. Classify findings: blocker (security/data loss), major (wrong behavior), minor (maintainability), suggestion.
 5. Provide file/line, failing scenario, impact and minimal remedy for each actionable finding.
 6. Re-run a focused check when possible. Keep unverified concerns explicitly labeled.
+7. For full changes, inspect decisions.json and real verification.json evidence, then use
+   aih ready <id> --stage review. A ready result is not proof, approval or permission to merge.
 ## Output
 Findings ordered by severity; requirement coverage; actual checks; residual risk; review recommendation.
 ## Constraints

package/core/skills/harness-spec/SKILL.md

@@ -8,12 +8,16 @@ description: Turn requirements into scoped OpenSpec change artifacts.
 ## Input
 User request, authoritative source links, existing specs and repository boundaries.
 ## Procedure
-1. Read source context and identify missing or conflicting business decisions.
+1. Read source context and identify missing or conflicting business decisions. Follow the installed
+   clarification workflow: ask 1–3 consequential questions with A/B/C trade-offs, a grounded
+   recommendation and free text. Reuse established answers and authorization.
 2. Draft proposal, design, tasks and capability delta specs in openspec/changes/<id>/.
 3. Use ADDED/MODIFIED/REMOVED requirement sections and WHEN/THEN acceptance scenarios.
 4. Include affected repositories, non-goals, security impact, migration and rollback.
 5. Plan vertical tasks with public test boundaries and trace them to requirements.
-6. Resolve consequential uncertainties; validate with the project's pinned OpenSpec CLI.
+6. Record reviewed decisions, answers and source references in decisions.json. Resolve consequential
+   uncertainties before the affected implementation; run aih ready <id> --stage implement.
+7. Validate with the project's pinned OpenSpec CLI; structural readiness does not replace it.
 ## Output
 Reviewable change artifacts and an explicit list of remaining decisions.
 ## Constraints

package/core/workflows/agent-routing.md

@@ -0,0 +1,28 @@
+# Agent preferences, model routing and execution
+
+Read project-owned .harness/agents.json when present. On legacy installs, absence means no declared
+routing preference; use actual host settings and report the gap. `aih setup --host <id>` resolves the
+contract without probing models or writing native host config. Source defaults are a recommendation,
+not evidence of model/account availability. Runtime permissions and the user's current model choice win.
+
+1. Select only relevant workflow/skills/source. Resolve namespaced role IDs against installed Core and
+   selected capability contracts; inactive or disabled routing cannot remove required quality/security checks.
+2. Model aliases use @name, provider/model/reasoning can be overridden per role. Missing role mappings
+   inherit project defaults and must be reported; never silently substitute another provider or premium.
+3. Verify requested/native model ID, reasoning support, authentication and delegation in the actual host.
+   Host-incompatible or unverified choices need a grounded user decision/check before model-dependent
+   execution. Explicit user mappings are declarations, not proof that a native model is available.
+4. Single-agent: one session performs sequential roles and relevant skills. Hybrid: one lead and an
+   independent helper only when useful, authorized and supported. Multi-agent: use separate contracts
+   and concise handoffs only when runtime supports it. Follow the host's actual delegation rules.
+5. Keep simple edits/clear bugfixes in one session. For parallel work isolate responsibilities/paths,
+   share only scope, source references, decisions, AC and blockers; do not send every skill/doc to each worker.
+6. Treat maxConcurrentAgents and maxRounds as requested caps, never counters enforced by this CLI.
+   Count the lead in concurrency planning; translate native worker/thread limits only after checking
+   their semantics. When a round limit is reached, checkpoint unresolved work instead of claiming done.
+7. Premium/Astra is allowed only through the user's explicit model/tier selection; automatic escalation
+   must remain false. An economy preference does not waive correctness/security or mandatory review.
+8. No real token budget or usage meter is supplied. Read real host usage when available; report unknown
+   cost/availability. Preserve existing model settings until the user agrees a native change.
+9. Handoff task/role ID, actual model/effort if known, files/revision, decisions, performed checks, remaining
+   questions and next owner. A same-session author review is not independent review.

package/core/workflows/bugfix.md

@@ -1,6 +1,8 @@
 # Bugfix workflow
 
 1. Capture expected versus observed behavior using redacted inputs and an environment fingerprint.
+   Apply `.harness/core/rules/project-conventions.md`; inspect comparable code and reuse existing
+   helpers before adding a fix. A small bugfix needs only a compact task note, not a full survey.
 2. Create the smallest reproducible failing test or repeatable observation. If blocked, document access
    or data needed; label an unverified hypothesis as such.
 3. Rank plausible causes and test one distinguishing prediction at a time.

package/core/workflows/clarification.md

@@ -0,0 +1,28 @@
+# Clarify consequential ambiguity before implementation
+
+Apply during setup, requirement discovery and any later change that exposes a new consequential gap.
+
+1. Read the user request, project facts, relevant code/specs and previously recorded decisions.
+2. Separate verified facts, consequential unknowns and reversible implementation details.
+   Ask about business behavior, public API contracts, data changes, authorization or costly architecture.
+   Use project conventions for routine choices; record assumptions rather than blocking every edit.
+3. Ask 1–3 questions per turn. For each, explain the decision in one sentence and give 2–3 distinct
+   choices labeled A/B/C, a short trade-off for each, and free text. Recommend one only when supported
+   by evidence and explain why. If evidence is insufficient, say so instead of inventing a default.
+   Use the host's question UI if available; plain text is a valid fallback.
+4. For critical decisions, an unanswered question is not approval. Pause only the affected slice;
+   continue independent authorized work. Do not silently implement a suggested answer.
+5. Save shared setup answers in local.md/environment.json. Save change-specific questions, selected
+   answers and source references in decisions.json. Set reviewed=true only after examining the actual
+   scope for consequential ambiguity; an empty decision list is valid when there are no such gaps.
+   Status open means unresolved; resolved needs both answer and source. Preserve superseded decisions
+   in Git/history and update affected specs when the user changes an answer.
+6. Run `aih ready <id> --stage implement` where a full spec is appropriate. A structural result does
+   not supply authorization. User authorization already given remains valid; do not ask a second
+   generic confirmation once the material decisions are settled.
+7. During code/review, record real verification evidence. Small low-risk changes can use the lightweight
+   workflow with an explicit rationale instead of scaffolding a full change.
+
+Example: "On duplicate phone number: A reject creation; B update the existing customer; C return the
+existing record unchanged. A matches the create-only API in the current PRD; confirm or correct it."
+Do not use that recommendation unless the actual source supports it.

package/core/workflows/project-setup.md

@@ -0,0 +1,37 @@
+# First-run project setup
+
+Read AGENTS.md, local.md, actual build files and existing environment configuration first.
+For project/MVP/architecture decisions, apply `solution-framing.md` at the appropriate depth.
+Use `aih setup` for structured suggestions; it never interviews the user or writes answers.
+Do not ask about facts already established in the repository or current conversation.
+
+1. Identify project scope, source documents, build/test commands and environment constraints.
+   Apply `.harness/core/rules/project-conventions.md`: classify each affected module as new, maintain
+   or mixed; inspect configured conventions, comparable code and public shared APIs. Adapter detection
+   is stack evidence, not a project-mode decision. For a new project, propose the relevant adapter's
+   minimal conventions; for maintenance, preserve the applicable project conventions.
+2. Ask only missing consequential choices using the clarification workflow. Ask 1–3 questions
+   per turn, with A/B/C options where suitable, a grounded recommendation and a free-text option.
+3. For Java, inspect Maven/Gradle wrappers before proposing PATH or a custom tool. A wrapper is
+   a recommendation only when present and consistent with project policy; do not switch corporate
+   tools or download a replacement without authorization.
+4. Record shared facts and decisions in `.harness/local.md`: scope/mode, authoritative source paths,
+   layout and dependency boundaries, reusable common APIs, naming/error/test conventions, commands
+   and approved exceptions. Link existing documentation instead of duplicating it. Keep missing facts
+   explicit; do not overwrite previous answers. Define exact tool IDs, argument arrays
+   and required file paths in `.harness/environment.json`. Record evidence/source, not guessed versions.
+5. For a machine-specific executable/file location, use `.harness/machine.json` or an environment
+   reference. The machine file can only override declared paths. It does not override permissions,
+   arguments, requirements or business decisions. Do not store passwords/tokens in either file.
+6. Ensure `.harness/.gitignore` excludes `/machine.json`. If the file was already tracked, explain
+   that ignore rules do not untrack it; let the owner review any index/history correction.
+7. Run `aih doctor`. Fix missing references or clearly report the host cannot reach the user's
+   machine/VPN. The host executes only reviewed commands with its own permissions. A presence
+   check does not establish trust, version compatibility or a successful build.
+8. Commit shared facts/configuration and the Harness snapshot after review. Preserve machine data
+   locally. Once existing answers and authorization cover the task, continue without another
+   redundant "may I start?" prompt.
+
+Example: "Which Maven should this project use? A: existing Wrapper (recommended because mvnw is
+present); B: Maven on PATH; C: internal Maven at a custom path. You can describe another setup."
+If C is selected, ask for only the missing executable/settings locations. Do not request credentials.

package/core/workflows/solution-framing.md

@@ -0,0 +1,33 @@
+# Project overview, MVP and architecture fit
+
+Apply before new-project implementation or consequential feature/architecture changes, and during
+impact review. Size the work to the request; an existing clear bugfix needs a short source/reuse note,
+not a fresh BRD, architecture pack or planning interview.
+
+1. Read the user request, local facts, authoritative docs/ADRs and affected source/tests. Establish
+   new/maintain/mixed scope, actual revision and relevant modules/integrations/trust/data boundaries.
+   Reuse approved decisions and inspect only the context needed; do not fabricate an unseen project map.
+2. For a product/new journey, establish actor/problem, complete user outcome, in/out MVP scope, AC and
+   minimum safety/data quality. Prototype and MVP are distinct goals. Missing scope/behavior questions
+   go to the actual owner; explicit existing authorization still covers routine implementation choices.
+3. Establish consequential quality constraints and testable NFR scenarios. Unknown traffic, latency,
+   recovery, budget or capacity stays explicit until confirmed. Avoid unsupported numeric targets.
+4. Compare 2–3 viable architecture options only when a real decision is open; evaluate complexity,
+   operations, testability, costs and reversibility against requirements/team context. Recommend a
+   grounded minimal fit. For maintenance preserve existing boundaries unless the agreed change requires more.
+5. Separate application/deployment architecture from feature patterns. Ports and Adapters defines
+   boundaries; Factory addresses creation. Strategy/Adapter/State require actual variation or state
+   needs. Direct code is valid; do not add interfaces, engines or layers for hypothetical future scale.
+6. Describe affected public module/data/API/event ownership and important success/failure flows, reuse,
+   dependency direction and rollout/rollback constraints. Record significant decisions with alternatives,
+   owner/status and reconsideration trigger; compact notes suffice for reversible details.
+7. Keep a source-linked overview/map or pointers in local.md. On a later change inspect touched entries
+   for drift, update only verified/decided context and preserve superseded decisions. Do not flood context.
+8. Use installed Product product-to-solution, Architecture discovery-to-design/change-review and
+   Delivery planning/execution-change workflows when selected. Absent modules, apply the compact
+   equivalent in existing OpenSpec design/tasks; do not auto-install optional modules.
+9. Handoff source revisions, requirement/AC/NFR/ADR IDs, decisions/status, code/public boundaries,
+   dependencies, verification and risks to Core/selected adapters, UIUX and DevOps where relevant.
+   Return gaps to the owning role; role documents do not launch agents or self-approve decisions.
+10. Review implementation against accepted scope/design and actual tests. Model behavior evaluations,
+    manual review and application checks are separate evidence. Structural ready is not approval.

package/core/workflows/spec-to-code.md

@@ -2,15 +2,30 @@
 
 | Stage | Input | Output and gate |
 | --- | --- | --- |
-| Discover | Request, repository, linked sources | Scope, uncertainties, affected repos and risks |
+| Discover | Request, repository, linked sources | Scope/mode, affected repos and risks, convention sources, comparable code and reuse candidates; clarify consequential unknowns |
 | Specify | Agreed behavior | proposal, design, delta specs and vertical tasks |
 | Review spec | Acceptance scenarios and design | Owner agreement for consequential choices; explicit task authorization may already cover routine choices |
-| Implement | One task with a public test boundary | Failing meaningful test, minimal implementation, green test |
+| Implement | One task with a public test boundary and reuse plan | Failing meaningful test, minimal implementation, green test; established boundaries and rationale for new components |
 | Verify | Changed behavior | Relevant automated checks and honest skipped-check list |
-| Review | Diff plus spec | Findings on correctness, security, compatibility and requirements |
+| Review | Diff plus spec and convention sources | Findings on correctness, security, compatibility, reuse, placement and unnecessary abstraction |
 | Deliver | Reviewed branch | PR with change ID, evidence, residual risks and rollback plan |
 | Archive | All associated PRs merged | Sync accepted specs and archive via OpenSpec in a separate reviewed change if needed |
 
+For new projects or consequential features, follow `solution-framing.md`: source-linked overview,
+MVP/NFR, justified architecture/pattern choices and delivery dependencies feed OpenSpec design/tasks.
+For first use, read `project-setup.md` in this workflow directory. Before implementing consequential
+unknowns, follow `clarification.md`: inspect existing answers, ask 1–3 A/B/C questions with grounded
+recommendations, and record answers/source in the change's decisions.json. Do not ask again once
+scope and authorization are already clear. Run `aih ready <id> --stage implement` after drafting;
+record actual checks in verification.json and use `--stage review` before handoff. These commands
+check structure, not business approval or the truth of test evidence.
+
+Apply `.harness/core/rules/project-conventions.md` even when a full spec is unnecessary. Before adding
+code, record inspected paths, reused public APIs, intended placement and reasons for new components
+in the task note or existing change. Preserve each module's conventions in mixed repositories. Review
+the diff against those facts and run configured lint/type/build/tests and available boundary checks;
+report manual review where automated architecture coverage is absent.
+
 Use the harness-spec skill to draft and harness-tdd to implement. Use harness-debugging when diagnosing
 an observed defect. Agents are roles, not automatically spawned workers; a single assistant can perform
 them sequentially. Respect the host's delegation rules.

package/docs/adapters.md

@@ -1,5 +1,7 @@
 # Adapter capabilities
 
+Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
+
 An adapter is a versioned instruction bundle, not an executable plugin. Core owns TDD, debugging,
 review and the general workflow. Adapter skills address technology-specific decisions and reuse Core.
 
@@ -81,3 +83,7 @@ Add rules and a concrete technology skill with testable inputs/outputs; avoid du
 Declare metadata/checks/cases and register new adapter IDs. Include detection positive/negative fixtures,
 install/removal/drift cases, and report validation tests. Run npm test, npm run validate and npm run
 test:package. Version changes and review installed snapshots before release.
+
+## Project coding conventions
+
+Core owns new/maintain/mixed mode, precedence, discovery/reuse and diff-review rules for every adapter. Java/Spring, React/Next.js and React Native declare `rules/conventions.md` for stack defaults; existing project decisions take precedence. See [Project conventions](project-conventions.md). Checks remain advisory/manual and do not enforce application architecture.

package/docs/agent-configuration.md

@@ -0,0 +1,99 @@
+# Agent configuration and model routing
+
+Harness declares preferences; the AI host performs model selection and execution. No provider calls,
+automatic native configuration, agent creation, token enforcement or usage tracking is supplied.
+
+## Setup
+```bash
+aih init --adapters java-spring --capabilities product,architecture,delivery
+# Or, for a new consumer:
+aih init --agent-preset economy
+aih setup --host codex
+aih check
+```
+Run only the init variant appropriate to a new consumer. Existing installs use reviewed update
+--dry-run/update/check. Recommended is the default; custom seeds the same valid starting file for
+editing. An explicit preset against existing agents.json refuses overwrite. setup prints A/B/C choices
+and resolved routes; it never interviews or writes answers. No new aih config command is necessary.
+
+## Ownership
+Canonical recommendation: config/agents.default.json in the package/source. It is copied as locked
+.harness/templates/agents.default.json. Project-owned .harness/agents.json is seeded on init or the
+first reviewed update and then preserved byte-for-byte, outside the managed lock. Editing it is expected.
+Old snapshots without agents.json remain readable. An older alternate --source without the new default
+uses the installed CLI's canonical seed; no source files are changed. Invalid custom config blocks writes
+with a field-level error; it is not reset automatically. Keep credentials in host-managed secrets, not here.
+
+## Contract and precedence
+Schema version 1 uses provider, defaultModel, defaultReasoning, models, agents and execution, with
+optional hosts. Role IDs are namespace:role: core:planner, product:project-manager and
+ delivery:project-manager remain distinct. Defaults cover all current roles; only installed selected
+roles are active. Unknown/custom role IDs can be declared but are not asserted to have a host contract.
+Future unmapped installed roles inherit project defaults and are listed by setup.
+
+Models are explicit native/opaque IDs or @alias references. models values are strings or
+{provider, model} descriptors; alias graphs must be finite, declared and acyclic. A bare balanced is
+an opaque model ID, while @balanced is an alias; this avoids silently accepting alias typos.
+Resolution: role model → project default model; role provider → alias descriptor provider → project
+provider; role reasoning → project default reasoning. Changing only defaultModel does not override
+explicit role mappings. enabled:false disables a dedicated route, not required review/security policies.
+
+```json
+{
+  "schema_version": 1,
+  "provider": "openai",
+  "defaultModel": "gpt-6.1-sol",
+  "defaultReasoning": "medium",
+  "models": { "economy": "gpt-6-luna", "balanced": "gpt-6.1-sol", "premium": "gpt-6-astra" },
+  "agents": {
+    "core:orchestrator": { "model": "@balanced", "reasoning": "high" },
+    "core:implementer": { "model": "@balanced", "reasoning": "medium" },
+    "core:documentation": { "model": "@economy", "reasoning": "low" }
+  },
+  "execution": { "mode": "hybrid", "maxConcurrentAgents": 2, "maxRounds": 3, "autoEscalateToPremium": false },
+  "hosts": {}
+}
+```
+This is a partial example; omitted registered roles inherit defaults. The shipped default covers Core,
+Product, Architecture and Delivery roles. Orchestrator/Planner/Architect/Reviewer/Security Reviewer
+use Sol high; BA/PO/PM/Implementer/Test Engineer use Sol medium; Documentation uses Luna low.
+Economy is Luna low with single-agent/one concurrent session; it is a preference, not a cost guarantee.
+
+Reasoning levels structurally accepted: none, minimal, low, medium, high, xhigh, max, ultra. Actual
+supported levels vary by model/client. Mode is single-agent, hybrid or multi-agent; concurrency is
+integer 1–32, rounds 1–20, and single-agent requires concurrency 1. These are schema bounds and advisory
+requests, not runtime capacity claims. Automatic premium escalation must be false; explicitly select
+@premium or another native model if desired. JSON max size 1 MiB; no shell text is executed.
+
+## Cross-provider and host mapping
+For Claude, choose an available Anthropic model and provider explicitly; OpenAI model IDs do not
+become Claude models. Gemini likewise needs an available Google/Vertex model. A role override may use:
+```json
+{ "provider": "anthropic", "model": "native-model-id-from-your-host", "reasoning": "medium" }
+```
+The placeholder is not an availability assertion. Alias descriptors allow the same explicit provider/model
+choice across several roles. Supported vendor transport/authentication must be configured in the host.
+
+Optional hosts.<host>.models maps provider/model to an explicit native replacement, and hosts.<host>.reasoning
+maps logical effort to native values. These are user-selected substitutions, not claims of equivalent
+models. For example, after inspecting the real Claude picker, replace this illustrative mapping target:
+```json
+{ "models": { "openai/gpt-6.1-sol": "native-claude-model-id" }, "reasoning": { "medium": "medium" } }
+```
+Put it inside hosts.claude-code. Configure every active request that needs translation, including Luna
+for documentation if used; unmapped incompatible routes are reported. setup marks availability unverified
+and runtime_verified:false even when a mapping is supplied. Unknown hosts also require verification.
+
+## Actual native integration
+[Tool setup](tool-setup/README.md) explains project-owned bridges. [Codex](tool-setup/codex.md),
+[Claude Code](tool-setup/claude-code.md) and [Gemini CLI](tool-setup/gemini-cli.md) contain model/native
+configuration references. Copy only a reviewed mapping into existing native config; do not overwrite it.
+CLI/IDE single sessions may retain one model while playing many roles; per-role preferences require
+supported native agents or deliberate separate sessions. Cursor/Copilot availability and reasoning
+controls vary by client. No role JSON automatically creates a native subagent or changes current session.
+
+## Lightweight execution
+[Routing workflow](../core/workflows/agent-routing.md) sizes execution to the task. Hybrid defaults to
+one lead plus at most one independent helper when supported. Keep inputs scoped, load skill metadata
+before one needed body and checkpoint unresolved work. Actual usage/quotas come from the host; no fake
+budget meter is inferred from model tiers, maxRounds or concurrency. See [Agent handoffs](agent-handoffs.md).

package/docs/agent-handoffs.md

@@ -11,6 +11,11 @@ AI Harness hiện có **role contracts**, không tạo các agent chạy tự đ
 | [product-owner](../capabilities/product/agents/product-owner.md) | Approved requirements | Epics/stories/AC, backlog readiness | Tự đánh dấu Ready khi còn thiếu phê duyệt |
 | [project-manager](../capabilities/product/agents/project-manager.md) | Scope và phụ thuộc | Timeline/risks/RAID theo nguồn | Bịa estimate/commitment |
 | [requirements-reviewer](../capabilities/product/agents/requirements-reviewer.md) | BRD/PRD, nguồn và stories | Review report, missing trace, human gate | Gọi draft là Approved |
+| [solution-architect](../capabilities/architecture/agents/solution-architect.md) | MVP/requirements, actual source/NFR | Overview, public boundaries/contracts, options/ADRs and verification | Self-approve decisions or impose patterns |
+| [architecture-reviewer](../capabilities/architecture/agents/architecture-reviewer.md) | Design/diff, ADRs and actual checks | Source-linked findings, drift/quality and residual risk | Claim independent approval of own work |
+| [delivery project-manager](../capabilities/delivery/agents/project-manager.md) | Reviewed scope/solution, actual capacity | Value slices, dependencies, risks and change assessment | Invent dates/progress or message stakeholders |
+| [orchestrator](../core/agents/orchestrator.md) | Authorized task, preferences and host capabilities | Scoped coordination and consolidated evidence | Auto-escalate premium or claim native workers exist |
+| [documentation](../core/agents/documentation.md) | Verified sources and decisions | Source-linked document diff and quality evidence | Invent approval or unperformed verification |
 | [planner](../core/agents/planner.md) | Scope, approved requirements, repo map | OpenSpec design/tasks/test outline | Implement ngoài scope |
 | [implementer](../core/agents/implementer.md) | Spec, tasks, repo, adapter | Code slice và actual test evidence | Merge/deploy |
 | [test-engineer](../core/agents/test-engineer.md) | AC, diff, contracts | Test scenarios, executed results/gaps | Tuyên bố pass khi chưa chạy |
@@ -77,3 +82,17 @@ Next gate: security-reviewer and human PR review
 ~~~
 
 Đây là mẫu handoff, không phải report của một task đã chạy.
+
+## Product and solution delivery
+
+Product Manager owns value/outcomes; Project Manager coordinates delivery. The existing Product PM
+role/template remains a compatibility entry; the Delivery capability supplies deeper planning.
+Use [Solution workflow](solution-workflow.md) and [tool setup](tool-setup/README.md); carry MVP/AC/NFR/ADR
+IDs and source revisions with each handoff. Return gaps to the appropriate owner and keep approval factual.
+
+## Model and execution preferences
+
+[Agent configuration](agent-configuration.md) resolves namespace:role without conflating Product PM
+with Delivery PM. `.harness/agents.json` is project-owned; missing mappings inherit/report defaults.
+Actual host settings/access and delegation rules control execution. Report actual model/effort if known,
+scoped context, round checkpoint and actual checks; do not claim JSON enforced token/concurrency limits.

package/docs/architecture.md

@@ -1,5 +1,7 @@
 # Architecture and scope
 
+Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
+
 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.
 
@@ -36,6 +38,17 @@ Commit consumer state before updates; after interruption inspect the marker, run
 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.
 
+## Project environment and structural readiness
+
+Project-owned environment.json records tools, files and command arguments; ignored machine.json may
+override declared paths only. No environment values are copied into the managed lock. Installer seeds
+the shared contract and preserves existing contents; the scoped ignore rule is appended transactionally.
+The environment reader uses metadata/path presence only, with no execution or private-value output.
+
+Setup is a host-facing question plan. Clarification instructions live in Core workflows.
+Readiness reads project-owned OpenSpec decision/evidence sidecars and Markdown structure, returning
+blocked or ready. It is not a semantic validator, runtime policy engine or approval mechanism.
+
 ## 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
@@ -43,7 +56,7 @@ own model-backed runtime; actual permissions, cost limits and network allowlists
 
 ## 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).
+`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` defaults to Product; explicit `--capability monetization` selects a declared installed template into project-owned `docs/monetization/`. Review [Monetization guide](monetization.md).
 
 ## Astro static-first adapter
 
@@ -105,3 +118,22 @@ DevOps is an optional stack-neutral capability for release procedures and SRE; t
 ## 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.
+
+## Solution delivery capabilities
+
+Product 1.2.0 adds MVP/outcomes and explicit template/example/quality/handoff sections. Optional
+Architecture and Delivery schema-1 modules use existing roles/templates/checks/evals and locked
+installation; soft recommendations never auto-select them. Core solution-framing provides proportional
+overview/MVP/NFR/architecture/impact context without requiring every capability or document.
+new-doc gains explicit --capability (default Product), validating installed metadata and declared
+templates and preserving project-owned outputs. See [Solution workflow](solution-workflow.md).
+Host configuration bridges are user-owned recipes in [tool setup](tool-setup/README.md); no host
+account configuration, native-agent installation, new dependency or orchestration engine is supplied.
+
+## Agent configuration boundary
+
+config/agents.default.json is the canonical recommendation, locked as templates/agents.default.json in
+the snapshot. agents.json is project-owned and preserved. agents.js validates/resolves aliases and
+namespaced roles; setup supplies an advisory host plan with availability unverified. No provider calls,
+native writes, orchestration, usage meter or automatic escalation. Old alternate sources use the packaged
+default when absent; old consumers without config remain valid. See [Agent configuration](agent-configuration.md).

package/docs/change-readiness.md

@@ -0,0 +1,67 @@
+# Hỏi rõ và kiểm tra change
+
+Với tính năng cần spec:
+
+```bash
+aih new-change add-customer-search
+aih ready add-customer-search --stage implement
+# Sau khi implement và ghi bằng chứng:
+aih ready add-customer-search --stage review
+```
+
+AI đọc yêu cầu/code/tài liệu trước. Nếu còn mơ hồ về nghiệp vụ, API, dữ liệu hoặc quyền truy cập,
+hỏi 1–3 câu mỗi lượt, có A/B/C, trade-off, đề xuất có lý do và phương án trả lời khác. Không hỏi lại
+điều đã được xác nhận. Không coi im lặng là đồng ý; tiếp tục phần độc lập đã được cho phép.
+
+## Hai file bổ sung cho mỗi change
+
+`decisions.json` ghi kết quả rà soát và những quyết định ảnh hưởng triển khai:
+
+```json
+{
+  "schema_version": 1,
+  "reviewed": true,
+  "decisions": [
+    {
+      "id": "duplicate-phone",
+      "question": "Xử lý số điện thoại đã tồn tại?",
+      "status": "resolved",
+      "answer": "Trả lỗi trùng; không cập nhật khách hàng cũ.",
+      "source": "Người dùng xác nhận trong ticket CRM-42."
+    }
+  ]
+}
+```
+
+Đây chỉ là ví dụ, không phải quyết định thực cho project của bạn. `reviewed: true` nghĩa đã rà soát
+các điểm mơ hồ, không phải quyền deploy/merge. `decisions: []` hợp lệ nếu thực sự không có điểm
+cần hỏi; không xóa các quyết định chưa trả lời để vượt kiểm tra.
+
+`verification.json` ghi bằng chứng thực chạy:
+
+```json
+{
+  "schema_version": 1,
+  "checks": [
+    { "name": "unit-tests", "status": "passed", "evidence": "CI run URL hoặc đường dẫn log có kết quả" },
+    { "name": "integration", "status": "skipped", "reason": "Host không truy cập được VPN nội bộ" }
+  ]
+}
+```
+
+Chỉ ghi passed khi có bằng chứng. Failed chặn review; skipped phải có lý do và luôn hiện riêng trong
+kết quả. Ít nhất một check hoặc manual review đã pass phải được ghi; tất cả skipped không đủ.
+
+## Lệnh thực sự kiểm tra gì?
+
+- Implement: proposal/design/tasks/spec phải có, không còn marker TODO/TBD/FIXME/template ngoài
+  code block; có cấu trúc requirement/scenario WHEN/THEN; đã rà soát và giải quyết các quyết định khai báo.
+- Review: thêm tasks trước merge đã hoàn thành và verification hợp lệ. Tasks chỉ thuộc phần
+  `## After merge` (hoặc `## 4. After merge`) được bỏ qua để không ép archive sớm.
+- Missing/invalid/blocked trả exit 1; ready trả exit 0. Không sửa file, gọi model hoặc chạy test.
+- Đây là kiểm tra cấu trúc, không thể phát hiện mọi mơ hồ trong ngôn ngữ tự nhiên hoặc chứng minh
+  bằng chứng là thật. Reviewer vẫn kiểm tra nguồn, diff và log; dùng OpenSpec CLI riêng để validate.
+
+Change cũ không bị tự sửa. Nếu muốn dùng ready, copy hai template từ
+`.harness/templates/openspec/` sau khi update, chỉ khi file đích chưa có; điền theo thực tế.
+Sửa nhỏ, ít rủi ro không cần full change: ghi rationale và bằng chứng ngay trong PR.

package/docs/cli.md

@@ -3,7 +3,7 @@
 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.
+Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift failure or blocked readiness/setup; 2 is a CLI usage error. Help and version are plain text; no arguments displays help.
 
 | Command | Options | Effect |
 | --- | --- | --- |
@@ -15,7 +15,9 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
 | 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 |
+| doctor | none | check plus configured environment/path diagnostics and generic PATH hints; no execution |
+| setup | none | Read-only host-facing question plan; skips tool-selection suggestions when tools are configured |
+| ready ID | --stage implement/review | Structural readiness; blocked returns exit 1, ready returns exit 0; no business approval |
 | 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 |
@@ -34,7 +36,21 @@ Selection changes belong in .harness/project.json; unknown or duplicate adapters
 
 ## 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).
+`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` defaults to Product; explicitly choose `--capability monetization` to scaffold a declared installed template into project-owned `docs/monetization/` without overwrite. No Google account access, ads publishing or metrics APIs are provided. See [Monetization guide](monetization.md).
+
+## Project environment and clarification
+
+See [Project configuration](project-configuration.md) for the schema and Maven example.
+Init/update seed a project-owned environment.json and append /machine.json to .harness/.gitignore,
+preserving previous content. Private machine files are not created, locked or published by the CLI.
+Doctor returns nonzero for configured required paths/variables that are missing; diagnostics omit values.
+Setup returns questions/options/recommendations for the AI host; it does not read stdin or write answers.
+Init/update/new-doc/new-change also return next_steps without executing them.
+
+See [Change readiness](change-readiness.md): new changes include decisions.json and verification.json
+when those templates are present in the installed lock. Legacy snapshots still scaffold their existing
+files; update first to adopt sidecars. ready does not rewrite old changes, validate upstream OpenSpec,
+run tests, infer every semantic ambiguity or verify that recorded evidence is true.
 
 ## Ownership and conflict behavior
 AGENTS.md ownership covers only text between the unique start/end markers, inclusive. Any modification
@@ -107,3 +123,25 @@ See [Getting started](getting-started.md) for CLI boundaries, [Full SDLC](end-to
 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.
+
+### Convention setup guidance
+
+`aih setup` suggests a new/maintain/mixed scope question for unconfigured environments without guessing an answer. Regardless of suggested questions, the host must inspect existing conventions and reuse opportunities; a configured tool does not establish project mode. Answers stay in project-owned `.harness/local.md`. See [Project conventions](project-conventions.md). No application scanning, scaffolding or commands are executed.
+
+## Architecture and Delivery drafts
+
+`aih new-doc <type>` still defaults to Product (idea/research remain under docs/discovery).
+Use `aih new-doc overview --capability architecture`, `aih new-doc adr --capability architecture` or
+`aih new-doc delivery-plan --capability delivery` for a declared template in that installed capability.
+Output is project-owned docs/<capability>/<type>.md; locked metadata/templates are required, drift and
+overwrite are refused, and no draft is filled or approved. --capability is supported only by new-doc.
+The historical Product delivery-plan path remains supported; do not duplicate an accepted plan.
+See [Solution workflow](solution-workflow.md) and [host setup](tool-setup/README.md).
+
+## Agent preferences
+
+`aih init --agent-preset recommended|economy|custom` seeds project-owned agents.json non-interactively;
+existing files are validated/preserved and explicit preset overwrite is refused. `aih setup --host codex`
+(or claude-code/gemini-cli/cursor/copilot/custom ID) exports resolved roles and compatibility limitations
+without probing models or editing host files. No extra config command, runtime or usage tracking.
+See [Agent configuration](agent-configuration.md).