aimship 0.1.0-preview.11 → 0.1.0-preview.13

package/CONTRIBUTING.md

@@ -14,7 +14,7 @@ Use GitHub Issues for bugs and feature suggestions. Provide the version, host de
 
 ## Documentation
 
-The English/Chinese README introduces the software delivery workflow, its value and outputs, gives the explicit first-use entry and expected receipt, and owns installation, upgrades, host management, version/health queries and uninstallation. The Guide owns the annotated delivery directory and document overview, and explains usage by scenario: starting without a requirements document, adopting materials, changing existing code, reading results, changing requirements, continuing and completing delivery. Avoid generic prompt tutorials; a contextual continuation entry belongs in the Guide. Keep stage mappings and document/identifier rules in the [shared agent references](skills/aimship/references/document-patterns.md); the Guide provides a brief explanation of traceability and retains user-facing [SQL and engineering version guidance](docs/guide.md#document-details). Keep both languages equivalent. Put source development and isolated validation procedures here, and agent/tool details in the [CLI protocol](docs/cli.md). Old installation/example URLs retain short compatibility pointers rather than duplicate command instructions.
+The English/Chinese README introduces the workflow, its value and outputs, and owns installation, upgrades, host management, version/health queries and uninstallation. After installation, it directs readers to the Guide. The Guide leads with first use, document review and continuation, then covers progress and acceptance, alternative starting points, troubleshooting and reference material. Explain what the user does and what follows; keep internal state/tool procedures out of the first-use path. Avoid generic prompt tutorials. Keep stage mappings and document/identifier rules in the [shared agent references](skills/aimship/references/document-patterns.md); retain the annotated [delivery directory](docs/guide.md#delivery-structure) as reference material. Keep both languages equivalent. Put source development and isolated validation here, and agent/tool details in the [CLI protocol](docs/cli.md). Old installation/example URLs retain short compatibility pointers rather than duplicate instructions.
 
 Validate public links and the shared stage/template mapping with `npm run check:docs`. Treat [artifact-map.json](skills/aimship/references/artifact-map.json) and the [document rules](skills/aimship/references/document-patterns.md) as the mapping to check against; update user-facing explanations when that mapping changes.
 
@@ -23,7 +23,7 @@ Validate public links and the shared stage/template mapping with `npm run check:
 
 To try unreleased initialization changes, open a session with access to the checkout and a separate disposable materials directory. Explicitly ask to use the checkout's `skills/aimship/SKILL.md`, read its core, and run `node bin/aimship.mjs bind` from this package root. Verify the returned releaseRoot/corePath/cliPath all point into that checkout and schemaVersion is 3; a version string alone is insufficient when local code retains the published version. Then provide a concrete synthetic request, the trial materials path, and the desired stop. Do not load the installed launcher or run install.
 
-In the next session, explicitly request that same source Skill and bind again, then provide the original delivery directory and ask to resume. Check its saved deliveryId, revision, review status and next action. This exercises source rules and local tooling without replacing global entries. Whether a specific host automatically discovers a checkout Skill is separate and must be tested rather than promised. Check `test/initialization.test.mjs` for deterministic initialization, interruption, old-format and approval-bypass regressions; their synthetic decisions are not real AI-host evidence.
+In the next session, explicitly request that same source Skill and bind again, then provide the original delivery directory and ask to resume. Check its saved deliveryId, revision, review status and next action. This exercises source rules and local tooling without replacing global entries. Whether a specific host automatically discovers a checkout Skill is separate and must be tested rather than promised. Check `test/initialization.test.mjs` for deterministic initialization, interruption and approval-bypass regressions; their synthetic decisions are not real AI-host evidence.
 
 <a id="isolated-installation-check"></a>
 ## Isolated installation lifecycle check
@@ -74,7 +74,7 @@ node scripts/run-examples.mjs <new-output-directory>
 The output directory must not exist. The harness creates isolated code and delivery folders, exercises real functions with Node assertions, and saves readable documents, state and evidence. It does not install Aimship, touch user deliveries, access the network or publish anything. Do not use a real delivery as the output. The scripts are source-checkout tools, not installed user commands.
 
 - **Authored, single batch:** a line-normalization PRD, plan before implementation, one review covering batch/overall scope, and independent normal/empty/error assertions. Execution updates the same plan; cases and RUN results share the testing document.
-- **Adopted, multiple batches:** preserved catalog PRD/prototype inputs, Scope mappings, shared price validation and quoting with each batch reviewed. A discount change keeps case v1 and adds v2, updates earlier review applicability and binds exact code hashes. A deliberate rounding fault produces a failed RUN, followed by repair review and a successful retest while retaining failure history. Shared business rules, role restrictions and performance requirements have independent identities and acceptance.
+- **Adopted, multiple batches:** preserved catalog PRD/prototype inputs, Scope mappings, shared price validation and quoting with each batch reviewed. A discount change updates the testing document while keeping stable case IDs, records document reapproval and earlier review applicability, and binds exact code hashes. A known rounding fault fails overall review; the example asserts that starting verification is rejected without changing state. A separate maintainer probe preserves six real assertions (five pass, rounding fails) in `negative-probe.json`; it is not a formal verification stage or RUN. After fixing the code and recording a matching passing repair review, formal verification runs all six assertions successfully. Failed review and probe evidence remain available. Shared business rules, role restrictions and performance requirements have independent identities and acceptance.
 
 These examples check local document/state behavior. They do not establish automatic Skill discovery, real cross-host continuation, UI interaction or HTTP acceptance. Run output records assertions and limitations. Results from older schemas do not establish current behavior.
 

package/README.md

@@ -4,7 +4,7 @@
 
 **Aimship is a software delivery workflow for AI tools, connecting requirements, design, implementation, review and verification.**
 
-For developers responsible for delivering a requirement. You provide the goal, existing materials and code locations. Aimship helps the agent turn them into a clear scope, a reasoned design, an implementation plan and verified results. It connects these stages so that you can follow the work, understand key decisions and assess what has actually been delivered.
+For developers responsible for delivering a requirement. You provide the goal and existing materials; code can be associated when needed. Aimship helps the agent turn them into a clear scope, a reasoned design, an implementation plan and verified results. It connects these stages so that you can follow the work, understand key decisions and assess what has actually been delivered.
 
 <a id="what-a-delivery-contains"></a>
 <a id="delivery-structure-and-documents"></a>
@@ -12,7 +12,7 @@ For developers responsible for delivering a requirement. You provide the goal, e
 Standard document outlines, identifiers and references connect requirements and acceptance criteria to designs, implementation tasks, reviews and test results. Documents are produced as needed for the delivery goal, giving you a consistent basis for review without requiring an empty template for every stage.
 
 <a id="delivery-workflow"></a>
-By default, you review documents individually after the agent's self-check. The agent presents current status, the document and review focus, then waits. After explicit approval is saved, work continues within the group; at a suggested session boundary it provides next work and a continuation entry, with the option to continue here; requested changes lead to revision, self-check and another review. Document approval remains separate from final delivery acceptance; an explicitly limited partial result is not presented as standard complete delivery.
+The agent organizes requirements, design, implementation and verification; you review key documents and important decisions. Feedback leads to revisions, and approval enables subsequent work. Final acceptance is based on the agreed goal and actual verification results.
 
 Documents and state are saved throughout the work, keeping progress, decisions and verification evidence traceable and reducing the need to repeat background or reconstruct earlier work.
 
@@ -43,7 +43,7 @@ Confirm npm's package installation prompt. `@preview` selects the published prev
 To install an exact published version, for example:
 
 ```sh
-npx aimship@0.1.0-preview.7 install --host codex
+npx aimship@0.1.0-preview.13 install --host codex
 ```
 
 If you already have an Aimship `.tgz` package, replace `VERSION` with its actual version and run from the directory containing it:
@@ -64,13 +64,9 @@ npx aimship@preview install --host codex --data-root "./MyDeliveries"
 
 The example uses a `MyDeliveries` folder under the current working directory; you can replace it with an absolute path to your preferred location. This sets the default material location for new deliveries. It is not a code repository location and does not move existing materials. Later installations retain the configuration; no per-project installation is needed.
 
-After installation, follow the [Guide](docs/guide.md#hosts) to select Aimship in your tool. AI tool integrations are experimental: actual Skill discovery and continuation across AI tools still need validation.
-
-## Start a delivery
-
-Explicitly select Aimship in your AI tool, or ask it to **use Aimship** for a concrete request. For example: “Use Aimship to deliver an export of the currently filtered orders. First clarify the fields; code will be prepared later.” A PRD, code repository and settled technical conditions are not required. A product name alone prompts a short clarification first.
-
-The agent preserves your request, helps you make the materials location accessible, and creates or resumes one delivery. Its receipt shows the actual saved directory, `status.md`, current work and next step. Opening a project or mentioning the name in passing does not activate Aimship. In a new session, explicitly use Aimship again and identify the same delivery; see the [Guide](docs/guide.md#start). Source edits do not update an installed Skill; contributors can use the [local source trial](CONTRIBUTING.md#local-source-trial).
+<a id="start-a-delivery"></a>
+<a id="getting-started"></a>
+After installation, follow the [Guide](docs/guide.md#start) to prepare a workspace, activate Aimship and begin your first request. For an existing delivery, follow [continuation](docs/guide.md#continue).
 
 <a id="update"></a>
 <a id="update-or-stop-using-aimship"></a>

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 **Aimship 是面向 AI 工具的软件交付流程，贯通需求、设计、实施、审核与验证。**
 
-面向有开发基础、对一项需求交付负责的开发者。你提供目标、已有资料和代码位置，Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
+面向有开发基础、对一项需求交付负责的开发者。你提供目标及已有资料，代码可按需要关联。Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
 
 <a id="一个需求会留下哪些文档"></a>
 <a id="交付目录与文档"></a>
@@ -12,7 +12,7 @@
 统一的文档大纲、编号和引用，将需求与验收标准关联到设计、实施任务、审核和测试结果。文档按交付目标和实际需要生成，既提供一致的阅读与核对依据，也不要求每个阶段都填一份空模板。
 
 <a id="交付流程"></a>
-默认由你逐份审核经过 Agent 自检的文档。Agent 给出当前状态、文档和审核重点，等待你审核；明确通过后保存批准，组内直接衔接，到建议会话边界提供下一步和续接入口，也可选择当前会话继续。提出修改意见时，Agent 修订、自检后重新送审。文档通过与最终交付验收分别记录；明确缩减范围的阶段性成果不会被当作标准完整交付。
+Agent 整理需求、设计方案并组织实施与验证，你审核关键文档和重要决定。修改意见纳入修订，审核通过后推进后续工作；最终依据约定目标和实际验证结果验收成果。
 
 文档与状态在工作过程中持续保存，使进度、决定和验证依据可追溯，减少重复交代背景和重新梳理已有工作的负担。
 
@@ -43,7 +43,7 @@ npx aimship@preview install --host codex --host claude-code
 安装指定的已发布版本，例如：
 
 ```sh
-npx aimship@0.1.0-preview.7 install --host codex
+npx aimship@0.1.0-preview.13 install --host codex
 ```
 
 如果已有 Aimship 的 `.tgz` 安装包，将 `VERSION` 替换为实际版本号，在包所在目录执行：
@@ -64,13 +64,9 @@ npx aimship@preview install --host codex --data-root "./MyDeliveries"
 
 示例使用当前执行目录下的 `MyDeliveries` 文件夹，也可以替换为所需位置的绝对路径。此选项设置后续新交付的默认资料位置，不是代码仓库位置，也不会搬迁已有资料。后续安装保留已有配置；无需逐项目安装。
 
-安装后，按[使用指南](docs/guide.zh-CN.md#hosts)在 AI 工具中选择 Aimship。AI 工具集成仍处于实验阶段，真实 Skill 发现和跨工具接续仍需验证。
-
-## 开始一次交付
-
-在 AI 工具中明确选择 Aimship，或明确要求**使用 Aimship** 处理具体诉求。例如：“使用 Aimship 交付按当前筛选条件导出订单的功能，先确认导出字段，代码稍后准备。”不要求先有 PRD、代码仓库或明确的技术条件。只有产品名称时，Agent 会先简短澄清实际问题。
-
-Agent 保留原始诉求，引导准备资料位置的访问条件，然后创建或续接同一次交付。回执会说明实际保存目录、`status.md`、当前工作和下一步。打开项目空间或偶然提到名称不会启用 Aimship。新会话仍需明确使用 Aimship 并定位原交付，详见[指南](docs/guide.zh-CN.md#start)。源码修改不会更新已安装的 Skill；贡献者可按[本地源码体验](CONTRIBUTING.md#local-source-trial)加载。
+<a id="开始一次交付"></a>
+<a id="使用入口"></a>
+安装完成后，按[使用指南](docs/guide.zh-CN.md#start)准备工作位置、启用 Aimship 并开始首个需求；已有交付可按[续接说明](docs/guide.zh-CN.md#continue)继续。
 
 <a id="update"></a>
 <a id="update-or-stop-using-aimship"></a>

package/docs/cli.md

@@ -4,12 +4,15 @@ Commands emit JSON. Errors include code/message/recovery and use a nonzero exit.
 
 ## Create and bind
 
-`bind` returns fixed CLI/core/stage paths, version and configured data root. Keep that binding for the session. Installation does not create deliveries.
+`bind` returns fixed CLI/core/stage paths, the bound version/schema, separate executing toolVersion/toolSchemaVersion, and configured data root. On a version switch, rebind through the stable launcher and read the returned fixed CLI help; a retained older executable may return stale schema metadata. Keep that binding for the session. Installation does not create deliveries.
+
+Default initialization must use a distinct delivery directory under the bound dataRoot; the root itself is not a delivery. The current project or supplied-material directory is not an explicit location choice. A different user-selected directory requires init input `storage: {"mode":"explicit","decisionRef":"source/location-decision.md"}` with a nonempty readable local record of that choice. The tool validates evidence access, not the truth of the decision. Do not supply dataRoot in input. No access means report the intended location and stop saving, without falling back elsewhere. Existing deliveries outside the root remain readable and recoverable.
 
 Before init, save the nonempty original input in `source/request.md`. A concrete request needs no PRD, code or known technical conditions yet. No templates are automatically created. Minimal input:
 
 ```json
 {
+  "language":"en",
   "goal": {"summary":"Export the currently filtered orders", "endpoint":null},
   "goalRef":"source/request.md",
   "documentPolicy":{"authority":null,"interaction":null,"prototypeCovered":null,"interface":null,"databases":null},
@@ -20,18 +23,18 @@ Before init, save the nonempty original input in `source/request.md`. A concrete
 }
 ```
 
-Only goal.summary is required in the input; absent endpoint defaults to null, goalRef to source/request.md, documents to [], and documentPolicy fields to null. Known facts may be supplied. Null means unknown, while false/none/[] mean explicitly not applicable. The CLI validates saved structure, not whether the user's request is concrete or authorized; the Agent must establish that before creating records.
+language and goal.summary are required in new input; absent endpoint defaults to null, goalRef to source/request.md, documents to [], and documentPolicy fields to null. Known facts may be supplied. Use `language: "zh-CN"` or `"en"`: explicit language preference takes precedence, otherwise use the delivery conversation language. This setting persists through update/render/resume and guides new formal documents; preserve original input, existing documents, filenames and machine identifiers. An explicit language update changes subsequent generated display, not existing document text. Null means unknown, while false/none/[] mean explicitly not applicable. The CLI validates saved structure, not whether the user's request is concrete or authorized; the Agent must establish that before creating records.
 
 ```sh
 node '<stable-launcher>' bind
 node '<fixed-cli>' init '<delivery-dir>' --rules-version '<bound-version>' --input '<init.json>'
 ```
 
-init uses schema 3, allocates deliveryId and revision 0, creates `.aimship/state.json`, and generates `status.md`. Add that ID to the document information at the next save point. Identity/version/timestamps, documentDigests, identityHistory, retiredIdentities and legacyRunIds are managed; never supply them in a patch. `writeResult` is return metadata, not state input. Its receipt contains actual identity, directory/state/status paths, bound version, current stage and next action; statusPath is null when view repair is needed. Verify the saved files before presenting the user receipt. Repeated init returns ALREADY_EXISTS; read/resume the same delivery and render a missing view instead of replaying creation.
+init uses schema 4, allocates deliveryId and revision 0, creates `.aimship/state.json`, and generates `status.md`. Add that ID to the document information at the next save point. Identity/version/timestamps, documentDigests are managed; never supply them in a patch. `writeResult` is return metadata, not state input. Its receipt contains actual identity, directory/state/status paths, bound version, current stage and next action; statusPath is null when view repair is needed. Verify the saved files before presenting the user receipt. Repeated init returns ALREADY_EXISTS; read/resume the same delivery and render a missing view instead of replaying creation.
 
-`documentPolicy.authority`: null while the requirement authority is undecided; authored → prd.md; adopted → scope.md; editable → an explicitly authorized existing PRD containing this commission's complete scope/authorization/endpoint. `legacy` is migration-only. `interaction`, `prototypeCovered`, `interface` (none/http/other) and target `databases` IDs record artifact conditions. They do not select a preset route. Register the first real PRD/Scope and switch goalRef in the same update; this reference-only transition does not need a fabricated goal decision. Actual goal/endpoint changes still require goal.decisionRef. Early frame/requirements/scope work can be active without the draft; done requires it. Design requires approved requirements and an agreed endpoint, but may analyze unknown technical conditions. Resolve those conditions before completing design or starting dependent contract/cases/plan/implementation. Required document approvals remain checked even when producer runs are absent; existing stage ordering and review semantics are unchanged.
+`documentPolicy.authority`: null while the requirement authority is undecided; authored → prd.md; adopted → scope.md; editable → an explicitly authorized existing PRD containing this commission's complete scope/authorization/endpoint. `interaction`, `prototypeCovered`, `interface` (none/http/other) and target `databases` IDs record artifact conditions. They do not select a preset route. Register the first real PRD/Scope and switch goalRef in the same update; this reference-only transition does not need a fabricated goal decision. Actual goal/endpoint changes still require goal.decisionRef. Early frame/requirements/scope work can be active without the draft; done requires it. Design requires approved requirements and an agreed endpoint, but may analyze unknown technical conditions. Resolve those conditions before completing design or starting dependent contract/cases/plan/implementation. Required document approvals remain checked even when producer runs are absent; existing stage ordering and review semantics are unchanged.
 
-Register documents as `{kind,path,mode,version,assetRefs?}`. List local/repository prototype images, scripts and other review-relevant assets in assetRefs so their bytes participate in the document fingerprint; the Agent must identify the complete asset set. Kinds: prd, scope, tech-design, plan, testing, review, diagnosis, handoff, change-log, prototype, contract, sql, source. New formal Markdown follows the artifact map's root filename and ordered anchors. Reused files additionally need `basisRef` recording location/version/coverage/gaps and editability; unsupported content is explicitly not checked. New HTML prototype is prototype/index.html; register other agreed formats. HTTP contracts use openapi.yaml unless reused. SQL filenames follow database count. Source files are immutable adopted versions by workflow, not OS access controls.
+Register documents as `{kind,path,mode,version,assetRefs?}`. List local/repository prototype images, scripts and other review-relevant assets in assetRefs so their bytes participate in the document fingerprint; the Agent must identify the complete asset set. Kinds: prd, scope, tech-design, plan, testing, review, diagnosis, handoff, change-log, prototype, contract, sql, source. New formal Markdown follows the artifact map's root filename and ordered ordinary Markdown headings. Reused files additionally need `basisRef` recording location/version/coverage/gaps and editability; unsupported content is explicitly not checked. New HTML prototype is prototype/index.html; register other agreed formats. HTTP contracts use openapi.yaml unless reused. SQL filenames follow database count. Source files are immutable adopted versions by workflow, not OS access controls.
 
 ## Update and inspect
 
@@ -44,17 +47,19 @@ node '<fixed-cli>' resume '<delivery-dir>' --rules-version '<bound-version>'
 
 Objects merge, arrays replace entirely; null is literal, not deletion. `--input -` accepts stdin JSON. A revision conflict requires rereading and reconciling, not guessing a revision. Keep one writing session per delivery.
 
-Stage runs are ordered `{id,stage,scope,progress,inputRefs,outputRefs}`. currentRun refers to one ID or null. Progress: planned/active/blocked/done; result: passed/failed/not-run/unknown/mixed; applicability: current/needs-review/unknown. Done requires a precise resultRef. Preserve past results in priorResultRef/historyResultRefs; do not delete started runs. Shared files never complete two runs automatically. Plan must complete before implementation; batch review, then overall review, then independent verify remains the agent's semantic responsibility.
+Stage runs are ordered `{id,stage,scope,progress,inputRefs,outputRefs}`. currentRun refers to one ID or null. Progress: planned/active/blocked/done; result: passed/failed/not-run/unknown/mixed; applicability: current/needs-review/unknown. Done requires a precise resultRef. Preserve past results in priorResultRef/historyResultRefs; do not delete started runs. Shared files never complete two runs automatically. Plan must complete before implementation. For standard delivery, review requires completed implementation coverage, verify requires a passing overall review with resolved preceding reviews, and handoff requires passing verification (or a passing rerun retaining earlier results). These required predecessors cannot be removed by empty dependsOn/inputRefs. Actual execution, coverage quality and approval authenticity still require Agent judgment.
+
+New Markdown uses the ordinary headings in the artifact map and searchable business IDs. Checks reject missing or duplicate definitions and unresolved ID references. Results use section keys or unique record IDs as search locators; no HTML anchors, embedded definition metadata, item versions or hidden traceability index are required. These structural checks do not establish semantic completeness.
 
-New Markdown uses explicit `<a id="..."></a>` anchors. Definition metadata in the document supplies namespace/ID/version/status/refs; see document-patterns. REV and RUN additionally set `run` to the stageRun ID and use a result anchor such as `review.md#rev-001-v1` or `testing.md#run-001-v1`. Basic uniqueness, exact reference resolution, REQ→AC, AC→TC and RUN→TC versions are checked; prose truth, every-assertion coverage and object versions require Agent review. `nextIds` reports historical maxima plus one, including retired IDs. Keep historical definitions; retired identities cannot be reused.
+Bare IDs resolve against current local definitions, including readable IDs in an explicitly registered editable Markdown requirement authority. File-qualified Markdown record citations check the actual source file and a unique substantive record; missing, duplicate or unreadable sources fail. Reused documents retain their outline and separately reported unchecked content. B/TASK/TC definitions belong in batch/task/case design sections; execution sections may cite those IDs without defining new obligations. Delivery `language` is required for all current states.
 
 References stay delivery-root-relative despite state being internal, or use `repo:<id>/<path>` / HTTP(S). Repository records `{id,path,role}` name actual absolute checkout/worktree roots. A branch is not a code version. Paths cannot escape roots through traversal or symlinks. check defaults to current inputs; --all adds registered history/decisions/outcomes. Exact fragments in registered new Markdown are checked; reused/remote/unsupported ones return not-checked. That does not establish semantics or passing verification.
 
-Read/check/resume are read-only. They return view diagnostics and changed registered documents; matching revisions do not prove unchanged formal content. Resume canProceed is conservative structural readiness, never authorization or acceptance. Read returns conflicting layout candidates and unknown formats without rewriting them. `scan <material-root>` reads immediate delivery children in both layouts, deduplicates deliveryId and reports conflicting/unknown/inaccessible records. It neither scans unknown roots nor determines code-writing safety; inspect recorded roles/scopes and actual Git/worktree identity.
+Read/check/resume are read-only. They return view diagnostics and changed registered documents; matching revisions do not prove unchanged formal content. Resume canProceed is conservative structural readiness, never authorization or acceptance. `scan <material-root>` reads immediate delivery children using .aimship/state.json, deduplicates deliveryId and reports conflicting/unknown/inaccessible records. It neither scans unknown roots nor determines code-writing safety; inspect recorded roles/scopes and actual Git/worktree identity.
 
 ## State and view recovery
 
-State writes are atomic per file and keep `.aimship/state.previous.json`. Across formal documents/state/status there is no transaction. First persist unfinished intent, edit and inspect documents, then save state. Managed document digests detect some external changes, never semantic equivalence.
+State writes are atomic per file and keep `.aimship/state.previous.json`. Across formal documents/state/status there is no transaction. First persist unfinished intent, edit and inspect documents, then save state. Managed document digests detect some external changes, never semantic equivalence. A changed source/request.md cannot be rebaselined by an unrelated update. Restore the preserved original before continuing; record actual requirement changes in the editable authority/change log, retaining the original input.
 
 A write returns the actual state revision and `writeResult: {stateSaved:true,revision,view}`. If view status is protected/error, the JSON is already saved. Do not replay the business patch; explicitly repair:
 
@@ -67,34 +72,24 @@ The delivery identity, view digest and state revision are stored in `.aimship/vi
 
 `recover <dir> --revision <backup-revision> --rules-version <bound-version>` restores only over missing/corrupt state, preserves corrupt bytes and advances revision. It refuses a valid or unknown state. Inspect actual effects afterward, never automatically repeat them. Remove only a stale task lock after confirming no writer exists.
 
-## Explicit migration and rule adoption
-
-Schema 3 is used for new deliveries; older tools treat it as unknown/read-only. Existing schema 2 continues without automatic conversion, and its recorded history is preserved. Schema 1 root state remains readable; normal updates/adopt require migration first. Unknown schemas stay read-only. To migrate one selected old delivery, record a compatibility assessment and original/new artifact mapping:
+## Rule updates
 
-```sh
-node '<new-fixed-cli>' migrate '<delivery-dir>' --revision '<old-revision>' --rules-version '<new-version>' --input '<assessment.json>'
-node '<new-fixed-cli>' adopt '<delivery-dir>' --revision '<returned-revision>' --rules-version '<new-version>' --input '<assessment.json>'
-```
 
-Both inputs are `{"compatibilityRef":"change-log.md#rules-switch"}`. Migration saves original state/recovery bytes under `.aimship/legacy/`, journals checksums in `.aimship/migration.json`, converts layout/schema and increments revision while retaining old rulesVersion. Interrupted migration resumes with the original parameters only after checksum checks; conflicting copies are preserved. Adopt separately records the assessed rule change. It does not convert business meaning.
-
-Reconcile legacy documents by role, preserve original text/results/version basis, register reused files or create new forward-looking documents. Move evidence/host configuration only with mapped references and correct relative-link/workspace resolution. Never fabricate a past plan stage or tests. Unchanged completed historical execution records retain their old format, verified against the preserved migration target. Changing applicability alone does not rewrite that history. Planned or in-progress runs and any run whose execution facts change must satisfy current artifact contracts; an old ID is not an exemption. After adoption, legacy document policy still blocks stage/outcome advancement and resume readiness; reconcile documents and set the current policy first. Subsequent new runs follow the new mapping. Finished deliveries are never swept by install.
-
-A compatible old fixed tool can checkpoint only next/checkpoint facts during version mismatch, once per active version. It cannot complete stages. Save before migration, reload new rules, migrate then adopt. Old tools must not write migrated schema 2. No DeliveryArc migration is provided.
+Bind the active tool and reload its rules before work. State, session and executing tool must use the same rules version. Software installation does not authorize changing delivery state versions or inventing approvals.
 
 Goal changes need a new goal.decisionRef; prior goals/outcomes are retained. A met goal requires goalConclusionRef; acceptance needs its own acceptanceRef. Merge and deployment refs remain independent. Reopening increments cycle, appends closureRefs and resets acceptance. See the [README](../README.md#update) for software lifecycle operations and the [Guide](guide.md#hosts) for host-discovery limits.
 
 ## Document review protocol
 
-Schema 2 now includes `reviewPolicy: 1` and append-only `reviewHistory` (new deliveries default to both). Old states remain readable with `review-adoption-required`; at the recorded compatibility point enable the policy with an empty history, without inventing historical approval. Rule adoption and document approval remain separate. This additive protocol requires the current rules version; keep old tools bound to their old rules.
+Schema 4 requires `reviewPolicy: 1`, append-only `reviewHistory` and `deliveryPolicy: {version: 1}`. Document approvals remain bound to document version/content; business item numbers do not replace them.
 
-Each record has `{id, kind, document, version, digest, sourceRef, summary}`. Kinds are `self-check`, `approved`, `changes-requested`, and `editorial`. `self-check` requires `result: "passed"` or `"failed"`; only a passing self-check can support approval. `approved` additionally requires `decision: "explicit-approval"`; `editorial` requires `previousDigest`. Use unique local review-record IDs (for example `approval-1`); these are state record identifiers, not a replacement for REQ/AC/CHG. Send the complete preserved history plus new records through revision-checked `update`. Existing records cannot be edited, removed or reordered. The tool records `sourceDigest` from readable local or repo-relative evidence; keep it unchanged when sending history back. Evidence files are versioned/immutable: changed or missing evidence produces evidence-changed and does not release dependencies; preserve the original bytes and add new decisions in new evidence files. Evidence fragments use explicit anchors. A remote source must have a local preserved decision excerpt with its original locator and date.
+Each record has `{id, kind, document, version, digest, sourceRef, summary}`. Kinds are `self-check`, `approved`, `changes-requested`, and `editorial`. `self-check` requires `result: "passed"` or `"failed"`; only a passing self-check can support approval. `approved` additionally requires `decision: "explicit-approval"`; `editorial` requires `previousDigest`. Use unique local review-record IDs (for example `approval-1`); these are state record identifiers, not a replacement for REQ/AC/CHG. Send the complete preserved history plus new records through revision-checked `update`. Existing records cannot be edited, removed or reordered. The tool records `sourceDigest` from readable local or repo-relative evidence; keep it unchanged when sending history back. Evidence files are versioned/immutable: changed or missing evidence produces evidence-changed and does not release dependencies; preserve the original bytes and add new decisions in new evidence files. Evidence fragments locate unique ordinary headings or numbered records, not HTML anchors. A remote source must have a local preserved decision excerpt with its original locator and date.
 
 `read`, `check`, and `resume` return `review.documents` with current `path`, `version`, `digest`, `selfCheck`, `approval` and status. First append a self-check of those exact bytes; after presenting the document and receiving explicit approval, append an approved record binding the same version/digest and the actual user message. Questions, silence, and “show the result” cannot be recorded as approval. A hash/source reference validates the record's content basis, **not user identity or authenticity**. Never synthesize a real approval to make an update pass.
 
 Production `progress: done` may be saved while approval is pending. Starting/completing dependent runs is blocked until prerequisite completion and document approval are current. Runs default to depending on their predecessor; explicit `dependsOn: [preceding-run-ids]` supports recorded independent branches, while input/output producers and earlier selected development prerequisites also apply. The initial applicable development order is requirements/Scope, technical design, interface/SQL, test-design, plan, implement. Unselected stages are not created. Contract can produce only SQL when no interface change applies; technical design no longer requires SQL files before completion.
 
-For new `plan.md` and `testing.md`, fingerprints cover the content before the fixed `execution` and `runs` anchors respectively. Append implementation and RUN/conclusion evidence after those boundaries. Reused formats and other documents use whole-file content; remote/binary or linked-asset semantic inspection still belongs to the host/Agent. `done`, matching hashes and structural checks do not prove semantic quality.
+For new `plan.md` and `testing.md`, fingerprints cover the content before the ordinary headings mapped to `execution` and `runs` respectively. Append implementation and RUN/conclusion evidence after those boundaries. Reused formats and other documents use whole-file content; remote/binary or linked-asset semantic inspection still belongs to the host/Agent. `done`, matching hashes and structural checks do not prove semantic quality.
 
 A material change needs an open CHG with impact/decision evidence, a revised document version, a new self-check and explicit reapproval. Old review records remain. Affected producer/dependent runs become `needs-review`; update currentRun/next to the re-review stop and restore applicability after evidence-backed rechecking in dependency order. Independent branches are preserved. An `editorial` record carries a prior approval only after a same-version self-check explains a formatting/typo change and references its previous digest; it is not a new user approval. Do not hide changed design in excluded result sections. Final `outcome.acceptance` stays independent.
 
@@ -106,10 +101,13 @@ New state defaults to `deliveryPolicy: {version: 1}`. The standard main sequence
 
 An explicit limited-scope decision (including no cases and testing) is referenced by `deliveryPolicy.partialRef` in existing PRD/Scope/change material. Such a scope may reach `outcome.goal: met` and have a real acceptance decision, but derived `completion.status` remains `partial-scope`, never `standard-complete`. Adding/changing/removing this basis needs a new goal.decisionRef, preserving goal history; set partialRef to null to restore standard scope. Standard goal completion checks recorded stages/approvals, passing batch and overall review, passing independent verification, handoff and resolvable evidence; standard-complete additionally requires recorded acceptance. These checks cannot prove actual execution or semantic quality. Failed or omitted checks must never be labeled passed.
 
+Independent review, verify-only work or limited handoff can omit standard upstream work only with a nonempty readable local partialRef (including a resolvable ordinary heading or record if supplied). The tool checks the evidence reference, not whether a user actually authorized its contents. Declared dependencies and applicable document approvals remain in force. Planned future work and draft materials may be saved before entry conditions are met; active/done transitions are checked. Existing records remain readable and report unresolved entry conditions rather than automatically acquiring a scope exception.
+
 Reviews identify their actual implementation coverage with `reviewOf: [implementationRunId, ...]`; overall review has `overall: true`. For a single batch one review may explicitly cover both. An unresolved failed review prevents standard completion even if an earlier overall review passed. A passing repair review or retest may list the superseded review/RUN result references in its existing `historyResultRefs`, preserving old failures; the Agent must verify that it actually resolves or covers them on current objects. Verification must follow the applicable overall review. Merely setting a link is not semantic evidence.
 
 `run.sessionGroup` is an advisory group ID persisted when a new policy-enabled run is saved: requirements; technical/contract/prototype; cases; plan; each implementation batch with its batch review; overall review; each verify batch. Adjusting groups does not change document approval, add a stage, or block work. `read/check/resume` expose `session.action`, groups and a concise continuation entry; pending review and unconfirmed saves do not return a next-stage entry. `writeResult.session` becomes reconcile-save with no entry if view saving fails, even when stateSaved is true. Repair at the returned revision; do not repeat the approval update. At a confirmed saved group boundary, the Agent suggests a new session without executing the next group in that response. A user request to continue here proceeds with the normal authorized update.
 
 `read` and `resume` accept optional `--delivery-id <known-id>` to reject a wrong directory binding. A directory remains required; no implicit latest-delivery lookup exists. Resume is read-only and inspects actual state, approval/content versions, references and view diagnostics; old prompts grant no approval. The Agent must additionally inspect relevant complete formal documents, actual artifacts and unfinished effects before acting.
 
-Old states without deliveryPolicy stay valid and report `historical-unassessed`; existing goal/acceptance is not rewritten. After active-rule adoption if needed, explicitly update deliveryPolicy together with a readable `compatibilityRef` assessing scope and evidence, without inventing old approvals or runs. A preserved historical met value is not automatically a new standard-complete claim. Reconcile gaps before claiming new completion; explicit limited scope remains distinguishable. Unknown future delivery policies are read-only and cannot be recovered over.
+
+Review run `ready` describes a completed, current record; `releaseReady` additionally requires a usable passing review before releasing dependent work. Failed review records remain saved. A later passing repair review must preserve the old result reference and cover the affected implementation scope; unrelated passing reviews do not clear the failure. Session suggestions distinguish exhausting registered work from completing the agreed goal: an unfinished goal with no next run requires arranging the next authorized work, not declaring finished.