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

package/lib/delivery.mjs

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import { fail } from './io.mjs';
+
+// Additive policy: absent means historical, never inferred complete or rewritten on read.
+export function validateDelivery(state) {
+  const p = state.deliveryPolicy;
+  if (p === undefined) return;
+  if (!p || p.version !== 1) fail('INVALID_STATE', 'Unsupported delivery policy.', 'Preserve the state and use a compatible tool.');
+  if (p.partialRef != null && (typeof p.partialRef !== 'string' || !p.partialRef.trim())) fail('INVALID_STATE', 'partialRef must identify the explicit scope decision.', 'Record the actual decision in the existing requirement or change record.');
+  for (const r of state.stageRuns) {
+    if (r.overall !== undefined && (r.stage !== 'review' || typeof r.overall !== 'boolean')) fail('INVALID_STATE', 'overall is a review scope flag.', 'Identify the actual overall review.');
+    if (r.sessionGroup !== undefined && (typeof r.sessionGroup !== 'string' || !r.sessionGroup.trim())) fail('INVALID_STATE', 'Invalid sessionGroup.', 'Use a nonempty advisory group ID.');
+    if (r.reviewOf !== undefined && (r.stage !== 'review' || !Array.isArray(r.reviewOf) || !r.reviewOf.length || new Set(r.reviewOf).size !== r.reviewOf.length || r.reviewOf.some(id => !state.stageRuns.some(x => x.id === id && x.stage === 'implement')))) fail('INVALID_STATE', 'reviewOf must identify implementation runs.', 'Record the actual reviewed batches.');
+  }
+}
+export function arrangeSessions(state) {
+  if (state.deliveryPolicy?.version !== 1) return;
+  for (const r of state.stageRuns) {
+    if (r.sessionGroup) continue;
+    const category = ['frame','requirements','scope'].includes(r.stage) ? 'requirements' : ['tech-design','contract','prototype'].includes(r.stage) ? 'technical' : r.stage;
+    const batch = r.stage === 'review' && !r.overall && r.reviewOf?.length === 1 ? state.stageRuns.find(x=>x.id===r.reviewOf[0]) : null;
+    r.sessionGroup = batch ? (batch.sessionGroup ?? `implement:${batch.id}`) : ['requirements','technical','test-design','plan'].includes(category) ? category : `${category}:${r.id}`;
+  }
+}
+export function completionStatus(state, review, {changed=[]}={}) {
+  if (state.deliveryPolicy?.version !== 1) return {status:'historical-unassessed', standardComplete:false, readyForAcceptance:false, gaps:['Historical outcomes are preserved; explicitly adopt the delivery policy after assessing evidence.']};
+  const runs=state.stageRuns, gaps=[];
+  if(changed.length) gaps.push('Changed or missing registered documents require reconciliation.');
+  const ready=r=>review.runs.find(x=>x.id===r.id)?.ready;
+  const has=stage=>runs.some(r=>r.stage===stage && ready(r));
+  for (const stage of ['tech-design','test-design','plan','implement','verify','handoff']) if (!has(stage)) gaps.push(`Missing current completed ${stage}.`);
+  if (!runs.some(r=>['requirements','scope'].includes(r.stage) && ready(r))) gaps.push('Missing reviewed requirements / Scope.');
+  if ((state.documentPolicy?.interface!=='none' || state.documentPolicy?.databases?.length) && !has('contract')) gaps.push('Missing applicable interface/SQL contract.');
+  if (state.documentPolicy?.interaction && !state.documentPolicy.prototypeCovered && !has('prototype')) gaps.push('Missing applicable interaction prototype.');
+  if (review.runs.some(r=>!r.ready)) gaps.push('Selected work or document approvals remain unresolved.');
+  const implementations=runs.filter(r=>r.stage==='implement');
+  if (implementations.some(r=>['failed','mixed','unknown','not-run'].includes(r.result))) gaps.push('Implementation results remain unresolved.');
+  const allReviews=runs.filter(r=>r.stage==='review');
+  const effectiveReviews=allReviews.filter((r,i)=>!allReviews.slice(i+1).some(later=>ready(later) && later.result==='passed' && later.historyResultRefs?.includes(r.resultRef)));
+  if (effectiveReviews.some(r=>!ready(r) || r.result!=='passed')) gaps.push('Review results remain unresolved.');
+  const reviews=allReviews.filter(r=>ready(r) && r.result==='passed');
+  for (const [i, batch] of implementations.entries()) {
+    if (!reviews.some(r=>r.reviewOf?.includes(batch.id) && runs.indexOf(r)>runs.indexOf(batch) && (!implementations[i+1] || runs.indexOf(r)<runs.indexOf(implementations[i+1])))) gaps.push(`Missing passing batch review for ${batch.id}.`);
+  }
+  const overall=reviews.findLast(r=>r.overall === true && implementations.length && implementations.every(b=>r.reviewOf?.includes(b.id) && runs.indexOf(r)>runs.indexOf(b)));
+  if (!overall) gaps.push('Missing passing overall implementation review.');
+  const allChecks=runs.filter(r=>r.stage==='verify');
+  const checks=allChecks.filter((r,i)=>!allChecks.slice(i+1).some(later=>ready(later) && later.result==='passed' && later.historyResultRefs?.includes(r.resultRef)));
+  if (!checks.length || checks.some(r=>!ready(r) || r.result!=='passed' || !overall || runs.indexOf(r)<runs.indexOf(overall))) gaps.push('Independent verification is not fully recorded as passed after overall review.');
+  const handoff=runs.findLast(r=>r.stage==='handoff' && ready(r));
+  if (handoff && checks.some(r=>runs.indexOf(r)>runs.indexOf(handoff))) gaps.push('Handoff precedes verification.');
+  if (state.openChanges.some(c=>c.status==='open')) gaps.push('Unresolved changes remain.');
+  const partial=!!state.deliveryPolicy.partialRef;
+  const readyForAcceptance=!partial && !gaps.length;
+  return {status:partial?'partial-scope':readyForAcceptance && state.outcome.goal==='met' && state.outcome.acceptance==='accepted'?'standard-complete':readyForAcceptance?'ready-for-acceptance':'incomplete',standardComplete:readyForAcceptance && state.outcome.goal==='met' && state.outcome.acceptance==='accepted',readyForAcceptance,gaps,partialRef:state.deliveryPolicy.partialRef??null,scope:'Recorded structure, approvals and results only; not independent proof of test execution or semantic quality.'};
+}
+export function sessionAdvice(directory,state,review,{saved=true}={}) {
+  const groups=[];
+  for (const r of state.stageRuns) {
+    const id=r.sessionGroup??'unrecorded';let g=groups.find(x=>x.id===id);if(!g)groups.push(g={id,runs:[]});g.runs.push(r.id);
+  }
+  const current=state.stageRuns.find(r=>r.id===state.currentRun);
+  const status=review.runs.find(r=>r.id===state.currentRun);
+  const pending=review.pending.some(p=>state.stageRuns.find(r=>r.id===p.run)?.progress==='done' || p.status==='changes-requested' || p.status==='self-check-failed');
+  const next=current?state.stageRuns[state.stageRuns.indexOf(current)+1]:state.stageRuns.find(r=>r.progress!=='done');
+  let action='continue-current';
+  if (!saved) action='reconcile-save';
+  else if(state.deliveryPolicy?.version !== 1) action='assess-compatibility';
+  else if(pending) action='await-review';
+  else if(!current && state.stageRuns.length && review.runs.every(r=>r.ready)) action='finished';
+  else if(current && (['failed','mixed','unknown','not-run'].includes(current.result) || current.progress==='blocked' || ['needs-review','unknown'].includes(current.applicability))) action='resolve-current';
+  else if(status?.ready) action=!next?'finished':next.progress!=='planned'?'inspect-existing-work':current.sessionGroup && current.sessionGroup===next.sessionGroup?'continue-group':'suggest-new-session';
+  if (saved && !pending && state.deliveryPolicy?.version === 1 && status?.ready && next && review.runs.find(r=>r.id===next.id)?.blockedBy.length) action='resolve-current';
+  const continuation=['assess-compatibility','reconcile-save','await-review','finished'].includes(action)?null:`Use Aimship to continue delivery ${JSON.stringify(path.resolve(directory))}; first read its current state and relevant formal documents, then continue the recorded work.`;
+  return {action,currentRun:current?.id??null,nextRun:next?.id??null,groups,continuation,advisory:true,note:'A session boundary is not a blocker or approval. Continue here when requested. Resolve the delivery identity, current approvals and unfinished effects on every resume; this text grants no approval.'};
+}

package/lib/state.mjs

@@ -1,3 +1,4 @@
+import { validateDelivery, arrangeSessions, completionStatus, sessionAdvice } from './delivery.mjs';
 import fs from 'node:fs/promises';
 import { validateReviewState, enforceReviews, reviewStatus } from './approvals.mjs';
 import path from 'node:path';
@@ -47,6 +48,7 @@ export function validateState(state) {
   requireThat(string(state.deliveryId) && string(state.rulesVersion), 'deliveryId and rulesVersion are required.');
   requireThat(object(state.goal) && string(state.goal.summary) && string(state.goal.endpoint), 'goal.summary and goal.endpoint are required.');
   ref(state.goalRef, 'goalRef');
+  if (state.compatibilityRef !== undefined) ref(state.compatibilityRef, 'compatibilityRef');
   if (state.goal.decisionRef !== undefined) ref(state.goal.decisionRef, 'goal.decisionRef');
   requireThat(Number.isSafeInteger(state.cycle) && state.cycle >= 1, 'cycle must be a positive integer.');
   refs(state.closureRefs, 'closureRefs');
@@ -75,6 +77,8 @@ export function validateState(state) {
   if (state.next.inputRefs !== undefined) refs(state.next.inputRefs, 'next.inputRefs');
   if (state.goalHistory !== undefined) requireThat(Array.isArray(state.goalHistory), 'goalHistory must be an array.');
   if (state.rulesHistory !== undefined) requireThat(Array.isArray(state.rulesHistory), 'rulesHistory must be an array.');
+  validateDelivery(state);
+  if (state.deliveryPolicy?.partialRef) ref(state.deliveryPolicy.partialRef, 'deliveryPolicy.partialRef');
   validateReviewState(state);
   return state;
 }
@@ -99,9 +103,11 @@ export async function readState(directory) {
   const paths=await locateState(directory); const state=await readJSON(paths.statePath);
   requireThat(object(state),'State must be an object.');
   const layoutMismatch=(state.schemaVersion===1 && !paths.legacy)||(state.schemaVersion===2 && paths.legacy);
-  const readOnly=paths.conflict || layoutMismatch || ![1,SCHEMA_VERSION].includes(state.schemaVersion) || (state.reviewPolicy !== undefined && state.reviewPolicy !== 1);
+  const readOnly=paths.conflict || layoutMismatch || ![1,SCHEMA_VERSION].includes(state.schemaVersion) || (state.reviewPolicy !== undefined && state.reviewPolicy !== 1) || (state.deliveryPolicy !== undefined && state.deliveryPolicy?.version !== 1);
   if (!readOnly) validateState(state);
-  return {...paths,state,readOnly,layoutMismatch,review:readOnly ? null : await reviewStatus(directory,state),view:await viewStatus(directory,state),documentChanges:await documentChanges(directory,state)};
+  const review=readOnly ? null : await reviewStatus(directory,state);
+  const view=await viewStatus(directory,state), changes=await documentChanges(directory,state);
+  return {...paths,state,readOnly,layoutMismatch,review,completion:review ? completionStatus(state,review,{changed:changes}) : null,session:review ? sessionAdvice(directory,state,review,{saved:view.status==='current' && !changes.length}) : null,view,documentChanges:changes};
 }
 async function inspectForWrite(directory,state,previous) {
   const inspected=await inspectDocuments(directory,state);
@@ -145,8 +151,8 @@ export async function initState(directory, input, rulesVersion, runtime) {
     const forbidden = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory', 'documentDigests', 'identityHistory', 'retiredIdentities', 'legacyRunIds', 'writeResult'];
     requireThat(object(input) && !forbidden.some(x => Object.hasOwn(input, x)), 'init input must not set tool-managed identity/version fields.');
     const now = new Date().toISOString();
-    const state = { reviewPolicy: 1, reviewHistory: [], cycle: 1, closureRefs: [], stageRuns: [], currentRun: null, openChanges: [], repositories: [], outcome: { goal: 'in-progress', acceptance: 'not-recorded' }, next: { action: 'Continue the confirmed arrangement.' }, ...input, schemaVersion: SCHEMA_VERSION, revision: 0, deliveryId: randomUUID(), rulesVersion, createdAt: now, updatedAt: now };
-    validateState(state); requireThat(state.documentPolicy.authority !== 'legacy', 'New deliveries cannot opt into legacy rules.'); await inspectForWrite(directory,state); await enforceReviews(directory,state); await atomicWrite(p.statePath, json(state)); return savedResult(directory,state);
+    const state = { deliveryPolicy: {version:1}, reviewPolicy: 1, reviewHistory: [], cycle: 1, closureRefs: [], stageRuns: [], currentRun: null, openChanges: [], repositories: [], outcome: { goal: 'in-progress', acceptance: 'not-recorded' }, next: { action: 'Continue the confirmed arrangement.' }, ...input, schemaVersion: SCHEMA_VERSION, revision: 0, deliveryId: randomUUID(), rulesVersion, createdAt: now, updatedAt: now };
+    arrangeSessions(state); validateState(state); requireThat(state.deliveryPolicy?.version === 1, 'New deliveries require deliveryPolicy version 1.'); requireThat(state.documentPolicy.authority !== 'legacy', 'New deliveries cannot opt into legacy rules.'); await inspectForWrite(directory,state); await enforceReviews(directory,state); await enforceCompletion(directory,state); await atomicWrite(p.statePath, json(state)); return savedResult(directory,state);
   });
 }
 function merge(base, patch) {
@@ -203,14 +209,22 @@ export async function updateState(directory, patch, revision, rulesVersion, runt
       next = { ...previous, rulesVersion, rulesHistory: [...(previous.rulesHistory ?? []), { from: previous.rulesVersion, to: rulesVersion, ref: patch.compatibilityRef, at: new Date().toISOString() }] };
     } else next = merge(previous, patch);
     if (mode === 'checkpoint') next.checkpoint.activeVersion = runtime.activeVersion;
-    validateState(next);
+    requireThat(previous.deliveryPolicy === undefined || next.deliveryPolicy?.version === previous.deliveryPolicy.version, 'Cannot remove or downgrade deliveryPolicy.');
+    if (previous.deliveryPolicy === undefined && next.deliveryPolicy !== undefined) {
+      requireThat(string(next.compatibilityRef) && patch.compatibilityRef !== undefined, 'Explicit delivery-policy adoption needs compatibilityRef; preserve historical outcomes.');
+      const basis = await checkReferences(directory,{...next,goalRef:next.compatibilityRef,next:{inputRefs:[]},stageRuns:[],currentRun:null});
+      requireThat(basis.every(r=>['exists','not-checked'].includes(r.status)), 'Compatibility assessment must be accessible before policy adoption.');
+    }
+    arrangeSessions(next); validateState(next);
     if (JSON.stringify(previous.goal) !== JSON.stringify(next.goal) || previous.goalRef !== next.goalRef) {
       requireThat(string(next.goal.decisionRef) && next.goal.decisionRef !== previous.goal.decisionRef, 'Goal revision requires a new explicit decisionRef; viewing results does not revise a goal.');
-      next.goalHistory = [...(previous.goalHistory ?? []), { goal: previous.goal, goalRef: previous.goalRef, outcome: previous.outcome, revision: previous.revision }];
+      next.goalHistory = [...(previous.goalHistory ?? []), { goal: previous.goal, goalRef: previous.goalRef, deliveryPolicy: previous.deliveryPolicy, outcome: previous.outcome, revision: previous.revision }];
     }
     requireThat(previous.documentPolicy?.authority === 'legacy' || next.documentPolicy?.authority !== 'legacy', 'Cannot downgrade a new delivery to legacy document rules.');
     if (mode === 'update' && next.documentPolicy?.authority === 'legacy') requireThat(Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k)), 'Reconcile legacy documents and set the current documentPolicy before advancing stages or outcomes.');
     if (mode === 'update') { await inspectForWrite(directory,next,previous); if (next.reviewPolicy === 1 || !Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k))) await enforceReviews(directory,next,previous); }
+    if (previous.deliveryPolicy?.partialRef !== next.deliveryPolicy?.partialRef && previous.deliveryPolicy !== undefined) requireThat(string(next.goal.decisionRef) && next.goal.decisionRef !== previous.goal.decisionRef, 'Scope changes need a new explicit goal decision.');
+    if (mode === 'update' && next.deliveryPolicy && previous.deliveryPolicy && JSON.stringify(previous.outcome)!==JSON.stringify(next.outcome)) await enforceCompletion(directory,next);
     retainHistory(previous, next); next.revision = previous.revision + 1; next.updatedAt = new Date().toISOString();
     validateState(next); await atomicWrite(p.backup, json(previous)); await atomicWrite(p.statePath, json(next)); return next.schemaVersion === 2 ? savedResult(directory,next) : next;
   });
@@ -224,7 +238,7 @@ export async function recoverState(directory, revision, rulesVersion, runtime) {
       const raw = await fs.readFile(p.statePath, 'utf8');
       let parsed; try { parsed = JSON.parse(raw); } catch { /* Corruption is preserved below. */ }
       if (parsed) {
-        if (parsed.reviewPolicy !== undefined && parsed.reviewPolicy !== 1) fail('UNKNOWN_SCHEMA','Cannot recover over an unknown review protocol.','Preserve the newer state and use a compatible tool.');
+        if ((parsed.deliveryPolicy !== undefined && parsed.deliveryPolicy?.version !== 1) || (parsed.reviewPolicy !== undefined && parsed.reviewPolicy !== 1)) fail('UNKNOWN_SCHEMA','Cannot recover over an unknown review protocol.','Preserve the newer state and use a compatible tool.');
         if (parsed.schemaVersion !== backup.schemaVersion) fail('UNKNOWN_SCHEMA', 'Cannot recover over an unknown schema.', 'Use a compatible tool; preserve the newer state.');
         try { validateState(parsed); fail('STATE_VALID', 'Current state is valid; refusing rollback.', 'Use a normal revision-checked update to reconcile facts.'); }
         catch (e) { if (!['INVALID_STATE','REVIEW_CHECK'].includes(e.code)) throw e; }
@@ -244,6 +258,8 @@ export async function checkReferences(directory, state, all = false) {
     state.openChanges.forEach(x => values.add(x.ref)); state.closureRefs.forEach(x => values.add(x));
     const add = value => { if (value !== undefined) { ref(value, 'registered reference'); values.add(value); } };
     const addOutcome = outcome => { for (const key of OUTCOME_REFS) add(outcome?.[key]); };
+    if (state.deliveryPolicy?.partialRef != null) add(state.deliveryPolicy.partialRef);
+    add(state.compatibilityRef);
     add(state.goal.decisionRef); addOutcome(state.outcome);
     for (const history of state.goalHistory ?? []) {
       add(history?.goalRef); add(history?.goal?.decisionRef); addOutcome(history?.outcome);
@@ -280,3 +296,11 @@ export async function checkReferences(directory, state, all = false) {
   }
   return results;
 }
+
+async function enforceCompletion(directory,state) {
+  if (state.deliveryPolicy?.version !== 1 || state.outcome.goal !== 'met') return;
+  const completion=completionStatus(state,await reviewStatus(directory,state));
+  if (!state.deliveryPolicy.partialRef && !completion.readyForAcceptance) fail('DELIVERY_INCOMPLETE','Standard delivery evidence is incomplete.','Keep the goal in progress, or record the explicitly limited scope without claiming standard completion.',completion);
+  const refs=await checkReferences(directory,state,true);
+  if (refs.some(r=>!['exists','not-checked'].includes(r.status))) fail('DELIVERY_INCOMPLETE','Completion references are missing.','Repair evidence references without inventing results.',{references:refs});
+}

package/lib/view.mjs

@@ -1,9 +1,10 @@
+import { completionStatus, sessionAdvice } from './delivery.mjs';
 import fs from 'node:fs/promises';
 import { reviewStatus } from './approvals.mjs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { atomicWrite, exists, hash, json, readJSON, noSymlinks } from './io.mjs';
-import { resolveRef } from './documents.mjs';
+import { resolveRef, documentChanges } from './documents.mjs';
 
 const paths = dir => ({ view: path.join(dir,'status.md'), meta: path.join(dir,'.aimship/view.json') });
 export async function viewStatus(directory, state) {
@@ -48,6 +49,9 @@ export async function renderText(directory,state) {
   for (const d of review.documents) lines.push(`| ${artifactLink(d.path)} | ${cell(d.version)} | ${d.status} | ${cell(d.approval)} |`);
   for (const p of review.pending) lines.push(`- Awaiting review: ${artifactLink(p.document)} (${cell(p.run)}; ${p.status})`);
   lines.push('', 'Approval records bind content and user decision evidence; the tool does not authenticate the user.', '');
+  const completion=completionStatus(state,review,{changed:await documentChanges(directory,state)}), session=sessionAdvice(directory,state,review);
+  lines.push('', '## Delivery completeness', '', `Assessment: ${completion.status}`, `Standard complete: ${completion.standardComplete}`, ...completion.gaps.map(g=>`- ${cell(g)}`), '', 'Historical goal/acceptance values are separate from this assessment.', '', '## Session suggestions', '', 'Requirements → technical/interface/SQL → test cases → plan → each implementation batch with its review → overall review → each verification batch. Only applicable work is grouped; these are context suggestions, not gates.', '', ...session.groups.map(g=>`- ${cell(g.id)}: ${g.runs.map(cell).join(', ')}`), '', `Next interaction: ${session.action}`);
+  if (session.continuation) lines.push('',cell(session.continuation));
   lines.push('','## Artifacts and plan','');
   const refs=new Set([...(state.documents??[]).map(d=>d.path),...state.stageRuns.flatMap(r=>[...r.outputRefs,r.resultRef].filter(Boolean)),...(state.next.inputRefs??[])]);
   for (const ref of refs) if (await available(directory,state,ref)) lines.push(`- ${artifactLink(ref)}`);
@@ -71,5 +75,6 @@ export async function generateView(directory,state,preserveEdits=false) {
   } catch(error) {return {status:'error',reason:error.code??error.message,...(preservedPath?{preservedPath}:{}),recovery:'State was saved. Repair the view paths, then render at the returned revision; do not replay update.'};}
 }
 export async function savedResult(directory,state) {
-  return {...state,writeResult:{stateSaved:true,revision:state.revision,view:await generateView(directory,state)}};
+  const view=await generateView(directory,state);
+  return {...state,writeResult:{stateSaved:true,revision:state.revision,view,session:sessionAdvice(directory,state,await reviewStatus(directory,state),{saved:view.status==='current'})}};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimship",
-  "version": "0.1.0-preview.8",
+  "version": "0.1.0-preview.9",
   "description": "Explicit, goal-driven delivery workflow for coding agents",
   "license": "MIT",
   "type": "module",

package/skills/aimship/SKILL.md

@@ -10,9 +10,9 @@ Activate only when the user explicitly asks to start or resume Aimship. Ordinary
 
 1. Run `"{{AIMSHIP_NODE}}" "{{AIMSHIP_LAUNCHER}}" bind` to resolve the installed version. Read the returned fixed-version core and CLI help. Use that fixed version's tools, carrying its rules version and the current state revision. If this is a source checkout rather than an installed entry, use `node bin/aimship.mjs bind` from the package root.
 2. Read the core at the path returned by `bind`. Resolve all supporting links below against that same fixed release, even if a cached entry mentions an older path. [The shared core](references/core.md) is the source-checkout reference. For an existing delivery, read its state and the current goal/Scope plus only the next step's required references. Do not create a replacement delivery, reset its plan, or infer a new goal from “continue”.
-3. For new work, use the binding’s configured `dataRoot` unless the user supplied a delivery location; do not infer it from the code root. Preserve the original request, identify the authorized endpoint and code locations, and propose the necessary ordered stages. After associating code scope, follow the core’s recorded-overlap check for independent deliveries. Existing explicit authorization and agreed arrangements remain valid. No answer is not acceptance. Create records only for an actual request.
-4. Read the selected [stage reference](references/core.md#stage-references) when reaching it. Explain design choices and unresolved decisions. Follow [document review](references/document-review.md): generate, self-check, give the document entry/short summary/next stage and pause. Explicit approval releases the next authorized stage without another start question; questions, silence and viewing results do not approve. Authorized implementation/review/repair/retest can then continue.
-5. At stable results and before a manual session switch, save the state and give a short continuation prompt. Keep a compact binding: delivery ID, absolute delivery directory, state path, current run, rules version, and fixed core/tool paths. After compaction, reload these references if absent; do not assume the full skill survived.
+3. For new work, use the binding’s configured `dataRoot` unless the user supplied a delivery location; do not infer it from the code root. Preserve the original request, identify the authorized endpoint and code locations, and establish the standard development sequence and applicable artifacts; respect explicitly limited scope and record its basis without calling it standard complete delivery. After associating code scope, follow the core’s recorded-overlap check for independent deliveries. Existing explicit authorization and agreed arrangements remain valid. No answer is not acceptance. Create records only for an actual request.
+4. Read the selected [stage reference](references/core.md#stage-references) when reaching it. Explain design choices and unresolved decisions. Follow [document review](references/document-review.md): generate, self-check, give the current document entry/status/review focus and wait; do not send a next-stage continuation prompt while review is pending. After explicit approval save and verify the record, then follow the core session interaction: continue within a group, suggest a new session at its boundary without executing the next group in that response; continuing here needs no new approval; questions, silence and viewing results do not approve. Authorized implementation/review/repair/retest can then continue.
+5. Use the core’s default session groups in existing state. At confirmed saved group boundaries give current results, next suggestion and one continuation line with the actual delivery directory; no extra prompt document. A requested full prompt is optional. On resume, uniquely verify the delivery and actual saved review/unfinished-work stop; never infer approval from the copied entry. Keep a compact binding: delivery ID, absolute delivery directory, state path, current run, rules version, and fixed core/tool paths. After compaction, reload these references if absent; do not assume the full skill survived.
 
 Read [recovery and updates](references/recovery.md) on interruption, version mismatch or missing references; [sources and change flow](references/sources-and-changes.md) when adopting external material or revising reviewed work; [host access](references/hosts.md) only when access or host setup needs attention. Read [document patterns](references/document-patterns.md) when establishing the artifact arrangement or producing a document. New deliveries keep formal documents at the root, source/request.md under source/, and structured state under .aimship/; status.md is the generated reading entry. On resume use the actual statePath returned by read, inspect view/document-change warnings, and explicitly repair or migrate as described in recovery. Do not treat a generated view as editable authority.
 

package/skills/aimship/references/core.md

@@ -33,13 +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. 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.
+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.
 
-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.
+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
 
@@ -65,7 +73,7 @@ Each run records its scope, required inputs, results and progress. A result may
 
 ## 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.
 
@@ -79,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, 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.
+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,7 +10,7 @@ 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.
 
-`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.
+`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 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.
 

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

@@ -1,12 +1,12 @@
 # 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.
+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 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.
+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.
@@ -17,7 +17,7 @@ New state has `reviewPolicy: 1` and append-only `reviewHistory`. Use the [CLI re
 
 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.
+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
 

package/skills/aimship/references/recovery.md

@@ -21,3 +21,9 @@ Migration converts state layout/schema only. Reconcile legacy requirements/desig
 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/stages/contract.md

@@ -24,4 +24,4 @@ Use openapi.yaml or the registered authoritative contract when interfaces apply.
 
 ## 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.
+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

@@ -26,4 +26,4 @@ Only a commissioned independent investigation produces diagnosis.md. Known-cause
 
 ## 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.
+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 approved current PRD/Scope, test cases/coverage, 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
 
@@ -24,4 +24,4 @@ Use plan.md. Preserve the `tasks` section anchor. Follow [document patterns](../
 
 ## 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.
+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

@@ -24,4 +24,4 @@ Use the registered prototype entry (new HTML: prototype/index.html). Follow [doc
 
 ## 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.
+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

@@ -24,4 +24,4 @@ Use the selected PRD/Scope requirement entry. Preserve the `requirements` sectio
 
 ## 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.
+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

@@ -24,4 +24,4 @@ Use the selected PRD/Scope requirement entry. Preserve the `scope` section ancho
 
 ## 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.
+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

@@ -26,4 +26,4 @@ Technical design does not require finished SQL before its review. After its appr
 
 ## 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.
+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

@@ -24,4 +24,4 @@ Use testing.md. Preserve the `cases` section anchor. Follow [document patterns](
 
 ## 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.
+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/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. -->