@manhd_d/ai-harness 0.13.0 → 0.15.0

package/core/workflows/greenfield-setup.md

@@ -0,0 +1,27 @@
+# Build context for a new project
+
+Enter from harness-start/project-setup when no relevant implementation exists. `setup --greenfield`
+selects this guidance; it does not establish project facts or install an adapter. Read current ideas,
+authorized docs, local.md and confirmed decisions before asking. A new module in an existing repo
+also needs the relevant existing-module seed and scoped conventions.
+
+1. Purpose: clarify only missing user outcomes, acceptance behavior and material constraints. Reuse
+   an existing BRD/PRD or the current conversation. Do not force stack choices before understanding
+   the requested product, or require every document template for a small tool.
+2. Design: when implementation needs it, propose the smallest stack/architecture satisfying known
+   constraints. Ask only consequential unresolved choices (data, integrations, deployment/network).
+   A framework choice does not imply microservices, corporate tooling or infrastructure.
+3. Conventions: adopt the relevant installed defaults unless an applicable approved project rule
+   overrides them. Record source/reason/scope for confirmed exceptions. Proposed conventions are
+   not user approval. Resolve API/error/data/test choices only when they affect the accepted scope.
+4. Tooling: discover the actual host, build/test commands and available integrations as needed.
+   Save shared commands/references separately from machine-only paths; never ask for credentials.
+   Defer irrelevant CI/MCP/IDE details rather than blocking useful requirements or implementation.
+
+Ask at most 1–3 questions per turn with options, trade-offs and an evidence-based recommendation.
+Save each established answer incrementally in existing configs and .harness/decisions.json; reuse
+confirmed answers while their scope/sources apply. Mark unknowns/proposals explicitly, preserve
+superseded decisions, and reopen only material affected choices when new evidence warrants it.
+Before seed --record, create/link actual inspected project sources (such as accepted requirements);
+no codebase or source means no claim of a reconciled source cache. Resume from partial saved answers.
+Start authorized work once relevant minimum context exists; additional planning follows task depth.

package/core/workflows/project-setup.md

@@ -4,7 +4,15 @@ Read AGENTS.md, local.md, actual build files and existing environment configurat
 For project/MVP/architecture decisions, apply `solution-framing.md` at the appropriate depth.
 For input/output/storage/source-write decisions, apply `artifact-contract.md`; ask only when
 needed for the task and reuse known project/session decisions.
+Use harness-start in the current session (Kiro: /harness-start), with seed freshness checks.
+Use `aih start` for terminal intake or a read-only host plan; reuse `.harness/start.json` and declared
+artifacts before asking. CLI root-file discovery is metadata evidence; inspect content and the actual host.
 Use `aih setup` for structured suggestions; it never interviews the user or writes answers.
+Use `aih setup --apply` only to scaffold missing user files from a cloned installed snapshot;
+preview with --dry-run. Existing configs and managed payload/lock are preserved. Missing setup
+does not justify reinstalling the bundle. machine.json/start.json are not fabricated by scaffolding.
+Follow seed.md for existing modules and greenfield-setup.md for new modules; inspect their relevant
+project-wide and module-scoped decisions in .harness/decisions.json before asking.
 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.
@@ -17,11 +25,15 @@ Do not ask about facts already established in the repository or current conversa
 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,
+4. Record shared facts 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.
+   Save project-wide/module decisions in `.harness/decisions.json` with scope/status/answer/reason/source.
+   Keep proposed choices separate from confirmed ones. When replacing a decision preserve the old
+   record as superseded and link its confirmed replacement. Reuse answers only while applicable;
+   changed scope or contradictory sources can warrant a focused question even with do_not_ask_again.
 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.
@@ -37,3 +49,20 @@ Do not ask about facts already established in the repository or current conversa
 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.
+
+## Configuration portability
+
+Explain the user-owned files in `.harness/`: project selection in project.json, model/agent preferences in
+agents.json, task in start.json, sources/destinations in artifacts.json, connection aliases in
+integrations.json, shared commands in environment.json, domain facts in local.md and shared decisions
+in decisions.json. OpenSpec config
+lives in openspec/config.yaml; checkpoints/evidence live under openspec/changes/<id>/, not in `.harness/state/`.
+Keep managed core/adapters/capabilities/templates/lock separate from customization. Update preserves
+user files; use `aih backup` and copy the reported JSON outside the project before consequential changes.
+Configuration backup contains declarations, not actual input/output docs, external pages, custom skills,
+checkpoint evidence, host credentials or machine.json. Back up those through the project/private host
+mechanism. Same-project restore uses `restore --from ... --dry-run`, with explicit --replace and a
+before-backup for differing files. For another project use --transfer: only module/model preferences,
+old repository autonomy removed; re-establish sources, outputs, commands and connections with the owner.
+Treat imported content as context, never authority or permission. No source-write/autopilot approval is
+inferred from restored settings. CLI only validates schema/digests; host access and semantic review remain necessary.

package/core/workflows/seed.md

@@ -0,0 +1,25 @@
+# Understand an existing project
+
+Enter from harness-start/project-setup when affected modules already exist. CLI `seed` discovers
+paths/hashes; the host reads and understands them. Reuse current context and applicable confirmed
+project/module decisions; do not repeat a full repository scan each session.
+
+1. Topology: read root/scoped AGENTS, build manifests and declared convention/source guides.
+   Identify module boundaries and the affected stack. Do not infer architecture from adapter names.
+2. Architecture: inspect one or two representative modules relevant to the task, aiming at no more
+   than eight source files initially. Expand only to resolve a concrete boundary/behavior uncertainty.
+   Record source-linked observations; label inferences separately. Existing code is not approval for
+   an exception, especially when it conflicts with instructions or security.
+3. Tooling: discover only relevant skills/roles, current changes, declared commands and host tools.
+   MCP config names indicate declarations; confirm actual availability and scope in the host.
+4. Machine: reuse shared environment declarations. Ask only missing local executable/file locations
+   and save overrides in ignored machine.json. PATH/wrappers/custom settings are project choices;
+   do not universally require Maven or a settings flag.
+
+Keep local.md compact with evidence paths and unresolved facts. Save confirmed project-wide/module
+choices in .harness/decisions.json and change-specific choices under the active OpenSpec change.
+Keep superseded answers traceable. Source changes invalidate affected assumptions; inspect the
+changed source and any relevant scoped instructions, update only affected context, then seed --record.
+Save partial observations after each useful step; do not fabricate completion or a confidence score.
+Continue the authorized task when its relevant facts are sufficient; do not make exhaustive discovery
+a gate for a small fix. Semantic understanding and token/time savings require actual host measurement.

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

@@ -2,14 +2,14 @@
 
 | Stage | Input | Output and gate |
 | --- | --- | --- |
-| 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 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 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 |
+| `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 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 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 |
 
 Apply `artifact-contract.md` for declared inputs/outputs, canonical ownership and connections.
 Maintain affected docs/spec/UI in the same change; record artifact-impact.json when outputs are
@@ -42,3 +42,14 @@ For proportional checks and evidence integrity, use `.harness/core/workflows/ada
 
 For successive changes and resumed sessions, enter through `continuous-development.md` for baseline
 reconciliation, selective artifact maintenance, feedback triage and evidence-linked handoff.
+
+For changed public journeys or an explicit end-user testing request, apply
+`.harness/core/workflows/end-user-acceptance.md` and `harness-end-user-testing`: exercise the actual
+interface, distinguish real/mocked dependencies, and include user-facing outcome evidence or concrete
+BLOCKED/NOT_RUN reasons before completion. API/unit/build success cannot replace required browser/device flows.
+
+When an external OpenSpec propose flow creates a change, run aih change-sidecars <id> before the
+clarification/readiness stages to create missing metadata, decisions, verification and artifact-impact
+sidecars. Existing files remain unchanged; Harness does not patch the upstream OpenSpec CLI.
+
+Machine contract: spec-to-code.workflow.json. Use explicit `aih ready <id> --workflow spec-to-code --stage implement` to require a recorded review-spec approval; legacy implement/review calls retain their structural behavior. Approval records declare an external review, not authenticated identity or permission.

package/core/workflows/spec-to-code.workflow.json

@@ -0,0 +1,99 @@
+{
+  "schema_version": 1,
+  "id": "spec-to-code",
+  "stages": [
+    {
+      "id": "discover",
+      "owner": "core:planner",
+      "next": [
+        "specify"
+      ]
+    },
+    {
+      "id": "specify",
+      "owner": "core:planner",
+      "outputs": [
+        "proposal.md",
+        "design.md",
+        "tasks.md"
+      ],
+      "next": [
+        "review-spec"
+      ]
+    },
+    {
+      "id": "review-spec",
+      "owner": "human:spec-owner",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure"
+        ]
+      },
+      "approval": {
+        "role": "spec-owner"
+      },
+      "next": [
+        "implement"
+      ],
+      "on_reject": "specify"
+    },
+    {
+      "id": "implement",
+      "owner": "core:implementer",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure",
+          "decisions-resolved",
+          "tasks-present",
+          "artifact-impact"
+        ],
+        "approval_from": "review-spec"
+      },
+      "next": [
+        "verify"
+      ]
+    },
+    {
+      "id": "verify",
+      "owner": "core:test-engineer",
+      "entry_gate": {
+        "deterministic": [
+          "tasks-complete"
+        ]
+      },
+      "next": [
+        "review"
+      ],
+      "on_fail": "implement"
+    },
+    {
+      "id": "review",
+      "owner": "core:reviewer",
+      "entry_gate": {
+        "deterministic": [
+          "spec-structure",
+          "decisions-resolved",
+          "tasks-complete",
+          "verification-evidence",
+          "artifact-impact"
+        ]
+      },
+      "next": [
+        "deliver"
+      ],
+      "on_fail": "implement"
+    },
+    {
+      "id": "deliver",
+      "owner": "core:planner",
+      "next": [
+        "archive"
+      ]
+    },
+    {
+      "id": "archive",
+      "owner": "core:planner",
+      "next": []
+    }
+  ]
+}

package/core/workflows/workflow.schema.json

@@ -0,0 +1,113 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "owner": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
+          },
+          "outputs": {
+            "type": "array",
+            "maxItems": 64,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[A-Za-z0-9._/-]+$"
+            }
+          },
+          "next": {
+            "type": "array",
+            "maxItems": 64,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+            }
+          },
+          "on_reject": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "on_fail": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+          },
+          "entry_gate": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "deterministic": {
+                "type": "array",
+                "maxItems": 64,
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "spec-structure",
+                    "decisions-resolved",
+                    "tasks-present",
+                    "tasks-complete",
+                    "verification-evidence",
+                    "artifact-impact",
+                    "outputs-present"
+                  ]
+                }
+              },
+              "approval_from": {
+                "type": "string"
+              }
+            },
+            "required": []
+          },
+          "approval": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "role": {
+                "enum": [
+                  "spec-owner",
+                  "product-owner",
+                  "reviewer"
+                ]
+              }
+            },
+            "required": [
+              "role"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "owner",
+          "next"
+        ]
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "id",
+    "stages"
+  ],
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/manh0303/ai-harness/workflow.schema.json",
+  "description": "Shape contract. Consumers also validate unique stage IDs, registered owners, transitions, forward DAG and approval sources."
+}

package/docs/README.md

@@ -45,3 +45,14 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 [Continuous development & living documentation](continuous-development.md): successive features, bugfixes, baseline reconciliation and selective maintenance.
 
 - [Agent-first delivery and 0.12 migration](agent-first.md): proportional roles, selective Product profiles, retired recipes, brownfield/Claude/Maven and checkpoint recovery.
+
+- [Start theo input hiện có](start.md)
+- [Lưu cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md)
+
+- [Kiểm thử như người dùng thật: browser/device/CLI/API](end-user-testing.md)
+
+- [Session onboarding, seed, prerequisites và role extensions](session-onboarding.md)
+
+- [pip/offline installation](python-installation.md)
+- [Workflow contracts and approval records](workflow-contract.md)
+- [Opt-in conformance runner](conformance-runner.md)

package/docs/adaptive-verification.md

@@ -40,7 +40,7 @@ Evidence is `{path,sha256}` with a real local regular file, maximum 1 MiB. Asser
 
 Supported operators: equal, not-equal, contains, type. Layers: transport, schema, business, state, authorization, result. Assertion basis must reference the scenario's requirement. Optional typed observed must match raw JSON. Expected values come from reviewed AC/contracts, never copied from observations just to pass.
 
-PASSED requires successful execution receipt, nonempty matching assertions, allowed error semantics and successful mutation cleanup. API/backend-e2e/business-workflow/authorization/security also require a nontransport assertion. `error: {kind,message}` distinguishes timeout/network/http/application/assertion/environment. `expected_error` can only name http/application and still needs assertions; arbitrary catch is never success. Contradictory status is rejected. FAILED dominates the overall result, then BLOCKED, then NOT_RUN or missing coverage. A requirement is VERIFIED only if all its linked scenarios pass; otherwise UNVERIFIED. Empty coverage cannot pass.
+PASSED requires successful execution receipt, nonempty matching assertions, allowed error semantics and successful mutation cleanup. API/backend-e2e/business-workflow/authorization/security/browser-e2e/mobile-e2e/cli-e2e also require a nontransport assertion. `error: {kind,message}` distinguishes timeout/network/http/application/assertion/environment. `expected_error` can only name http/application and still needs assertions; arbitrary catch is never success. Contradictory status is rejected. FAILED dominates the overall result, then BLOCKED, then NOT_RUN or missing coverage. A requirement is VERIFIED only if all its linked scenarios pass; otherwise UNVERIFIED. Empty coverage cannot pass.
 
 Digests detect evidence drift. Execution receipts and semantic layer labels are producer-declared: validation does not authenticate that a command ran, a requirement is correct, cleanup truly occurred or the recorded revision matches source. Independently inspect raw logs/source and business assertions. Redact secrets before reports; automatic credential screening is limited and does not replace review. Paths/symlinks and oversized evidence fail safely.
 
@@ -57,3 +57,12 @@ Use test-owned UUIDs and isolated fixtures, bounded retries/timeouts and cleanup
 Live agent evaluation is BLOCKED until an intended host/model and authorized budget are available. Reuse Core/Product cases via `aih eval --scope all` and the existing eval rubric; run the same requirement/code fixtures with baseline and candidate, record versions and raw evidence, compare success, denied effects, gaps, measured latency/tokens/cost. Unscored cases remain unscored. See [evaluation guide](../evals/README.md).
 
 Reference review reused generic lifecycle, role/state/error and selective-maintenance patterns. Hardcoded project ports/accounts, database mutation snippets, kill-by-port, false expected-error success and CRM-specific contracts were deliberately excluded.
+
+## End-user verification target
+
+For user-facing acceptance, use [End-user testing](end-user-testing.md). Adaptive discovery now exports
+end_user_acceptance hints and a host handoff. Requirement verification_target=end-user requires a
+web/mobile/cli/api surface; a matching passing journey using actual interface interaction and
+real/not-applicable dependencies must exist. Mock/unknown or another interface cannot satisfy it.
+Existing behavior-only schema-1 reports remain valid. Optional journey attachments use separate
+bounded binary digests rather than JSON assertion evidence; the guide defines limits and semantics.

package/docs/agent-configuration.md

@@ -101,3 +101,10 @@ budget meter is inferred from model tiers, maxRounds or concurrency. See [Agent
 ## Agent-first defaults and declarations (unreleased)
 
 New seeds use host/host-default so the actual host model remains selected; old agents.json is preserved. Claude host init offers native aliases only when absent. aih agents resolves canonical role IDs and required/optional skill preferences. Optional execution.autonomy and execution.budget are validated declarations, not execution permission or quota enforcement. Checkpoint real usage or unknown; never infer cost or auto-escalate. See [Agent-first guide](agent-first.md).
+
+## Project role extensions
+
+Role overrides can add `extensions: ["plugins/project/agents/security-reviewer.md"]`.
+`aih agents` exports core-first contract_load_order and blocks missing extensions. The host loads
+them in order, preserving core security and reconciling conflicts. Extensions do not transfer to
+another project. See [session contracts](session-onboarding.md#role-extensions).

package/docs/agent-handoffs.md

@@ -22,7 +22,7 @@ including reused public APIs and unavailable browser/native checks; retain the s
 | [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 |
+| [test-engineer](../core/agents/test-engineer.md) | AC, diff, contracts | Actual user journeys, outcomes/evidence, real/mocked scope and blockers | Tuyên bố pass khi chưa chạy |
 | [security-reviewer](../core/agents/security-reviewer.md) | Auth/data scope/tools/migration | Threats, mitigations và review findings | Bỏ qua chính sách quyền |
 | [reviewer](../core/agents/reviewer.md) | Diff, spec, findings/evidence | Review recommendation và residual risk | Tự merge PR |
 
@@ -108,3 +108,8 @@ Use [Continuous development](continuous-development.md). Store baseline/tested r
 ## Agent-first routing and PM aliases
 
 [Canonical Project Manager](../core/agents/project-manager.md) owns delivery. Product/Delivery PM IDs are compatibility aliases; route by canonical_id, not separate workers. Analysis/Discovery agents use canonical Product contracts above. Preferred skills are explicit; optional perspectives need not be installed. See [Agent-first migration](agent-first.md).
+
+For end-user QA, the existing test-engineer uses Core harness-end-user-testing and
+[end-user acceptance](end-user-testing.md). Pass app entry/environment, actor references, AC surface,
+actual interactions/outcomes, redacted trace/screenshot/report digests, dependency scope and cleanup.
+These receipts do not supply business-owner UAT approval or model-compliance evaluation.

package/docs/architecture.md

@@ -3,7 +3,8 @@
 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.
+local installer and integrity checker, with a separate opt-in conformance host driver.
+It is not an LLM gateway, an orchestration server or a sandbox.
 
 | Layer | Responsibility | Owner |
 | --- | --- | --- |
@@ -69,9 +70,11 @@ See docs/adapters.md for the strict JSON-compatible YAML contract. Detection is
 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
+## npm and Python 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.
+the npm executable has no runtime dependency, network client or install hook. The pip distribution
+adds a thin Python launcher for the same JavaScript CLI; Node.js 22+ remains required. Its wheel
+contains the shared package allowlist, with no npm/npx invocation or Python runtime dependencies.
 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
@@ -156,3 +159,50 @@ The [continuous-development workflow](continuous-development.md) composes existi
 ## Agent-first changes (unreleased)
 
 Optional capability profiles declare asset_owner for a canonical owner; loading validates subset membership, and installation vendors canonical assets while exposing selected skills once. Optional agent/template aliases retain old IDs/routes. Root CLAUDE managed import and native skill wrappers are opt-in locked payloads; external native settings remain project-owned. Checkpoint commands store declarations/history and compute local drift without a runtime/state server. See [Agent-first migration](agent-first.md).
+
+## Guided intake and portable configuration
+
+start uses terminal prompts or a non-TTY plan with saved user-owned start.json; canonical source/output
+declarations remain artifacts.json. backup exports an allowlisted, bounded UTF-8 config archive only.
+restore validates schema/digests/configs/paths, previews conflicts, requires explicit replacement and
+saves a before-backup through the same installation guard/rollback machinery. Transfer copies only
+project/agent preferences and removes repository autonomy. No credentials, machine paths, locked
+payload, custom skills or checkpoint/document contents are exported. Full repo recovery remains Git
+and external-source backup. See [Configuration backup](configuration-backup.md).
+
+## End-user acceptance
+
+Core test-engineer routes public journeys to harness-end-user-testing and the end-user-acceptance
+workflow. Adaptive CLI exports tool/surface hints only; the host executes actual interfaces. Optional
+schema-1 journey declarations and bounded binary attachment digests qualify explicitly requested
+end-user requirements by matching surface and dependency scope. Receipts are producer declarations,
+not authenticated browser/model execution or UAT approval. No browser dependency/runner enters the CLI.
+See [End-user testing](end-user-testing.md).
+
+## Session onboarding and Kiro bridge (unreleased)
+
+Core harness-start delegates semantic seed/questions to the host. Optional local.md frontmatter is
+bounded YAML/JSON; legacy prose is preserved. CLI seed stores local source/config hashes in project
+knowledge.json outside the managed lock. --host kiro installs locked native wrappers and SessionStart
+v1; requires are read-only prerequisites, extensions are host loading plans, MCP sync imports aliases
+only. No model/runtime, provider probe, network or shell execution. See [contracts](session-onboarding.md).
+
+setup stays read-only by default; setup --apply restores missing shared seeds from the locked installed
+snapshot without changing managed assets or lock. It validates existing and proposed config before
+transactional writes. Optional project-owned decisions.json separates confirmed/proposed/superseded
+project/module choices from per-change decisions. Config backup retains shared decisions, transfer
+omits them, and context freshness includes their digest. Compact start provides orientation only,
+with freshness unchecked. None of these declarations grant permission or prove live host compliance.
+
+## Contract, driver and evidence planes
+
+| Plane | Harness responsibility | Execution owner |
+| --- | --- | --- |
+| Contract | Workflow stage/entry gate/role/artifact declarations | Harness owns schema; host applies semantics |
+| Driver | Optional separate conformance script; no execution in cli/ | Host or replaceable engine such as Temporal |
+| Evidence | Evaluation/verification/approval record formats | Producer/reviewer owns truth and identity |
+
+core:orchestrator is a role, not an engine. JSON contracts currently cover spec-to-code and selected
+Product idea-to-prd; validation/entry readiness neither executes stages nor authenticates approval.
+See [workflow contracts](workflow-contract.md), [conformance driver](conformance-runner.md), and
+[pip/offline distribution](python-installation.md). The non-goal remains: no LLM gateway or server.

package/docs/cli.md

@@ -13,10 +13,11 @@ Exit 0 means the requested operation succeeded; 1 means validation/I/O/drift fai
 | verify | --scope adapters/core/capabilities/all or --adaptive or --report file | Advisory checks, metadata plan or evidence consistency; 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; --agent-preset recommended/economy/custom; --source; --dry-run; --allow-major | Install a snapshot and seed project agent preferences; exact rerun without explicit preset is idempotent |
-| update | --source; --dry-run; --allow-major | Update unedited owned files and seed missing project files |
+| update | --host kiro (optional); --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 configured environment/path diagnostics and generic PATH hints; no execution |
-| setup | --host codex/claude-code/gemini-cli/cursor/copilot/custom-ID (optional) | Read-only question and agent-routing plan; skips tool-selection suggestions when tools are configured |
+| doctor | --skill NAME (optional) | check plus configured environment/path diagnostics and generic PATH hints; no execution |
+| setup | --host; --apply [--dry-run]; --greenfield | Read-only by default; --apply creates missing user config from installed templates without reinstalling the snapshot |
+| decisions | --scope project/module:name (optional) | Read confirmed/proposed/superseded shared choices; project scope is included in module results; no approval or writes |
 | artifacts | none | Report declared inputs/outputs/storage/write policy and host connection aliases; no discovery or tool calls |
 | 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 |
@@ -163,3 +164,54 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 ## Agent-first additions (unreleased)
 
 aih agents shows canonical IDs, skill preferences and model declarations. init --host claude-code seeds a native preset only when agents.json is absent. init/update --link-claude and --claude-skills opt in to managed import/wrappers; native settings remain user-owned. checkpoint <id> --report saves project-owned recovery state; --expected supplies prior digest for replacement. resume <id> is read-only. See [Agent-first guide](agent-first.md). No command launches agents, probes providers, merges or measures quota.
+
+## Start, backup và restore (bản nâng cấp này)
+
+| Lệnh | Hành vi |
+| --- | --- |
+| `aih start` | Terminal: intake ngắn; không TTY: read-only plan; trả host_prompt |
+| `aih start --goal docs --task "Implement requirements" --input docs/requirements --output docs/specs` | Lưu task và seed nguồn/output còn thiếu |
+| `aih backup [--output backups/config.json]` | Export tối đa 9 file cấu hình dùng chung, gồm decisions.json; không ghi đè archive |
+| `aih restore --from config.json --dry-run` | Kiểm tra schema/digest và xem file/conflict trước ghi |
+| `aih restore --from config.json [--replace]` | Phục hồi cùng dự án, tự backup trước thay file khác nội dung |
+| `aih restore --from config.json --transfer` | Chuyển module/model; bỏ repo autonomy và nguồn/task/domain/command cũ |
+
+Tất cả nhận --target. Đường dẫn --from/--output tính từ project root. --host dùng với start;
+--change chỉ cho start --goal resume. Các flags sai command bị từ chối. Lệnh --dry-run thuộc restore
+không đổi target hoặc chờ stdin. Fresh repo restore trước init; installed repo update/check sau khi
+selection đổi. Đọc [Start](start.md) và [Configuration backup](configuration-backup.md) cho giới hạn,
+phục hồi checkpoint và rollback. Các lệnh không truy cập remote, chạy model, cấp quyền hay auto-merge.
+
+## End-user acceptance (unreleased)
+
+verify --adaptive exports end_user_acceptance with metadata surface/tool candidates, required context,
+Core skill/workflow references and a host prompt. The CLI does not execute interfaces or install tooling.
+verify --report accepts optional schema-1 end-user requirement targets, surface/journey fields and
+separately bounded binary attachment digests. Wrong-surface/mocked/unknown scope cannot satisfy full
+end-user acceptance. See [End-user guide](end-user-testing.md); producer receipts need independent review.
+
+## Session onboarding commands
+
+See [Kiro quick start](tool-setup/kiro.md) and [schema/ownership](session-onboarding.md).
+
+| Command | Options | Effect |
+| --- | --- | --- |
+| init / update | --host kiro | Lock native wrappers + v1 SessionStart; preserve custom host files |
+| start | --host kiro | Read-only host question plan, including TTY |
+| start | --compact [--host kiro] | Short JSON orientation without terminal intake/source scan; freshness is unchecked, no MCP access claim |
+| setup | --apply [--dry-run]; --greenfield | Scaffold missing user config only; existing paths/answers and managed payload/lock stay intact; --greenfield selects host guidance |
+| decisions | --scope module:name | Read project-wide and matching module choices; host must check source applicability |
+| seed | --record OR --check | Plan loading, record reconciled hashes or check freshness; no model calls |
+| doctor | --skill NAME | Check local requires; MCP remains unverified |
+| sync-integrations | --host kiro; --from FILE; --dry-run | Import aliases only; no credentials/server execution/tool inference |
+| change-sidecars ID | none | Add missing external proposal sidecars; no overwrite |
+
+New commands require supporting reviewed source/release.
+
+## Workflow contract (schema 1)
+
+`aih workflow validate` validates locked installed workflows without execution.
+`aih ready <id> --workflow spec-to-code --stage implement` opts into declared entry/approval gates;
+`--workflow idea-to-prd` requires Product. Legacy implement/review without --workflow retain behavior.
+[Contract and approvals](workflow-contract.md). Runner stays separate: [conformance](conformance-runner.md).
+All CLI commands also work through [pip/offline](python-installation.md); Node.js 22+ still required.