aimship 0.1.0-preview.19 → 0.1.0-preview.21

package/lib/view.mjs

@@ -1,5 +1,7 @@
 import { text, displayValue } from './language.mjs';
-import { completionStatus, sessionAdvice, suggestedNextStage } from './delivery.mjs';
+import {phaseOf,phaseOrder} from './domains.mjs';
+import {generatedKinds,generatedArea,initialGeneratedBody,projectionText} from './projections.mjs';
+import { completionStatus, sessionAdvice } from './delivery.mjs';
 import fs from 'node:fs/promises';
 import { reviewStatus } from './approvals.mjs';
 import path from 'node:path';
@@ -8,18 +10,36 @@ import { atomicWrite, exists, hash, json, readJSON, noSymlinks } from './io.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) {
-  const t=(en,zh)=>text(state,en,zh);
-  const p=paths(directory);
-  try {
-    if (!await exists(p.view)) return { status:'missing', recovery:t('Run render at the current revision.','使用当前修订重新生成视图。') };
-    await noSymlinks(p.view); await noSymlinks(p.meta);
-    if (!await exists(p.meta)) return { status:'modified', recovery:t('No trusted generation digest; preserve edits with render --preserve-edits.','没有可信的生成摘要；请保留手工修改后重新生成视图。') };
-    const meta=await readJSON(p.meta), raw=await fs.readFile(p.view,'utf8');
-    if (hash(raw)!==meta.hash) return { status:'modified', recovery:t('Inspect the edits, then render --preserve-edits.','先核对修改，再保留手工内容并重新生成视图。') };
-    const current=meta.deliveryId===state.deliveryId && meta.revision===state.revision;
-    return { status:current?'current':'stale', revision:meta.revision, recovery:current?null:t('Run render; do not replay the saved business update.','重新生成视图，不要重放已保存的业务更新。') };
-  } catch(error) { return {status:'error',reason:error.code ?? error.message,recovery:t('Inspect view/metadata paths; preserve untrusted content before render.','核对视图和元数据路径，重新生成前保留现有内容。')}; }
+async function metadata(directory){
+ const p=paths(directory);await noSymlinks(p.meta);return await exists(p.meta)?readJSON(p.meta):null;
+}
+const recovery=state=>text(state,'Render at the current revision; do not replay the saved business update. Preserve modified generated content before rebuilding.','按当前修订重新生成；不要重放已保存的业务更新。重建前保留改动过的生成内容。');
+async function inspectStatus(directory,state,meta){
+ const p=paths(directory);await noSymlinks(p.view);
+ if(!await exists(p.view))return {path:'status.md',status:'missing'};
+ const raw=await fs.readFile(p.view,'utf8');
+ if(!meta||meta.deliveryId!==state.deliveryId||hash(raw)!==meta.hash)return {path:'status.md',status:'modified'};
+ return {path:'status.md',status:meta.revision===state.revision?'current':'stale',revision:meta.revision};
+}
+async function inspectProjection(directory,state,doc,meta){
+ await noSymlinks(path.join(directory,doc.path));
+ if(!await exists(path.join(directory,doc.path)))return {path:doc.path,status:'missing',reason:'DOCUMENT_MISSING'};
+ const raw=await fs.readFile(path.join(directory,doc.path),'utf8'),area=generatedArea(raw,doc.kind);
+ if(area.count!==1)return {path:doc.path,status:'error',reason:area.reason??(area.count?'DUPLICATE_GENERATED_SECTION':'GENERATED_SECTION_MISSING')};
+ const record=meta?.deliveryId===state.deliveryId?meta.artifacts?.[doc.path]:null;
+ if(!record)return {path:doc.path,status:initialGeneratedBody(area.body)?'missing':'modified'};
+ if(record.hash!==hash(area.body))return {path:doc.path,status:'modified'};
+ return {path:doc.path,status:record.revision===state.revision?'current':'stale',revision:record.revision};
+}
+const projectionDocs=state=>state.documents.filter(d=>d.mode==='new'&&generatedKinds.includes(d.kind));
+const aggregate=items=>['error','modified','missing','stale'].find(s=>items.some(x=>x.status===s))??'current';
+export async function viewStatus(directory,state){
+ try{
+  const meta=await metadata(directory),statusView=await inspectStatus(directory,state,meta),artifacts=[];
+  for(const doc of projectionDocs(state))artifacts.push(await inspectProjection(directory,state,doc,meta));
+  const status=aggregate([statusView,...artifacts]);
+  return {status,revision:meta?.revision,statusView,artifacts,recovery:status==='current'?null:recovery(state)};
+ }catch(error){return {status:'error',reason:error.code??error.message,recovery:recovery(state)};}
 }
 const cell = x => String(x ?? 'not recorded').replaceAll('|','\\|').replaceAll('\n',' ');
 const link = ref => `[${ref.replaceAll('[','\\[').replaceAll(']','\\]')}](${ref.split('#')[0].replaceAll(' ','%20').replaceAll('(','%28').replaceAll(')','%29')})`;
@@ -27,82 +47,96 @@ async function available(directory,state,ref) {
   if (/^https?:\/\//.test(ref)) return true;
   const p=resolveRef(directory,state,ref); return p && await exists(p);
 }
-// Runs retain execution history; the user sees one row per delivery responsibility.
-const batchReview = (state,r) => r.stage==='review' && r.overall!==true && r.reviewOf?.some(id=>state.stageRuns.some(x=>x.id===id && x.stage==='implement'));
-const phaseOf = (state,r) => batchReview(state,r)?'implement':r.stage;
-function phaseOrder(state) {
-  const selected=[...new Set(state.stageRuns.map(r=>phaseOf(state,r)))];
-  if(state.deliveryPolicy.partialRef)return selected;
-  const order=['requirements','tech-design','contract','test-design','plan','implement','review','verify','handoff'];
-  if(state.documentPolicy.interface==='none' && state.documentPolicy.databases?.length===0 && !selected.includes('contract'))order.splice(order.indexOf('contract'),1);
-  for(const stage of selected.filter(s=>!order.includes(s))) {
-    const at=state.stageRuns.findIndex(r=>phaseOf(state,r)===stage);
-    const next=state.stageRuns.slice(at+1).map(r=>phaseOf(state,r)).find(s=>order.includes(s));
-    const prior=state.stageRuns.slice(0,at).map(r=>phaseOf(state,r)).findLast(s=>order.includes(s));
-    order.splice(next?order.indexOf(next):prior?order.indexOf(prior)+1:0,0,stage);
-  }
-  return order;
+// One responsibility per main-stage row; internal review and repair facts stay
+// in the relevant batch view.
+const batchReview=(_state,r)=>r.stage==='review'&&r.reviewScope==='batch';
+export function derivedNextAction(state,review,{changed=[]}={}){
+ const t=(en,zh)=>text(state,en,zh),model=review.execution;
+ if(state.next.questionRef)return t('Resolve the recorded question before its dependent work.','先解决已记录问题，再推进依赖它的工作。');
+ if(changed.length||review.evidenceIssues.length)return t('Reconcile the changed material or review evidence.','核对变化的资料或审核依据。');
+ if(review.pending.length)return t('Review or correct the current document content.','审核或修订当前文档内容。');
+ const current=state.stageRuns.find(r=>r.id===state.currentRun),s=review.runs.find(r=>r.id===current?.id);
+ if(current&&(s?.blockedBy.length||current.progress==='blocked'||['needs-review','unknown'].includes(current.applicability)))return t('Resolve the current dependency or affected scope.','处理当前依赖或受影响范围。');
+ if(state.deliveryPolicy.partialRef){
+  if(current?.stage==='review'&&['failed','mixed','unknown'].includes(current.result)&&!s?.resolvedBy)return t('Resolve the cited review within the agreed limited scope.','在约定限定范围内处理所引审查。');
+  return s?.ready?t('Stop at the saved scope boundary and assess the result against the agreed limited goal.','在已保存的范围边界停止，对照约定限定目标核对结果。'):t('Complete the current agreed limited scope and its recorded dependencies.','完成当前约定限定范围及其已记录依赖。');
+ }
+ if(model.batches.some(b=>b.status==='needs-repair'))return t('Repair and recheck the affected batch within its authorized scope.','在已授权范围内修复并复查受影响批次。');
+ if(model.batches.some(b=>b.status==='await-review'))return t('Complete this batch review and authorized repairs before its batch stop.','完成本批审查及授权内修复，再在批次边界停止。');
+ if(current?.stage==='review'&&['failed','mixed','unknown'].includes(current.result)&&!s?.resolvedBy)return t('Resolve the cited review and recheck its actual scope.','处理所引审查，并按实际范围复查。');
+ if(model.batches.length&&model.batches.every(b=>b.status==='complete')){
+  if(!model.overall)return t('Summarize implementation and stop. Start the existing overall review in a new session, or here when explicitly requested.','汇总实施结果后停止；建议新会话执行已有整体审查，明确要求时可在当前会话继续。');
+  if(model.verification.coverage.some(c=>['failed','mixed'].includes(c.result)))return t('Resolve the cited verification failures and retest their actual coverage after the necessary repair review.','处理所引验证失败，在必要的修复审查后按实际覆盖重测。');
+  if(!model.verification.passed)return t('Prepare the actual test environment and perform separate formal verification; inspect the current coverage below.','准备实际测试环境并独立正式验证；核对下方当前覆盖。');
+  if(!state.stageRuns.some(r=>r.stage==='handoff'&&review.runs.find(x=>x.id===r.id)?.ready))return t('Prepare the handoff from the current review and verification results.','依据当前审查和验证结果准备交接。');
+  return state.outcome.acceptance==='accepted'?t('Assess the recorded delivery conclusion.','核对已记录的交付结论。'):t('Review the handoff and record the actual user acceptance.','审核交接并记录实际用户验收。');
+ }
+ if(current?.stage==='review'&&current.reviewScope==='batch'&&s?.releaseReady)return t('This batch is complete. Stop before starting the next authorized batch.','本批已完成；在开始下一授权批次前停止。');
+ if(current?.stage==='plan'&&s?.releaseReady)return t('The plan is approved. Start only the agreed implementation batch.','计划已批准；只开始约定的实施批次。');
+ if(current?.stage==='implement')return t('Finish this authorized batch and its batch review; stop before the next batch.','完成当前授权批次及批审，在下一批前停止。');
+ return t('Continue the current agreed stage after its required review or continuation.','在所需审核或继续指令后接续当前约定阶段。');
 }
-export async function renderText(directory,state) {
+export async function renderText(directory,state,snapshot) {
   const t=(en,zh)=>text(state,en,zh), v=x=>cell(displayValue(state,x));
   const artifactLink=ref=>ref.startsWith('repo:')
     ? `[${cell(ref.split('#')[0])}](${encodeURI(resolveRef(directory,state,ref)).replaceAll('(','%28').replaceAll(')','%29')})`
     : link(ref.split('#')[0]);
-  const review=await reviewStatus(directory,state), changed=await documentChanges(directory,state);
+  const review=snapshot?.review??await reviewStatus(directory,state), changed=snapshot?.changed??await documentChanges(directory,state);
   const completion=completionStatus(state,review,{changed}), session=sessionAdvice(directory,state,review);
   const current=state.stageRuns.find(r=>r.id===state.currentRun) ?? state.stageRuns.at(-1);
   const currentReview=review.runs.find(r=>r.id===current?.id);
   const humanDocs=review.documents.filter(d=>currentReview?.documents.includes(d.path));
   const failed=r=>['failed','mixed'].includes(r.result);
   const progress=r=> {
-    const check=review.runs.find(x=>x.id===r.id);
+    const check=review.runs.find(x=>x.id===r.id), resolved=check?.resolvedBy;
     if(r.progress==='planned')return t('Not started','尚未开始');
     if(r.id===state.currentRun && state.next.questionRef)return t('Awaiting clarification','待确认具体问题');
     if(r.progress==='blocked' || check?.blockedBy.length || ['needs-review','unknown'].includes(r.applicability))return t('Needs attention','需要处理');
-    if(failed(r) && !check?.resolvedBy)return t('Result needs resolution','结果待处理');
-    if(r.result==='unknown' && !check?.resolvedBy)return t('Result not yet known','结果尚未确定');
-    if(r.result==='not-run' && !check?.resolvedBy)return t('Not run','未执行');
-    if(r.stage==='review' && r.progress==='done' && !r.result && !check?.resolvedBy)return t('Review result not recorded','审查结果未记录');
+    if(failed(r) && !resolved)return t('Result needs resolution','结果待处理');
+    if(r.result==='unknown' && !resolved)return t('Result not yet known','结果尚未确定');
+    if(r.result==='not-run' && !resolved)return t('Not run','未执行');
+    if(r.stage==='review' && r.progress==='done' && !r.result && !resolved)return t('Review result not recorded','审查结果未记录');
     if(check?.documents.some(file=>['self-check-failed','changes-requested','evidence-changed','unavailable'].includes(review.documents.find(d=>d.path===file)?.status)))return t('Needs revision or checking','需要修改或核对');
     if(r.progress==='done' && check?.waiting.length)return check.waiting.every(file=>review.documents.find(d=>d.path===file)?.input)?t('Input check pending','输入材料待核对'):t('Document prepared; awaiting review','文档已完成，待审核');
     if(r.progress==='done' && check?.documents.length && check.documents.every(file=>review.documents.find(d=>d.path===file)?.status==='adopted'))return t('Provided material adopted','已采用现有材料');
     return r.progress==='done'?t('Completed','已完成'):t('In progress','进行中');
   };
-  const phaseName=stage=>stage==='review' && (!state.deliveryPolicy.partialRef || state.stageRuns.some(r=>r.stage==='implement' || r.overall===true))?t('Overall review','整体审查'):v(stage);
+  const standaloneReview=!!state.deliveryPolicy.partialRef&&!review.execution.batches.length;
+  const phaseName=stage=>stage==='review' && !standaloneReview?t('Overall review','整体审查'):v(stage);
   const runName=r=>batchReview(state,r)?t('implement · Batch review','实施 · 批次审查'):phaseName(r.stage);
   const phaseProgress=stage=> {
-    const all=state.stageRuns.filter(r=>phaseOf(state,r)===stage);
-    const runs=all.filter(r=>!review.runs.find(x=>x.id===r.id)?.resolvedBy);
-    if(!runs.length || runs.every(r=>r.progress==='planned'))return stage==='contract' && (state.documentPolicy.interface===null || state.documentPolicy.databases===null)?t('Applicability to be determined during design','待技术设计确认是否适用'):t('Not started','尚未开始');
-    const pending=r=>r.progress!=='planned' && (r.progress!=='done' || progress(r)!==t('Completed','已完成') && progress(r)!==t('Provided material adopted','已采用现有材料'));
-    const attention=runs.filter(pending);
-    if(attention.length)return progress(attention.find(r=>r.id===state.currentRun)??attention.at(-1));
-    if(runs.some(r=>r.progress==='planned'))return t('In progress','进行中');
-    if(stage==='implement') {
-      const batches=state.stageRuns.filter(r=>r.stage==='implement');
-      const covered=batches.filter(b=>state.stageRuns.some(r=>r.stage==='review' && r.reviewOf?.includes(b.id) && state.stageRuns.indexOf(r)>state.stageRuns.indexOf(b) && review.runs.find(x=>x.id===r.id)?.releaseReady && r.result==='passed')).length;
-      return covered===batches.length?t(`Recorded batches completed: ${batches.length}; batch reviews passed`,`已记录批次完成 ${batches.length}；批次审查通过`):t(`Recorded batches completed: ${batches.length}; batch review pending`,`已记录批次完成 ${batches.length}；待批次审查`);
-    }
-    // A previous overall conclusion cannot cover later implementation work.
-    if(stage==='review' && state.stageRuns.some(r=>r.stage==='implement')) {
-      const batches=state.stageRuns.filter(r=>r.stage==='implement');
-      if(!runs.some(r=>r.overall===true && batches.every(b=>r.reviewOf?.includes(b.id) && state.stageRuns.indexOf(r)>state.stageRuns.indexOf(b))))return t('Review required for current batches','当前批次待整体审查');
+    const runs=state.stageRuns.filter(r=>phaseOf(r)===stage&&!review.runs.find(x=>x.id===r.id)?.resolvedBy);
+    if(stage==='implement'&&review.execution.batches.length){
+      const batches=review.execution.batches,complete=batches.filter(b=>b.status==='complete').length;
+      return t(`Business batches complete: ${complete}/${batches.length}`,`业务批次完成 ${complete}/${batches.length}`)+(batches.some(b=>['needs-repair','needs-review','blocked'].includes(b.status))?t('; needs attention','；需要处理'):'');
     }
+    if(stage==='review'&&review.execution.overall)return t('Completed','已完成');
+    if(stage==='verify'&&review.execution.verification.passed)return t('Completed','已完成');
+    if(!runs.length||runs.every(r=>r.progress==='planned'))return stage==='contract'&&(state.documentPolicy.interface===null||state.documentPolicy.databases===null)?t('Applicability to be determined during design','待技术设计确认是否适用'):t('Not started','尚未开始');
+    if(stage==='verify')return t('Coverage incomplete; see current testing results','覆盖尚未完成；见当前测试结果');
+    const pending=runs.filter(r=>r.progress!=='planned'&&!review.runs.find(x=>x.id===r.id)?.releaseReady);
+    if(pending.length)return progress(pending.find(r=>r.id===state.currentRun)??pending.at(-1));
+    if(runs.some(r=>r.progress==='planned'))return t('In progress','进行中');
+    if(stage==='review'&&!standaloneReview)return t('Review required for current implementation','当前实施待整体审查');
     return runs.every(r=>progress(r)===t('Provided material adopted','已采用现有材料'))?t('Provided material adopted','已采用现有材料'):t('Completed','已完成');
   };
+  const kinds={frame:['prd'],requirements:['prd'],prototype:['prototype'],diagnose:['diagnosis'],'tech-design':['tech-design'],contract:['contract','sql'],'test-design':['testing'],plan:['plan'],implement:['plan'],review:['review'],verify:['testing'],handoff:['handoff']};
+  const stageFiles=new Set();
+  for(const stage of phaseOrder(state)){
+    for(const doc of state.documents.filter(d=>kinds[stage]?.includes(d.kind)))if(await available(directory,state,doc.path))stageFiles.add(doc.path);
+    for(const ref of state.stageRuns.filter(r=>r.stage==='contract'&&stage==='contract').flatMap(r=>r.outputRefs)){const file=ref.split('#')[0];if(file&&!file.includes('/')&&await available(directory,state,file))stageFiles.add(file);}
+  }
+  // Registered formal entries also appear in adopted-material navigation when
+  // no selected main-stage row owns them. Do not link those twice above it.
+  for(const doc of state.documents)if(!doc.path.startsWith('.aimship/')&&await available(directory,state,doc.path))stageFiles.add(doc.path);
+  const workRefs=[...new Set(state.next.inputRefs??[])].filter(ref=>ref!=='.aimship/init.md'&&!stageFiles.has(ref.split('#')[0]));
   const lines=[t('# Delivery progress','# 交付进度'),'',cell(state.goal.summary),'',t('## Current stage and your next action','## 当前阶段与用户操作'),''];
   lines.push(`${t('Current stage','当前阶段')}: ${current?runName(current):v('requirements preparation')}${current?' · '+progress(current):''}`);
   for(const d of humanDocs)lines.push(`- ${artifactLink(d.path)} ${cell(d.version)} · ${d.selfCheck?t('Self-check recorded as passed','自检记录通过'):t('Self-check pending','待自检')} · ${v(d.status)}`);
-  lines.push('',`${t('Next action','下一步')}: ${cell(state.next.action)}`);
+  lines.push('',`${t('Next action','下一步')}: ${cell(derivedNextAction(state,review,{changed}))}`);
+  if(workRefs.length)lines.push('',`${t('Work references','待办依据')}: ${workRefs.map(artifactLink).join('; ')}`);
   if(session.action==='await-review')lines.push('',t('Review the document above and approve it or give feedback.','请查看上方文档，通过或反馈修改。'));
   if(state.next.questionRef)lines.push('',`${t('Question and impact','问题与影响')}: ${artifactLink(state.next.questionRef)}`);
-  if(session.instruction)lines.push('',cell(session.instruction));
-  const next=suggestedNextStage(state);
-  if(next && current?.progress==='done' && !['resolve-current','finished','assess-outcome'].includes(session.action)) {
-    const scheduled=state.stageRuns[state.stageRuns.indexOf(current)+1];
-    const label=scheduled?runName(scheduled):next==='review'?(current.stage==='implement'?t('implement · Batch review','实施 · 批次审查'):t('Overall review','整体审查')):phaseName(next);
-    lines.push('',`${t('After this stop','当前停点处理后')}: ${label}${session.action==='await-review'?t(' (after approval)','（批准后）'):''}`);
-  }
   const problems=[];
   if(current && current.progress!=='planned') {
     if(current.progress==='blocked')problems.push(cell(current.scope));
@@ -115,8 +149,26 @@ export async function renderText(directory,state) {
   for(const c of state.openChanges.filter(c=>c.status==='open'))problems.push(`${t('Open change','待处理变更')}: ${artifactLink(c.ref)}`);
   if(review.evidenceIssues.length)problems.push(t('Recorded review evidence needs checking.','已记录的审核依据需要核对。'));
   if(problems.length)lines.push('',t('## Items to resolve','## 当前待处理事项'),'',...problems.map(p=>'- '+p));
-  lines.push('',t('## Delivery progress','## 整体进度'),'',t('| Stage | Status |','| 阶段 | 状态 |'),'| --- | --- |');
-  for(const stage of phaseOrder(state))lines.push(`| ${phaseName(stage)} | ${phaseProgress(stage)} |`);
+  const refs=new Map(), used=new Set();
+  const names={testing:t('Test cases and results','用例与结果'),sql:'SQL',prd:t('Requirements','需求依据'),source:t('Source material','来源材料'),prototype:t('Prototype','原型')};
+  for(const d of state.documents)if(!d.path.startsWith('.aimship/'))refs.set(d.path,`${names[d.kind]??v(d.kind)} · ${cell(d.version)}`);
+  for(const ref of state.stageRuns.filter(r=>r.stage==='contract').flatMap(r=>r.outputRefs)) {
+    const file=ref.split('#')[0];
+    if(file && !file.includes('/') && !refs.has(file))refs.set(file,t('Additional contract','补充契约'));
+  }
+  const artifacts=async stage=> {
+    const entries=new Map();
+    for(const d of state.documents.filter(d=>kinds[stage]?.includes(d.kind)))entries.set(d.path,d.path);
+    const runs=state.stageRuns.filter(r=>phaseOf(r)===stage && !review.runs.find(x=>x.id===r.id)?.resolvedBy);
+    for(const ref of runs.flatMap(r=>r.outputRefs))if(refs.has(ref.split('#')[0]))entries.set(ref.split('#')[0],ref);
+    const latest=runs.findLast(r=>r.progress==='done' && r.resultRef);
+    if(latest && refs.has(latest.resultRef.split('#')[0]))entries.set(latest.resultRef.split('#')[0],latest.resultRef);
+    const links=[];
+    for(const [file,ref] of entries)if(await available(directory,state,file)){used.add(file);links.push(artifactLink(file)+(ref.includes('#')?' · '+cell(ref.split('#')[1]):''));}
+    return links.join('; ') || t('Not yet recorded','尚未记录');
+  };
+  lines.push('',t('## Delivery progress','## 整体进度'),'',t('| Stage | Artifact or result | Status |','| 阶段 | 成果 | 状态 |'),'| --- | --- | --- |');
+  for(const stage of phaseOrder(state))lines.push(`| ${phaseName(stage)} | ${await artifacts(stage)} | ${phaseProgress(stage)} |`);
   lines.push('',`${t('Delivery conclusion','交付结论')}: ${v(completion.status)}`);
   // Full completion diagnostics matter at handoff, not as a list of early-stage defects.
   if(current?.stage==='handoff' || state.outcome.goal==='met')lines.push(...completion.gaps.map(g=>'- '+cell(g)));
@@ -125,41 +177,57 @@ export async function renderText(directory,state) {
   if(state.outcome.deploymentRef)lines.push(`${t('Deployment record','部署记录')}: ${artifactLink(state.outcome.deploymentRef)}`);
   lines.push('',t('## Goal and adopted materials','## 目标与采用材料'),'',`${t('Endpoint','交付终点')}: ${cell(state.goal.endpoint??t('To be confirmed','待确认'))}`);
   if(state.documentPolicy.interface===null || state.documentPolicy.databases===null)lines.push('',t('Interface/database applicability will be determined during technical design.','接口／数据库适用性待技术设计确认。'));
-  const refs=new Map();
-  const names={testing:t('Test cases and results','用例与结果'),sql:'SQL',prd:t('Requirements','需求依据'),source:t('Source material','来源材料'),prototype:t('Prototype','原型')};
-  for(const d of state.documents)if(!d.path.startsWith('.aimship/'))refs.set(d.path,`${names[d.kind]??v(d.kind)} · ${cell(d.version)}`);
-  // Contract stages may have supplementary formal formats (for example RPC).
-  // Root outputs are artifact entries, not approval claims; evidence stays under .aimship/.
-  for(const ref of state.stageRuns.filter(r=>r.stage==='contract').flatMap(r=>r.outputRefs)) {
-    const file=ref.split('#')[0];
-    if(file && !file.includes('/') && !refs.has(file))refs.set(file,t('Additional contract','补充契约'));
-  }
-  for(const [ref,role] of refs)if(await available(directory,state,ref))lines.push(`- ${role}: ${artifactLink(ref)}`);
-  lines.push('',t('## Continue this delivery','## 接续本次交付'),'',`${t('Delivery directory','交付目录')}: ${cell(path.resolve(directory))}`,'',t('You can continue here, or start a new session with “Use Aimship to continue this delivery” and this directory. The AI reads the saved state and materials and resumes the current stop.','可在当前会话继续；新会话请说“使用 Aimship 继续本次交付”并提供此目录。AI 会读取已保存状态和材料，接续本页停点。'));
+  for(const [ref,role] of refs)if(!used.has(ref) && await available(directory,state,ref))lines.push(`- ${role}: ${artifactLink(ref)}`);
   if(state.repositories.length) {
     lines.push('',t('## Associated engineering','## 关联工程'),'',t('| Object | Location | Role |','| 工程 | 位置 | 用途 |'),'| --- | --- | --- |');
     for(const r of state.repositories)lines.push(`| ${cell(r.id)} | ${cell(r.path)} | ${cell(r.role)} |`);
   }
-  lines.push('',t('## Saved information','## 保存信息'),'',`${t('Delivery','交付')}: ${state.deliveryId}`,`${t('State revision','状态修订')}: ${state.revision}`,`${t('Rules','规则版本')}: ${state.rulesVersion}`,`${t('State saved','状态保存时间')}: ${state.updatedAt}`,'',t('Generated from saved state and document checks. Update the formal records, not this page. Recorded results are not independent proof of execution.','由保存状态和文档检查生成；请更新正式记录，不手改本页。记录结果不等于独立验证了实际执行。'),'');
+  lines.push('',t('## Saved information','## 保存信息'),'',`${t('Delivery directory','交付目录')}: ${cell(path.resolve(directory))}`,`${t('Delivery','交付')}: ${state.deliveryId}`,`${t('State revision','状态修订')}: ${state.revision}`,`${t('Rules','规则版本')}: ${state.rulesVersion}`,`${t('State saved','状态保存时间')}: ${state.updatedAt}`,'',t('Generated from saved state and document checks. Update the formal records, not this page. Recorded results are not independent proof of execution.','由保存状态和文档检查生成；请更新正式记录，不手改本页。记录结果不等于独立验证了实际执行。'),'');
   return lines.join('\n');
 }
-export async function generateView(directory,state,preserveEdits=false) {
-  const p=paths(directory); const diagnostic=await viewStatus(directory,state);
-  let preservedPath;
-  try {
-    if (['modified','error'].includes(diagnostic.status) && await exists(p.view)) {
-      if (!preserveEdits) return {...diagnostic,status:'protected'};
-      await noSymlinks(p.view);
-      preservedPath=path.join(directory,'.aimship',`status-edits-${randomUUID()}.md`);
-      await atomicWrite(preservedPath,await fs.readFile(p.view));
-    }
-    const text=await renderText(directory,state);
-    await atomicWrite(p.view,text);
-    await atomicWrite(p.meta,json({deliveryId:state.deliveryId,revision:state.revision,hash:hash(text)}));
-    return {status:'current',revision:state.revision,...(preservedPath?{preservedPath}:{})};
-  } catch(error) {return {status:'error',reason:error.code??error.message,...(preservedPath?{preservedPath}:{}),recovery:text(state,'State was saved. Repair the view paths, then render at the returned revision; do not replay update.','状态已保存。请修复视图路径，并在返回的修订上重新生成视图；不要重复业务更新。')};}
+export async function generateView(directory,state,preserveEdits=false){
+ const p=paths(directory),results=[],metaBase={deliveryId:state.deliveryId,artifacts:{}};
+ let meta;
+ try{meta=await metadata(directory);}catch(error){
+  if(!preserveEdits||error.code!=='INVALID_JSON')return {status:'error',reason:error.code??error.message,recovery:recovery(state)};
+  try{await noSymlinks(p.meta);await atomicWrite(path.join(directory,'.aimship',`view-metadata-edits-${randomUUID()}.json`),await fs.readFile(p.meta));meta=null;}catch(cause){return {status:'error',reason:cause.code??cause.message,recovery:recovery(state)};}
+ }
+ if(meta?.deliveryId===state.deliveryId)Object.assign(metaBase,meta,{artifacts:{...meta.artifacts}});
+ const review=await reviewStatus(directory,state),changed=await documentChanges(directory,state),snapshot={review,changed};
+ async function preserve(file,raw,label){const target=path.join(directory,'.aimship',`${label}-edits-${randomUUID()}.md`);await atomicWrite(target,raw);return target;}
+ let statusView;
+ try{
+  const diagnostic=await inspectStatus(directory,state,meta);let preservedPath;
+  if(diagnostic.status==='modified'){
+   if(!preserveEdits)statusView={...diagnostic,status:'protected'};
+   else preservedPath=await preserve(p.view,await fs.readFile(p.view),'status');
+  }
+  if(!statusView){const body=await renderText(directory,state,snapshot);await atomicWrite(p.view,body);metaBase.hash=hash(body);metaBase.revision=state.revision;statusView={path:'status.md',status:'current',revision:state.revision,...(preservedPath?{preservedPath}:{})};}
+ }catch(error){statusView={path:'status.md',status:'error',reason:error.code??error.message};}
+ for(const doc of projectionDocs(state)){
+  try{
+   const diagnostic=await inspectProjection(directory,state,doc,meta),file=path.join(directory,doc.path);
+   if(diagnostic.status==='error'||diagnostic.reason==='DOCUMENT_MISSING'){results.push(diagnostic);continue;}
+   const raw=await fs.readFile(file,'utf8'),area=generatedArea(raw,doc.kind),body=projectionText(state,review,doc.kind);let preservedPath;
+   if(body===area.body){metaBase.artifacts[doc.path]={hash:hash(body),revision:state.revision};results.push({path:doc.path,status:'current',revision:state.revision});continue;}
+   // A sourceDigest pins the entire source file, including its generated area.
+   // Never change that evidence, even when asked to preserve manual view edits.
+   if(state.reviewHistory.some(r=>r.sourceDigest&&r.sourceRef.split('#')[0]===doc.path)){results.push({path:doc.path,status:'protected',reason:'APPROVAL_EVIDENCE_SOURCE'});continue;}
+   if(diagnostic.status==='modified'){
+    if(!preserveEdits){results.push({...diagnostic,status:'protected'});continue;}
+    preservedPath=await preserve(file,raw,doc.kind);
+   }
+   if(await fs.readFile(file,'utf8')!==raw){results.push({path:doc.path,status:'protected',reason:'CONTENT_CHANGED_DURING_RENDER'});continue;}
+   await atomicWrite(file,raw.slice(0,area.bodyStart)+body+raw.slice(area.end));
+   metaBase.artifacts[doc.path]={hash:hash(body),revision:state.revision};
+   results.push({path:doc.path,status:'current',revision:state.revision,...(preservedPath?{preservedPath}:{})});
+  }catch(error){results.push({path:doc.path,status:'error',reason:error.code??error.message});}
+ }
+ try{await atomicWrite(p.meta,json(metaBase));}catch(error){return {status:'error',reason:error.code??error.message,statusView,artifacts:results,recovery:recovery(state)};}
+ const failed=[statusView,...results].filter(r=>r.status!=='current'),status=failed.some(r=>r.status==='error')?'error':failed.length?'protected':'current';
+ return {status,revision:state.revision,statusView,artifacts:results,...(failed.length?{recovery:recovery(state)}:{})};
 }
-export async function savedResult(directory,state,{initialized=false}={}) {
-  const view=await generateView(directory,state);
-  return {...state,writeResult:{stateSaved:true,revision:state.revision,view,receipt:{status:view.status==='current'?'saved':'view-repair-required',deliveryId:state.deliveryId,directory:path.resolve(directory),statePath:path.join(path.resolve(directory),'.aimship/state.json'),statusPath:view.status==='current'?path.join(path.resolve(directory),'status.md'):null,rulesVersion:state.rulesVersion,currentStage:state.stageRuns.find(r=>r.id===state.currentRun)?.stage??(state.goalRef==='.aimship/init.md'?'requirements preparation':null),nextAction:state.next.action,repositoryCount:state.repositories.length,...(initialized?{workspaceHint:text(state,`Add ${path.resolve(directory)} to your current project/workspace; ignore this if already added.`,`请将「${path.resolve(directory)}」添加到当前项目／工作空间；已添加则忽略。`)}:{})},session:sessionAdvice(directory,state,await reviewStatus(directory,state),{saved:view.status==='current'})}};
+export async function savedResult(directory,state,{initialized=false}={}){
+ const view=await generateView(directory,state),review=await reviewStatus(directory,state);
+ return {...state,writeResult:{stateSaved:true,revision:state.revision,view,receipt:{status:view.status==='current'?'saved':'view-repair-required',deliveryId:state.deliveryId,directory:path.resolve(directory),statePath:path.join(path.resolve(directory),'.aimship/state.json'),statusPath:view.statusView?.status==='current'?path.join(path.resolve(directory),'status.md'):null,rulesVersion:state.rulesVersion,currentStage:state.stageRuns.find(r=>r.id===state.currentRun)?.stage??(state.goalRef==='.aimship/init.md'?'requirements preparation':null),nextAction:derivedNextAction(state,review),repositoryCount:state.repositories.length,...(initialized?{workspaceHint:text(state,`Add ${path.resolve(directory)} to your current project/workspace; ignore this if already added.`,`请将「${path.resolve(directory)}」添加到当前项目／工作空间；已添加则忽略。`)}:{})},session:sessionAdvice(directory,state,review,{saved:view.status==='current'})}};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimship",
-  "version": "0.1.0-preview.19",
+  "version": "0.1.0-preview.21",
   "description": "Explicit, goal-driven delivery workflow for coding agents",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,6 @@
   },
   "homepage": "https://github.com/clsx/aimship#readme",
   "aimship": {
-    "protocolVersion": 1
+    "protocolVersion": 2
   }
 }

package/skills/aimship/SKILL.md

@@ -10,8 +10,8 @@ Activate only when the user explicitly asks to start or resume Aimship. A clear
 
 1. Run `"{{AIMSHIP_NODE}}" "{{AIMSHIP_LAUNCHER}}" bind`, then read the returned fixed-version [core](references/core.md) and CLI help. Use that release's tools and references. In a source checkout, run `node bin/aimship.mjs bind` from its package root.
 2. Locate the same delivery and read its state, initialization notes and current materials. For new work, follow [initialization](references/core.md#initialization): preserve the commission in `.aimship/init.md`, use a separate directory under the bound dataRoot, and save the actual language and scope. A concrete request is enough; code and a PRD can come later. Resume existing work rather than initialize it again.
-3. Follow the current [stage reference](references/core.md#stage-references), complete its work and self-check, then save and report the artifacts and current stop. For a newly written or substantively revised reviewable document, show its link and review focus and collect the user's decision using [document review](references/document-review.md). Adopt unchanged supplied materials from the actual commission without asking for their review again. Keep unresolved questions in the document with their impact and the point when an answer is needed.
-4. At the saved stop, present the document and the decisions it needs, or explain what continuation will do. Save the user's actual approval of the current content before dependent work; approval and continuation can be expressed together. Keep work within a stage continuous. Use the core's major work boundaries for a new-session suggestion; a pending document stays at review in either session.
+3. Use [routing](references/routing.md) to determine this turn's stage, actual scope and user-visible stop from the request and saved state. Load the selected [stage contract](references/core.md#stage-references), not every stage. Each has inputs, goal/scope, actions, outputs/result and completion/stop. Shared approval, change, source and recovery rules remain in their common references.
+4. Execute that work unit within the commission. One implementation batch includes local checks, batch review and authorized repair/recheck; keep separate internal runs but do not ask for continuation between them. Stop at batch closure, a real dependency, a required document review, or the selected overall-review/verification boundary. After the last batch, save its implementation summary and recommend a new session for the existing overall review; continue it here only with explicit authorization. A request for overall review alone does not authorize full testing. Save actual content approval before dependent work; approval and continuation may be expressed together.
 5. Report the saved directory, materials and next action using the core's User-facing updates guidance. On initialization, remind the user once to add the actual directory to the current project/workspace, ignoring the reminder if already added. On resume, preserve the delivery ID, current stop, language and fixed rule/tool paths; reload these if context is lost.
 
 

package/skills/aimship/references/core.md

@@ -26,7 +26,7 @@ This flow follows explicit Aimship activation in the first and every new session
 1. Preserve the user's relevant wording, sources, constraints and visible discussion. Distinguish user decisions, reported facts, Agent suggestions and unknowns. Do not re-ask known answers or treat discussion as approval. Before write access exists, keep this in the conversation and say it is not saved. If a session switch is necessary before saving, provide copyable context with the intended path, original input and pending operation; it is not a new approval.
 2. Bind the actual tool/core version and keep its returned dataRoot. Inspect the intended delivery folder or known candidates for existing state, partial creation or conflicting material. Read and resume existing state, checking deliveryId when known, including older deliveries outside today’s configured root. For a new location explicitly chosen by the user, preserve that actual decision in a nonempty local file within the delivery and supply `storage: {mode: "explicit", decisionRef: "<delivery-relative file>"}` to init; the reference is a file path without a fragment. Never invent the decision or override the tool’s dataRoot to make a path pass. Otherwise use a separate folder under the bound dataRoot. Ask only when identity/location is unresolved; do not create a replacement or infer ownership from a matching name.
 3. Reuse the current workspace’s access to the intended materials path without changing that path. If access is missing, follow [AI tool access](hosts.md) with the exact required path; the user adds the original directory or grants the needed access. If the target does not exist, use its accessible existing parent to create it as part of saving this delivery, or explain which directory the user must create/open. No silent fallback into the workspace, unrelated probe files or global settings changes. Workspace names and “I added it” are not proof: normal reads establish read access only; actual saves establish write access for that operation. Do not report saved work before the result confirms it.
-4. Write concise initialization notes in .aimship/init.md: the original commission in its own words, language, supplied material locations, adopted copies, explicit user limits and the delivery endpoint. Distinguish the user’s words from your summary. Keep stable context here, current progress in state/status and business changes in formal requirements; date any necessary initialization-time observation so it cannot be mistaken for current execution. Do not duplicate the general workflow or conversation history. Set `language` to `zh-CN` or `en`: an explicit user preference takes precedence, otherwise use the language of this conversation. The Agent saves this delivery setting in init; it is not an installation setting or a command the user must learn. Use init to create state and its generated status.md. An omitted or null endpoint defaults to standard delivery; provide an actual narrower endpoint when the user limits the work. Before PRD exists, use goalRef .aimship/init.md, empty documents and null for unknown documentPolicy conditions/authority (schema 4). A requirements/frame run can be active without a draft; a done result still requires its formal artifact. Do not create empty templates or mark unknown conditions false/none/[] to pass init. Use next for the concrete pending questions/work; no parallel initialization ledger.
+4. Write concise initialization notes in .aimship/init.md: the original commission in its own words, language, supplied material locations, adopted copies, explicit user limits and the delivery endpoint. Distinguish the user’s words from your summary. Keep stable context here, current progress in state/status and business changes in formal requirements; date any necessary initialization-time observation so it cannot be mistaken for current execution. Do not duplicate the general workflow or conversation history. Set `language` to `zh-CN` or `en`: an explicit user preference takes precedence, otherwise use the language of this conversation. The Agent saves this delivery setting in init; it is not an installation setting or a command the user must learn. Use init to create state and its generated status.md. An omitted or null endpoint defaults to standard delivery; provide an actual narrower endpoint when the user limits the work. Before PRD exists, use goalRef .aimship/init.md, empty documents and null for unknown documentPolicy conditions/authority (schema 5). A requirements/frame run can be active without a draft; a done result still requires its formal artifact. Do not create empty templates or mark unknown conditions false/none/[] to pass init. Use next for the concrete pending questions/work; no parallel initialization ledger.
 5. Inspect stateSaved, revision and view from the actual result. Read back the saved state and status entry before reporting complete initialization. If the view failed, preserve the ID/revision and repair it with render; do not init again. If the response was lost, read before retrying. Source-only partial creation resumes at the same intended location after checking its ownership; stale locks require confirming the writer stopped.
 6. Give a concise receipt: initialized / resumed / incomplete, recognizable delivery, actual absolute directory and readable status link (only when available), saved materials, bound version, saved language, code association and checked access, current stage/work and next action. A repository registration alone does not prove access. Do not claim original initialization facts for an old delivery. Separate existing materials retained or copied from documents newly authored or revised and delivery records newly created. Report “unchanged” only when supported by the actual operations and source evidence. For a complete unchanged supplied PRD with clear intent to deliver from it, report input adoption without requesting repeated source approval; clarify only actual uncertainties. On first initialization, add one neutral reminder with the actual directory: add it to the current project/workspace, ignoring this if already added. No tool-specific instructions or membership check are needed. Then continue authorized requirement clarification, unless the user requested a stop.
 
@@ -71,7 +71,7 @@ Standard development order: PRD → technical design → interface/SQL → test
 
 ### 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.
+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. Register approved business batches separately from execution runs. Record review coverage with reviewOf implementation IDs and explicit reviewScope: batch or overall; repairs keep the business batch identity when applicable. 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/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.
 
@@ -79,7 +79,7 @@ Current completion claims require the recorded scope, approvals and actual resul
 
 ## Stage references
 
-Read the reference for the current responsibility, not all stage references on every turn.
+Use [routing](routing.md) to select the current work unit, then read its stage contract. Do not load all stages on every turn. Review dispatch selects a batch, overall or recheck contract; modules are instructions, not separate user commands, agents or isolated contexts.
 
 | Responsibility | Read when | Reference |
 | --- | --- | --- |
@@ -98,9 +98,19 @@ Read the reference for the current responsibility, not all stage references on e
 
 Each run records its scope, required inputs, results and progress. A result may be a section in a shared document. A `done` run records completed work, not human approval. Adopted user input is distinct from reviewed AI output. Proceed when required AI-output approvals or adopted-input checks 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.
 
+## Project context and decisions
+
+Use the relevant current implementation, interfaces, database structures and applicable repository conventions to understand this change. Investigation, design, contract/SQL, implementation and review reuse that context according to their responsibilities. Existing code is evidence, not a requirement to copy it or repair unrelated historical debt. Read the applicable parts of available instructions; when none exist, use the current code/contracts and user requirements and proceed. Do not require a new conventions/context document or whole-project compliance proof.
+
+Investigate facts accessible through the code, documents and tools instead of turning that work into questions for the user. Present only substantive business, authorization or design decisions with their impact, recommendation and dependent work. Hold the work that needs that answer; nonblocking details can remain for later investigation or verification. A design review need not resolve every future execution condition, but must disclose gaps that affect the decision or correctness of the next work.
+
 ## 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 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.
+Complete one authorized implementation work unit (implement → necessary development checks → automatic batch review → authorized repair/recheck), save and report its closure, then stop before the next batch. Compile/type checks and local tests are development self-checks, not code review or formal verification; choose them for the actual change rather than requiring a full suite after every batch. Planned tests can be written with implementation; writing them does not mean they passed. Keep brief development checks and existing evidence references in plan execution.
+
+After the last batch and its review are complete, summarize implementation and remaining work, save and stop. Recommend a new session for the existing overall-review responsibility; do not start it automatically. Explicit authorization to continue overall review in the current session permits that path, without a special phrase, session proof or extra approval record. This also applies to a single business batch: its batch review does not replace overall review. Overall review examines the combined current object and stops before formal verification. A review request alone does not commission execution of the test plan.
+
+After passing overall review, hand over the reviewed object, agreed environment preparation and formal verification scope. Use the actual project conditions: where testing requires a deployed test environment, it must be ready for that execution; local units or other agreed checks need no deployment. Aimship does not initiate deployment or add a deployment stage. Formal RUN records and optional coverage-based groups belong to testing execution. Groups follow coverage and conditions, not development batches; retests are new RUNs, not new business batches.
 
 For standard delivery, registering review/verify/handoff as active or done requires their actual predecessors even when dependsOn or inputRefs are empty: review identifies completed implementation objects (an overall review covers all preceding batches), verification follows a passing overall review and resolved preceding reviews, and handoff follows passing verification or an evidenced passing rerun. Draft documents and planned work may be saved earlier. Independent review, verification or limited handoff requires the existing deliveryPolicy.partialRef to point to readable local evidence of the explicitly limited commission; an empty dependency list is not such authorization. Existing declared dependencies and document approvals still apply. These are state-tool checks, not interception of general-purpose file, test or deployment tools.
 
@@ -110,13 +120,17 @@ Each conclusion identifies who/what produced it, date, object/version, scope, ba
 
 Execution progress (`planned`, `active`, `blocked`, `done`) is separate from pass/fail/not-run/unknown, current applicability, goal achievement and user acceptance. A finished failed verification is still failed. Review is not runtime testing. Neither the presence of a report nor successful tool exit proves the goal.
 
+### Conditional host delegation
+
+Use the host's existing subagent capability when there are independent work blocks and the benefit exceeds coordination cost. Small work, shared-write conflicts or hosts without that capability proceed serially. Do not split frontend/backend automatically. Give each delegated block the relevant approved design/contracts, project context, scope and nonoverlapping write boundary. The main agent gathers required results, checks integration and completes the batch review, then records the delivery facts through the same state tool. Actual delegation is evidenced by host tool activity, not role-played summaries. Delegation adds no delivery stage, business batch, scheduling store, host plugin or proof gate, and does not make results inherently correct.
+
 ## State and stopping
 
 Use the installed tool's documented state protocol. Read the current revision before a write and provide the expected revision; never bypass a conflict by blindly increasing it. State stores summaries and references, not copies of requirements or test reports. Persist the unfinished intent before changing multiple documents, then verify the artifacts before recording completion. No cross-file transaction is promised.
 
 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 each stage boundary, save the completed work and self-check, show its artifacts, current stop and next suggestion, then stop. Recommend a new session at the major boundaries below, without requiring one. Work continuously inside a stage; do not pause after each small step. Existing sessionGroup is only contextual grouping, never permission to cross stages. Each implementation batch and its batch review retain their own results; overall review remains distinct. Do not create a session approval record or require proof of a changed session ID.
+At each user-visible work-unit boundary, save the completed work and self-check, show its artifacts, actual stop and next action, then stop. Implementation and batch review save separate runs as internal checkpoints in one authorized batch work unit; continue its review/repair before the batch stop. A real permission, scope, approval or technical dependency can stop that work earlier. Existing sessionGroup is contextual grouping, not authorization. Overall review and formal verification remain distinct stops. Recommend a new session at the major boundaries below without requiring one; no session approval record or changed-session-ID proof.
 
 Recommend switching after requirements are ready for technical design, after design and applicable contracts before test design, after the plan before implementation, after an implementation batch and its review, and after overall review before independent verification. Combine coinciding boundaries. Directory creation alone, individual documents inside a design group, test design before planning, and implementation before its batch review do not need another suggestion. For a pending document at a major boundary, recommend resuming its review, not starting the next stage. A failed review stays with its repairs.
 
@@ -124,7 +138,7 @@ For a reviewable draft, show only its current stage/status, document entry and r
 
 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.
 
-After a stage is saved, wait for explicit approval where document review is required, or for continuation where it is not. An approval may include “continue”; record it and proceed without a second confirmation. Approval without a continuation request leaves a saved boundary. Never treat “continue” alone as document approval. Continuing in this session needs no session permission. Stage-internal work and authorized repair remain continuous; failures lead to repair/re-review rather than mechanical advancement. At final handoff do not invent a next-session task.
+After a user-visible work unit is saved, wait for explicit approval where document review is required, or for continuation where it is not. An approval may include “continue”; record it and proceed without a second confirmation. Approval without a continuation request leaves a saved boundary. Never treat “continue” alone as document approval. Ordinary continuation in this session needs no session permission; starting overall review after implementation still follows the explicit scope authorization above. Stage-internal work and authorized repair remain continuous; failures lead to repair/re-review rather than mechanical advancement. At final handoff do not invent a next-session task.
 
 At a recommended session boundary or when the user requests continuation help, give current status, artifact and next suggestion, followed by one line in the saved delivery language using the actual absolute directory: “Use Aimship to continue delivery <actual directory>; first read the current state and relevant formal documents, then continue the recorded work.” In Chinese: “使用 Aimship 继续交付「实际目录」，先读取当前状态和相关正式文档再接续。” Do not output placeholders or long prompts at every stage. Full tasks, inputs, deliverable requirements, review stops and unresolved matters stay in existing state/formal documents/rules, not a new prompt or handoff file. A complete prompt may be generated when requested, without an arbitrary length limit.
 
@@ -136,4 +150,4 @@ Small corrections within the original goal can reopen the same delivery: preserv
 
 ## Formal artifacts and generated status
 
-Read [document patterns](document-patterns.md) when establishing or revising the arrangement. All new formal documents use its fixed outlines and [artifact map](artifact-map.json). Schema 4 uses ordinary Markdown and searchable business numbers. Preserve the saved language; do not translate original materials. status.md is generated from structured state; tasks remain in plan.md. read/check/resume are read-only; inspect view and document-change warnings, and use explicit render to repair a stale/missing view. Preserve edits before rebuilding; never infer a business decision from hand-edited display text. After partial view failure use the saved revision, not a repeated business update.
+Read [document patterns](document-patterns.md) when establishing or revising the arrangement. All new formal documents use its fixed outlines and [artifact map](artifact-map.json). Schema 5 / delivery protocol 2 uses ordinary Markdown and searchable business numbers. Preserve the saved language; do not translate original materials. State holds the control facts for batches, runs, reviews, verification coverage and acceptance. Submit domain operations through the current CLI, not replacement control arrays. status.md and the finite generated sections of plan/testing/review derive from those same facts. AI maintains approved definitions, explanations, detailed REV/RUN records and evidence; do not hand-maintain a second progress table. read/check/resume are read-only; inspect view and document-change warnings, and use explicit render to repair a stale/missing view. Preserve edits before rebuilding; never infer a business decision from hand-edited display text. After partial view failure use the saved revision, not a repeated business update.

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

@@ -1,6 +1,6 @@
 # Delivery documents and traceability
 
-[artifact-map.json](artifact-map.json) is the shared mapping for stages, templates and checks. Use [templates](templates/prd.md) for newly authored documents; preserve the ordinary section headings and their order, write visible headings and body in the saved delivery language, and explain inapplicable sections. Use the English or Chinese headings listed in the artifact map; numbered heading prefixes are optional. Keep business IDs and file paths unchanged. Original sources and existing documents are not automatically translated when the language changes. Templates are drafting guidance, not empty artifacts to generate for every delivery.
+[artifact-map.json](artifact-map.json) is the shared mapping for stages, templates and checks. Use [templates](templates/prd.md) for newly authored documents; preserve the ordinary section headings and their order, write visible headings and body in the saved delivery language, and explain inapplicable sections. Use the English or Chinese headings listed in the artifact map; new AI-authored formal Markdown uses an unnumbered document title and numbered body headings (1, 1.1, 1.1.1). This is writing guidance, not another validation gate. Preserve supplied PRDs/prototypes, OpenAPI, SQL and machine files; do not renumber old documents automatically. Pure editorial reconciliation follows the existing approval protocol, while substantive changes still require review. Keep business IDs and file paths unchanged. Original sources and existing documents are not automatically translated when the language changes. Templates are drafting guidance, not empty artifacts to generate for every delivery.
 
 One request has one directory. New deliveries default to separate folders under the bound dataRoot; formal documents are at the delivery folder’s root, not at dataRoot or the current project merely because materials already exist there. `.aimship/init.md` holds the original commission and stable initialization context; adopted external versions stay in `source/` without overwriting. Follow [source retention and editing boundaries](sources-and-changes.md#location-and-version-discipline) for originals, necessary resources and subsequent versions. State, recovery copies, necessary evidence and generated AI-tool configuration belong under `.aimship/`. Generated `status.md` presents stable main stages, current review/questions, next work and registered formal artifacts. Implementation includes batch reviews; overall review is separate. Batches, repairs and repeated runs stay in the state history rather than creating more main-stage rows. No default INDEX, duplicate stage ledger, docs/sql hierarchy, transcript or full export. A requested export is a dated object/version snapshot, never an editing authority.
 
@@ -12,7 +12,7 @@ Use one registered PRD as the requirement authority. If an existing PRD fully fi
 
 A prototype is optional according to the work. Reuse adequate supplied material; create a prototype only when it helps clarify the agreed interaction and is selected for this delivery. Otherwise describe behavior in the PRD/design. A selected prototype needs its current input check when supplied unchanged, or its document approval when AI-authored or substantively revised, before implementation. New HTML uses `prototype/index.html`; other agreed formats may be registered.
 
-`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` separates approved TASK/B definitions from their current execution status: planned, active, code complete, review pending/passed, blocked and remaining work as applicable. Update existing TASK/B status after each batch, retaining necessary dated execution facts and object references. Save phase progress in state and render status; do not copy the full task table into status. `testing.md` keeps cases/coverage, all RUN/retests in its execution section, and a maintained latest conclusion in its final section; verification follows overall review. Updating execution/current results does not reapprove unchanged design. 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` retains approved goals, dependencies and TASK/B definitions in its design sections. Register those batches and record execution/review facts through the state tool. Its finite generated execution section is the one current batch progress table; AI maintains necessary dated execution notes, object references, deviations and blockers outside it. Do not duplicate machine state per TASK or copy the full task table into status. `testing.md` keeps cases/coverage in its design part and detailed formal RUN/retests in execution; its finite generated summary shows current effective coverage/results. `review.md` retains detailed REV findings/repairs/rechecks, while its finite generated section shows current review results. All views consume the same saved facts; none is a second editable state ledger. Brief development checks stay in plan execution with evidence references; retests are new RUNs in the same verification scope, not new development batches; verification follows overall review. Updating execution/current results does not reapprove unchanged design. 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.
 
@@ -49,3 +49,17 @@ Register `documentPolicy` and `documents` per [CLI](../../../docs/cli.md). Draft
 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.
+
+### Finite generated sections
+
+New native plan/testing/review documents reserve these visible H3 sections from their templates, using the saved delivery language:
+
+| Document | English heading | Chinese heading |
+| --- | --- | --- |
+| plan | 5.1 Current batch progress (generated) | 5.1 当前批次进度（由状态生成） |
+| testing | 5.1 Current verification (generated) | 5.1 当前验证结果（由状态生成） |
+| review | 1.1 Current review (generated) | 1.1 当前审查结论（由状态生成） |
+
+Keep the next AI-maintained subsection at the same heading level so the boundary is explicit. The tool owns only the generated H3 body up to the next same/higher heading, not the document or approved definitions. Draft it empty or with the template placeholder; submit facts through the CLI and let render update it. Detailed case expectations, findings, implementation notes, RUN/REV history and evidence remain AI-maintained. Do not move definitions into these sections or hand-edit a displayed result to advance work.
+
+A missing/duplicate section or modified generated body is a view issue, not permission to guess an old table or rewrite the document. Inspect the exact diagnostic and preserve edits before explicitly rebuilding. A view repair uses the saved revision without replaying facts. Source evidence bound to a decision remains immutable; generated refresh must not rewrite that approval basis.

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

@@ -25,10 +25,10 @@ New state has `reviewPolicy: 1` and append-only `reviewHistory`. Use the [CLI re
 
 For new plan/testing templates, approval covers content before the ordinary execution headings mapped to `execution`/`runs` respectively. Subsequent task execution and RUN/conclusion records belong in their later sections; moving changed design into result sections to evade review is forbidden. Other documents and reused formats use the whole registered file. For prototype assets and remotely adopted formats, preserve a readable local fixed-version review basis that identifies every relevant asset/version; report binary/remote inspection limits. Register local/repository linked assets in documents[].assetRefs to bind their bytes; the Agent must check that this set is complete. Do not claim entry-file hashing alone verifies all linked assets.
 
-Stage runs use the agreed array order; by default a run depends on its predecessor. `dependsOn` can state explicit preceding dependencies for independent work, and declared input/output producer links plus earlier selected development prerequisites also apply. Record the reason for changing an arrangement. A pending AI-output review or unresolved input question 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.
+Stage runs retain their actual order and explicit relationships. Design responsibilities follow the selected development sequence; engineering work uses registered batch dependencies, reviewOf coverage and current reviewed/tested objects rather than an automatic dependency on the immediately preceding execution. `dependsOn` can record additional preceding dependencies. Record the reason for changing an arrangement. A pending AI-output review or unresolved input question 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. For a revised supplied input, record the actual updated adoption basis and check the new content without inventing approval; AI-authored or substantively rewritten outputs require renewed approval. Then 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.
+Use existing CHG records to explain semantic changes, affected requirements/documents/runs and the real decision source. Submit their impactRef and affectedRefs so the core can mark the actual dependent batch/review/coverage facts for reassessment. 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. For a revised supplied input, record the actual updated adoption basis and check the new content without inventing approval; AI-authored or substantively rewritten outputs require renewed approval. Then 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 to an approved output, 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.