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

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

@@ -0,0 +1,172 @@
+{
+  "version": 2,
+  "documents": {
+    "prd": {
+      "path": "prd.md",
+      "sections": [
+        "info",
+        "goals",
+        "scope",
+        "requirements",
+        "states",
+        "acceptance",
+        "arrangement"
+      ]
+    },
+    "scope": {
+      "path": "scope.md",
+      "sections": [
+        "info",
+        "goals",
+        "adoption",
+        "exclusions",
+        "decisions",
+        "acceptance",
+        "arrangement"
+      ]
+    },
+    "tech-design": {
+      "path": "tech-design.md",
+      "sections": [
+        "basis",
+        "architecture",
+        "modules",
+        "data",
+        "errors",
+        "risks",
+        "coverage"
+      ]
+    },
+    "plan": {
+      "path": "plan.md",
+      "sections": [
+        "basis",
+        "batches",
+        "tasks",
+        "validation",
+        "execution",
+        "remaining"
+      ]
+    },
+    "testing": {
+      "path": "testing.md",
+      "sections": [
+        "basis",
+        "environment",
+        "cases",
+        "coverage",
+        "runs",
+        "conclusion"
+      ]
+    },
+    "review": {
+      "path": "review.md",
+      "sections": [
+        "basis",
+        "reviews",
+        "conclusion"
+      ]
+    },
+    "diagnosis": {
+      "path": "diagnosis.md",
+      "sections": [
+        "goals",
+        "symptoms",
+        "environment",
+        "evidence",
+        "causes",
+        "unknowns",
+        "conclusion"
+      ]
+    },
+    "handoff": {
+      "path": "handoff.md",
+      "sections": [
+        "goals",
+        "artifacts",
+        "usage",
+        "results",
+        "limits",
+        "outcomes"
+      ]
+    },
+    "change-log": {
+      "path": "change-log.md",
+      "sections": [
+        "changes",
+        "remaining"
+      ]
+    }
+  },
+  "stages": {
+    "frame": {
+      "kind": "requirement",
+      "section": "goals"
+    },
+    "requirements": {
+      "kind": "requirement",
+      "section": "requirements",
+      "sectionByKind": {
+        "prd": "requirements",
+        "scope": "adoption"
+      },
+      "humanReview": true
+    },
+    "scope": {
+      "kind": "requirement",
+      "section": "scope",
+      "sectionByKind": {
+        "prd": "scope",
+        "scope": "goals"
+      },
+      "humanReview": true
+    },
+    "prototype": {
+      "kind": "prototype",
+      "section": null,
+      "humanReview": true
+    },
+    "diagnose": {
+      "kind": "diagnosis",
+      "section": "conclusion",
+      "humanReview": true
+    },
+    "tech-design": {
+      "kind": "tech-design",
+      "section": "coverage",
+      "humanReview": true
+    },
+    "contract": {
+      "kind": "contract",
+      "section": null,
+      "humanReview": true,
+      "additionalKind": "sql"
+    },
+    "test-design": {
+      "kind": "testing",
+      "section": "cases",
+      "humanReview": true
+    },
+    "plan": {
+      "kind": "plan",
+      "section": "tasks",
+      "humanReview": true
+    },
+    "implement": {
+      "kind": "plan",
+      "section": "execution"
+    },
+    "review": {
+      "kind": "review",
+      "section": "reviews"
+    },
+    "verify": {
+      "kind": "testing",
+      "section": "runs"
+    },
+    "handoff": {
+      "kind": "handoff",
+      "section": "outcomes"
+    }
+  }
+}

package/skills/aimship/references/core.md

@@ -4,7 +4,7 @@
 
 A delivery has one centralized material directory, a preserved original request, current requirements or adopted sources plus Scope, an endpoint, and a state record. 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.
 
-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 design-only commission may have no repository. A short bug fix still needs its original report, context, expected behavior, scope and acceptance criteria, but not a full PRD.
+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 design-only commission may have no repository. 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.
 
@@ -16,7 +16,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. Read their `state.json` summaries; 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>` 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.
 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.
@@ -33,11 +33,13 @@ Records can be stale and cannot detect all other work. Do not switch another ses
 
 ## Agree an ordered arrangement
 
-Choose stages from the responsibilities below based on the goal and existing inputs. Requirements and scope alignment are always needed; they may be one short conversation and one document. Adopt adequate existing artifacts as inputs without claiming their stages were newly executed. Do not create empty stage runs or templates.
+Choose stages from the responsibilities below based on the goal and existing inputs. Requirements and scope alignment are always needed; use the fixed PRD/Scope conditions in [document patterns](document-patterns.md). Adopt adequate existing artifacts as inputs without claiming their stages were newly executed. Do not create empty stage runs or templates.
 
 Show the selected order and endpoint. If the user already specified or accepted this arrangement, record the decision and proceed. An unanswered proposal remains a proposal. Once agreed, follow the order; adding, dropping or reordering work needs a reason and an updated record. Important changes follow [change flow](sources-and-changes.md). A stage may recur as distinct instances with stable IDs and explicit scopes.
 
-Explain each design's key decisions, why they fit the requirements, tradeoffs, artifact location and remaining questions. Ordinary internal implementation choices stay with the agent. Ask for material changes to goals, scope, external behavior, compatibility, significant cost, data handling or an explicit technical commitment. Honor an agreed human review point, without adding approvals to every document.
+Explain each design's key decisions, why they fit the requirements, tradeoffs, artifact location and remaining questions. Ordinary internal implementation choices stay with the agent. Ask for material changes to goals, scope, external behavior, compatibility, significant cost, data handling or an explicit technical commitment. Follow [document review](document-review.md): present each selected reviewable document after self-check and pause for explicit approval. An approval automatically starts the next authorized stage without a second start confirmation.
+
+Default applicable development order: PRD/Scope → technical design → interface/SQL → test cases → plan → implementation/review/verification → handoff. Adapt to the actual endpoint and existing inputs as described in [document review](document-review.md); do not force all stages into specialist commissions.
 
 ## Stage references
 
@@ -59,7 +61,7 @@ Read the reference for the current responsibility, not all thirteen on every tur
 | verify | Executing the agreed checks and recording evidence | [verify](stages/verify.md) |
 | handoff | Delivering against the current goal or handing over incomplete work | [handoff](stages/handoff.md) |
 
-Each run records its scope, required inputs, results and progress. A result may be a section in a shared document. Proceed when this run's requirements are met, the next inputs exist, authorization covers it and no relevant unresolved issue blocks it. An issue blocks only dependent work; changing the order to continue other work is still an explicit plan change.
+Each run records its scope, required inputs, results and progress. A result may be a section in a shared document. A `done` run records production completion, not human approval. Proceed when required document approvals match current content, this run's requirements are met, the next inputs exist, authorization covers it and no relevant unresolved issue blocks it. An issue blocks only dependent work; changing the order to continue other work is still an explicit plan change.
 
 ## Implementation and evidence
 
@@ -77,8 +79,12 @@ Use the installed tool's documented state protocol. Read the current revision be
 
 Important semantic changes retain historical review and test facts, mark affected conclusions for review and update the current editable authority. Do not overwrite external adopted sources. See [sources and change flow](sources-and-changes.md).
 
-At stable results save the state, remaining issues and next action. On a session switch give: “Use Aimship to continue <absolute delivery directory>; read state.json, the current goal/Scope and next-step inputs; <specific blocker if any>.” A new session reloads the same delivery, not the whole transcript. Use [recovery](recovery.md) for mismatch or uncertainty. Keep one active writing session per delivery.
+At stable results save the state, remaining issues, current review stop/pending document and next stage. Show the same facts in chat; an explicit approval releases the next authorized step without asking whether to begin again. On a session switch give: “Use Aimship to continue <absolute delivery directory>; read the actual statePath returned by read (new: .aimship/state.json), the current goal/Scope and next-step inputs; <specific blocker if any>.” A new session reloads the same delivery, not the whole transcript. Use [recovery](recovery.md) for mismatch or uncertainty. Keep one active writing session per delivery.
 
 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.
 
 Small corrections within the original goal can reopen the same delivery: preserve its previous closure and result basis, increment the cycle, and review/verify affected work. A separate goal or substantial redesign starts a related delivery; retain the defect or source relationship without introducing parent/child scheduling. Prepared, accepted, merged and deployed are independent facts.
+
+## 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.

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

@@ -1,19 +1,41 @@
-# Optional document patterns
+# Delivery documents and traceability
 
-Use only the needed sections and artifacts. These are prompts for useful content, not empty files to generate automatically. Small work may combine diagnosis, test design, review, verification and handoff in `results.md`, with distinct referenced sections.
+[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.
 
-**Requirements / Scope:** original request or adopted source; background; current goal and endpoint; included/excluded scope; authorized objects and constraints; requirements and acceptance criteria; source mapping; conflicts/decisions and open questions. Keep original input separate from revised current content.
+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.
 
-**Technical design:** current requirement basis; engineering constraints; chosen structure and alternatives/tradeoffs; interface links; data and compatibility; failure/recovery; risks and open decisions. For database changes link the independent SQL and its dialect/version, existing schema basis and execution conditions.
+## Input and output conditions
 
-**Plan:** batch ID and goal; requirement coverage; files/repositories and boundary; dependencies and interface; each batch review scope; overall review and independent verification. State tracks progress, so do not create a competing progress table.
+Author current requirements in `prd.md`, including scope. Adopt an authoritative PRD/prototype through `scope.md`, preserving source/version/original IDs and gaps. Prior authorship does not make an adopted source editable. Only explicit maintenance of an editable authoritative PRD that completely expresses this commission's scope/authorization/endpoint permits registered reuse without another PRD/Scope. Scattered ideas/screenshots/reference cases are inputs to a PRD, not automatically authoritative requirements.
 
-**Verification plan:** requirement/risk → scenario and observable expected result; environment/data/tools; normal, error, boundary and relevant regression cases; known execution gaps. Keep missing-condition cases visible.
+Interaction changes require a prototype when existing adopted material does not cover them and that work lies within the commissioned endpoint. New HTML uses `prototype/index.html`; register other agreed formats or reused entries. No interaction change means no invented prototype. Investigation/clarification-only requirements describe that commission and leave future development undefined.
 
-**Review record:** actor/source and date; exact objects/versions/differences; batch/overall/affected scope; requirements/design basis; findings, disposition and conclusion. A single-batch review explicitly covers both batch and overall responsibilities.
+`test-design` precedes the selected `plan`; both reviewable documents need explicit approval. `plan` must finish before first implementation, even one small batch. `plan.md` holds both planned TASK/B records and actual execution, distinctly; state holds stage progress. `testing.md` holds cases/coverage and appended RUN records; verification follows overall review. Verify-only may register existing cases with version/coverage, without claiming test-design occurred. Review-only does not require implementation/tests. No arbitrary small-task merging, `implementation.md`, `test-plan.md`, `verification.md`, or `results.md` for new work.
 
-**Verification record:** actor/source and date; case version; tested code/build and environment; executed commands/operations; assertions and actual results; pass/fail/not-run/unknown; evidence locations; missing conditions and recovery action. Append a retest rather than rewriting the earlier failure.
+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.
 
-**Change:** stable ID; reason and decision source; old/new meaning; affected artifacts/runs; remaining uncertainty; work completed and review/verification result. One important decision affecting several artifacts remains one record.
+`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.
 
-**Handoff:** current goal (and explicit revision if any); completed deliverables and links; how to use/check; actual review and verification scope; limitations/remaining work; goal achievement, acceptance, merge and deployment as separate facts; continuation if incomplete.
+## 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.
+
+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:
+
+```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 ...
+```
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+Preserve the fixed outlines and identity rules during [document review](document-review.md). Plan/testing design approval excludes their later execution/result sections; keep actual execution there.

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

@@ -0,0 +1,28 @@
+# Review one document, then continue
+
+The selected development order is requirements intake / PRD or Scope → technical design → interface contract and independent SQL when applicable → test cases → implementation plan → implementation with batch and overall review → independent verification → handoff and acceptance. Test design precedes planning. Keep the agreed endpoint: prototype and investigation have their own reviewable outputs; design-only stops at the commissioned design. Review-only and verify-only use their existing object/case basis without inventing implementation or uncommissioned upstream stages. Frame clarifies inputs; requirements/Scope provides the reviewed requirement authority. Do not generate empty stages or templates. When two responsibilities share the same already-approved current document, reuse that exact approval without asking twice.
+
+For requirements/Scope, prototype, independent diagnosis, technical design, each interface/SQL document, test cases and implementation plan:
+
+1. Generate or revise the concrete document, preserving its fixed outline, identities and references. Self-check its content, coverage, consistency and actual entry. Mark production complete separately from this self-check.
+2. Save the self-check record for that version/content. Give the user the document link, a short summary of decisions and unresolved questions, current review status and the next selected stage. Stop for human review. For several interface/SQL files, name and present each document individually; do not ask approval of an unspecified supporting package or introduce a scope-selection interface.
+3. An explicit user approval of the presented document is sufficient. Record the actual message/decision source and exact document version/content, then automatically begin the next authorized stage (or present the next applicable interface/SQL document). Do not ask again whether to start, and do not assess how carefully the user read it. A question, silence or “show me the results” is not approval.
+4. Answer questions while retaining the stop. For requested edits, record `changes-requested`, revise, self-check and present again. Neither `done`, an existing file, nor an Agent review substitutes for user approval. A prior explicit decision may be recorded if it really identifies this exact content; never manufacture one from general implementation permission.
+
+Do not ask human approval for every execution log, batch review or test result. Once the plan and required documents are approved, authorized implementation, Agent review, defect repairs within those requirements and retests can continue, showing results. New material decisions and production actions still need their own authorization. Final `outcome.acceptance` is a separate user decision; document approval does not accept the delivery, merge, deploy or execute SQL.
+
+## State and evidence
+
+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.
+
+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` and chat show the current stage, pending document, review status and next stage. `resume` preserves the same stop and never automatically turns a question or old `done` into approval.
+
+## Changes and old states
+
+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

@@ -5,11 +5,13 @@ Reuse the current session's access when normal file operations succeed. Do not c
 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.
 
 - 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 `host/cursor.code-workspace` inside the delivery with `folders` 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.
+- 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.
 
 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.
 
-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 installation guide](../../../docs/installation.md).
+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 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.

package/skills/aimship/references/recovery.md

@@ -11,3 +11,13 @@ A tool/version mismatch stops new stage advancement. Save only in-progress facts
 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.
+
+## Schema 1 to schema 2
+
+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.

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

@@ -26,3 +26,11 @@ Markdown/HTML are principal carriers, not a format whitelist. Images, screenshot
 4. Review affected work and execute affected verification as required by the goal, then close the same change with its result and remaining issues.
 
 Formatting/typo corrections do not require semantic re-review. Implementation bugs are fixed against the requirements; do not weaken the requirements to match the bug. Tools detect structural problems, not every semantic dependency. State uncertainty in the impact analysis rather than claiming complete automatic coverage.
+
+## 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.
+
+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.
+
+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.

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

@@ -1,4 +1,4 @@
-# Define interfaces
+# Define interfaces and independent SQL
 
 ## Basis
 
@@ -10,10 +10,18 @@ Update/reuse the authoritative HTTP OpenAPI when applicable; create a delivery-l
 
 ## Continue when
 
-The cooperating parties have an unambiguous applicable contract consistent with the current requirements/design. No relevant interface change means this responsibility need not be selected.
+The cooperating parties have an unambiguous applicable contract consistent with the current requirements/design. Select this responsibility for interface or database changes; omit it only when neither applies. SQL-only work does not invent an interface artifact.
 
 ## Decisions and blockers
 
 A breaking interface/compatibility decision needs its proper authority. Missing consumers or schemas remain stated gaps, not fabricated agreements.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use openapi.yaml or the registered authoritative contract when interfaces apply. Database changes produce independent database.sql for one target, or database-<id>.sql per target, with target/dialect/version/schema basis/conditions and ordered requirement/design references. Review each file individually after technical design approval and before test cases. Do not execute SQL or modify engineering migrations without explicit authorization. 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

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

@@ -17,3 +17,13 @@ The investigation goal is met, or the inability to determine a cause and a concr
 If the apparent small fix expands into behavior or scope changes, explain the impact before dependent implementation.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## 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.
+
+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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

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

@@ -17,3 +17,7 @@ The commissioned exploration has a clear objective and its uncertainty is visibl
 A missing business objective or incompatible expected outcomes needs a user decision; independent evidence gathering may continue.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use the selected PRD/Scope requirement entry. Preserve the `goals` section anchor (Scope uses adoption/goals as applicable). 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.

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

@@ -17,3 +17,7 @@ The report honestly matches the current commissioned endpoint. Complete the deli
 Showing results does not revise the endpoint. Required blocked verification means incomplete acceptance, even when code is ready. Small later corrections reopen with preserved closure; independent goals create related deliveries.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use handoff.md. Preserve the `outcomes` 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.

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

@@ -17,3 +17,9 @@ The planned batch is implemented and known deviations are resolved or explicitly
 Expanded external behavior, data handling or authorization needs return to the relevant decision. A rejected permission remains blocked and is not retried through another host.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use plan.md. Preserve the `execution` 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.
+
+Update TASK/B status and actual execution in the existing plan.md, preserving planned versus actual and code versions. Do not generate implementation.md.

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

@@ -2,7 +2,7 @@
 
 ## Basis
 
-Read current Scope, applicable design/contracts and relevant repository boundaries.
+Read approved current PRD/Scope, test cases/coverage, applicable design/contracts and relevant repository boundaries.
 
 ## Work and result
 
@@ -10,10 +10,18 @@ Define executable batches, each goal and requirement coverage, dependencies, aut
 
 ## Continue when
 
-Batches can be executed in order and together cover the delivery goal. Small work may keep a concise ordered arrangement in state rather than a separate plan.
+Batches can be executed in order and together cover the delivery goal. Every implementation, including a single small batch, requires a completed plan and plan.md before it begins.
 
 ## Decisions and blockers
 
 A material change in scope/endpoint needs a decision; routine task splitting does not. Record the reason if changing the existing order.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use plan.md. Preserve the `tasks` 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

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

@@ -17,3 +17,11 @@ The relevant interactions and states are clear and consistent with current requi
 Missing visual/browser tools require an explicit unverified scope. Resolve contradictory behavior through requirements/Scope; do not silently alter external prototypes.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use the registered prototype entry (new HTML: prototype/index.html). 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

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

@@ -17,3 +17,11 @@ The requirements are adequate for the commissioned next work and material ambigu
 Ask for business behavior, compatibility or endpoint choices that cannot be inferred. Do not invent user acceptance.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use the selected PRD/Scope requirement entry. Preserve the `requirements` section anchor (Scope uses adoption/goals as applicable). 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

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

@@ -17,3 +17,7 @@ The agreed scope has actually been examined and issues blocking progression are
 Do not replace an agreed human review with agent review. Review cannot be reported as a running test; unrelated work need not be re-reviewed.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use review.md. Preserve the `reviews` 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.

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

@@ -17,3 +17,11 @@ The goal, authority and scope are clear enough for the selected next work, with
 Material conflicting sources or uncertain authority needs clarification; format differences alone do not. Never choose source priority by filename or date.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use the selected PRD/Scope requirement entry. Preserve the `scope` section anchor (Scope uses adoption/goals as applicable). 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

package/skills/aimship/references/stages/tech-design.md

@@ -6,7 +6,7 @@ Read current requirements/Scope, relevant engineering instructions, architecture
 
 ## Work and result
 
-Choose an approach with concrete components, dependencies, errors/recovery, compatibility and tradeoffs. Link authoritative contracts instead of duplicating them. For database changes create separate delivery-local SQL and explain dialect/version, existing schema basis, conditions and sequence. Do not edit migration files or execute SQL without that commission.
+Choose an approach with concrete components, dependencies, errors/recovery, compatibility and tradeoffs. Link authoritative contracts instead of duplicating them. For database changes design the data change and the subsequent independent SQL deliverable; explain dialect/version, existing schema basis, conditions and sequence. Do not edit migration files or execute SQL without that commission.
 
 ## Continue when
 
@@ -17,3 +17,13 @@ The design can guide the agreed next work and correctness-affecting issues have
 Missing schema/dialect or material compatibility/data decisions block dependent design claims. An explicitly revised conceptual-design endpoint must retain these limitations.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use tech-design.md. Preserve the `coverage` 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.
+
+Technical design does not require finished SQL before its review. After its approval, contract produces and presents database.sql for one target, or database-<id>.sql per independent target. No SQL for no database change.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.

package/skills/aimship/references/stages/test-design.md

@@ -10,10 +10,18 @@ Map each goal/risk to observable checks: normal behavior, relevant errors/bounda
 
 ## Continue when
 
-The goal and material risks have appropriate checks and missing execution conditions are explicit. Simple checklists may share a later report.
+The goal and material risks have appropriate checks and missing execution conditions are explicit. Complete and obtain approval of cases/coverage before the selected plan stage. Write them in testing.md; execution remains explicitly not run until verify.
 
 ## Decisions and blockers
 
 Missing tools or execution authority do not justify deleting a valid case. Clarify acceptance omissions through current requirements rather than measuring only test count.
 
 Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.
+
+## Artifact contract
+
+Use testing.md. Preserve the `cases` 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.
+
+## Human document review
+
+Apply [document review](../document-review.md): generate → self-check → present the concrete document entry, short summary and next stage → pause. Record explicit user approval of this version/content, then continue the next authorized step automatically. Questions or edit requests retain the stop; edits require self-check and re-review. Production `done` is separate from approval and final acceptance.