aimship 0.1.0-preview.8 → 0.1.0-preview.9

package/CONTRIBUTING.md

@@ -12,7 +12,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, 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 from an idea, adopting materials, changing existing code, reading results, changing requirements, continuing and completing delivery. Avoid fixed prompt examples. Keep detailed artifact, stage and identifier rules in the bilingual [document reference](docs/reference.md). 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 software delivery workflow, its value and outputs, 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 from an idea, 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 detailed artifact, stage and identifier rules in the bilingual [Guide appendix](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.
 
 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.
 
@@ -68,3 +68,17 @@ The output directory must not exist. The harness creates isolated code and deliv
 - **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.
 
 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.
+
+## Preview releases
+
+The [Publish preview workflow](.github/workflows/publish-preview.yml) is manually dispatched in `clsx/aimship`. It does not publish on push. Review and commit the versioned source, run tests and documentation/package checks, push the default branch and an exact `vX.Y.Z-preview.N` tag, then select that same tag as both the workflow ref and its `tag` input. The tagged commit must contain the workflow and matching `package.json` version. For example, with the GitHub CLI:
+
+```sh
+gh workflow run publish-preview.yml --repo clsx/aimship --ref vX.Y.Z-preview.N -f tag=vX.Y.Z-preview.N
+```
+
+Validation runs on a GitHub-hosted runner without OIDC permission. It checks the release context, runs the full tests and documentation/package checks, and packs once. Every tarball member is compared with the source. The publishing job receives that exact artifact, rechecks its source and digest, and publishes `aimship` publicly to `https://registry.npmjs.org` with the `preview` tag. It verifies the downloaded bytes, provenance and unchanged `latest` tag. Actions and runner Node/npm versions are pinned in the workflow; these CI versions are not a replacement for the package's stated runtime requirements or a claim of cross-platform validation.
+
+The npm package's trusted publisher must identify GitHub Actions, owner `clsx`, repository `aimship`, workflow filename `publish-preview.yml`, no environment, and allow direct `npm publish`. Staged publishing is not used. No long-lived npm token is stored. Only the publishing job has `id-token: write`; both jobs have `contents: read`. This is an ongoing publishing permission for that workflow, so changes to it deserve release-security review. A newly created npm trust must complete its first successful publication within npm's required window; see [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+On any uncertain publish result, inspect the registry and run logs before retrying. An existing version with different integrity stops the workflow; an identical version is verified without republishing. Missing provenance or unexpected dist-tags also stops verification rather than silently changing settings. Preserve the run URL, commit, artifact digest and registry outcome. Create the GitHub prerelease separately after successful npm verification, using the same tag and validated package; the publishing workflow has no repository write permission. Do not reuse a released version for changed package contents.

package/README.md

@@ -4,7 +4,7 @@
 
 **A software delivery workflow for AI tools, connecting requirements, design, implementation, review and verification.**
 
-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, 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.
 
 <a id="what-a-delivery-contains"></a>
 <a id="delivery-structure-and-documents"></a>
@@ -12,7 +12,7 @@ You provide the goal, existing materials and code locations. Aimship helps the a
 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 the document, a short summary and the next step, then waits for your review. Explicit approval automatically advances to the next authorized stage according to your arrangements; requested changes lead to revision, self-check and another review. Document approval remains separate from final delivery acceptance.
+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.
 
 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.
 
@@ -145,7 +145,7 @@ Full uninstall retains delivery materials, user code, custom files and necessary
 ## Documentation and contributions
 
 <a id="use-cases-and-examples"></a>
-The **[Guide](docs/guide.md)** explains how to start work, review documents, inspect results, handle changes and resume. The [document reference](docs/reference.md) covers artifact rules; [CONTRIBUTING](CONTRIBUTING.md) covers development and isolated validation; the [CLI protocol](docs/cli.md) serves agents and tool developers.
+The **[Guide](docs/guide.md)** explains how to start work, review documents, inspect results, handle changes and resume. Artifact and traceability details are also in the Guide; [CONTRIBUTING](CONTRIBUTING.md) covers development and isolated validation; the [CLI protocol](docs/cli.md) serves agents and tool developers.
 
 Aimship is in preview, with ongoing improvements to the workflow, usability and compatibility. Share problems and suggestions from actual use through [GitHub Issues](https://github.com/clsx/aimship/issues); read the contribution guide before contributing to development.
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 **面向 AI 工具的软件交付流程，贯通需求、设计、实施、审核与验证。**
 
-你提供目标、已有资料和代码位置，Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
+面向有开发基础、对一项需求交付负责的开发者。你提供目标、已有资料和代码位置，Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
 
 <a id="一个需求会留下哪些文档"></a>
 <a id="交付目录与文档"></a>
@@ -12,7 +12,7 @@
 统一的文档大纲、编号和引用，将需求与验收标准关联到设计、实施任务、审核和测试结果。文档按交付目标和实际需要生成，既提供一致的阅读与核对依据，也不要求每个阶段都填一份空模板。
 
 <a id="交付流程"></a>
-默认由你逐份审核经过 Agent 自检的文档。Agent 给出文档、短摘要和下一步，等待你审核；明确通过后，按你的安排自动衔接下一授权阶段。提出修改意见时，Agent 修订、自检后重新送审。文档通过与最终交付验收分别记录。
+默认由你逐份审核经过 Agent 自检的文档。Agent 给出当前状态、文档和审核重点，等待你审核；明确通过后保存批准，组内直接衔接，到建议会话边界提供下一步和续接入口，也可选择当前会话继续。提出修改意见时，Agent 修订、自检后重新送审。文档通过与最终交付验收分别记录；明确缩减范围的阶段性成果不会被当作标准完整交付。
 
 文档与状态在工作过程中持续保存，使进度、决定和验证依据可追溯，减少重复交代背景和重新梳理已有工作的负担。
 
@@ -145,7 +145,7 @@ npx aimship@preview uninstall
 ## 文档与贡献
 
 <a id="适用场景与示例"></a>
-**[使用指南](docs/guide.zh-CN.md)**说明如何开始需求、审核文档、查看成果、处理变更和接续。[交付文档参考](docs/reference.zh-CN.md)说明产物规则；[CONTRIBUTING](CONTRIBUTING.md)说明开发和隔离验证；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
+**[使用指南](docs/guide.zh-CN.md)**说明如何开始需求、审核文档、查看成果、处理变更和接续。产物与追溯细则也在指南中；[CONTRIBUTING](CONTRIBUTING.md)说明开发和隔离验证；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
 
 Aimship 目前处于预览阶段，流程、使用体验和兼容性仍在完善。欢迎通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈实际使用中遇到的问题和改进建议；参与开发请先阅读贡献指南。
 

package/docs/cli.md

@@ -96,3 +96,17 @@ For new `plan.md` and `testing.md`, fingerprints cover the content before the fi
 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.
 
 See the [Agent review workflow](../skills/aimship/references/document-review.md) for presentation, automatic continuation after approval and compatibility responsibilities.
+
+## Standard completeness and session suggestions
+
+New state defaults to `deliveryPolicy: {version: 1}`. The standard main sequence is requirements/acceptance, technical and applicable contract/interaction artifacts, cases, plan, implementation with batch review, overall review, verification, handoff/acceptance. Do not present stageRuns as an arbitrary menu of core stages. Preserve existing materials and inspect them before adoption; reuse does not imply approval.
+
+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.
+
+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.

package/docs/guide.md

@@ -48,19 +48,23 @@ Provide the relevant repository and feature location, expected behavior, current
 
 The agent examines the implementation, confirms requirements and technical constraints, and arranges design, implementation, review and verification. Ordinary debugging stays within the current work; a significant unknown requiring independent investigation leads to an arrangement change. `plan.md` tracks implementation, while `review.md` and `testing.md` record review and actual verification results.
 
+Preserve adopted versions of external material; a URL alone may not retain a version, and access gaps must be explicit. An existing editable PRD may be reused when you explicitly commission its maintenance and it fully states this scope, authorization and endpoint. Earlier authorship alone does not permit changing an adopted original.
+
 In all these situations, the agent preserves the original request and maintains delivery records. Important business, scope, compatibility, cost or data decisions remain yours; routine technical decisions stay within your authorization. An unanswered decision is not treated as approval, and dependent work waits for resolution.
 
 <a id="review"></a>
 <a id="review-documents-and-continue"></a>
 ## 3. Proceed and review
 
-The usual development order is PRD/Scope → technical design → interfaces and independent SQL when applicable → test cases → implementation plan → implementation/review/verification → handoff and acceptance. Prototype, investigation and design-only work keep their agreed endpoint; review-only and verify-only reuse their existing basis.
+The standard sequence is requirements and acceptance criteria → technical design with applicable interface/SQL/interaction artifacts → test cases → implementation plan → implementation batches with batch review → overall review → verification → delivery acceptance. The agent organizes this sequence without asking you to select every core stage. Unrelated artifacts are not created; existing formal material is inspected before adoption, which does not itself constitute approval.
+
+After drafting and self-checking each document that needs your review, the agent shows the current stage status, document entry and review focus. Explicitly approve it or raise questions. Discussion, silence and requests to see results are not approval; revisions are self-checked and presented again. No next-stage continuation prompt is issued while review is pending.
 
-For each document requiring your review, the agent generates and self-checks it, provides a link, a short summary and the next stage, then waits for your review. Read the document and either request changes or explicitly approve it. Requested edits are revised, self-checked and presented again. Questions, silence and asking to see results do not count as approval.
+After explicit approval, the agent records the decision and document version, saves progress and next work, checks the save result, and then suggests the next action in the same handling of your message. You need not separately confirm saving or the prompt; failed saves are reported honestly. Within a suggested session group, the next item starts directly. At a group boundary, the agent suggests a new session and provides a short entry without executing the next group in that response. Say “continue in this session” to proceed without another approval. See [session grouping suggestions](#continue).
 
-Your explicit approval is recorded against that document version and automatically starts the next authorized stage; no second start confirmation is needed. If you have explicitly arranged to continue in a new session, the agent saves a handoff first; see [session arrangements](#continue). The chat shows the current stage, pending document, review status and next stage. Document approval is separate from final delivery acceptance.
+If you explicitly exclude test cases and testing, the agent explains and records that scope once, completes the authorized development and review, and hands over an **untested partial result**. It does not quietly add excluded work or repeatedly persuade you. Finishing that scope is not standard complete delivery or a passing verification result. Document approval remains separate from final delivery acceptance.
 
-Authorized implementation, agent reviews, defect repairs and retests can proceed continuously. Each implementation batch is reviewed, followed by overall review and independent verification. New material decisions and production actions still need authorization.
+Authorized implementation, batch checks/repairs and retests can proceed. Review or test findings first lead to repairs or the existing change flow. New material decisions and production actions still need their corresponding authorization.
 
 <a id="results"></a>
 <a id="3-inspect-progress-and-results"></a>
@@ -73,7 +77,7 @@ Start with the delivery's **`status.md`** for the current stage, pending documen
 
 By default, each request has its own delivery directory under `~/Aimship/`, while code stays in its existing repositories.
 
-The tree below lists delivery artifacts and their purposes. Files are generated according to the selected stages and input conditions; unselected stages produce no empty documents. `prd.md` and `scope.md` are alternative requirement entries, not two files required for every delivery.
+The tree below lists delivery artifacts and their purposes. Files follow the agreed delivery scope and actual artifact conditions; unrelated work produces no empty documents. `prd.md` and `scope.md` are alternative requirement entries, not two files required for every delivery.
 
 ```text
 ~/Aimship/
@@ -105,7 +109,7 @@ The tree below lists delivery artifacts and their purposes. Files are generated
 
 Formal documents are directly in the request folder. `source/` preserves adopted originals; `.aimship/` holds internal records. The software itself is installed separately in `~/.aimship/`.
 
-Filenames, outlines and identifier rules come from shared templates. Requirements and acceptance criteria link to implementation tasks, reviews and versioned test cases/results. The [document reference](reference.md) explains exactly when each artifact is produced and what it contains.
+Filenames, outlines and identifier rules come from shared templates. Requirements and acceptance criteria link to implementation tasks, reviews and versioned test cases/results. The [document details](#document-details) explain when each artifact is produced and what it contains.
 
 <a id="changes"></a>
 <a id="review-verify-and-change"></a>
@@ -126,9 +130,9 @@ Meaningful changes and their impact are recorded in `change-log.md`; see `status
 <a id="6-resume-after-a-pause-or-in-another-session"></a>
 ## 6. Session arrangements and continuing work
 
-### The maintainer's session practice
+### Session grouping suggestions
 
-To manage growing context, the maintainer has used the following arrangement of separate sessions (windows):
+The following arrangement is based on experience from actual projects and can be adjusted to task size. At delivery creation or requirements confirmation, the agent records applicable suggested groups in state and shows them in `status.md`:
 
 | Work | Session arrangement |
 | --- | --- |
@@ -140,19 +144,23 @@ To manage growing context, the maintainer has used the following arrangement of
 | Overall review | One session |
 | Test execution | One session per test batch |
 
-This is practical experience, not a required split or a stage completion condition. Adjust it to the task's size, volume of materials and accumulated context. Assess any combined arrangement in actual use. Sharing a session for technical design, SQL and interfaces still requires the agreed document order: review technical design first, then each applicable interface/SQL document individually. A shared window does not bypass approval.
+This is practical experience, not a required split or a stage completion condition. Adjust it to the task's size, volume of materials and accumulated context. Assess any combined arrangement in actual use. Sharing a session for technical design, SQL and interfaces still requires the agreed document order: review technical design first, then each applicable interface/SQL document individually. A shared session does not bypass approval.
 
-Implementation batches and test batches serve different purposes. Test batches follow the verification arrangement and need not correspond one-to-one with implementation batches; this does not require testing after every implementation batch. A new window alone does not guarantee independent judgment or quality. Each new session still needs the relevant complete formal documents, saved state and actual artifacts, not just a brief chat summary.
+Implementation batches and test batches serve different purposes. Test batches follow the verification arrangement and need not correspond one-to-one with implementation batches; this does not require testing after every implementation batch. A new session alone does not guarantee independent judgment or quality. Each new session still needs the relevant complete formal documents, saved state and actual artifacts, not just a brief chat summary.
 
 ### Arrange the next session and hand off
 
-Aimship defines stages, artifacts, reviews and handoffs; it does not create new sessions. When changing windows, open a new session in your AI tool and provide the same delivery directory and handoff information.
+At a suggested boundary, the agent first confirms that approval, results and state were saved, then reports current results and next work, suggests a new session, and provides one copyable entry using the actual delivery directory:
+
+> Use Aimship to continue delivery <actual directory>; first read the current state and relevant formal documents, then continue the recorded work.
 
-If you want to change sessions after approving a document, say so with the approval, for example: “This document is approved. Save the handoff first; I will continue in a new window.” The agent records approval and your continuation arrangement without starting the next stage in the current session. For implementation or test batches, you can instead say: “Finish this batch, save the results and handoff, and leave the next batch for a new session.” This does not add human approval requirements to execution records.
+You do not need to repeat a session-switch instruction with each approval or separately confirm saving and prompt generation. Say “continue in this session” to proceed. Grouping is a context suggestion, not an approval or blocker. Final handoff has no unnecessary next-stage entry. Ask for a complete prompt when needed; the default is not a long prompt at every stage or a separate prompt/handoff file.
 
-Before ending the current session, have the agent save progress, review status, unresolved issues and the next step, and provide the full delivery directory path and relevant code locations. In the new session, select Aimship and provide the same delivery directory. The agent reads the relevant complete formal documents and state, checks actual artifacts and continues according to the saved arrangement. Ensure that a different tool can access the same materials and code.
+Aimship itself does not create sessions. After the current session confirms saving and stops writing, open a new session in your AI tool, select Aimship and paste the entry. The new session must uniquely locate the same delivery and inspect actual state, document approval versions, relevant complete formal documents, artifacts and unfinished operations before acting. A trustworthy binding avoids repeated path questions; a missing or ambiguous binding requires a directory or candidate selection, never a guessed latest delivery. Saying “continue next stage” or copying an old prompt grants no approval; a pending draft remains pending across sessions.
 
-Keep only one writing session per delivery; the old session must stop writing before the new one takes over. Pending documents still require your explicit approval, and changing windows cannot bypass review. Progress and next steps remain in the same `status.md`; you do not need to copy the entire chat.
+Keep one writing session per delivery. Code locations and access permissions must remain available; switching sessions cannot bypass reviews or affected-work stops. Progress stays in the same `status.md`, without copying the entire chat.
+
+Official CLI documentation checked on 2026-10-25 describes [`/new`](https://developers.openai.com/codex/cli/slash-commands) for Codex, [`/new-chat`](https://cursor.com/docs/cli/reference/slash-commands) for Cursor CLI, and [`/clear`](https://code.claude.com/docs/en/interactive-mode#command-history) for Claude Code to start a fresh chat/session. Check the command list of your installed CLI version; these are documentation checks, not a claim of testing each tool. They differ from simply redrawing the screen or compacting context. Save and stop the current writer first.
 
 ### Handle interruptions and version changes
 
@@ -180,6 +188,8 @@ Review artifact locations, usage instructions, review and verification conclusio
 
 The agent records goal completion, user acceptance, merge and deployment separately. Asking for a preview does not shorten the goal; if you explicitly end early, the handoff preserves the original goal and unfinished work.
 
+Standard complete delivery needs evidence for the main sequence, required document approvals, passing batch/overall reviews, independent verification and final acceptance. `status.md` distinguishes standard completeness from completion of the agreed scope and user acceptance. Tools check records; they cannot independently prove execution or semantic quality. An explicitly limited result can be finished and handed over as partial scope; untested work is labeled untested. Historical outcomes and acceptance remain intact, initially unassessed under the new standard. Inspect evidence and explicitly adopt the new rules before continuing, without inventing historical approvals or tests.
+
 Small later corrections can continue the same delivery while preserving its earlier completion record. A new goal or substantial redesign starts a related delivery.
 
 <a id="troubleshoot"></a>
@@ -200,7 +210,7 @@ For a bug report, include the tool and Aimship versions, the operation, expected
 
 <a id="artifacts"></a>
 <a id="keep-only-useful-artifacts"></a>
-See the [delivery document reference](reference.md) for generation conditions, stage outputs, outlines and identifier rules. The agent maintains these as work progresses; you do not need to learn them all before starting.
+See the [document details](#document-details) for generation conditions, stage outputs, outlines and identifier rules. The agent maintains these as work progresses; you do not need to learn them all before starting.
 
 <a id="update"></a>
 <a id="update-or-stop-using-aimship"></a>
@@ -208,3 +218,60 @@ For software upgrades, adding tools, version queries and installation health che
 
 <a id="uninstall"></a>
 For tool disconnection or full uninstallation, see the [README](../README.md#uninstall). Source development and isolated validation belong in [Contributing](../CONTRIBUTING.md).
+
+<a id="document-details"></a>
+## Appendix: document details
+
+Use the preceding sections for everyday work. This appendix covers stage outputs, SQL and traceability; file locations follow the [delivery directory](#delivery-structure).
+
+<a id="choose-the-requirement-authority"></a>
+See [starting work](#start) for source adoption. PRD and Scope are alternative requirement authorities, not duplicate documents to create by default.
+
+<a id="stage-outputs-and-content"></a>
+### Stage outputs
+
+This is an internal responsibility/file mapping for understanding artifacts, not a menu of arbitrary stages to select. See [progress and review](#review) for the standard sequence and limited scope. Sharing plan/testing does not complete stages together, and file existence 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 |
+
+<a id="sql-changes-and-progress"></a>
+### SQL and engineering versions
+
+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.
+
+<a id="fixed-outlines-and-traceable-identifiers"></a>
+### 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/guide.zh-CN.md

@@ -48,19 +48,23 @@ Agent 会核对资料是否可访问、是否覆盖本次目标。采用权威 P
 
 Agent 会检查相关实现，确认需求与技术约束，安排设计、实施、审核和验证。普通调试随当前工作处理；重大未知问题需要独立调查时，再调整安排。`plan.md` 记录实施进度，`review.md` 和 `testing.md` 分别记录审核与实际验证结果。
 
+外部材料按采用版本保留原件，链接本身未必保留版本，访问缺口应明确。只有你明确委托维护现有可编辑 PRD，且它完整表达本次范围、授权和终点时，才登记复用；不能仅凭“以前由我们编写”就修改采用的原件。
+
 以上场景都由 Agent 保留原始委托并维护交付记录。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常技术取舍由 Agent 处理。待决问题没有回应时不会被视为批准，相关依赖工作等待解决。
 
 <a id="review"></a>
 <a id="逐份审核与自动衔接"></a>
 ## 3. 推进与审核
 
-通常的开发顺序是 PRD／Scope → 技术方案 → 接口和独立 SQL（适用时）→ 测试用例 → 实施计划 → 实施／评审／验证 → 交付验收。原型、调查和仅设计委托保留约定终点；仅 review、仅 verify 使用已有依据。
+标准主线是需求和验收标准 → 技术设计及适用的接口／SQL／交互产物 → 测试用例 → 实施计划 → 分批实施（含批内 review）→ 整体 review → 测试验证 → 交付验收。Agent 根据需求落实这条主线，不要求你逐项勾选核心阶段；无关产物不生成，已有正式材料先核对采用，采用不等于批准。
+
+每份需人审文档生成、自检后，Agent 展示当前阶段状态、文档入口和审核重点，等待你明确通过或提出问题。讨论、沉默和要求看结果都不算批准；修改后自检并重新送审。待审期间不提前提供下一阶段的续接提示。
 
-每份需人审文档生成、自检后，Agent 给出文档入口、短摘要和下一阶段，等待你审核。你阅读文档后提出修改意见，或明确表示通过。有修改意见时，Agent 修改、自检后再次送审。提问、沉默和要求看结果都不算批准。
+你明确通过后，Agent 在一次处理中记录批准及文档版本、保存进度和下一步、检查保存结果，再给出下一步建议。无需分别确认保存或提示词；保存失败时会如实说明。同一建议会话组内直接衔接下一项，不再询问是否开始；到组间边界则建议新会话并给出简短入口，本轮不同时执行下一阶段。你说“在当前会话继续”即可直接继续，不增加审批，具体见[会话划分建议](#continue)。
 
-你明确通过后，批准会关联该文档版本，Agent 自动开始下一授权阶段，不再询问是否开始。如果你已明确安排换会话继续，Agent 会先保存交接信息，具体见[会话安排](#continue)。聊天中会显示当前阶段、待审文档、审核状态和下一阶段。文档批准与最终交付验收分开。
+如果你明确不要测试用例和测试，Agent 会一次说明并记录范围，完成授权的开发与 review 后交接**未测试的阶段性成果**，不会偷偷补做或反复劝说。阶段性范围完成不等于标准完整交付完成，也不能写成验证通过。文档批准与最终交付验收分别记录。
 
-授权内的实施、Agent 评审、缺陷修复和复测可连续推进。实施按批次审核，全部完成后整体审核，再独立验证。新增实质决定和生产动作仍需对应授权。
+授权内的实施、批内检查／修复和复测可继续推进；review 或测试发现问题时先修复或按既有规则回流。新增实质决定和生产动作仍需对应授权。
 
 <a id="results"></a>
 <a id="3-查看进度与成果"></a>
@@ -73,7 +77,7 @@ Agent 会检查相关实现，确认需求与技术约束，安排设计、实
 
 默认每个需求在 `~/Aimship/` 下使用独立交付目录，代码保留在原仓库。
 
-下方列出交付产物及其用途；实际生成范围由所选阶段和输入条件确定，未选阶段不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
+下方列出交付产物及其用途；实际生成范围由约定交付范围和产物条件确定，无关工作不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
 
 ```text
 ~/Aimship/
@@ -105,7 +109,7 @@ Agent 会检查相关实现，确认需求与技术约束，安排设计、实
 
 正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
 
-文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[交付文档参考](reference.zh-CN.md)进一步说明每种文档的生成条件和具体内容。
+文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[文档细则](#document-details)进一步说明每种文档的生成条件和具体内容。
 
 <a id="changes"></a>
 <a id="review-verify-and-change"></a>
@@ -126,33 +130,37 @@ Agent 会分析对范围、设计、实现和验证的影响，记录决定，
 <a id="6-暂停后或换会话继续"></a>
 ## 6. 会话安排与继续工作
 
-### 维护者的分窗口实践
+### 会话划分建议
 
-为了控制上下文不断累积带来的负担，维护者实际使用过以下会话（窗口）安排：
+以下安排基于实际项目中的使用经验，可按任务规模调整。交付初建或需求确认时，Agent 会将适用的建议分组记录在状态中，并显示在 `status.md`：
 
-| 工作内容 | 窗口安排 |
+| 工作内容 | 会话安排 |
 | --- | --- |
-| 需求／Scope | 一个窗口 |
-| 技术文档、SQL、接口文档 | 共用一个窗口 |
-| 测试用例设计 | 一个窗口 |
-| 实施计划 | 一个窗口 |
-| 实施 | 每个实施批次一个窗口，包含该批 Agent 评审 |
-| 整体 review | 一个窗口 |
-| 测试执行 | 每个测试批次一个窗口 |
+| 需求／Scope | 一个会话 |
+| 技术文档、SQL、接口文档 | 共用一个会话 |
+| 测试用例设计 | 一个会话 |
+| 实施计划 | 一个会话 |
+| 实施 | 每个实施批次一个会话，包含该批 Agent 评审 |
+| 整体 review | 一个会话 |
+| 测试执行 | 每个测试批次一个会话 |
 
-这是使用经验，不是强制分窗规则或阶段完成条件。可按任务规模、资料量和上下文累积情况调整；合并后的效果需在实际工作中核对。技术文档、SQL 和接口共用窗口时，仍按既定顺序先审技术文档，再逐份审核适用的接口／SQL 文档，不能因为共用窗口而跳过审核。
+这是使用经验，不是强制会话划分规则或阶段完成条件。可按任务规模、资料量和上下文累积情况调整；合并后的效果需在实际工作中核对。技术文档、SQL 和接口共用会话时，仍按既定顺序先审技术文档，再逐份审核适用的接口／SQL 文档，不能因为共用会话而跳过审核。
 
-实施批次与测试批次承担不同工作。测试批次按验证安排划分，不要求与实施批次一一对应，也不要求每个实施批次结束后立即测试。新窗口本身不保证判断独立或质量；每个新会话仍需读取相关的完整正式文档、已保存状态和实际成果，不能只靠简短聊天摘要接手。
+实施批次与测试批次承担不同工作。测试批次按验证安排划分，不要求与实施批次一一对应，也不要求每个实施批次结束后立即测试。新会话本身不保证判断独立或质量；每个新会话仍需读取相关的完整正式文档、已保存状态和实际成果，不能只靠简短聊天摘要接手。
 
 ### 安排新会话与交接
 
-Aimship 负责阶段、产物、审核与交接规范，本身不创建新会话。需要换窗口时，由你在所用的 AI 工具中开启新会话，再提供同一交付目录和交接信息。
+到建议会话边界，Agent 先确认批准、成果和状态已保存，再说明当前成果与下一步，建议新会话并提供一行可复制入口，其中使用真实交付目录：
+
+> 使用 Aimship 继续交付「实际目录」，先读取当前状态和相关正式文档再接续。
 
-如果希望文档通过后换窗口，在批准时一并说明，例如：“这份文档通过。先保存交接信息，我会在新窗口继续。”Agent 会记录批准和你的续接安排，不在当前会话直接开始下一阶段。实施或测试批次则可以说：“完成本批，保存结果和交接信息，下一批在新会话继续。”这不增加对执行记录的人工审批要求。
+你无需每次批准时再强调要换会话，也无需分别确认保存或生成提示词。可以直接回复“在当前会话继续”；会话划分只是上下文建议，不是审批或阻塞条件。最后交付结束时不提供无意义的下一阶段入口。需要完整提示词时可以提出，默认不逐阶段输出长提示词，也不新建提示词或交接文件。
 
-结束当前会话前，请 Agent 保存进度、审核状态、未解决问题和下一步，并给出交付目录的完整路径及相关代码位置。新会话中选择 Aimship，提供同一个交付目录；Agent 读取相关的完整正式文档和状态、核对实际成果后，按已保存的安排继续。更换 AI 工具时也要确保能访问同一份资料和代码。
+Aimship 本身不创建新会话。等当前会话确认保存并停止写入后，在 AI 工具中开启新会话，选择 Aimship 并粘贴入口。新会话必须唯一定位同一交付，核对实际状态、文档审批版本、相关完整正式文档、实际成果和未完成操作，再确定行动。已有可信绑定时不重复索要路径；没有明确绑定或有多个候选时会询问目录，不能猜“最近一个”。单说“继续下一阶段”或复制旧提示词不会形成新的批准，待审草案换会话仍然待审。
 
-同一交付只保留一个写入会话，旧会话停止写入后再由新会话接手。待审文档仍需你明确通过，换窗口不能跳过审核。进度和下一步仍从同一份 `status.md` 查看，无需复制完整聊天。
+同一交付只保留一个写入会话。代码位置和访问权限仍需可用，不能因换会话绕过审核或受影响工作的停点。进度始终从同一份 `status.md` 查看，无需复制完整聊天。
+
+截至 2026-10-25 核对的官方 CLI 文档：Codex 使用 [`/new`](https://developers.openai.com/codex/cli/slash-commands)，Cursor CLI 使用 [`/new-chat`](https://cursor.com/docs/cli/reference/slash-commands)，Claude Code 使用 [`/clear`](https://code.claude.com/docs/en/interactive-mode#command-history) 开始新的聊天／会话。以所用 CLI 版本的命令列表为准；这里是文档核对，不代表已逐一实测。这些操作不同于仅清屏或压缩上下文，使用前先保存并停止当前写入。
 
 ### 处理中断与版本变化
 
@@ -180,6 +188,8 @@ Aimship 负责阶段、产物、审核与交接规范，本身不创建新会话
 
 Agent 会分别记录目标完成、用户验收、合并和部署的实际情况。要求预览不代表缩短目标；明确提前结束时，交接中保留原目标和未完成工作。
 
+标准完整交付需要主线工作、必要文档批准、通过的批内／整体 review、独立验证及最终验收都有依据。`status.md` 将标准完整性与约定范围的完成、用户验收分别显示；工具核对记录，不能独立证明测试真实执行或内容正确。明确缩减范围的成果可完成并交接，但会显示为阶段性范围；未测试就明确写未测试。旧交付保留原完成和验收记录，先标为尚未按新标准评估，核对证据并明确采用新规则后再续接，不补造历史审批或测试。
+
 后续小修正可以继续原交付，并保留此前完成记录；新目标或大幅重新设计则建立关联的新交付。
 
 <a id="troubleshoot"></a>
@@ -200,7 +210,7 @@ Agent 会分别记录目标完成、用户验收、合并和部署的实际情
 
 <a id="artifacts"></a>
 <a id="keep-only-useful-artifacts"></a>
-文档生成条件、阶段产物、大纲与编号规则见[交付文档参考](reference.zh-CN.md)。这些规则由 Agent 随工作维护，无需在开始前逐项掌握。
+文档生成条件、阶段产物、大纲与编号规则见[文档细则](#document-details)。这些规则由 Agent 随工作维护，无需在开始前逐项掌握。
 
 <a id="update"></a>
 <a id="update-or-stop-using-aimship"></a>
@@ -208,3 +218,60 @@ Agent 会分别记录目标完成、用户验收、合并和部署的实际情
 
 <a id="uninstall"></a>
 断开 AI 工具或完整卸载见 [README](../README.zh-CN.md#uninstall)。源码开发与隔离验证见[贡献指南](../CONTRIBUTING.md)。
+
+<a id="document-details"></a>
+## 附录：文档细则
+
+日常操作见前文；本附录用于查阅阶段产物、SQL 和追溯规则。文档位置以[交付目录](#delivery-structure)为准。
+
+<a id="需求依据与输入条件"></a>
+需求采用条件见[按当前情况开始](#start)。PRD 与 Scope 是需求依据的两种选择，不默认同时编写。
+
+<a id="阶段产物与内容"></a>
+### 阶段产物
+
+下表是内部职责与文件映射，用于理解成果，不是需要用户任意勾选的流程菜单。标准顺序与阶段性范围见[推进与审核](#review)。共用 plan/testing 不代表阶段同时完成；文件存在也不等于完成。
+
+| 阶段 | 使用条件 | 产物及内容 |
+| --- | --- | --- |
+| `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`：目标、产物、使用方式、审核／验证结果、限制，以及完成／验收／集成状态 |
+
+<a id="sql变更和进度"></a>
+### SQL 与工程版本
+
+SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案通过后的 contract 阶段、测试用例之前准备并逐份审核。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
+
+已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
+
+<a id="固定大纲和可追溯编号"></a>
+### 大纲与追溯编号
+
+新文档遵循[统一模板和规则](../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/cli.mjs

@@ -16,10 +16,10 @@ const HELP = {
     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.',
+    read: 'read <dir> [--rules-version <version>] [--delivery-id <known-id>]. 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). 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.',
+    resume: 'resume <dir> [--rules-version <version>] [--delivery-id <known-id>]. 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.',
     recover: 'recover <dir> --revision <backup-revision> --rules-version <version>. Restore state.previous.json only over missing/corrupt state; preserve corrupted bytes. Inspect actual artifacts afterward; nothing reruns.',
@@ -30,6 +30,8 @@ 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.'},
+    deliveryPolicy: 'New states default to {version:1}; partialRef identifies an explicitly limited scope, null restores standard scope with a new goal decision. Legacy absence remains historical-unassessed; explicit adoption requires compatibilityRef. Completion is derived separately from goal/acceptance.',
+    sessions: 'run.sessionGroup is an advisory context group, auto-filled for new runs; reviewOf names implementation runs and overall:true identifies overall review. read/check/resume expose session/completion; writeResult.session is withheld on failed view saving. No session gate or automatic execution.',
     stages: STAGES,
     progress: ['planned', 'active', 'blocked', 'done'],
     result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
@@ -67,7 +69,7 @@ function parse(argv) {
     const item = argv[i];
     if (!item.startsWith('--')) { positional.push(item); continue; }
     const name = item.slice(2);
-    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.');
+    if (!['help', 'version', 'all', 'preserve-edits', 'input', 'rules-version', 'delivery-id', '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);
@@ -119,7 +121,7 @@ async function binding(runtime) {
 }
 function allowed(command, options) {
   const common = ['help', 'version'];
-  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: [] };
+  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', 'delivery-id', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'delivery-id', '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) {
@@ -153,9 +155,10 @@ export async function run(argv, context) {
   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);
+  if (options['delivery-id'] && options['delivery-id'] !== read.state.deliveryId) fail('DELIVERY_ID_MISMATCH','This directory is not the bound delivery.','Locate the intended delivery; do not guess the latest one.');
   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: 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 (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: read.statePath, review:read.review, completion:read.completion, session:read.session, 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);
@@ -164,9 +167,9 @@ export async function run(argv, context) {
     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);
     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' } };
+    return { command, data: { structure: 'valid', review:read.review, completion:read.completion, session:read.session, 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, 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.'] : [])] } };
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, review:read.review, completion:read.completion, session:read.session, 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: !mismatch && !missing.length && !documents.issues.length ? read.session?.continuation ?? null : null, 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.'] : [])] } };
 }