aimship 0.1.0-preview.7 → 0.1.0-preview.9

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

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "documents": {
     "prd": {
       "path": "prd.md",
@@ -109,7 +109,8 @@
       "sectionByKind": {
         "prd": "requirements",
         "scope": "adoption"
-      }
+      },
+      "humanReview": true
     },
     "scope": {
       "kind": "requirement",
@@ -117,31 +118,39 @@
       "sectionByKind": {
         "prd": "scope",
         "scope": "goals"
-      }
+      },
+      "humanReview": true
     },
     "prototype": {
       "kind": "prototype",
-      "section": null
+      "section": null,
+      "humanReview": true
     },
     "diagnose": {
       "kind": "diagnosis",
-      "section": "conclusion"
+      "section": "conclusion",
+      "humanReview": true
     },
     "tech-design": {
       "kind": "tech-design",
-      "section": "coverage"
+      "section": "coverage",
+      "humanReview": true
     },
     "contract": {
       "kind": "contract",
-      "section": null
-    },
-    "plan": {
-      "kind": "plan",
-      "section": "tasks"
+      "section": null,
+      "humanReview": true,
+      "additionalKind": "sql"
     },
     "test-design": {
       "kind": "testing",
-      "section": "cases"
+      "section": "cases",
+      "humanReview": true
+    },
+    "plan": {
+      "kind": "plan",
+      "section": "tasks",
+      "humanReview": true
     },
     "implement": {
       "kind": "plan",

package/skills/aimship/references/core.md

@@ -33,11 +33,21 @@ 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; 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.
+Use the standard delivery sequence for a developer responsible for a requirement: requirements and acceptance criteria → technical design with applicable interface/SQL/interaction artifacts → test cases → plan → implementation batches with batch review → overall review → verification → handoff and acceptance. Do not offer an arbitrary checklist of core stages or a pluggable workflow. Internal runs and batches organize this sequence. 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 releases the next authorized work; use the session boundary interaction below, without a second approval or start confirmation.
+
+Standard development order: PRD/Scope → technical design → interface/SQL → test cases → plan → implementation/review/verification → handoff. Generate only applicable artifacts. Inspect existing formal materials and register adoption without treating adoption as approval. Respect an explicitly limited commission without presenting it as standard complete delivery.
+
+### Standard completeness and limited scope
+
+New deliveries use `deliveryPolicy: {version: 1}`. `outcome.goal` describes the agreed scope and `outcome.acceptance` the actual user decision; neither alone means standard complete delivery. The tool reports a separate derived completion assessment. Standard completion requires reviewed requirements/design/cases/plan and applicable artifacts, completed implementation with passing batch and overall review, passing independent verification, handoff and explicit final acceptance. Record review coverage with reviewOf implementation IDs and overall: true for the overall review. Records validate structure/evidence references, not truth or user identity; inspect actual results and coverage.
+
+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.
 
 ## Stage references
 
@@ -59,11 +69,11 @@ 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
 
-For multiple batches: implement batch → review batch, repeat; after every batch is complete and reviewed, review the whole change, then independently verify. 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 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.
 
 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.
 
@@ -77,7 +87,17 @@ 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 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.
+At delivery creation / requirements confirmation, record the default session suggestions in existing state: requirements; technical design plus applicable interface/SQL/prototype; cases; plan; each implementation batch including its review/repairs; overall review; each verification batch. `sessionGroup` is advisory and shown in status.md. Adjust it to actual applicable work and context without reapproving unchanged content. Overall review remains a separate suggested session; a single review may cover both batch and whole scope when explicitly recorded. Never introduce a session approval stage, a blocked state for not switching, or a requirement to prove that the session ID changed.
+
+For a reviewable draft, show only its current stage/status, document entry and review focus; ask for explicit approval or questions. Do not issue the next stage's continuation prompt before approval. Discussion and edits retain the stop; self-check and present revisions again.
+
+After explicit approval, in one handling of the message: preserve the actual decision source and exact reviewed version; update approval, current run and next work together as appropriate; inspect the returned saved revision and view result (reread when uncertain); then report the saved outcome and next suggestion. Do not ask the user separately to approve saving or the prompt. If state saving failed, do not claim success; if state saved but the view failed, repair the view at that revision without replaying the approval. Only give the handoff entry once the save is confirmed.
+
+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.
+
+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.
 
 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.
 

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

@@ -10,9 +10,9 @@ Author current requirements in `prd.md`, including scope. Adopt an authoritative
 
 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.
 
-`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.
+`test-design` precedes `plan` in standard delivery; both reviewable documents need explicit approval. If the user explicitly excludes cases/testing, record the limited scope once and do not generate empty testing artifacts or call the result standard complete delivery. `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.
 
-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 before tech-design completes. 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.
+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.
 
@@ -37,3 +37,5 @@ REQ/source → AC → design/operation/SQL, TASK → actual repository object
 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 in the standard delivery. An explicitly limited scope can omit cases/verification, but is a partial handoff, not standard complete delivery. 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 stage/review status and review focus. Do not give the next-stage continuation prompt while review is pending. 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, save and inspect the result, then follow the core session interaction: begin the next item within the current group (including the next applicable interface/SQL document); at a group boundary give the saved result and concise continuation entry, without executing the next group in that response. A request to continue here proceeds directly. 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` 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.
+
+## 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/recovery.md

@@ -19,3 +19,11 @@ Read reports the actual statePath and layout. Use migrate on one explicitly sele
 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.
+
+## Session boundary and completion compatibility
+
+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.

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

@@ -32,3 +32,5 @@ Formatting/typo corrections do not require semantic re-review. Implementation bu
 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,7 +10,7 @@ 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
 
@@ -20,4 +20,8 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 
 ## Artifact contract
 
-Use openapi.yaml or the registered authoritative contract. 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 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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

@@ -23,3 +23,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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/handoff.md

@@ -21,3 +21,5 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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.
+
+Use the derived completion assessment alongside goal and acceptance. A user-authorized scope without cases/verification may be finished as an explicitly untested partial handoff, never standard complete delivery. No next-session prompt is needed at the final endpoint.

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

@@ -2,11 +2,11 @@
 
 ## Basis
 
-Read current Scope, applicable design/contracts and relevant repository boundaries.
+Read approved current PRD/Scope, test cases/coverage for standard delivery (or the explicit limited-scope basis), applicable design/contracts and relevant repository boundaries.
 
 ## Work and result
 
-Define executable batches, each goal and requirement coverage, dependencies, authorized file/repository scope and interfaces. Arrange batch implementation/review, overall review, then independent verification. Include known cross-delivery interface, database, test-data/service and integration dependencies in this same plan, with necessary sequencing or use arrangements. Keep test-code development in appropriate batches; do not add per-batch full testing gates.
+Define executable batches, each goal and requirement coverage, dependencies, authorized file/repository scope and interfaces. Arrange batch implementation/review, overall review, then independent verification within the agreed scope; explicitly excluded testing remains an untested partial handoff. Include known cross-delivery interface, database, test-data/service and integration dependencies in this same plan, with necessary sequencing or use arrangements. Keep test-code development in appropriate batches; do not add per-batch full testing gates.
 
 ## Continue when
 
@@ -21,3 +21,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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

@@ -21,3 +21,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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

@@ -21,3 +21,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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

@@ -21,3 +21,5 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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.
+
+Record reviewOf with the actual implementation-run IDs; mark overall: true only for an overall review. The batch review shares that batch’s suggested session, while overall review has its own suggestion. Resolve findings before continuation; a suggestion never substitutes for a passing review.

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

@@ -21,3 +21,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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
 
@@ -22,4 +22,8 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 
 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.
 
-Produce database.sql for one target, or database-<id>.sql per independent target, before completing this stage. No SQL for no database change.
+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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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,7 +10,7 @@ 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. Write cases and coverage in testing.md; execution remains explicitly not run until verify.
+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
 
@@ -21,3 +21,7 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 ## 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, current review status and focus → wait. Record explicit user approval of this version/content, then follow the core session interaction: continue within the group, or suggest a new session at its boundary; continue here if requested. 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/templates/plan.md

@@ -32,3 +32,4 @@ Actual changes and object versions by TASK/B; preserve original plan and disting
 
 Unfinished effects and recovery, not a second stage ledger. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
+<!-- Review guidance: retain the fixed outline. Technical design precedes interface/SQL production; test cases precede planning. Self-check and explicit document approval are separate from stage done. For plan/testing, keep execution records after execution/runs respectively. -->

package/skills/aimship/references/templates/prd.md

@@ -37,3 +37,5 @@ AC, requirement reference, condition, operation, decidable expected result. Repl
 
 Selected order, artifact locations/reuse, dependencies, Q with impact/status/decision source. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
+
+<!-- Arrangement guidance: standard delivery sequence and applicable artifacts; preserve an explicit limited-scope decision without claiming standard completeness. Suggested session groups live in state, are shown in status, and are not approval conditions. -->

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

@@ -37,3 +37,5 @@ AC, requirement/source identity, conditions, actions and expected results. Repla
 
 Selected order, artifact locations/reuse, permissions and open Q. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
+
+<!-- Arrangement guidance: standard delivery sequence and applicable artifacts; preserve an explicit limited-scope decision without claiming standard completeness. Suggested session groups live in state, are shown in status, and are not approval conditions. -->

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

@@ -37,3 +37,4 @@ Reasons, alternatives, compatibility and technical risks. Replace guidance with
 
 REQ/AC to module/operation/SQL section and unresolved Q. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
+<!-- Review guidance: retain the fixed outline. Technical design precedes interface/SQL production; test cases precede planning. Self-check and explicit document approval are separate from stage done. For plan/testing, keep execution records after execution/runs respectively. -->

package/skills/aimship/references/templates/testing.md

@@ -32,3 +32,4 @@ RUN, TC@version, exact code/build or document object, command/operation, asserti
 
 Separate passed, failed, blocked and unexecuted; explain applicability after change. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
+<!-- Review guidance: retain the fixed outline. Technical design precedes interface/SQL production; test cases precede planning. Self-check and explicit document approval are separate from stage done. For plan/testing, keep execution records after execution/runs respectively. -->