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

package/skills/aimship/references/artifact-map.json

@@ -11,7 +11,27 @@
         "states",
         "acceptance",
         "arrangement"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Document information and sources",
+          "Background, goals and non-goals",
+          "Scope, engineering objects and endpoint",
+          "Requirements and behavior",
+          "States, interaction and recovery",
+          "Acceptance criteria",
+          "Dependencies, questions and stage arrangement"
+        ],
+        "zh-CN": [
+          "文档信息与来源",
+          "背景、目标与非目标",
+          "范围与交付终点",
+          "需求与行为",
+          "状态、交互与恢复",
+          "验收标准",
+          "依赖、待确认问题与阶段安排"
+        ]
+      }
     },
     "scope": {
       "path": "scope.md",
@@ -23,7 +43,27 @@
         "decisions",
         "acceptance",
         "arrangement"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Document information and source versions",
+          "Goal, engineering objects and endpoint",
+          "Source mapping and adopted scope",
+          "Exclusions and constraints",
+          "Conflicts, gaps and supplementary decisions",
+          "Acceptance basis",
+          "Authorization, questions and stage arrangement"
+        ],
+        "zh-CN": [
+          "文档信息与来源",
+          "目标与交付终点",
+          "采用范围与来源",
+          "排除范围",
+          "决定与冲突",
+          "验收标准",
+          "阶段安排"
+        ]
+      }
     },
     "tech-design": {
       "path": "tech-design.md",
@@ -35,7 +75,27 @@
         "errors",
         "risks",
         "coverage"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Basis and engineering context",
+          "Architecture and key flows",
+          "Modules and interaction implementation",
+          "Data, interfaces and SQL",
+          "Errors and nonfunctional design",
+          "Tradeoffs and risks",
+          "Requirement coverage and questions"
+        ],
+        "zh-CN": [
+          "设计依据",
+          "架构与边界",
+          "模块与职责",
+          "数据与接口",
+          "错误与恢复",
+          "风险与取舍",
+          "需求覆盖"
+        ]
+      }
     },
     "plan": {
       "path": "plan.md",
@@ -46,7 +106,25 @@
         "validation",
         "execution",
         "remaining"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Implementation basis and scope",
+          "Batches and dependencies",
+          "Tasks and completion criteria",
+          "Review and independent verification arrangement",
+          "Task status and execution records",
+          "Deviations, blockers and remaining work"
+        ],
+        "zh-CN": [
+          "计划依据",
+          "实施批次",
+          "实施任务",
+          "验证安排",
+          "执行记录",
+          "剩余工作"
+        ]
+      }
     },
     "testing": {
       "path": "testing.md",
@@ -57,7 +135,25 @@
         "coverage",
         "runs",
         "conclusion"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Basis and scope",
+          "Environment, data and execution conditions",
+          "Test cases",
+          "Coverage and verification arrangement",
+          "Execution and retest records",
+          "Defects, current conclusion and remaining work"
+        ],
+        "zh-CN": [
+          "测试依据",
+          "测试环境",
+          "测试用例",
+          "覆盖说明",
+          "执行记录",
+          "验证结论"
+        ]
+      }
     },
     "review": {
       "path": "review.md",
@@ -65,7 +161,19 @@
         "basis",
         "reviews",
         "conclusion"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Review basis and scope",
+          "Review records",
+          "Open findings and current conclusion"
+        ],
+        "zh-CN": [
+          "审查依据",
+          "审查记录",
+          "审查结论"
+        ]
+      }
     },
     "diagnosis": {
       "path": "diagnosis.md",
@@ -77,7 +185,27 @@
         "causes",
         "unknowns",
         "conclusion"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Investigation goal and scope",
+          "Observed and expected behavior",
+          "Environment and reproduction",
+          "Checks and evidence",
+          "Cause assessment",
+          "Impact and unknowns",
+          "Conclusion and next action"
+        ],
+        "zh-CN": [
+          "调查目标",
+          "问题表现",
+          "环境与范围",
+          "证据",
+          "原因分析",
+          "待确认问题",
+          "调查结论"
+        ]
+      }
     },
     "handoff": {
       "path": "handoff.md",
@@ -88,14 +216,42 @@
         "results",
         "limits",
         "outcomes"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Current goal comparison",
+          "Artifacts, repositories and versions",
+          "Usage",
+          "Review and verification",
+          "Limitations and remaining work",
+          "Acceptance, integration, release and continuation"
+        ],
+        "zh-CN": [
+          "目标与范围",
+          "成果清单",
+          "使用说明",
+          "验证结果",
+          "限制与遗留事项",
+          "交付结论"
+        ]
+      }
     },
     "change-log": {
       "path": "change-log.md",
       "sections": [
         "changes",
         "remaining"
-      ]
+      ],
+      "headings": {
+        "en": [
+          "Important changes",
+          "Unfinished impact handling"
+        ],
+        "zh-CN": [
+          "变更记录",
+          "剩余影响"
+        ]
+      }
     }
   },
   "stages": {

package/skills/aimship/references/core.md

@@ -4,9 +4,11 @@
 
 A delivery has one centralized material directory, a preserved original request, a state record, and current requirements or adopted sources plus Scope as they are formed. The final endpoint may initially be unknown. Code stays in its existing locations. A single repository and several repositories use the same model; there is no project registration step, repository count limit, or route classification.
 
+The project workspace is the AI tool's working context, not necessarily a code repository. Initialization needs no code location or repository association. Work in that workspace and, using the tool's supported controls when needed, have the user add or grant access to the actual delivery directory in place; do not copy its documents into the workspace. Do not invent workspace membership when it is unknown or claim to add a folder automatically. The configured dataRoot remains the default, not a new Aimship folder relative to the working directory.
+
 Understand the intended result, supplied evidence, authorized changes and endpoint. Record known answers instead of asking again. Clarify only gaps that affect this work, with a recommendation and its consequence. Do not promote assumptions into user decisions. A delivery may start without a repository; a design-only commission may never need one. A short bug fix still needs its original report, context, expected behavior, scope and acceptance criteria, with a concise prd.md using the fixed outline.
 
-Use the configured material root (default `~/Aimship`), with one identifiable directory per delivery. Do not create it during installation. Before creating a new directory, use the user's explicit target or check a possible existing match; ambiguous candidates need selection, not a global “latest” pointer. If access fails, retain the request and intended location in the conversation and say what has not been saved. Continue the same delivery after access is restored.
+Use the dataRoot returned by bind (default `~/Aimship`), with a separate identifiable folder for each new delivery; the root itself is not a delivery. A project, code checkout or prototype directory describes existing materials, not a request to store the delivery there. Check possible existing matches before creating anything; ambiguous candidates need selection, not a global “latest” pointer. Only an explicit user choice changes the new delivery location. If access fails, retain the request and intended location in the conversation, report what is unsaved and resume there when access is restored; never fall back to the current workspace. Installation does not create delivery materials.
 
 Read repository instructions and existing tools for the relevant work. Record relevant pre-existing modifications and distinguish them from the delivery's changes. Do not clean a working tree, initialize Git, modify an unrelated repository, or expand write access merely to simplify the workflow.
 
@@ -16,13 +18,13 @@ Read repository instructions and existing tools for the relevant work. Record re
 This flow follows explicit Aimship activation in the first and every new session. Opening a project or merely mentioning Aimship does not activate it. A concrete problem, defect, technical objective or intended change is sufficient; a complete PRD, code, technical stack and final endpoint are not prerequisites. With only a product name or broad direction, ask a focused question about the actual problem before creating records; do not invent features or a full product scope.
 
 1. Preserve the user's relevant wording, sources, constraints and visible discussion. Distinguish user decisions, reported facts, Agent suggestions and unknowns. Do not re-ask known answers or treat discussion as approval. Before write access exists, keep this in the conversation and say it is not saved. If a session switch is necessary before saving, provide copyable context with the intended path, original input and pending operation; it is not a new approval.
-2. Bind the actual tool/core version and use the configured dataRoot or the user's location. Inspect the explicit target or known candidates for an existing delivery, partial creation or conflicting material. Read and resume existing state, checking deliveryId when known. Do not guess a global latest delivery, create a replacement, overwrite sources, or infer ownership from a matching name. Ask only when identity/location is unresolved.
-3. Reuse the current accessible workspace. If access is missing, follow [host access](hosts.md) with the exact required materials path; the user prepares the project/access. If the target does not exist, use its accessible existing parent or explain which directory the user must create/open. No silent fallback into code, unrelated probes or global settings changes. Workspace names and “I added it” are not proof; normal reads and actual saves establish this session's access only.
-4. Save the original input in source/request.md without replacing existing material. Reuse existing CLI init to create state and its generated status.md. Before PRD/Scope exists, use goalRef source/request.md, empty documents and null for unknown endpoint and documentPolicy conditions/authority (schema 3). A requirements/frame/scope run can be active without a draft; a done result still requires its formal artifact. Do not create empty templates or mark unknown conditions false/none/[] to pass init. Use next for the concrete pending questions/work; no parallel initialization ledger.
-5. Inspect stateSaved, revision and view from the actual result. Read back the saved state and status entry before reporting complete initialization. If the view failed, preserve the ID/revision and repair it with render; do not init again. If the response was lost, read before retrying. Source-only partial creation resumes at the same intended location after checking its ownership; stale locks require confirming the writer stopped. Unknown formats remain read-only.
-6. Give a concise receipt: initialized / resumed / incomplete, recognizable delivery, actual absolute directory and readable status link (only when available), saved materials, bound version, code association and checked access, current stage/work and next action. A repository registration alone does not prove access. Do not claim original initialization facts for an old delivery. Then continue authorized requirement clarification, unless the user requested a stop.
+2. Bind the actual tool/core version and keep its returned dataRoot. Inspect the intended delivery folder or known candidates for existing state, partial creation or conflicting material. Read and resume existing state, checking deliveryId when known, including older deliveries outside today’s configured root. For a new location explicitly chosen by the user, preserve that actual decision in a nonempty local file within the delivery and supply `storage: {mode: "explicit", decisionRef: "<delivery-relative file>"}` to init; the reference is a file path without a fragment. Never invent the decision or override the tool’s dataRoot to make a path pass. Otherwise use a separate folder under the bound dataRoot. Ask only when identity/location is unresolved; do not create a replacement or infer ownership from a matching name.
+3. Reuse the current workspace’s access to the intended materials path without changing that path. If access is missing, follow [AI tool access](hosts.md) with the exact required path; the user adds the original directory or grants the needed access. If the target does not exist, use its accessible existing parent to create it as part of saving this delivery, or explain which directory the user must create/open. No silent fallback into the workspace, unrelated probe files or global settings changes. Workspace names and “I added it” are not proof: normal reads establish read access only; actual saves establish write access for that operation. Do not report saved work before the result confirms it.
+4. Save the original input in source/request.md without replacing existing material. Set `language` to `zh-CN` or `en`: an explicit user preference takes precedence, otherwise use the language of this conversation. The Agent saves this delivery setting in init; it is not an installation setting or a command the user must learn. Use init to create state and its generated status.md. Before PRD/Scope exists, use goalRef source/request.md, empty documents and null for unknown endpoint and documentPolicy conditions/authority (schema 4). A requirements/frame/scope run can be active without a draft; a done result still requires its formal artifact. Do not create empty templates or mark unknown conditions false/none/[] to pass init. Use next for the concrete pending questions/work; no parallel initialization ledger.
+5. Inspect stateSaved, revision and view from the actual result. Read back the saved state and status entry before reporting complete initialization. If the view failed, preserve the ID/revision and repair it with render; do not init again. If the response was lost, read before retrying. Source-only partial creation resumes at the same intended location after checking its ownership; stale locks require confirming the writer stopped.
+6. Give a concise receipt: initialized / resumed / incomplete, recognizable delivery, actual absolute directory and readable status link (only when available), saved materials, bound version, saved language, code association and checked access, current stage/work and next action. A repository registration alone does not prove access. Do not claim original initialization facts for an old delivery. Then continue authorized requirement clarification, unless the user requested a stop.
 
-Register the first substantive PRD/Scope, select its authority and change goalRef in the same update when drafting it. This reference transition alone does not alter the user's goal or require a fabricated approval; an actual endpoint/scope change still needs its decision source. Formal requirements and each subsequent selected reviewable document keep their existing self-check/explicit-approval stops. Unknown technical conditions can be investigated during design, but must be resolved before completing design or advancing work that depends on them. Omitting a stage record cannot bypass its input document approvals. Initialization/check/resume readiness permits only the recorded current work, not all future stages.
+Register the first substantive PRD/Scope, select its authority and change goalRef in the same update when drafting it. This reference transition alone does not alter the user's goal or require a fabricated approval; an actual endpoint/scope change still needs its decision source. Formal requirements and each subsequent selected reviewable document keep their existing self-check/explicit-approval stops. Write new formal headings/body and next-action text in the saved delivery language while retaining business IDs, machine keys and paths. Preserve source text and existing documents without automatic translation. Unknown technical conditions can be investigated during design, but must be resolved before completing design or advancing work that depends on them. Omitting a stage record cannot bypass its input document approvals. Initialization/check/resume readiness permits only the recorded current work, not all future stages.
 
 “Clarify requirements first” describes current work, not a requirements-only endpoint or full development permission. Use null until the actual endpoint is known, then save the real decision before dependent work. Keep known conditions when available; false/none/[] mean explicitly not applicable, not unknown. Later changes use existing impact/re-review rules.
 
@@ -36,7 +38,7 @@ Several independent deliveries may progress at the same time, each with its own
 
 Check when code scope is associated or changed, before entering implementation, or when an actual code working directory changes. Do not repeat it every turn or stage. Once the code scope is known:
 
-1. Enumerate all delivery directories in the accessible configured material root and any other explicitly known/authorized material roots or delivery locations. Use `scan <known-root>` or read both legacy `state.json` and new `.aimship/state.json` summaries; deduplicate deliveryId and report conflicting copies; do not limit the search to recent folders. Do not scan the whole disk, code trees, processes, PRDs or full histories. Do not discover unknown custom roots by searching the home directory. Report roots checked and inaccessible, invalid or unknown-format records; unseen custom roots and non-Aimship work remain outside the check.
+1. Enumerate all delivery directories in the accessible configured material root and any other explicitly known/authorized material roots or delivery locations. Use `scan <known-root>` to read `.aimship/state.json` summaries; deduplicate deliveryId and report conflicting copies; do not limit the search to recent folders. Do not scan the whole disk, code trees, processes, PRDs or full histories. Do not discover unknown custom roots by searching the home directory. Report roots checked and inaccessible, invalid or unknown-format records; unseen custom roots and non-Aimship work remain outside the check.
 2. Exclude this delivery by `deliveryId`. Compare `repositories[].path` (the actual checkout/worktree root), role, `currentRun`, relevant `stageRuns` scope/progress, `outcome`, `next` and recorded update time. Repository IDs are local to each delivery and are not global repository identity. Use already recorded repository identity; when needed and accessible, read only local Git root/common-directory metadata for the associated paths to distinguish linked worktrees. Normalize existing paths to their actual location; nested paths in one checkout are not independent isolation. Distinct independent checkouts may share a recorded repository identity even with different Git directories. If identity/location cannot be established, report it as unknown rather than assuming separation.
 3. Include older active, blocked or uncertain deliveries. A `done` stage, completed handoff, old timestamp or declined acceptance alone does not close a delivery. A recorded met goal with no recorded remaining code work is ended; otherwise use the existing explicit closing conclusion if needed. `not-met` or `unknown` is not automatically ended. Read only the relevant Scope/plan/conclusion section when state summaries cannot establish writing intent or closure. Do not rewrite another delivery's state. Ended deliveries are not active writers, although their unmerged results or known dependencies can still matter.
 4. Compare actual writing intent and locations using the table below. A stage label alone is not permission to write code. Keep one brief result in the existing Scope/plan or results section, linked from the current delivery's existing references when needed: check occasion, roots/limits, relevant delivery IDs and recorded stages, actual directories, known dependencies and chosen arrangement. State stays authoritative; do not add a registry, index, second progress ledger or service.
@@ -67,7 +69,7 @@ New deliveries use `deliveryPolicy: {version: 1}`. `outcome.goal` describes the
 
 If the user explicitly excludes cases and testing (or limits the commission to an earlier endpoint), explain the consequence once, preserve that scope decision in existing PRD/Scope/change records, and register `deliveryPolicy.partialRef`. Do not quietly add the excluded work or repeatedly persuade the user. Finish the authorized work and hand off the untested or otherwise limited result, recording omitted work and remaining limits. Its agreed scope can be met and accepted, but its completion assessment stays partial-scope, never standard-complete or verified. No special external-testing mode or extra documents are needed. Existing implementation/approval dependencies still apply. Scope changes preserve the earlier goal/decision/history; started runs are not erased to manufacture completion.
 
-States without deliveryPolicy remain historical-unassessed: preserve their outcomes, approvals and results. At a stable continuation point, read current evidence, adopt active rules if needed, then explicitly add policy with compatibilityRef and the appropriate scope basis. Do not fabricate old reviews or tests, rewrite historical met/accepted, or bulk-upgrade ended deliveries. A later assessment may show missing standard evidence while the historical scope outcome remains intact. Keep unknown future policies read-only. New completion claims require actual current evidence.
+Current completion claims require the recorded scope, approvals and actual results. Saved business history does not replace current evidence.
 
 ## Stage references
 
@@ -95,9 +97,11 @@ Each run records its scope, required inputs, results and progress. A result may
 
 For multiple batches: implement batch → review batch, repeat; after every batch is complete and reviewed, review the whole change, then independently verify within the agreed scope. For one batch, one review record may explicitly cover both batch and whole-change scopes. Do not create a complete testing gate after every batch. Planned tests can be written with implementation; writing them does not mean they passed.
 
+For standard delivery, registering review/verify/handoff as active or done requires their actual predecessors even when dependsOn or inputRefs are empty: review identifies completed implementation objects (an overall review covers all preceding batches), verification follows a passing overall review and resolved preceding reviews, and handoff follows passing verification or an evidenced passing rerun. Draft documents and planned work may be saved earlier. Independent review, verification or limited handoff requires the existing deliveryPolicy.partialRef to point to readable local evidence of the explicitly limited commission; an empty dependency list is not such authorization. Existing declared dependencies and document approvals still apply. These are state-tool checks, not interception of general-purpose file, test or deployment tools.
+
 Record review and verification against actual objects: repository ID, commit if any, relevant uncommitted/untracked paths and content digests or necessary patch, scope and baseline. Distinguish pre-existing changes. A branch name alone is insufficient. For documents record file/section and the content basis; preserve necessary old excerpts when a digest would not explain the reviewed meaning.
 
-Each conclusion identifies who/what produced it, date, object/version, scope, basis, result and evidence. Distinguish user review, agent review, actual execution and user-reported results. Actual verification also records commands or operations, environment/data, case version and unexecuted checks. If the object changes during testing, determine which results remain applicable and retest affected checks.
+Each conclusion identifies who/what produced it, date, object/version, scope, basis, result and evidence. Distinguish user review, agent review, actual execution and user-reported results. Actual verification also records commands or operations, environment/data, case document version and unexecuted checks. If the object changes during testing, determine which results remain applicable and retest affected checks.
 
 Execution progress (`planned`, `active`, `blocked`, `done`) is separate from pass/fail/not-run/unknown, current applicability, goal achievement and user acceptance. A finished failed verification is still failed. Review is not runtime testing. Neither the presence of a report nor successful tool exit proves the goal.
 
@@ -115,9 +119,9 @@ After explicit approval, in one handling of the message: preserve the actual dec
 
 Within the same suggested group, continue the next authorized item immediately. At a group boundary, report completed work and next work, suggest a new session and give the concise continuation entry; do not execute the next group in the same response. If the user says to continue here, do so without another approval or mandatory switch; advance currentRun to the actual work. Review or verification failures first lead to repair/re-review through the existing change flow, not mechanical advancement. At final handoff there is no pointless next-session entry.
 
-Default handoff output is current status, artifact and next suggestion, followed by one localized line using the actual absolute directory: “Use Aimship to continue delivery <actual directory>; first read the current state and relevant formal documents, then continue the recorded work.” In Chinese: “使用 Aimship 继续交付「实际目录」，先读取当前状态和相关正式文档再接续。” Do not output placeholders or long prompts at every stage. Full tasks, inputs, deliverable requirements, review stops and unresolved matters stay in existing state/formal documents/rules, not a new prompt or handoff file. A complete prompt may be generated when requested, without an arbitrary length limit.
+Default handoff output is current status, artifact and next suggestion, followed by one line in the saved delivery language using the actual absolute directory: “Use Aimship to continue delivery <actual directory>; first read the current state and relevant formal documents, then continue the recorded work.” In Chinese: “使用 Aimship 继续交付「实际目录」，先读取当前状态和相关正式文档再接续。” Do not output placeholders or long prompts at every stage. Full tasks, inputs, deliverable requirements, review stops and unresolved matters stay in existing state/formal documents/rules, not a new prompt or handoff file. A complete prompt may be generated when requested, without an arbitrary length limit.
 
-In a new session, explicitly activate Aimship and uniquely resolve the same delivery from a trustworthy path/binding; if missing or ambiguous, request the directory or candidate selection, never a global latest delivery. Read the actual statePath returned by read, verify deliveryId when known, reload fixed rules and current inputs, and inspect document approval versions, real artifacts and unfinished effects before choosing work. An old prompt or “continue next stage” is not approval. A draft remains pending across sessions. Stop the old writer before the new writer takes over. Aimship does not create sessions, use the clipboard, or launch an AI tool.
+In a new session, explicitly activate Aimship and uniquely resolve the same delivery from a trustworthy path/binding; if missing or ambiguous, request the directory or candidate selection, never a global latest delivery. Read the actual statePath returned by read, verify deliveryId when known, retain the saved language, reload fixed rules and current inputs, and inspect document approval versions, real artifacts and unfinished effects before choosing work. An old prompt or “continue next stage” is not approval. A draft remains pending across sessions. Stop the old writer before the new writer takes over. Aimship does not create sessions, use the clipboard, or launch an AI tool.
 
 End when the current confirmed goal is met. For design work this means the agreed design, not code execution. For development it includes agreed review and verification. “Show me the result” does not shorten the goal. If the user explicitly changes the endpoint, preserve the old goal, decision and unfinished work, update the arrangement, and assess the revised goal. An incomplete handoff is allowed but is not goal completion.
 
@@ -125,4 +129,4 @@ Small corrections within the original goal can reopen the same delivery: preserv
 
 ## Formal artifacts and generated status
 
-Read [document patterns](document-patterns.md) when establishing or revising the arrangement. All new formal documents use its fixed outlines and [artifact map](artifact-map.json). status.md is generated from structured state; tasks remain in plan.md. read/check/resume are read-only; inspect view and document-change warnings, and use explicit render to repair a stale/missing view. Preserve edits before rebuilding; never infer a business decision from hand-edited display text. After partial view failure use the saved revision, not a repeated business update.
+Read [document patterns](document-patterns.md) when establishing or revising the arrangement. All new formal documents use its fixed outlines and [artifact map](artifact-map.json). Schema 4 uses ordinary Markdown and searchable business numbers. Preserve the saved language; do not translate original materials. status.md is generated from structured state; tasks remain in plan.md. read/check/resume are read-only; inspect view and document-change warnings, and use explicit render to repair a stale/missing view. Preserve edits before rebuilding; never infer a business decision from hand-edited display text. After partial view failure use the saved revision, not a repeated business update.

package/skills/aimship/references/document-patterns.md

@@ -1,8 +1,8 @@
 # Delivery documents and traceability
 
-[artifact-map.json](artifact-map.json) is the shared mapping for stages, templates and checks. Use [templates](templates/prd.md) for newly authored documents; preserve section order and anchors, translate visible headings freely, and explain inapplicable sections. Templates are drafting guidance, not empty artifacts to generate for every delivery.
+[artifact-map.json](artifact-map.json) is the shared mapping for stages, templates and checks. Use [templates](templates/prd.md) for newly authored documents; preserve the ordinary section headings and their order, write visible headings and body in the saved delivery language, and explain inapplicable sections. Use the English or Chinese headings listed in the artifact map; numbered heading prefixes are optional. Keep business IDs and file paths unchanged. Original sources and existing documents are not automatically translated when the language changes. Templates are drafting guidance, not empty artifacts to generate for every delivery.
 
-One request has one directory. Formal documents are at its root. `source/request.md` preserves the original commission or source entry; other adopted versions stay in `source/` without overwriting. State, recovery copies, necessary evidence and generated host configuration belong under `.aimship/`. Generated `status.md` is the reading entry; no default INDEX, docs/sql hierarchy, AI copy, transcript or full export. A requested export is a dated object/version snapshot, never an editing authority.
+One request has one directory. New deliveries default to separate folders under the bound dataRoot; formal documents are at the delivery folder’s root, not at dataRoot or the current project merely because materials already exist there. `source/request.md` preserves the original commission or source entry; other adopted versions stay in `source/` without overwriting. Follow [source retention and editing boundaries](sources-and-changes.md#location-and-version-discipline) for originals, necessary resources and subsequent versions. State, recovery copies, necessary evidence and generated AI-tool configuration belong under `.aimship/`. Generated `status.md` is the reading entry; no default INDEX, docs/sql hierarchy, AI copy, transcript or full export. A requested export is a dated object/version snapshot, never an editing authority.
 
 ## Input and output conditions
 
@@ -16,27 +16,33 @@ Interaction changes require a prototype when existing adopted material does not
 
 Use `tech-design.md`. HTTP changes use `openapi.yaml` or the registered engineering authority; no extra contract wrapper. Non-HTTP formats are explicitly registered. Database changes require independent `database.sql` (one target) or `database-<id>.sql` per target in contract, after technical-design approval and before test cases. Technical design records the data approach and SQL plan without requiring finished SQL. SQL headers identify target/dialect/version/schema basis/conditions; ordered sections cite requirements/design. Never substitute a Markdown block or migration reference, or execute/change migration mechanisms without authorization.
 
-`diagnosis.md` belongs only to an explicitly selected independent investigation. Known-cause bugs and ordinary development debugging do not add diagnose. Major unknowns require a recorded stage adjustment; hold dependent work. Implementation defects go to implementation, design errors to design, requirement gaps to PRD/Scope, incorrect expectations to versioned cases.
+`diagnosis.md` belongs only to an explicitly selected independent investigation. Known-cause bugs and ordinary development debugging do not add diagnose. Major unknowns require a recorded stage adjustment; hold dependent work. Implementation defects go to implementation, design errors to design, requirement gaps to PRD/Scope, incorrect expectations to the testing document.
 
 ## Identities and references
 
-New local identities: REQ (type distinguishes functional, shared rule, permission, technical or quality), AC, B, TASK, TC, REV, RUN, CHG, Q, PAGE. Start at 001, increment after the historical maximum (including retired), never reuse an identity for another obligation. Shared rules, independent acceptance and single-role access/performance requirements must not disappear inside generic feature prose. Preserve external prefixes and source/version namespace. Splits/merges receive new identities and map old to new; classification changes retain identity.
+Use readable IDs for different entities: REQ for requirements, AC for acceptance, TASK/B for implementation, TC for cases, REV/RUN for review/execution records, and CHG/Q/PAGE where useful. Start each kind at 001. Keep the same obligation's ID across documents; do not give different entities the same ID. Users should be able to search an ID in ordinary Markdown. Do not require hyperlinks or any reader's HTML support.
 
-One effective definition per namespace/ID; historical versions are explicitly labeled. Keep ordinary repeated citations as references, not duplicate definitions. New local Markdown uses explicit anchors and definition metadata beside the actual table row/section:
+Define each ID once in its owning document, in a table's first column, a heading or a bullet, with substantive content: REQ/AC and optional PAGE mappings in PRD or Scope, TASK/B in plan, TC/RUN in testing, REV in review, CHG in change log. Put requirements, acceptance, batches, tasks and cases in their existing corresponding sections. The same document's coverage, summaries and execution records, as well as other documents, may cite those numbers in prose or tables without redefining them. Q records may be defined where the question is resolved. For example:
 
 ```markdown
-<a id="req-001-v1"></a>
-<!-- aimship:def {"id":"REQ-001","version":1,"status":"current","refs":["local:AC-001@1"]} -->
-REQ-001 | functional | ... actual obligation and source ...
+| ID | Requirement | Acceptance |
+| --- | --- | --- |
+| REQ-001 | Usernames must be unique; duplicates show an error. | AC-001 |
+
+| ID | Acceptance criterion |
+| --- | --- |
+| AC-001 | For REQ-001, registering an existing username leaves data unchanged and displays the duplicate-name error. |
 ```
 
-Optional `namespace` defaults to `local`; source identity may use `source-v1`. External IDs keep their original spelling (including nonnumeric forms such as `acceptance.login`); `:` and `@` are reserved reference delimiters. For an external ID without a recognized prefix, set `kind` to REQ, AC, B, TASK, TC, REV, RUN, CHG, Q or PAGE when its role is needed for coverage checks, for example `{"namespace":"source-v1","id":"acceptance.login","kind":"AC","version":1,"status":"current","refs":[]}`. Reference it as `source-v1:acceptance.login@1`; do not renumber the source. `status` is current/historical/retired. `refs` uses namespace:ID@version (no implicit latest). Put metadata at the single definition; table/Markdown citations elsewhere may repeat. Retain old TC definitions or necessary prior meaning and increment versions for semantic changes. RUN metadata cites exact TC versions; its prose binds code/build, actual command/assertion/result/evidence. Tools check metadata resolution and basic coverage; Agent checks whether it truly covers every assertion.
+A case can define TC-001 and cite AC-001; its later RUN record cites TC-001. Use a distinct REV/RUN number for each actual review/execution and retain failed records. State identifies which implementation a review covers; ordinary record text identifies tested code, commands, results and evidence. Document versions and content-bound approval remain required; there is no per-item version/namespace/retirement protocol.
+
+Bare IDs refer to the current local authority. To cite an external number, use that ID as the visible label of a link to its Markdown source file; the reader opens the file and searches the number. A file-qualified record locator is also checked without requiring a working browser anchor. The file must be readable and the numbered record unique and substantive; a path alone is not proof. An explicitly registered editable Markdown PRD may supply readable REQ/AC definitions without being copied or forced into this outline; unparsed source content remains unchecked. Preserve originals and source-retention boundaries.
 
-REQ/source → AC → design/operation/SQL, TASK → actual repository object → REV, and AC → TC@version → RUN@object. Relationships live in those documents, not a trace.md or a second state matrix. Q is defined once in the discovering document with impact/needed decision/status/source; resolving it also updates the affected formal authority, linked to one CHG if meaning changes. Old review/test facts remain; only affected current applicability becomes needs-review.
+Do not insert HTML anchor tags, machine JSON comments, an index, sidecar or traceability matrix. Do not automatically renumber unchanged requirements. Keep external source IDs in their original material; describe adopted obligations and their source correspondence in the ordinary Scope. Basic checks recognize local IDs in definitions and citations, reject duplicates, missing references and empty records, and require REQ/AC, TC or TASK records when completing their respective work or recording a passing document self-check. Define B records in the batch section, TASK records in the task section and TC records in the case section, never below the execution boundary. Execution text may cite existing batches, tasks and cases. These checks do not prove that every business obligation or test assertion is covered; the Agent and document review must check meaning.
 
 ## Saving and checking
 
-Register `documentPolicy` and `documents` per [CLI](../../../docs/cli.md). Draft at stage start; completion requires the mapped artifact and precise result anchor, not merely a filename. New Markdown anchors/metadata are machine-checkable; reused/remote/binary material needs recorded basis and explicit unchecked scope. Local references remain relative to delivery root even though JSON moved internally.
+Register `documentPolicy` and `documents` per [CLI](../../../docs/cli.md). Draft at stage start; completion requires the mapped artifact and a searchable section or result record, not merely a filename. Internal file#locator references denote a template section key, unique ordinary heading or record ID; they need not be clickable. Use file links and visible locator text when presenting results. Reused/remote/binary material needs recorded basis and explicit unchecked scope. Local references remain relative to delivery root even though JSON moved internally.
 
 Save unfinished intent, update formal documents, inspect them, then revision-check state. A matching status revision does not prove documents unchanged. Read/check/resume diagnose only. A saved state with a failed view must be repaired using render at the returned revision, never replayed. Preserve hand-edited status before rebuilding and interpret intent against existing authority; it cannot confer acceptance or publishing permission.
 

package/skills/aimship/references/document-review.md

@@ -15,7 +15,7 @@ Do not ask human approval for every execution log, batch review or test result.
 
 New state has `reviewPolicy: 1` and append-only `reviewHistory`. Use the [CLI review protocol](../../../docs/cli.md#document-review-protocol) for exact fields. `read`, `check` and `resume` return current fingerprints and review status; state tools check records and dependencies, not user identity or authenticity. Preserve a concise, faithful decision excerpt with original conversation/message locator and date in a local evidence file or existing formal record. Do not label a synthetic test decision as a real user's approval. Keep decision evidence files immutable and add new decisions in new files. The source hash records submitted evidence bytes, not an authenticated signature; changed/missing evidence blocks release until reconciled.
 
-For new plan/testing templates, approval covers content before `execution`/`runs` respectively. Subsequent task execution and RUN/conclusion records belong in their later sections; moving changed design into result sections to evade review is forbidden. Other documents and reused formats use the whole registered file. For prototype assets and remotely adopted formats, preserve a readable local fixed-version review basis that identifies every relevant asset/version; report binary/remote inspection limits. Register local/repository linked assets in documents[].assetRefs to bind their bytes; the Agent must check that this set is complete. Do not claim entry-file hashing alone verifies all linked assets.
+For new plan/testing templates, approval covers content before the ordinary execution headings mapped to `execution`/`runs` respectively. Subsequent task execution and RUN/conclusion records belong in their later sections; moving changed design into result sections to evade review is forbidden. Other documents and reused formats use the whole registered file. For prototype assets and remotely adopted formats, preserve a readable local fixed-version review basis that identifies every relevant asset/version; report binary/remote inspection limits. Register local/repository linked assets in documents[].assetRefs to bind their bytes; the Agent must check that this set is complete. Do not claim entry-file hashing alone verifies all linked assets.
 
 Stage runs use the agreed array order; by default a run depends on its predecessor. `dependsOn` can state explicit preceding dependencies for independent work, and declared input/output producer links plus earlier selected development prerequisites also apply. Record the reason for changing an arrangement. A pending document holds dependent work; it does not authorize unrelated work outside the commission. `status.md` shows the current stage, pending document, review status and recorded next stage. While review is pending, chat presents only the current document/status and review focus; give the next-work suggestion after approval has been saved and checked. `resume` preserves the same stop and never automatically turns a question or old `done` into approval.
 
@@ -24,5 +24,3 @@ Stage runs use the agreed array order; by default a run depends on its predecess
 Use existing CHG records to explain semantic changes, affected requirements/documents/runs and the real decision source. Change the document version, keep old approvals and necessary old meaning/evidence, mark affected producer/dependent runs `needs-review`, and return to the corresponding document stage. An old approval cannot release new content. After renewed approval, recheck affected downstream work in dependency order and restore applicability with evidence; never clear every result or reset unaffected branches. Update `currentRun`/`next` to the actual re-review stop. Tools cannot infer all semantic dependencies: Agent impact analysis remains necessary.
 
 For a formatting/typo-only adjustment, self-check the new digest and append an `editorial` reconciliation that cites the previous approved digest and explains why meaning is unchanged. It carries the old approval without fabricating a new user decision. No full downstream re-review is needed. A changed requirement, case expectation or design choice is never editorial.
-
-Old schema 1 follows migrate then adopt; schema 2 without reviewPolicy stays readable, but does not prove historical approval. At a stable compatibility point, preserve historical runs and evidence, reconcile documents, and enable `reviewPolicy: 1, reviewHistory: []`. Review current prerequisite documents before resuming dependent work. Do not invent user approvals or rerun completed engineering work just to fill a new field; only its current applicability must be assessed. Ended deliveries are not bulk migrated.

package/skills/aimship/references/hosts.md

@@ -1,21 +1,23 @@
-# Host access
+# AI tool access
 
-Reuse the current session's access when normal file operations succeed. Do not create probe files, rescan all permissions every stage or treat a second project as permission for the current conversation. Keep the materials directory separate from repository roots and set the correct working directory for engineering commands.
+The project workspace is the AI tool's working context; it need not contain a code repository. Use the actual delivery directory in place. If needed, ask the user to add that directory to the workspace or grant access through supported controls, without copying materials. Do not claim to know folder membership or automatically add folders when the tool provides no such evidence. Code location is needed only for work that uses code, not for initialization.
 
-When access is missing, name the exact delivery/repository path and the needed operation. Retain the original request and continuation context. Do not disable host permission controls, grant the entire home directory or silently move materials into the repository.
+Reuse the current session's access when normal file operations succeed. A successful read does not prove write access; check the actual save result before reporting persistence. Do not create probe files, rescan all permissions every stage or treat a second project as permission for the current conversation. Keep the materials directory separate from repository roots and set the correct working directory for engineering commands.
+
+When access is missing, name the exact delivery/repository path and the needed operation. Retain the original request and continuation context. Do not disable AI tool permission controls, grant the entire home directory or silently move materials into the repository.
 
 - Codex: explicitly select Aimship (CLI `$aimship`). If CLI startup is needed, verify the executable/version/help and use its supported `--cd` and repeated `--add-dir` syntax for the needed writable directories. For desktop, rely on the actual current interface or official guidance; never invent a directory button or claim a prepared path has been granted access.
 - Cursor: explicitly use `/aimship`. When useful, prepare `.aimship/host/cursor.code-workspace` inside the delivery with absolute `folders[].path` entries only, referencing materials and repositories; preserve an existing workspace's settings. The user opens/adds folders when necessary. For CLI verify the exact executable (do not assume bare `agent` is Cursor) and current `--workspace` / `--add-dir` support.
 - Claude Code: explicitly use `/aimship`; verify current `/add-dir` or `--add-dir` behavior when additional access is needed. Do not fork the skill or start a subagent.
 
-Installation discovery, actual selection, model behavior, directory access and continuation are separate evidence levels. Codex/Cursor share the managed `.agents/skills/aimship` entry; Claude Code uses `.claude/skills/aimship`. A host may discover both, including when it is not registered with Aimship. Registration controls installer-managed connections, not another host’s compatibility scanning. Managed entries must point to the same stable installation; do not assume duplicate precedence or delete unrelated entries. Record duplicates as observed, and consult the published support matrix for tested surfaces.
+Installation discovery, actual selection, model behavior, directory access and continuation are separate evidence levels. Codex/Cursor share the managed `.agents/skills/aimship` entry; Claude Code uses `.claude/skills/aimship`. An AI tool may discover both, including when it is not registered with Aimship. Registration controls installer-managed connections, not another AI tool’s compatibility scanning. Managed entries must point to the same stable installation; do not assume duplicate precedence or delete unrelated entries. Record duplicates as observed, and consult the published support matrix for tested surfaces.
 
-After compaction or manual switching, reload the fixed-version core, state and current-stage inputs if missing. Do not rely on a host retaining all skill text. If even the binding location is absent, request the delivery path. Re-invoking an entry to restore context continues the existing delivery; it does not create another one.
+After compaction or manual switching, reload the fixed-version core, state and current-stage inputs if missing. Do not rely on an AI tool retaining all Skill text. If even the binding location is absent, request the delivery path. Re-invoking an entry to restore context continues the existing delivery; it does not create another one.
 
-When changing hosts, use the same delivery directory and state; do not duplicate requirements, Scope or design to establish a new session. Permissions must be granted separately in each host. Keep one writing host/session for the delivery. User-facing entry/reload and lifecycle instructions are in [the user guide](../../../docs/guide.md#hosts).
+When changing AI tools, use the same delivery directory and state; do not duplicate requirements, Scope or design to establish a new session. Permissions must be granted separately in each AI tool. Keep one writing tool/session for the delivery. User-facing entry/reload and lifecycle instructions are in [the user guide](../../../docs/guide.md#hosts).
 
-When reconciling an old Aimship-created workspace, resolve relative folders against its old file location before writing the new internal file. Verify actual checkout/worktree identity. Do not move or replace a user-owned existing workspace.
+Do not move or replace a user-owned workspace. Check the actual directory identity and access before continuing.
 
-For initialization, materials access is sufficient; code may be associated later. An existing accessible project should be reused. When a new target folder cannot yet be opened, guide the user to the existing parent or to create/open the intended folder, according to actual tool capabilities. Preserve unsaved input before any session switch. Recheck necessary access in the new session; a project name is not evidence of permissions. Follow the core's initialization receipt after the actual save.
+For initialization, materials access is sufficient; code may be associated later. Reuse an existing project’s access, not its directory as the delivery destination. Use a separate delivery folder under bind’s dataRoot unless the user explicitly selected another location. Supplying an existing prototype or opening its project is not that choice; preserve and associate the material at its actual location. When a new target folder cannot yet be opened, guide the user to the existing parent or to create/open the intended folder, according to actual tool capabilities. Preserve unsaved input before any session switch. Recheck necessary access in the new session; a project name is not evidence of permissions. If the configured location remains inaccessible, report the blocker without saving the delivery in a fallback directory. Follow the core’s initialization receipt after the actual save.
 
-For an unreleased source trial, explicitly read the checkout Skill and bind its package-root CLI. Verify releaseRoot/corePath/cliPath and schemaVersion, not just the package version: local edits may retain the published version number. Do not fall back to a cached installed Skill. Loading the source manually does not establish host automatic discovery.
+For an unreleased source trial, explicitly read the checkout Skill and bind its package-root CLI. Verify releaseRoot/corePath/cliPath and the returned fixed CLI’s help/schema, not just the package version: local edits may retain the published version number. Do not fall back to a cached installed Skill. Loading the source manually does not establish AI-tool automatic discovery.

package/skills/aimship/references/recovery.md

@@ -6,32 +6,28 @@ A revision conflict means another writer or manual change intervened. Read and r
 
 A path move requires the provided new location and identity evidence, not a disk-wide name search. Keep IDs stable. Repair references after checking the relevant repository/delivery; do not move or copy code. Preserve manual document edits and assess their intent and downstream impact before updating state.
 
-A tool/version mismatch stops new stage advancement. Save only in-progress facts through the documented limited checkpoint if safe; it cannot finish a stage or declare a goal met. At a stable boundary read the current complete installation's core, current stage and state, handle any compatibility needs, then explicitly adopt the current rules version. Keep the same goal, decisions and history. If the old context cannot reliably refresh, give the manual continuation prompt; do not open a new conversation automatically.
+A tool/version mismatch stops new stage advancement. Run bind through the stable installation launcher and read the returned fixed-version core and CLI help. Use that bound tool and protocol, not cached metadata from another executable. Preserve unfinished work and actual decisions; do not change state versions by hand or invent approvals. If the conversation cannot reliably refresh, provide a manual continuation prompt; do not open a new conversation automatically.
 
-Unknown newer formats remain readable as files but must not be overwritten or silently downgraded. Structural migrations require a supported conversion, necessary backup, clear description and validation. If no migration exists, preserve the materials and state the gap; do not invent historical stages. Compatible rules updates do not require new goal approval. Never sweep ended deliveries during install; only assess an ended delivery when it is reopened.
 
-Installation and data are separate. Explicit install manages product-owned files and host entries. Preserve user customizations and unrelated same-name skills; report the exact conflict. Uninstall retains delivery materials, customization and necessary configuration. Recovery retains a bounded previous installation, not every runtime forever. Consult the CLI help for implemented operations; do not bypass checks with raw state edits to obtain a success result.
+Installation and data are separate. Explicit install manages product-owned files and AI-tool entries. Preserve user customizations and unrelated same-name skills; report the exact conflict. Uninstall retains delivery materials, customization and necessary configuration. Recovery retains a bounded previous installation, not every runtime forever. Consult the CLI help for implemented operations; do not bypass checks with raw state edits to obtain a success result.
 
-## Schema 1 to schema 2
+## State and view recovery
 
-Read reports the actual statePath and layout. Use migrate on one explicitly selected delivery, with the old revision and a compatibilityRef; then adopt active rules at the returned revision. The migration journal and byte-preserved source copies stay under .aimship. A pending journal requires the original migrate parameters, not a normal update. Conflicting dual layouts and unknown schemas never accept normal writes.
-
-Migration converts state layout/schema only. Reconcile legacy requirements/design/implementation/test-plan/verification by their actual role, retaining original text and versioned results. Register legacy files as reused with a compatibility basis; create missing new plan/testing content for future work without inventing historical stages. Move necessary evidence and Aimship-created host files only with a concrete mapping, rewrite report links, and resolve workspace relative folders from the old location. Ordinary business source is never overwritten.
 
 State is authoritative for stages; status is generated. JSON may have saved while view generation failed: use returned revision and render, never repeat update. Read/check/resume never repair implicitly. Inspect changed registered documents even when view revision matches. render --preserve-edits retains a modified status before replacing it; interpret intent and update the formal authority separately.
 
-Follow [document review](document-review.md) for saved review stops, approval history, exact content versions, affected dependency re-review and old-state compatibility. Read/resume never infer approval from done or create a new user decision.
+Follow [document review](document-review.md) for saved review stops, approval history, exact content versions, affected dependency re-review and current document checks. Read/resume never infer approval from done or create a new user decision.
 
-## Session boundary and completion compatibility
+## Session boundary and completion
 
 Use the core’s session interaction. Locate the actual delivery before reading; an explicit path or trustworthy unique binding is necessary. Check deliveryId when supplied, current approval fingerprints, current inputs and unfinished side effects; never treat an old continuation prompt as authority. Pending review remains pending. A session suggestion is not a blocker; a request to continue here uses the same saved work without a new approval. No automatic sessions or clipboard actions.
 
-Older state without deliveryPolicy is historical-unassessed, not invalid. Preserve met/accepted and old evidence. Adopt active rules and explicitly add deliveryPolicy with compatibilityRef after a real scope/evidence assessment; partialRef records an actual limited commission. No inferred historical approvals, no bulk migration. Standard completion remains separately assessed. Unknown newer delivery policies are read-only.
+Current deliveries require the document approval and delivery policies. Their recorded outcomes, actual decisions and execution history remain separate from ordinary business numbering.
 
-## Early initialization and schema 3
+## Early initialization and schema 4
 
-New initialization may have only source/request.md, .aimship/state.json and status.md; technical conditions and endpoint may be null. Missing PRD/Scope at this point is normal. Read/check/resume use the same early-state rules; do not fill placeholders or infer non-applicability to clear warnings. Register the real draft when formed and retain the existing approval stops.
+New initialization saves the selected language and location basis and may have only source/request.md, .aimship/state.json and status.md; technical conditions and endpoint may be null. Missing PRD/Scope at this point is normal. Read/check/resume use the same early-state rules; do not fill placeholders or infer non-applicability to clear warnings. Register the real draft when formed and retain the existing approval stops.
 
 If source exists but state does not, inspect the original input and ownership before completing init at that location. If state exists, resume its ID instead; init deliberately rejects duplicates. A failed view or interrupted receipt never requires a second init. Inspect state then repair only the view at the saved revision, preserving manual status edits. Do not remove locks without checking that the writer stopped.
 
-Schema 1 retains the existing explicit migration to schema 2. Schema 2 remains supported with its recorded conditions and history, without automatic rewriting or invented first-use facts. New deliveries use schema 3 so older tools refuse unknown semantics. Normal updates preserve the schema; no bulk conversion of old deliveries is required. Unknown future formats remain read-only.
+On resume, keep the saved language and original source/request.md. Record new intent through the formal requirements/change flow; never automatically translate or overwrite original materials.

package/skills/aimship/references/sources-and-changes.md

@@ -2,7 +2,7 @@
 
 ## Adopt without rewriting the source
 
-Preserve the original request once. For external PRDs, prototypes and images keep the original and necessary adopted version read-only. Keep referenced HTML/Markdown assets when needed to understand that version. A mutable URL alone cannot establish what was adopted. Record origin, location, version/digest, adopted sections and reading gaps. Do not claim visual understanding from text extraction or file storage.
+Preserve the original request once. If source/request.md changes after initialization, restore its original bytes before continuing state writes; an unrelated update must not adopt a new source digest. Record subsequent intent in the editable PRD/Scope and a CHG when meaning changes. If the original cannot be recovered reliably, preserve the conflicting material and report the blocker instead of replacing the recorded basis. Preserve external PRD, prototype, handover-note and image originals at their supplied locations. Retain the adopted versions as described under [location and version discipline](#location-and-version-discipline); neither storing files nor extracting text establishes visual or interaction validation.
 
 Use existing requirement IDs. If none exist, assign local IDs mapped to source sections, pages, prototype screens or short excerpts. Scope records the current goal, inclusion/exclusion, source mappings, acceptance, constraints, conflicts and adopted decisions. Do not transcribe an entire adequate PRD or create a second one merely to fit a template. Self-owned requirements may also carry Scope.
 
@@ -29,8 +29,15 @@ Formatting/typo corrections do not require semantic re-review. Implementation bu
 
 ## Location and version discipline
 
-Preserve raw adopted versions under source/, including source/request.md. Author current requirements in prd.md or adopt authoritative material through scope.md. Formal outputs remain at the delivery root. New source versions are additional records, never replacements of adopted originals. Normal business evidence belongs in .aimship/evidence/; installation diagnostics and repeated state returns belong in product-maintainer validation, not the delivery.
+The agent preserves the necessary formally adopted versions under `source/`, alongside `source/request.md`; the user need not move or manually copy originals. This is source evidence retention, not a second editable delivery or automatic synchronization.
 
-Use CHG for significant changes, stable REQ/AC and exact TC versions. Retain failed RUN and historical REV records. Q closes only after its decision also reaches the affected formal text. See document-patterns for namespaces, retired IDs, split/merge mapping and structure. An explicit full export must identify its date and object/version and remain a snapshot.
+- Retain the adopted PRD, prototype, handover notes or images, plus HTML/Markdown images, styles, scripts and other resources needed to read or operate that adopted version. Do not copy unrelated workspace files. Background material that is only consulted need not be imported as a whole.
+- In the current PRD/Scope, identify the original location, retained version/path and version or digest, adopted scope, and any missing resources or reading limits. An unpinned mutable URL is insufficient evidence. If access or tools prevent retention, report the precise gap and hold conclusions that require it; never claim the adopted set is complete.
+- Keep `source/` versions read-only as adopted evidence. Name the actual editable document or prototype before revising it. New formal requirements use `prd.md` or `scope.md`; a newly authored HTML prototype uses `prototype/index.html`. An external original is editable only when explicitly authorized; a retained source copy does not become that editable authority by default.
+- Adopt an original's new version as a separate record, assess its impact and re-review affected work. Do not overwrite the earlier adopted version or silently synchronize either direction. Preserve the origin-to-version mapping so there is one clear current basis.
 
-Follow [document review](document-review.md) for saved review stops, approval history, exact content versions, affected dependency re-review and old-state compatibility. Read/resume never infer approval from done or create a new user decision.
+The CLI checks registered paths, artifacts and review evidence; it does not import materials, discover every asset dependency or prove a snapshot is complete. Normal business evidence belongs in .aimship/evidence/; installation diagnostics and repeated state returns belong in product-maintainer validation, not the delivery.
+
+Use CHG for significant changes, stable REQ/AC/TC numbers and the actual tested document/code version. Retain failed RUN and historical REV records. Q closes only after its decision also reaches the affected formal text. See document-patterns for ordinary numbered definitions, references and structure. An explicit full export must identify its date and object/version and remain a snapshot.
+
+Follow [document review](document-review.md) for saved review stops, approval history, exact content versions, affected dependency re-review and current document checks. Read/resume never infer approval from done or create a new user decision.

package/skills/aimship/references/stages/diagnose.md

@@ -20,7 +20,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 
 ## Artifact contract
 
-Use diagnosis.md. Preserve the `conclusion` section anchor. Follow [document patterns](../document-patterns.md) and the single [artifact map](../artifact-map.json). Keep this run independent even when its document is shared. New runs need a precise result location; adopted work is not a newly executed stage.
+Use diagnosis.md. Preserve the ordinary template headings and section order. Follow [document patterns](../document-patterns.md) and the single [artifact map](../artifact-map.json). Keep this run independent even when its document is shared. New runs need a precise result location; adopted work is not a newly executed stage.
 
 Only a commissioned independent investigation produces diagnosis.md. Known-cause bugs and normal development debugging stay within their current stage. Record an arrangement change before adding a mid-delivery investigation.