aimship 0.1.0-preview.7 → 0.1.0-preview.8

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/recovery.md

@@ -19,3 +19,5 @@ 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.

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, 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

@@ -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, 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/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
 
@@ -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, 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

@@ -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, 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

@@ -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, 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/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, 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
 
@@ -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, 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,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, 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/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/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. -->