aimship 0.1.0-preview.4 → 0.1.0-preview.8

package/docs/installation.md

@@ -1,117 +1,28 @@
-# Installation and lifecycle
+# Installation guide moved
 
-## Installation layout
+Installation and software lifecycle commands live in the README. The Guide covers using Aimship after installation. This page preserves the old entry points.
 
-Aimship installs fixed releases under `~/.aimship/` and a stable launcher at `~/.aimship/bin/aimship.mjs`. User configuration and custom content are separate from release files. A current release and at most one ordinary recovery release are retained; changed or unowned files are preserved and reported.
+- [English installation instructions](../README.md#install)
+- [中文安装说明](../README.zh-CN.md#install)
 
-Choose `codex`, `cursor` or `claude-code` using repeatable `--host`. Registered hosts use one core and rules version. No per-project install, administrator privilege, npm global install, background updater or resident process is required. Source checkout, local tarball and registry examples all invoke this same installer; choose the appropriate source, do not stack them as separate host installations or add manual skill copies alongside managed entries. Installing software, connecting a host and starting a delivery are separate actions. Installation never creates `~/Aimship` or an empty delivery and never changes code repositories.
+<a id="installation-layout"></a>
+<a id="registry-installation-after-publication"></a>
+Installation options: [English](../README.md#install) · [中文](../README.zh-CN.md#install). Delivery layout: [English](guide.md#delivery-structure) · [中文](guide.zh-CN.md#delivery-structure).
 
-Node 22+ and npm are required. Installation and tool behavior have been checked on macOS arm64 with Node 24 and 26. Node 22 and other operating systems are not yet verified. Shell examples below use a POSIX shell. Preserve any existing installation before resolving conflicts.
+<a id="source-and-local-packages"></a>
+Local package installation: [English](../README.md#install) · [中文](../README.zh-CN.md#install). Source packaging: [Contributing](../CONTRIBUTING.md#isolated-installation-check).
 
-## Source and local packages
+<a id="isolated-trial"></a>
+Isolated installation validation: [Contributing](../CONTRIBUTING.md#isolated-installation-check).
 
-From the source checkout:
+<a id="host-entry-and-reload"></a>
+Host entry and reload: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts).
 
-```sh
-node bin/aimship.mjs install --host codex
-```
+<a id="add-a-host-inspect-and-update"></a>
+Upgrade, add a host or inspect the installation: [English](../README.md#update) · [中文](../README.zh-CN.md#update).
 
-From the directory containing a supplied tarball:
+<a id="disconnect-or-uninstall"></a>
+Disconnect or uninstall: [English](../README.md#uninstall) · [中文](../README.zh-CN.md#uninstall).
 
-```sh
-npx --offline file:./aimship-0.1.0-preview.4.tgz install --host codex
-```
-
-Run these against your real home only when you intend to install. Repeat `--host` to connect multiple hosts in that operation. No login to npm is needed to consume a local tarball; npm still needs a writable cache. The installer reports the installation home, previous/target version, action/result, registered hosts and entry locations. A zero exit status is not proof that a host has loaded the skill.
-
-### Isolated trial
-
-These commands use one disposable installation and npm cache, not your real configuration. Put the candidate tarball in your current directory first:
-
-```sh
-trial=$(mktemp -d)
-trial=$(cd "$trial" && pwd -P)
-npx --yes --offline --cache "$trial/npm-cache" file:./aimship-0.1.0-preview.4.tgz install --home "$trial/home" --host codex
-node "$trial/home/.aimship/bin/aimship.mjs" --version
-node "$trial/home/.aimship/bin/aimship.mjs" status
-node "$trial/home/.aimship/bin/aimship.mjs" install --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall
-```
-
-`--home` redirects only Aimship's managed installation. It does not make the running host discover this home, log in, or inherit permissions. The installed launcher and fixed release CLI default later management operations to their own installation home. An explicit `--home` overrides that target. After inspection, the disposable directory can be removed by its owner; do not substitute a real home for this temporary variable.
-
-## Registry installation after publication
-
-This candidate has not been published. After the maintainer confirms the package identity and publishes this exact preview, the proposed initial command is:
-
-```sh
-npx aimship@preview install --host codex
-```
-
-The `preview` tag selects the preview channel. To select an exact version, replace `@preview` with its version number. Confirm the package installation when npm prompts. npm obtains the installer; it copies a complete local release, so subsequent use does not depend on that npm cache. Do not use an unversioned command and assume it selects the preview channel. A missing package/version is a distribution failure, not a successful installation.
-
-## Host entry and reload
-
-| Host | Managed entry | Explicit use | After install, update or disconnect |
-| --- | --- | --- | --- |
-| Codex | `~/.agents/skills/aimship/` with `agents/openai.yaml` | Select Aimship; CLI `$aimship` | Start a new conversation or restart the CLI, then inspect its actual skill selector. If stale, restart the app. |
-| Cursor | Same `.agents/skills/aimship/` entry | `/aimship` | Start a new agent session; inspect Customize → Skills in the editor. Restart the host if the list remains stale. |
-| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | Start a new session and inspect slash-command discovery; restart the host if stale. |
-
-These host integrations are experimental; end-to-end host behavior and cross-host continuation have not yet been verified. Check skill discovery and directory access in your host before starting a delivery. Each host needs its own authentication, model availability and permission to access materials and code. Do not disable permission controls or grant unrelated directories. No cloud synchronization is installed or enabled.
-
-Codex and Cursor share the managed entry. Cursor also documents compatibility discovery from Claude/Codex directories. Aimship registers only selected hosts; it cannot guarantee that an unselected compatible host will not display an entry. If two same-name entries appear, inspect their paths and installation version rather than deleting unrelated files. Shared entry presence is distinct from registration, host discovery, login and permission. See the official [Cursor directories](https://cursor.com/docs/skills) and [Codex skill locations](https://learn.chatgpt.com/docs/build-skills).
-
-After an update, a running conversation may retain old rules. Save current facts, reload the bound core and current stage at a stable point, and use the existing compatibility/adoption process; start a new conversation if context cannot reliably refresh. Version mismatch stops new workflow writes. Never infer that installation instantly changed an active conversation.
-
-## Add a host, inspect and update
-
-Reuse the installed core without fetching another package:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
-node "$HOME/.aimship/bin/aimship.mjs" --version
-node "$HOME/.aimship/bin/aimship.mjs" status
-```
-
-Repeating the same install is safe for unchanged managed files. Adding a host preserves existing registrations. `status` reads Aimship's known installation files and managed entries; it does not scan projects or query host accounts. It separates registered hosts, missing/modified files, shared entries, pending installation and active version from unverified host capabilities. It is diagnostic, not a semantic delivery validator.
-
-To update from a new local release, run that release's `install` command with the same installation home. No `--host` is necessary for an existing installation: registered hosts are retained, and a core whose last host was disconnected remains a core-only installation. After publication, the explicit preview-channel update is:
-
-```sh
-npx aimship@preview install
-```
-
-There is one installation/update operation: `install`. `update` in the low-level CLI modifies delivery state and is **not** a software updater. The installer reports old and target versions and the result, updates the shared core and selected entries, and preserves configuration, custom content and every delivery. Completed deliveries are not traversed or rewritten. No automatic update runs in the background.
-
-## Disconnect or uninstall
-
-Disconnect one host, leaving the core and other registrations usable:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
-```
-
-If another registered host needs a shared entry, that file is retained and reported. Disconnecting the last host retains the core so version/status and later host connection remain available. A compatible host may still discover an entry used by another host; this command does not change that host's settings.
-
-Remove all managed programs and entries:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall
-```
-
-Full uninstall retains all delivery materials, user code, custom files and necessary configuration. Modified/unowned files are preserved and listed. No option purges delivery history. The launcher is removed on complete removal; inspect the returned result. Restart existing host sessions to discard cached rules.
-
-## Troubleshooting and recovery
-
-- **Foreign or modified entry/release:** read the reported path, keep its contents and resolve ownership or merge customizations explicitly. Do not force-overwrite it to obtain a successful exit status.
-- **Partial installation:** `status` can identify pending work. Rerun the exact pending package against the same home after correcting the reported cause. Binding/new workflow writes remain suspended until recovery completes. Do not choose a different version mid-recovery.
-- **Launcher unavailable:** run `node bin/aimship.mjs status --home <installation-home>` from the exact source/package installer. A missing launcher or damaged diagnostic module cannot diagnose itself. `status` reports facts without repairing them; only after inspecting the cause should you rerun the exact installer or reconcile retained files.
-- **Unexpected version:** use the stable launcher for the installed active version. A CLI inside an older release can report a different tool version; reload the current binding before continuing. A source checkout is not automatically an installed release.
-- **Package not found/authentication error:** confirm the exact package/version and public registry. Installation of a public release does not itself prove publish rights. Do not paste credentials into a bug report.
-- **Skill absent or duplicated:** inspect the actual host selector and returned entry paths after reloading. A file check alone cannot diagnose host discovery; retain this as unverified until observed.
-- **Directory denied:** authorize only the needed delivery/code roots in that host. Shared material storage does not share permissions. Report the exact denied operation rather than relocating user materials or changing security settings.
-- **Different host/session:** explicitly resume the same absolute delivery directory and inspect state/current inputs. Do not copy materials, reset the goal or run two writers. See [the user guide](guide.md).
-
-The initial data root can be selected with `--data-root` on installation. Existing configuration is retained on later installs; no language setting or second installation mode is introduced. Low-level state/version/recovery contracts are in [the CLI protocol](cli.md).
+<a id="troubleshooting-and-recovery"></a>
+Installation problems: [English](../README.md#installation-troubleshooting) · [中文](../README.zh-CN.md#installation-troubleshooting). Delivery continuation: [English](guide.md#continue) · [中文](guide.zh-CN.md#continue).

package/docs/reference.md

@@ -0,0 +1,78 @@
+# Aimship Delivery Document Reference
+
+[中文](reference.zh-CN.md) · [Guide](guide.md) · [README](../README.md)
+
+Use this reference to look up document generation conditions, stage outputs and identifier rules. Start with the Guide for everyday use.
+
+Use the [annotated directory tree in the Guide](guide.md#delivery-structure) as the layout reference. Formal documents are directly in the request directory, new prototypes in `prototype/`, preserved inputs in `source/`, and machine records/evidence in `.aimship/`. There is no extra `docs/` or `sql/` layer within a delivery.
+
+## Choose the requirement authority
+
+| Input condition | Requirement document | Prototype handling |
+| --- | --- | --- |
+| An authoritative PRD/prototype is supplied for adoption | `scope.md` records adopted versions, scope, gaps, decisions and acceptance; originals remain unchanged | Reuse covered interactions; create a prototype for uncovered interaction changes within the commissioned endpoint |
+| An idea, discussion, screenshots or scattered references | Author `prd.md`, including scope and acceptance | Create a prototype when the commissioned work changes interactions and existing material does not cover them |
+| Technical refactoring or a known-cause fix | Author `prd.md` describing the technical goal, boundaries, behavior constraints and acceptance | No prototype when there is no interaction change |
+| Independent investigation, review-only or verification-only | PRD/Scope defines that commission and its endpoint | Do not invent a future implementation or prototype |
+
+`prd.md` and `scope.md` are alternatives for the requirement authority, not duplicate descriptions to create together. If you explicitly commission maintenance of an existing editable authoritative PRD and it fully expresses this delivery's scope, authorization and endpoint, register and reuse it. Earlier authorship alone does not make adopted material editable.
+
+Preserve incoming versions in `source/`, including externally supplied PRDs, prototypes and images. Generated formal documents stay in the locations above. External originals are not rewritten when requirements change. A URL alone may not preserve a version; the agent records the available source/version and any access gaps. Reading text, inspecting a visual, interacting with a prototype and editing its original format are distinct capabilities.
+
+## Stage outputs and content
+
+Stage names are stable identifiers. This table is a catalog, not a fixed sequence; the accepted arrangement selects stages and dependencies. Every delivery retains the original request, a requirement/scope authority and state records, even when no separate requirements stage is needed. Sharing `plan.md` or `testing.md` does not complete both stages automatically: each stage retains its own status and result. Documents are drafted when their stage begins, and file creation alone does not establish completion.
+
+| Stage | When used | Output and content |
+| --- | --- | --- |
+| `frame` | The problem or intended result needs clarification | Goal/background section of PRD/Scope: problem, outcome, non-goals and assumptions |
+| `requirements` | Requirements need authoring or adoption | `prd.md`: goals, scope, requirements, states, acceptance and arrangement; or `scope.md`: source adoption, scope, exclusions, decisions, acceptance and arrangement |
+| `scope` | Commission boundaries need explicit resolution | Update PRD scope or Scope goals/boundaries; no second requirements document |
+| `prototype` | Required interaction changes are not covered by existing material | New HTML at `prototype/index.html` with related assets; other agreed formats or reused entries are registered |
+| `diagnose` | An independent investigation is explicitly arranged | `diagnosis.md`: goal, symptoms, environment, evidence, causes, unknowns and conclusion |
+| `tech-design` | Technical solution needs designing | `tech-design.md`: basis, architecture, modules, data/contracts, errors, risks and requirement coverage; SQL is produced and reviewed in contract after this design is approved |
+| `contract` | Interfaces or database changes need formal artifacts | HTTP: `openapi.yaml` or the registered authority; agreed non-HTTP format; independent SQL per target, reviewed individually |
+| `test-design` | Test cases need authoring | `testing.md`: basis, environment, cases/assertions and requirement/acceptance coverage |
+| `plan` | Before any implementation, including one small batch | `plan.md`: basis, batches, tasks, validation approach, execution section and remaining work |
+| `implement` | Execute the accepted plan | Code in its repositories; actual task status, objects and deviations in the same `plan.md` |
+| `review` | Review a batch, the integrated result or a review-only commission | `review.md`: review basis, each review's scope/findings/resolution and conclusion |
+| `verify` | Execute versioned cases after the required review, or a verification-only commission | Append execution batches/RUNs, actual results/evidence, retests and conclusion to the same `testing.md` |
+| `handoff` | Deliver the agreed endpoint | `handoff.md`: goal, artifacts, usage, review/verification results, limits and completion/acceptance/integration outcomes |
+
+During development, test-design precedes plan; each document follows the [review flow](guide.md#review-documents-and-continue). `plan` completes before the first implementation. Each implementation batch is reviewed, followed by overall review and independent verification. Test code can be authored during implementation; there is no full testing gate imposed after each batch. For one batch, one review may cover both batch and overall scope if explicitly recorded. Verification-only work may adopt existing versioned cases without claiming to have executed `test-design`.
+
+Ordinary debugging and known-cause bugs do not add `diagnose`. Fix implementation defects in implementation, design errors in technical design, requirement gaps in PRD/Scope, and incorrect expectations in versioned cases. A major unknown requiring separate investigation needs a recorded stage adjustment; dependent work waits.
+
+## SQL, changes and progress
+
+| Artifact | Generation rule and content |
+| --- | --- |
+| `database.sql` | Required when database structures or data change; one database target uses this single root-level file |
+| `database-<id>.sql` | Multiple independent database targets get one file each; use a stable target ID |
+| `change-log.md` | Record meaningful changes: reason, old/new meaning, decision, affected documents/work and remaining actions |
+| `status.md` | Generated reading entry: goal, progress, blockers, next action and document links |
+| `.aimship/state.json` | Managed state: goal/stages, document references, version binding and associated repositories/worktrees/code locations |
+
+SQL identifies the target, dialect, version/schema basis and execution conditions, and links ordered statements to requirements/design. It is prepared and individually reviewed in contract after technical design approval and before test cases. A Markdown SQL snippet or migration reference does not replace this deliverable. Generating SQL does not authorize executing it or changing a repository's migration mechanism.
+
+Existing engineering HTTP contracts remain authoritative; avoid a second competing copy. Project current and target versions are recorded in PRD/Scope with their engineering source and observation basis; an unspecified version remains unspecified. `plan.md` records actual changes, while review and test results identify the exact commit/build or uncommitted content. Each repository has its own version and object references. These differ from Aimship’s rules version, state schema and save revision. The handoff records final code objects and actual merge/release status; a target version does not establish publication.
+
+## Fixed outlines and traceable identifiers
+
+New documents follow [shared templates and rules](../skills/aimship/references/document-patterns.md). Section order and stable anchors are retained; visible headings can be translated. Inapplicable sections explain why. Short tasks use the same outline, with shorter content. Unselected stages do not produce empty documents, and there is no arbitrary small-task merging.
+
+| Identifier | Meaning |
+| --- | --- |
+| `REQ-001`, `AC-001` | Requirement and acceptance criterion |
+| `B-001`, `TASK-001` | Implementation batch and task |
+| `PAGE-001`, `Q-001` | Prototype page and tracked question |
+| `TC-001`, `RUN-001` | Test case and actual verification run |
+| `REV-001`, `CHG-001` | Review and meaningful change |
+
+Each series starts at `001` and advances beyond its historical maximum, including retired items; three digits are the minimum width. An ID is never reused for a different obligation. Within a namespace and version, an identity has one effective definition; other documents reference it. Classification or layout changes retain the ID, while splits/merges create new IDs linked to the originals.
+
+References connect requirements/acceptance to design, tasks, code objects, reviews, case versions and actual runs. These relationships may be many-to-many: `REQ-001` and `TC-001` are not related merely because their numbers match. Shared rules, permissions and quality requirements receive independent identities when independently testable. External IDs retain their spelling and source/version namespace; sources without IDs receive local mappings to their original locations. Changed case meaning gets a new version; earlier failures and their case/code versions remain traceable.
+
+For example: `REQ-001 → AC-002 → TC-004@1 → RUN-003` records the explicit requirement-to-result relationship. A RUN also identifies the tested code/build and evidence; the case ID alone does not prove execution.
+
+The tools check structure, references and basic coverage. The agent must still assess whether the content and assertions actually satisfy the requirement; valid metadata alone is not proof.

package/docs/reference.zh-CN.md

@@ -0,0 +1,78 @@
+# Aimship 交付文档参考
+
+[English](reference.md) · [使用指南](guide.zh-CN.md) · [README](../README.zh-CN.md)
+
+本文供需要查阅文档生成条件、阶段产物及编号规则时使用；日常操作请先阅读使用指南。
+
+目录位置以 [使用指南的注释目录树](guide.zh-CN.md#delivery-structure)为准：正式文档直接放在需求目录，新原型放在 `prototype/`，原始资料放在 `source/`，内部状态和证据放在 `.aimship/`。交付内不再增加 `docs/` 或 `sql/` 层级。
+
+## 需求依据与输入条件
+
+| 输入条件 | 需求文档 | 原型处理 |
+| --- | --- | --- |
+| 提供权威 PRD／原型供本次采用 | 用 `scope.md` 记录采用版本、本次范围、缺口、决定和验收，保留原件 | 已覆盖的交互复用；委托范围内有未覆盖的交互变化时补原型 |
+| 只有想法、讨论、截图或零散参考 | 自编 `prd.md`，其中包含范围和验收 | 委托范围内涉及交互变化、且现有材料未覆盖时生成原型 |
+| 技术重构或已知原因的修复 | 自编 `prd.md`，说明技术目标、边界、行为约束和验收 | 不涉及交互变化就不生成原型 |
+| 独立调查、只做 review 或只做验证 | PRD／Scope 只定义本次委托及终点 | 不虚构后续实施需求或原型 |
+
+`prd.md` 和 `scope.md` 是需求依据的两种选择，不应默认同时创建两份重复描述。如果你明确委托维护一份已有、可编辑的权威 PRD，且它完整表达本次范围、授权和终点，可以登记复用。仅凭“以前由我们编写”不能认定采用的原件可以修改。
+
+外来的 PRD、原型、图片等按采用版本保留在 `source/`，自己生成的正式文档按上述位置存放。需求变化时不改写外部原件。单独一个链接未必能保留资料版本，Agent 应记录可用来源、版本和访问缺口。提取文本、查看视觉内容、操作原型和编辑原格式，是不同能力。
+
+## 阶段产物与内容
+
+阶段名称是稳定标识。下表是阶段目录，不是强制顺序；实际选用哪些阶段及其依赖，由接受后的执行安排决定。即使无需单独执行需求阶段，每次交付仍保留原始委托、需求／范围依据和状态记录。共用 `plan.md` 或 `testing.md` 不代表两个阶段同时完成，各阶段分别记录状态和结果。文档在对应阶段开始时形成草稿，文件已创建不等于阶段已完成。
+
+| 阶段 | 使用条件 | 产物及内容 |
+| --- | --- | --- |
+| `frame` 问题定义 | 问题或预期结果仍需澄清 | PRD／Scope 的目标与背景章节：问题、目标、非目标和假设 |
+| `requirements` 需求 | 需要编写或采用需求 | `prd.md`：目标、范围、需求、状态、验收和执行安排；或 `scope.md`：资料采用、本次范围、排除项、决定、验收和执行安排 |
+| `scope` 范围确认 | 需要明确本次委托边界 | 更新 PRD 的范围或 Scope 的目标／边界，不再新建另一份需求说明 |
+| `prototype` 原型 | 所需交互变化未被现有资料覆盖 | 新 HTML 使用 `prototype/index.html`，相关资源放在同目录；其他约定格式或复用入口单独登记 |
+| `diagnose` 调查定位 | 明确安排了独立调查 | `diagnosis.md`：目标、现象、环境、证据、原因、未知项和结论 |
+| `tech-design` 技术方案 | 需要设计技术实现 | `tech-design.md`：依据、架构、模块、数据／契约、异常、风险和需求覆盖；通过后在 contract 生成并审核所需 SQL |
+| `contract` 契约及 SQL | 接口或数据库变化需要正式产物 | HTTP 使用 `openapi.yaml` 或已登记的工程权威契约；非 HTTP 使用约定格式；每个目标库的独立 SQL 逐份审核 |
+| `test-design` 测试设计 | 需要编写测试用例 | `testing.md`：依据、环境、用例／断言，以及需求和验收覆盖 |
+| `plan` 实施计划 | 任何实施开始前，包括单个小批次 | `plan.md`：依据、批次、任务、验证安排、执行记录章节和剩余工作 |
+| `implement` 实施 | 执行已确定的计划 | 在代码仓库实施；同一份 `plan.md` 记录实际任务状态、代码对象和偏差 |
+| `review` 审核 | 审核某批、整体成果，或单独受托 review | `review.md`：审核依据、各次审核范围、发现与处理、结论 |
+| `verify` 验证 | 必要 review 后执行带版本用例，或单独受托验证 | 在同一份 `testing.md` 追加执行批次／RUN、实际结果、证据、重测和结论 |
+| `handoff` 交接 | 交付约定终点的成果 | `handoff.md`：目标、产物、使用方式、审核／验证结果、限制，以及完成／验收／集成状态 |
+
+开发流程中，test-design 先于 plan；文档按[审核流程](guide.zh-CN.md#逐份审核与自动衔接)处理。`plan` 必须先于首次实施完成。每批实施后 review，全部完成后整体 review，再独立验证。实施时可以编写测试代码，但不额外设置逐批全量测试门禁。只有一批时，一次 review 可以明确覆盖批次和整体范围。单独委托验证时，可以采用已有、明确版本的用例，不声称重新执行过 `test-design`。
+
+普通开发调试、已知原因的 Bug 不增加 `diagnose`。实现错误回到实施，设计错误回到技术方案，需求缺口回到 PRD／Scope，错误的测试预期回到带版本的用例。出现需要独立调查的重大未知项时，应记录阶段调整，相关依赖工作暂停。
+
+## SQL、变更和进度
+
+| 产物 | 生成规则与内容 |
+| --- | --- |
+| `database.sql` | 数据库结构或数据发生变化时需要；一个数据库目标在需求根目录使用这一份文件 |
+| `database-<id>.sql` | 多个独立数据库目标各一份，`id` 使用稳定的目标标识 |
+| `change-log.md` | 有重要变更时记录原因、旧／新含义、决定、影响文档与工作，以及剩余动作 |
+| `status.md` | 自动生成的阅读入口，显示目标、进度、阻塞、下一步和文档链接 |
+| `.aimship/state.json` | 工具维护的状态，包含目标／阶段、文档引用、版本绑定及关联仓库／worktree／代码位置 |
+
+SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案通过后的 contract 阶段、测试用例之前准备并逐份审核。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
+
+已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
+
+## 固定大纲和可追溯编号
+
+新文档遵循[统一模板和规则](../skills/aimship/references/document-patterns.md)，保留章节顺序和稳定锚点，可翻译展示标题。不适用章节说明原因，小需求使用相同大纲、缩短内容。未选择的阶段不生成空文档，也不按“小需求”随意合并文件。
+
+| 编号 | 含义 |
+| --- | --- |
+| `REQ-001`、`AC-001` | 需求、验收标准 |
+| `B-001`、`TASK-001` | 实施批次、任务 |
+| `PAGE-001`、`Q-001` | 原型页面、待决问题 |
+| `TC-001`、`RUN-001` | 测试用例、实际验证执行 |
+| `REV-001`、`CHG-001` | 审核、重要变更 |
+
+各类编号从 `001` 开始，在包含已废弃条目的历史最大值后递增，三位是最小补零宽度。旧编号不用于另一项义务。同一命名空间和适用版本内，一个编号只有一处有效定义，其他文档引用该定义。分类或排版变化保留编号，拆分／合并则创建新编号并关联原编号。
+
+需求／验收通过引用关联到设计、任务、代码对象、审核、用例版本和实际执行，允许多对多关联；不能因数字相同就认定 `REQ-001` 对应 `TC-001`。可独立测试的公共规则、权限和质量要求应具有独立身份。外部编号保留原样，并携带来源／版本命名空间；无原编号时建立指向原文位置的本地映射。用例含义改变后产生新版本，先前失败及当时的用例和代码版本仍可追溯。
+
+例如，`REQ-001 → AC-002 → TC-004@1 → RUN-003` 表示明确的需求到结果关联。RUN 同时记录被测代码／构建及证据，仅存在用例编号不能证明已执行。
+
+工具检查结构、引用和基础覆盖；Agent 仍需判断正文和断言是否真正满足需求。元信息合法不等于内容正确。

package/lib/approvals.mjs

@@ -0,0 +1,153 @@
+import { isDeepStrictEqual } from 'node:util';
+import { artifactMap, safeRead, anchors } from './documents.mjs';
+import { fail, hash } from './io.mjs';
+
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const reject = message => fail('REVIEW_CHECK', message, 'Read review status. Preserve history, self-check the current document, and record only an actual explicit user decision.');
+const kinds = ['self-check', 'approved', 'changes-requested', 'editorial'];
+export function validateReviewState(state) {
+  if (state.reviewPolicy === undefined) return;
+  if (state.reviewPolicy !== 1 || !Array.isArray(state.reviewHistory)) reject('Unsupported review policy or missing reviewHistory.');
+  const ids = new Set();
+  for (const r of state.reviewHistory) {
+    if (!r || !text(r.id) || ids.has(r.id) || !kinds.includes(r.kind) || !text(r.document) || !text(r.version) || !/^[a-f0-9]{64}$/.test(r.digest ?? '') || !text(r.sourceRef) || !text(r.summary)) reject('Review records need unique ID, kind, document, version, digest, sourceRef and summary.');
+    ids.add(r.id);
+    if (r.kind === 'self-check' && !['passed','failed'].includes(r.result)) reject('Self-check records must distinguish passed from failed.');
+    if (r.kind === 'approved' && r.decision !== 'explicit-approval') reject('Approval requires an explicit user approval decision; questions, silence and requests to see results are not approval.');
+    if (r.kind === 'editorial' && !/^[a-f0-9]{64}$/.test(r.previousDigest ?? '')) reject('Editorial reconciliation needs the previous approved digest.');
+  }
+  for (const [index, run] of state.stageRuns.entries()) {
+    if (run.dependsOn !== undefined && (!Array.isArray(run.dependsOn) || new Set(run.dependsOn).size !== run.dependsOn.length || !run.dependsOn.every(id => state.stageRuns.slice(0, index).some(r => r.id === id)))) reject(`${run.id}: dependencies must be unique preceding run IDs.`);
+  }
+}
+// Shared execution/result sections are outside the approved design surface.
+// Reused formats have no inferred boundary: the entire pinned file is reviewed.
+export async function reviewFingerprint(directory, state, doc) {
+  const stop = doc.mode === 'new' ? { plan: 'execution', testing: 'runs' }[doc.kind] : null;
+  let body = await safeRead(directory, state, doc.path, stop ? 'utf8' : null);
+  if (body === null) return null;
+  if (stop) {
+    const at = body.search(new RegExp(`<a\\s+id=["']${stop}["']\\s*><\\/a>`));
+    if (at < 0) return null;
+    body = body.slice(0, at);
+  }
+  const assets = [];
+  for (const ref of doc.assetRefs ?? []) { const bytes = await safeRead(directory,state,ref,null); if (bytes === null) return null; assets.push([ref,hash(bytes)]); }
+  return hash(assets.length ? JSON.stringify([hash(body),assets]) : body);
+}
+function decisionFor(state, doc, digest) {
+  let approved = null, checked = null, latest = null;
+  for (const r of state.reviewHistory ?? []) {
+    if (r.document !== doc.path) continue;
+    if (r.kind === 'changes-requested') { approved = null; checked = null; }
+    if (['approved','editorial'].includes(r.kind)) approved = r;
+    if (r.version === doc.version && r.digest === digest) {
+      latest = r;
+      if (r.kind === 'self-check') { checked = r.result === 'passed' ? r : null; if (r.result === 'failed') approved = null; }
+    }
+  }
+  if (approved?.version !== doc.version || approved?.digest !== digest) approved = null;
+  return { approved, checked, latest };
+}
+export async function reviewStatus(directory, state) {
+  if (state.reviewPolicy !== 1) return { compatibility: 'review-adoption-required', canProceed: false, pending: [], runs: [], documents: [], instruction: 'Preserve old results. Enable reviewPolicy: 1 with an empty reviewHistory after compatibility assessment; no historical approval is inferred.' };
+  const map = await artifactMap(), documents = [], evidenceIssues = [], evidenceCache = new Map();
+  for (const r of state.reviewHistory ?? []) {
+    if (!evidenceCache.has(r.sourceRef)) { try { evidenceCache.set(r.sourceRef,await evidence(directory,state,r.sourceRef)); } catch { evidenceCache.set(r.sourceRef,null); } }
+    if (!r.sourceDigest || evidenceCache.get(r.sourceRef) !== r.sourceDigest) evidenceIssues.push(r.id);
+  }
+  for (const doc of state.documents ?? []) {
+    if (['source','change-log','review','handoff'].includes(doc.kind)) continue;
+    let digest = null;
+    try { digest = await reviewFingerprint(directory, state, doc); } catch { /* Missing input remains blocked. */ }
+    const { approved, checked, latest } = decisionFor(state, doc, digest);
+    documents.push({ path: doc.path, version: doc.version, digest, selfCheck: checked?.id ?? null, approval: approved?.id ?? null, status: !digest ? 'unavailable' : approved && (evidenceIssues.includes(approved.id) || (checked && evidenceIssues.includes(checked.id))) ? 'evidence-changed' : approved ? 'approved' : latest?.kind === 'changes-requested' ? 'changes-requested' : latest?.kind === 'self-check' && latest.result === 'failed' ? 'self-check-failed' : checked ? 'pending' : 'self-check-required' });
+  }
+  const runs = [], requirement = state.documentPolicy?.authority === 'adopted' ? 'scope' : 'prd';
+  for (const [i, run] of state.stageRuns.entries()) {
+    const spec = map.stages[run.stage];
+    let required = [];
+    if (spec?.humanReview) {
+      const kind = spec.kind === 'requirement' ? requirement : spec.kind;
+      required = (state.documents ?? []).filter(d => d.kind === kind || (run.stage === 'contract' && d.kind === 'sql')).map(d => d.path);
+    }
+    const declared = run.dependsOn ?? (i ? [state.stageRuns[i - 1].id] : []);
+    const producers = state.stageRuns.slice(0, i).filter(r => r.outputRefs.some(out => run.inputRefs.some(input => out.split('#')[0] === input.split('#')[0]))).map(r => r.id);
+    const development = ['requirements','scope','tech-design','contract','test-design','plan','implement'];
+    const prerequisites = development.includes(run.stage) ? state.stageRuns.slice(0,i).filter(r=>development.includes(r.stage) && development.indexOf(r.stage)<development.indexOf(run.stage)).map(r=>r.id) : [];
+    const dependsOn = [...new Set([...declared, ...producers, ...prerequisites])];
+    const blockedBy = dependsOn.filter(id => !runs.find(r => r.id === id)?.ready);
+    const waiting = required.filter(file => documents.find(d => d.path === file)?.status !== 'approved');
+    const ready = run.progress === 'done' && !['needs-review','unknown'].includes(run.applicability) && !blockedBy.length && !waiting.length && (!spec?.humanReview || required.length > 0);
+    runs.push({ id: run.id, stage: run.stage, progress: run.progress, applicability: run.applicability, documents: required, waiting, dependsOn, blockedBy, ready });
+  }
+  const current = runs.find(r => r.id === state.currentRun);
+  const pending = runs.filter(r => r.progress !== 'planned').flatMap(r => r.waiting.map(document => ({ run: r.id, document, status: documents.find(d => d.path === document)?.status })));
+  const nextRun = runs.find(r => !r.ready);
+  const nextStage = current ? runs[runs.indexOf(current) + 1]?.stage ?? null : nextRun?.stage ?? null;
+  return { compatibility: 'current', documents, runs, pending, evidenceIssues, currentRun: current?.id ?? null, nextRun: nextRun?.id ?? null, nextStage, canProceed: current ? !current.blockedBy.length && !(current.progress === 'done' && !current.ready) && current.progress !== 'blocked' && !['needs-review','unknown'].includes(current.applicability) : !pending.length && !runs.some(r=>r.progress==='blocked' || ['needs-review','unknown'].includes(r.applicability)), identity: 'Record validation only; user identity, intent and source authenticity are not authenticated.' };
+}
+async function evidence(directory, state, ref) {
+  if (!text(ref) || ref.includes('\\') || ref.split('#')[0].split('/').includes('..') || ref.startsWith('/') || (/^[a-zA-Z]:/.test(ref) && !ref.startsWith('repo:'))) reject('Review evidence must stay inside a registered root.');
+  let body;
+  try { body = await safeRead(directory, state, ref); } catch { reject(`Cannot read review evidence ${ref}.`); }
+  if (!text(body)) reject(`Preserve locally readable review evidence for ${ref}.`);
+  const fragment = ref.split('#')[1];
+  if (fragment && !anchors(body).includes(fragment)) reject(`Review evidence anchor not found: ${ref}.`);
+  return hash(body);
+}
+export async function enforceReviews(directory, state, previous) {
+  validateReviewState(state);
+  if (state.reviewPolicy !== 1) reject('Adopt the review protocol before workflow updates; old results remain readable but are not approvals.');
+  const oldHistory = previous?.reviewHistory ?? [];
+  for (const old of previous?.documents ?? []) if (oldHistory.some(r=>r.document===old.path) && !state.documents.some(d=>d.path===old.path && d.kind===old.kind)) reject(`Preserve reviewed document registration ${old.path}.`);
+  if (state.reviewHistory.length < oldHistory.length || !oldHistory.every((r, i) => isDeepStrictEqual(r, state.reviewHistory[i]))) reject('Preserve review history unchanged and in order.');
+  const prefix = { ...state, reviewHistory: [...oldHistory] };
+  for (const r of state.reviewHistory.slice(oldHistory.length)) {
+    const doc = state.documents.find(d => d.path === r.document);
+    if (!doc || r.version !== doc.version || r.digest !== await reviewFingerprint(directory, state, doc)) reject(`${r.id}: review must bind the current registered document version and content.`);
+    const prior = decisionFor(prefix, doc, r.digest);
+    if (r.kind === 'approved' && !prior.checked) reject(`${r.id}: self-check the same content before recording approval.`);
+    if (r.kind === 'editorial' && (!prior.checked || !decisionFor(prefix, doc, r.previousDigest).approved)) reject(`${r.id}: editorial reconciliation needs a self-check and the previous approval at the same version.`);
+    r.sourceDigest = await evidence(directory, state, r.sourceRef);
+    prefix.reviewHistory.push(r);
+  }
+  // Only the initial selected development sequence is ordered; later rework can recur.
+  const order = ['requirements','scope','tech-design','contract','test-design','plan','implement'];
+  const first = stage => state.stageRuns.findIndex(r => r.stage === stage);
+  for (let i = 0; i < order.length; i++) for (let j = i + 1; j < order.length; j++) {
+    const a = first(order[i]), b = first(order[j]);
+    if (order[i] === 'requirements' && order[j] === 'scope') continue;
+    if (a >= 0 && b >= 0 && a > b && !previous?.stageRuns.some(r => r.id === state.stageRuns[b].id && r.progress !== 'planned')) reject(`${order[i]} must precede ${order[j]} in the initial development arrangement.`);
+  }
+  const restoring = new Set(state.stageRuns.filter(r=>r.applicability === 'current' && previous?.stageRuns.some(old=>old.id===r.id && old.applicability==='needs-review')).map(r=>r.id));
+  let status = await reviewStatus(directory, state);
+  // Invalidate only registered producer/dependency paths. Independent branches retain their facts.
+  const affected = new Set();
+  for (const doc of state.documents) {
+    const oldDoc = previous?.documents?.find(d => d.path === doc.path);
+    const latest = oldHistory.filter(r => r.document === doc.path && ['approved','editorial'].includes(r.kind)).at(-1);
+    const now = status.documents.find(d => d.path === doc.path);
+    if (!oldDoc || !latest || !now) continue;
+    const changed = latest.digest !== now.digest || latest.version !== doc.version;
+    const editorial = state.reviewHistory.slice(oldHistory.length).some(r=>r.document===doc.path && r.kind==='editorial' && r.digest===now.digest);
+    const requested = state.reviewHistory.slice(oldHistory.length).some(r=>r.document===doc.path && (r.kind==='changes-requested' || (r.kind==='self-check' && r.result==='failed')));
+    if ((!changed && !requested) || editorial) continue;
+    if (changed && !state.openChanges.some(c => c.status === 'open')) reject(`${doc.path}: record the material change and impact in an open CHG, or self-check an editorial reconciliation.`);
+    if (changed && now.status === 'approved' && doc.version === latest.version) reject(`${doc.path}: a material revision needs a new document version; use editorial only for unchanged meaning.`);
+    for (const r of status.runs.filter(r => r.documents.includes(doc.path) && r.progress !== 'planned')) affected.add(r.id);
+  }
+  for (const r of status.runs) if (r.dependsOn.some(id => affected.has(id))) affected.add(r.id);
+  for (const r of state.stageRuns) if (affected.has(r.id) && r.progress !== 'planned') r.applicability = 'needs-review';
+  status = await reviewStatus(directory, state);
+  const previousStatus = previous?.reviewPolicy === 1 ? await reviewStatus(directory, previous) : null;
+  for (const run of state.stageRuns) {
+    const old = previous?.stageRuns.find(r => r.id === run.id);
+    const progressing = ['active','done'].includes(run.progress) && (!old || old.progress !== run.progress || old.resultRef !== run.resultRef || restoring.has(run.id));
+    if (restoring.has(run.id) && run.applicability === 'needs-review') reject(`${run.id}: current document or dependency still needs review.`);
+    if (progressing && status.runs.find(r => r.id === run.id).blockedBy.length) reject(`${run.id}: prerequisite completion, approval or affected dependency is unresolved.`);
+    if (old && old.progress !== 'planned' && previousStatus && !previousStatus.runs.find(r=>r.id===old.id).dependsOn.every(id=>status.runs.find(r=>r.id===run.id).dependsOn.includes(id))) reject(`${run.id}: preserve started dependencies; record revised work as a new run.`);
+  }
+  if (state.outcome.goal === 'met' && previous?.outcome.goal !== 'met' && status.runs.some(r => !r.ready)) reject('Resolve selected stages and document approvals before declaring the goal met.');
+  return status;
+}

package/lib/cli.mjs

@@ -1,19 +1,24 @@
+import { migrateState, scanDeliveries } from './migrate.mjs';
+import { inspectDocuments } from './documents.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { exists, fail, noSymlinks, readJSON } from './io.mjs';
 import { install, installPaths, installationStatus, installationVersion, readConfig, uninstall } from './install.mjs';
-import { SCHEMA_VERSION, STAGES, assertInstallationComplete, assertRules, checkReferences, initState, readState, recoverState, updateState, validateState } from './state.mjs';
+import { SCHEMA_VERSION, STAGES, renderState, assertInstallationComplete, assertRules, checkReferences, initState, readState, recoverState, updateState, validateState } from './state.mjs';
 
 const HELP = {
   usage: 'node <aimship.mjs> <command> [delivery-directory] [options]',
   commands: {
+    render: 'render <dir> --revision <N> --rules-version <version> [--preserve-edits]. Explicitly rebuild status.md; preserve manual edits before replacement. Does not replay a state update.',
+    migrate: 'migrate <dir> --revision <old-N> --rules-version <active-version> --input <json-file|->. Input {compatibilityRef}; preserve legacy state then move to schema 2. Adopt rules separately; documents require reviewed reconciliation.',
+    scan: 'scan <material-root>. Read immediate delivery directories in both layouts, deduplicate IDs and report conflicts/unknown records. No global search or write.',
     status: 'status [--home <dir>]. Read only Aimship-managed paths and fixed entries. Report registration, shared entry presence/integrity, active version, pending work and config problems. Host loading, login and access permissions remain unverified; no directories are created.',
     bind: 'Resolve active installation once. Returns immutable release/core/stage/CLI paths plus configured dataRoot, configPath and customPath. Source mode returns the default data root with null config/custom paths. No directories are created. Optional --home is for isolated testing.',
     init: 'init <dir> --input <json-file|-> --rules-version <version>. Create state once; input requires goal {summary, endpoint} and goalRef. Does not create templates.',
     read: 'read <dir> [--rules-version <version>]. Read-only JSON access; unknown schemas remain readable.',
     update: 'update <dir> --revision <N> --rules-version <version> --input <json-file|->. Recursively merge objects; arrays replace in full. Identity/history fields are managed. null is a literal value, not deletion.',
-    check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Does not prove semantics, anchor contents, remote access, or validation results.',
+    check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Checks explicit anchors/identity metadata in new local Markdown; reused and unsupported fragments are explicitly not checked. Does not prove semantics, remote access or validation results.',
     resume: 'resume <dir> [--rules-version <version>]. Read state and return fixed rule paths, required inputs, warnings, and continuation text; never execute work or rewrite state.',
     checkpoint: 'checkpoint <dir> --revision <N> --rules-version <old-version> --input <json-file|->. Save only checkpoint {summary, ref?} and next when a version mismatch interrupts ongoing work. Cannot complete work.',
     adopt: 'adopt <dir> --revision <N> --rules-version <active-version> --input <json-file|->. Input is {compatibilityRef}; records the assessed stable-point rule switch without changing business history.',
@@ -24,16 +29,17 @@ const HELP = {
   },
   stateProtocol: {
     schemaVersion: SCHEMA_VERSION,
+    documentReview: {reviewPolicy:1, reviewHistory:'Append-only {id,kind,document,version,digest,sourceRef,summary}. self-check requires result: passed|failed; approved requires decision: explicit-approval; editorial requires previousDigest. Read review.documents for current digests. Tools validate records, not user identity. See docs/cli.md#document-review-protocol.'},
     stages: STAGES,
     progress: ['planned', 'active', 'blocked', 'done'],
     result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
     applicability: ['current', 'needs-review', 'unknown'],
     outcome: { goal: ['in-progress', 'met', 'not-met', 'unknown'], acceptance: ['not-recorded', 'accepted', 'declined', 'unknown'] },
-    stageInstance: { id: 'stable-instance-id', stage: '<stage>', scope: 'batch or whole-delivery scope', progress: 'planned', inputRefs: [], outputRefs: [], resultRef: 'results.md#unique-historical-section (required when done)' },
+    stageInstance: { id: 'stable-instance-id', stage: '<stage>', scope: 'batch or whole-delivery scope', progress: 'planned', inputRefs: [], outputRefs: [], resultRef: 'review.md#rev-001-v1 (required when done)' },
     references: 'delivery-relative/path#optional-fragment, repo:<registered-id>/<repo-relative-path>#fragment, or HTTP(S) URL. Local paths cannot escape their root. Repository registration: {id, path: absolute-path, role}.',
     topLevel: {
-      managed: 'schemaVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, rulesHistory. Do not supply these in init/update.',
-      requiredInit: 'goal: {summary, endpoint}; goalRef: current requirements or Scope reference. Save the original request in that referenced document before init.',
+      managed: 'schemaVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, rulesHistory, documentDigests, identityHistory, retiredIdentities, legacyRunIds, writeResult. Do not supply these in init/update.',
+      requiredInit: 'goal: {summary, endpoint}; goalRef: current requirements or Scope reference. Save source/request.md and the registered PRD/Scope draft before init; documentPolicy and documents are required.',
       stageRuns: 'Ordered array of stageInstance objects, default []. Every ID is unique; currentRun must match one of these IDs or be null. Stage types may repeat with distinct IDs.',
       currentRun: 'Instance ID or null (default). Do not invent an ID without registering its instance in stageRuns.',
       repositories: 'Array of {id, path: absolute-path, role, ...optional-version-facts}, default []. No repository is required for a design-only goal.',
@@ -45,10 +51,12 @@ const HELP = {
     },
     minimalInit: {
       goal: { summary: 'Repair the search empty-state message', endpoint: 'Implement, review, and verify the agreed repair' },
-      goalRef: 'requirements.md',
-      stageRuns: [{ id: 'diagnose-1', stage: 'diagnose', scope: 'Search empty-state repair', progress: 'planned', inputRefs: ['requirements.md'], outputRefs: [] }],
-      currentRun: 'diagnose-1',
-      next: { action: 'Reproduce and diagnose the reported message', inputRefs: ['requirements.md'] }
+      goalRef: 'prd.md',
+      documentPolicy: {authority:'authored',interaction:false,prototypeCovered:false,interface:'none',databases:[]},
+      documents: [{kind:'prd',path:'prd.md',mode:'new',version:'1'}],
+      stageRuns: [{ id: 'requirements-1', stage: 'requirements', scope: 'Search empty-state repair', progress: 'planned', inputRefs: ['prd.md'], outputRefs: [] }],
+      currentRun: 'requirements-1',
+      next: { action: 'Draft the confirmed requirements', inputRefs: ['prd.md'] }
     },
     safety: 'Done is execution progress only. Results, applicability, goal attainment, acceptance, merge, and deployment are independent. Preserve old result references with priorResultRef/historyResultRefs. Goal revision needs a new goal.decisionRef; prior goals are retained automatically.'
   }
@@ -59,8 +67,8 @@ function parse(argv) {
     const item = argv[i];
     if (!item.startsWith('--')) { positional.push(item); continue; }
     const name = item.slice(2);
-    if (!['help', 'version', 'all', 'input', 'rules-version', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
-    const value = ['help', 'version', 'all'].includes(name) ? true : argv[++i];
+    if (!['help', 'version', 'all', 'preserve-edits', 'input', 'rules-version', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
+    const value = ['help', 'version', 'all', 'preserve-edits'].includes(name) ? true : argv[++i];
     if (value === undefined || (typeof value === 'string' && value.startsWith('--'))) fail('USAGE', `Missing value for ${item}`, 'Provide the option value.');
     if (name === 'host') (options.hosts ??= []).push(value);
     else { if (Object.hasOwn(options, name)) fail('USAGE', `Repeated option: ${item}`, 'Provide one value; only --host is repeatable.'); options[name] = value; }
@@ -111,7 +119,7 @@ async function binding(runtime) {
 }
 function allowed(command, options) {
   const common = ['help', 'version'];
-  const perCommand = { status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
+  const perCommand = { render: ['revision','rules-version','preserve-edits','home'], migrate:['revision','rules-version','input','home'], scan:['home'], status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
   for (const key of Object.keys(options)) if (![...common, ...(perCommand[command] ?? [])].includes(key)) fail('USAGE', `Option --${key} is not valid for ${command}.`, `Run help ${command}.`);
 }
 export async function run(argv, context) {
@@ -135,25 +143,30 @@ export async function run(argv, context) {
   if (command === 'status') return { command, data: { toolVersion: pkg.version, ...await installationStatus({ home: installHome }) } };
   if (command === 'install') return { command, data: await install(context.sourceRoot, { home: installHome, hosts: options.hosts, dataRoot: options['data-root'] }) };
   if (command === 'uninstall') return { command, data: await uninstall({ home: installHome, hosts: options.hosts }) };
+  if (command === 'scan') return {command,data:await scanDeliveries(path.resolve(positional[1]))};
   const runtime = await runtimeFor(context.sourceRoot, options, context.installRoot);
   if (command === 'bind') return { command, data: await binding(runtime) };
   const directory = path.resolve(positional[1]); const rulesVersion = options['rules-version'];
+  if (command === 'render') return {command,data:await renderState(directory,revisionOf(options.revision),rulesVersion,runtime,options['preserve-edits'])};
+  if (command === 'migrate') return {command,data:await migrateState(directory,revisionOf(options.revision),rulesVersion,runtime,await inputJSON(options.input))};
   if (command === 'init') return { command, data: await initState(directory, await inputJSON(options.input), rulesVersion, runtime) };
   if (['update', 'checkpoint', 'adopt'].includes(command)) return { command, data: await updateState(directory, await inputJSON(options.input), revisionOf(options.revision), rulesVersion, runtime, command) };
   if (command === 'recover') return { command, data: await recoverState(directory, revisionOf(options.revision), rulesVersion, runtime) };
   const read = await readState(directory);
   let mismatch = null;
   if (!read.readOnly) { try { assertRules(read.state, rulesVersion, runtime); } catch (error) { mismatch = { code: error.code, ...error.details, recovery: error.recovery }; } }
-  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: path.join(directory, 'state.json') } };
-  if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: 'Unknown schema: no structure checking, mutation, or automatic work is permitted.' } };
+  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: read.statePath, review:read.review, view: read.view, documentChanges: read.documentChanges, layoutConflict:read.conflict??false, layoutMismatch:read.layoutMismatch??false, candidates:read.candidates, migration:read.migration?.status??null } };
+  if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: read.conflict?'Conflicting state layouts require explicit reconciliation.':'Unknown schema: no structure checking, mutation, or automatic work is permitted.', candidates:read.candidates } };
   validateState(read.state); const references = await checkReferences(directory, read.state, options.all);
+  const documents=await inspectDocuments(directory,read.state);
   const missing = references.filter(x => !['exists', 'not-checked'].includes(x.status));
   if (command === 'check') {
     if (missing.length) fail('REFERENCE_CHECK', 'Required references are missing or inaccessible.', 'Repair the specific registered paths; do not scan the disk or overwrite source materials.', { references, versionMismatch: mismatch });
     if (mismatch) fail('VERSION_MISMATCH', 'State is structurally valid, but rules are not bound consistently.', mismatch.recovery, mismatch);
-    return { command, data: { structure: 'valid', references, semantics: 'not-checked' } };
+    if (documents.issues.length) fail('DOCUMENT_CHECK','Document mapping or identities need repair.','Inspect listed issues.',documents);
+    return { command, data: { structure: 'valid', review:read.review, references, documents, view:read.view, documentChanges:read.documentChanges, semantics: 'not-checked' } };
   }
   const currentRun = read.state.stageRuns.find(x => x.id === read.state.currentRun) ?? null;
   const blocked = currentRun?.progress === 'blocked';
-  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, canProceed: !mismatch && missing.length === 0 && !blocked, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read state.json and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, review:read.review, canProceed: read.review.canProceed && read.state.documentPolicy?.authority !== 'legacy' && !mismatch && missing.length === 0 && !blocked && !documents.issues.length && !read.documentChanges.length && read.view.status === 'current' && (!read.migration || read.migration.status === 'complete'), statePath:read.statePath, view:read.view, documentChanges:read.documentChanges, documents, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read ${read.statePath} and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
 }