aimship 0.1.0-preview.20 → 0.1.0-preview.21

package/lib/approvals.mjs

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from 'node:util';
-import { artifactMap, safeRead, hasLocator, sections } from './documents.mjs';
+import { artifactMap, safeRead, hasLocator, sections, definitions } from './documents.mjs';
 import { fail, hash } from './io.mjs';
+import {evaluateRuns} from './domains.mjs';
 
 const text = value => typeof value === 'string' && value.trim().length > 0;
 const reject = message => fail('REVIEW_CHECK', message, 'Read review status. Preserve history, self-check the current document, and record only an actual explicit user decision.');
@@ -33,7 +34,7 @@ export async function reviewFingerprint(directory, state, doc) {
   }
   const assets = [];
   for (const ref of doc.assetRefs ?? []) { const bytes = await safeRead(directory,state,ref,null); if (bytes === null) return null; assets.push([ref,hash(bytes)]); }
-  return hash(assets.length ? JSON.stringify([hash(body),assets]) : body);
+  return hash(assets.length||doc.coverageRefs ? JSON.stringify([hash(body),assets,doc.coverageRefs??null]) : body);
 }
 function decisionFor(state, doc, digest) {
   let approved = null, checked = null, latest = null;
@@ -49,49 +50,6 @@ function decisionFor(state, doc, digest) {
   if (approved?.version !== doc.version || approved?.digest !== digest) approved = null;
   return { approved, checked, latest };
 }
-// A corrective review may consume a failed conclusion without first pretending
-// it passed. Its recorded coverage must include the object it supersedes.
-function reviewsResult(later, earlier) {
-  return later.stage === 'review' && earlier.stage === 'review' && text(earlier.resultRef)
-    && later.historyResultRefs?.includes(earlier.resultRef)
-    && (!earlier.overall || later.overall === true)
-    && (earlier.reviewOf?.length
-      ? earlier.reviewOf.every(id => later.reviewOf?.includes(id))
-      : !later.reviewOf?.length && later.scope === earlier.scope);
-}
-// Required edges for standard delivery are derived from the actual work, not
-// optional inputRefs/dependsOn. Limited commissions retain their selected graph.
-function standardEntry(state, run, index, completed) {
-  const before=state.stageRuns.slice(0,index), dependsOn=[], issues=[];
-  const status=id=>completed.find(r=>r.id===id);
-  const implementations=before.filter(r=>r.stage==='implement');
-  if(run.stage==='review') {
-    const covered=run.reviewOf??[];
-    if(!covered.length) issues.push('entry:implementation-coverage');
-    dependsOn.push(...covered);
-    if(run.overall && implementations.some(r=>!covered.includes(r.id))) issues.push('entry:overall-coverage');
-    for(const id of covered) {
-      const implementation=state.stageRuns.find(r=>r.id===id);
-      if(['failed','mixed','unknown','not-run'].includes(implementation?.result)) issues.push(`entry:implementation-result:${id}`);
-    }
-  } else if(['verify','handoff'].includes(run.stage)) {
-    if(!implementations.length) issues.push('entry:implementation');
-    dependsOn.push(...implementations.map(r=>r.id),...before.filter(r=>r.stage==='review').map(r=>r.id));
-    const overall=before.findLast(r=>r.stage==='review' && r.overall && r.result==='passed' && status(r.id)?.releaseReady && implementations.length && implementations.every(b=>r.reviewOf?.includes(b.id) && before.indexOf(b)<before.indexOf(r)));
-    if(!overall) issues.push('entry:passing-overall-review');
-    if(run.stage==='handoff') {
-      const checks=before.filter(r=>r.stage==='verify');
-      const effective=checks.filter((r,i)=>!checks.slice(i+1).some(later=>status(later.id)?.releaseReady && later.result==='passed' && later.historyResultRefs?.includes(r.resultRef)));
-      if(!effective.length) issues.push('entry:verification');
-      dependsOn.push(...checks.map(r=>r.id));
-      for(const check of effective) {
-        if(check.result!=='passed') issues.push(`entry:verification-result:${check.id}`);
-        if(overall && before.indexOf(check)<before.indexOf(overall)) issues.push(`entry:verification-before-review:${check.id}`);
-      }
-    }
-  }
-  return {dependsOn,issues};
-}
 export async function reviewStatus(directory, state) {
   const map = await artifactMap(), documents = [], evidenceIssues = [], evidenceCache = new Map();
   for (const r of state.reviewHistory ?? []) {
@@ -113,64 +71,16 @@ export async function reviewStatus(directory, state) {
     try { await evidence(directory,state,state.deliveryPolicy.partialRef); limitedScope=true; }
     catch { /* Report an unavailable scope basis; never silently grant an exception. */ }
   }
-  const runs = [], requirement = 'prd';
-  for (const [i, run] of state.stageRuns.entries()) {
-    const spec = map.stages[run.stage];
-    let required = [];
-    if (spec?.humanReview) {
-      const kind = spec.kind === 'requirement' ? requirement : spec.kind;
-      required = (state.documents ?? []).filter(d => d.kind === kind || (run.stage === 'contract' && d.kind === 'sql')).map(d => d.path);
-    }
-    const declared = run.dependsOn ?? (i ? [state.stageRuns[i - 1].id] : []);
-    const producers = state.stageRuns.slice(0, i).filter(r => r.outputRefs.some(out => run.inputRefs.some(input => out.split('#')[0] === input.split('#')[0]))).map(r => r.id);
-    const development = ['requirements','tech-design','contract','test-design','plan','implement'];
-    const prerequisites = development.includes(run.stage) ? state.stageRuns.slice(0,i).filter(r=>development.includes(r.stage) && development.indexOf(r.stage)<development.indexOf(run.stage)).map(r=>r.id) : [];
-    const gated=state.deliveryPolicy?.version===1 && ['review','verify','handoff'].includes(run.stage);
-    const entrance=gated && !limitedScope ? standardEntry(state,run,i,runs) : {dependsOn:[],issues:[]};
-    if(gated && state.deliveryPolicy.partialRef && !limitedScope) entrance.issues.push('entry:limited-scope-evidence');
-    const dependsOn = [...new Set([...declared, ...producers, ...prerequisites,...entrance.dependsOn])];
-    const blockedBy = dependsOn.filter(id => {
-      const dependency = runs.find(r => r.id === id);
-      const original = state.stageRuns.find(r => r.id === id);
-      return !dependency?.releaseReady && !(dependency?.ready && reviewsResult(run, original));
-    });
-    blockedBy.push(...entrance.issues);
-    // An omitted producer run must not turn an unapproved input into permission.
-    // Schema 4 keeps prerequisite approvals even when producer runs are omitted.
-    if (state.schemaVersion === 4) {
-      const needs = [];
-      if (['prototype','tech-design','contract','test-design','plan','implement'].includes(run.stage)) needs.push(requirement);
-      if (['contract','test-design','plan','implement'].includes(run.stage)) needs.push('tech-design');
-      if (['plan','implement'].includes(run.stage) && !state.deliveryPolicy?.partialRef) needs.push('testing');
-      if (run.stage === 'implement') needs.push('plan');
-      if (['test-design','plan','implement'].includes(run.stage)) {
-        if (state.documentPolicy.interface !== null && state.documentPolicy.interface !== 'none') needs.push('contract');
-        if (state.documentPolicy.databases?.length) needs.push('sql');
-      }
-      if (run.stage === 'implement' && state.stageRuns.some(r=>r.stage==='prototype')) needs.push('prototype');
-      for (const kind of needs) {
-        const inputs = (state.documents ?? []).filter(d=>d.kind === kind);
-        if (!inputs.length || inputs.some(d=>!['approved','adopted'].includes(documents.find(r=>r.path===d.path)?.status))) blockedBy.push(`approval:${kind}`);
-      }
-    }
-    const waiting = required.filter(file => !['approved','adopted'].includes(documents.find(d => d.path === file)?.status));
-    const ready = run.progress === 'done' && !['needs-review','unknown'].includes(run.applicability) && !blockedBy.length && !waiting.length && (!spec?.humanReview || required.length > 0);
-    const releaseReady = ready && (run.stage !== 'review' || run.result === 'passed');
-    runs.push({ id: run.id, stage: run.stage, progress: run.progress, applicability: run.applicability, documents: required, waiting, dependsOn, blockedBy, ready, releaseReady });
-    if (releaseReady && run.stage === 'review') {
-      for (const earlier of runs.slice(0,-1)) {
-        if (earlier.ready && reviewsResult(run, state.stageRuns.find(r=>r.id===earlier.id))) {
-          earlier.releaseReady = true;
-          earlier.resolvedBy = run.id;
-        }
-      }
-    }
-  }
+  let expectedCoverage=[];
+  const testing=state.documents.find(d=>d.kind==='testing');
+  if(testing){const body=await safeRead(directory,state,testing.path).catch(()=>null);expectedCoverage=testing.mode==='new'&&body?definitions(body,testing.path,map.documents.testing).filter(d=>d.id.startsWith('TC-')).map(d=>testing.path+'#'+d.id):(testing.coverageRefs??[]);}
+  const execution=evaluateRuns(state,documents,map,{limitedScope,expectedCoverage,evidenceIssues});
+  const runs=execution.runs;
   const current = runs.find(r => r.id === state.currentRun);
   const pending = runs.filter(r => r.progress !== 'planned').flatMap(r => r.waiting.map(document => ({ run: r.id, document, status: documents.find(d => d.path === document)?.status })));
   const nextRun = runs.find(r => !r.ready);
   const nextStage = current ? runs[runs.indexOf(current) + 1]?.stage ?? null : nextRun?.stage ?? null;
-  return { compatibility: 'current', documents, runs, pending, evidenceIssues, currentRun: current?.id ?? null, nextRun: nextRun?.id ?? null, nextStage, canProceed: !state.next.questionRef && (current ? !current.blockedBy.length && !(current.progress === 'done' && !current.releaseReady) && current.progress !== 'blocked' && !['needs-review','unknown'].includes(current.applicability) : !pending.length && !runs.some(r=>r.progress==='blocked' || (r.progress === 'done' && !r.releaseReady) || (r.progress !== 'planned' && r.blockedBy.length) || ['needs-review','unknown'].includes(r.applicability))), identity: 'Record validation only; user identity, intent and source authenticity are not authenticated.' };
+  return { compatibility: 'current', execution, documents, runs, pending, evidenceIssues, currentRun: current?.id ?? null, nextRun: nextRun?.id ?? null, nextStage, canProceed: !state.next.questionRef && (current ? !current.blockedBy.length && !(current.progress === 'done' && !current.releaseReady) && current.progress !== 'blocked' && !['needs-review','unknown'].includes(current.applicability) : !pending.length && !runs.some(r=>r.progress==='blocked' || (r.progress === 'done' && !r.releaseReady) || (r.progress !== 'planned' && r.blockedBy.length) || ['needs-review','unknown'].includes(r.applicability))), identity: 'Record validation only; user identity, intent and source authenticity are not authenticated.' };
 }
 async function evidence(directory, state, ref) {
   if (!text(ref) || ref.includes('\\') || ref.split('#')[0].split('/').includes('..') || ref.startsWith('/') || (/^[a-zA-Z]:/.test(ref) && !ref.startsWith('repo:'))) reject('Review evidence must stay inside a registered root.');
@@ -214,34 +124,45 @@ export async function enforceReviews(directory, state, previous) {
     const a = first(order[i]), b = first(order[j]);
     if (a >= 0 && b >= 0 && a > b && !previous?.stageRuns.some(r => r.id === state.stageRuns[b].id && r.progress !== 'planned')) reject(`${order[i]} must precede ${order[j]} in the initial development arrangement.`);
   }
-  const restoring = new Set(state.stageRuns.filter(r=>r.applicability === 'current' && previous?.stageRuns.some(old=>old.id===r.id && old.applicability==='needs-review')).map(r=>r.id));
-  let status = await reviewStatus(directory, state);
-  // Invalidate only registered producer/dependency paths. Independent branches retain their facts.
-  const affected = new Set(revisedApprovedPrd ? status.runs.filter(r=>r.stage==='requirements' && r.progress!=='planned').map(r=>r.id) : []);
-  for (const doc of state.documents) {
-    const oldDoc = previous?.documents?.find(d => d.path === doc.path);
-    const latest = oldHistory.filter(r => r.document === doc.path && (['approved','editorial'].includes(r.kind) || (oldDoc?.mode==='input' && r.kind==='self-check' && r.result==='passed'))).at(-1);
-    const now = status.documents.find(d => d.path === doc.path);
-    if (!oldDoc || !latest || !now) continue;
-    const changed = latest.digest !== now.digest || latest.version !== doc.version;
-    const editorial = state.reviewHistory.slice(oldHistory.length).some(r=>r.document===doc.path && r.kind==='editorial' && r.digest===now.digest);
-    const requested = state.reviewHistory.slice(oldHistory.length).some(r=>r.document===doc.path && (r.kind==='changes-requested' || (r.kind==='self-check' && r.result==='failed')));
-    if ((!changed && !requested) || editorial) continue;
-    if (changed && !state.openChanges.some(c => c.status === 'open')) reject(`${doc.path}: record the material change and impact in an open CHG, or self-check an editorial reconciliation.`);
-    if (changed && ['approved','adopted'].includes(now.status) && doc.version === latest.version) reject(`${doc.path}: a material revision needs a new document version; use editorial only for unchanged meaning.`);
-    for (const r of status.runs.filter(r => r.documents.includes(doc.path) && r.progress !== 'planned')) affected.add(r.id);
+  let status=await reviewStatus(directory,state);
+  const addedChanges=state.openChanges.filter(c=>!previous?.openChanges.some(old=>JSON.stringify(old)===JSON.stringify(c)));
+  const affected=new Set();
+  for(const doc of state.documents){
+    const priorDoc=previous?.documents.find(d=>d.path===doc.path),oldApproval=oldHistory.findLast(r=>r.document===doc.path&&(['approved','editorial'].includes(r.kind)||(priorDoc?.mode==='input'&&r.kind==='self-check'&&r.result==='passed')));
+    const now=status.documents.find(d=>d.path===doc.path);if(!priorDoc||!oldApproval||!now)continue;
+    const changed=oldApproval.digest!==now.digest||oldApproval.version!==doc.version;
+    const previousContentChanged=previous.documentDigests?.[doc.path]!==state.documentDigests?.[doc.path]||priorDoc.version!==doc.version;
+    const editorial=state.reviewHistory.slice(oldHistory.length).some(r=>r.document===doc.path&&r.kind==='editorial');
+    if(!changed||editorial)continue;
+    const change=(previousContentChanged?addedChanges:state.openChanges).find(c=>c.impactRef&&Array.isArray(c.affectedRefs));
+    if(!change)reject(`${doc.path}: record the material change and scoped impact, or reconcile a true editorial change.`);
+    if(['approved','adopted'].includes(now.status)&&doc.version===oldApproval.version)reject(`${doc.path}: material content needs a new version.`);
+    if(!previousContentChanged)continue;
+    for(const r of state.stageRuns){if(r.stage==='verify'){const refs=(r.coverageRefs??[]).filter(ref=>change.affectedRefs.includes(ref)||change.affectedRefs.includes(doc.path));r.invalidCoverageRefs=[...new Set([...(r.invalidCoverageRefs??[]),...refs])];}if(r.progress!=='planned'&&(r.outputRefs.includes(doc.path)&&!['implement','review','verify'].includes(r.stage)||change.affectedRefs.some(ref=>r.inputRefs.includes(ref)||r.outputRefs.includes(ref)||r.resultRef===ref||state.batches.some(b=>b.id===r.batchId&&(b.definitionRef===ref||b.taskRefs.includes(ref))))))affected.add(r.id);}
   }
-  for (const r of status.runs) if (r.dependsOn.some(id => affected.has(id))) affected.add(r.id);
-  for (const r of state.stageRuns) if (affected.has(r.id) && r.progress !== 'planned') r.applicability = 'needs-review';
-  status = await reviewStatus(directory, state);
-  const previousStatus = previous?.reviewPolicy === 1 ? await reviewStatus(directory, previous) : null;
-  for (const run of state.stageRuns) {
-    const old = previous?.stageRuns.find(r => r.id === run.id);
-    const progressing = ['active','done'].includes(run.progress) && (!old || old.progress !== run.progress || old.resultRef !== run.resultRef || restoring.has(run.id));
-    if (restoring.has(run.id) && run.applicability === 'needs-review') reject(`${run.id}: current document or dependency still needs review.`);
-    if (progressing && status.runs.find(r => r.id === run.id).blockedBy.length) reject(`${run.id}: prerequisite completion, approval or affected dependency is unresolved.`);
-    if (old && old.progress !== 'planned' && previousStatus && !previousStatus.runs.find(r=>r.id===old.id).dependsOn.every(id=>status.runs.find(r=>r.id===run.id).dependsOn.includes(id))) reject(`${run.id}: preserve started dependencies; record revised work as a new run.`);
+  // A new authority or an explicit scoped impact need not edit the same file.
+  for(const change of addedChanges){const old=previous?.openChanges.find(c=>c.id===change.id);if(!change.impactRef||!change.affectedRefs||old&&old.impactRef===change.impactRef&&JSON.stringify(old.affectedRefs)===JSON.stringify(change.affectedRefs))continue;
+    for(const r of state.stageRuns){if(r.progress==='planned')continue;const refs=change.affectedRefs;if(r.stage==='verify'){const invalid=(r.coverageRefs??[]).filter(ref=>refs.includes(ref)||refs.includes(ref.split('#')[0]));r.invalidCoverageRefs=[...new Set([...(r.invalidCoverageRefs??[]),...invalid])];}
+      if(refs.some(ref=>r.inputRefs.includes(ref)||r.outputRefs.includes(ref)||r.resultRef===ref||state.batches.some(b=>b.id===r.batchId&&(b.definitionRef===ref||b.taskRefs.includes(ref)))))affected.add(r.id);
+    }
+  }
+  let changed=true;while(changed){const size=affected.size,affectedB=new Set(state.stageRuns.filter(r=>affected.has(r.id)&&r.batchId).map(r=>r.batchId));for(const b of state.batches)if(b.dependsOn.some(id=>affectedB.has(id)))for(const r of state.stageRuns.filter(r=>r.batchId===b.id&&r.progress!=='planned'))affected.add(r.id);for(const r of state.stageRuns)if([...(r.dependsOn??[]),...(r.reviewOf??[])].some(id=>affected.has(id)))affected.add(r.id);changed=affected.size!==size;}
+  for(const r of state.stageRuns)if(affected.has(r.id))r.applicability='needs-review';
+  status=await reviewStatus(directory,state);
+  for(const r of state.stageRuns)if(r.applicability==='needs-review'&&!['implement','review','verify','handoff'].includes(r.stage)&&state.reviewHistory.slice(oldHistory.length).some(h=>r.outputRefs.includes(h.document)&&['approved','editorial','self-check'].includes(h.kind))&&r.outputRefs.length&&r.outputRefs.every(ref=>['approved','adopted'].includes(status.documents.find(d=>d.path===ref)?.status)))r.applicability='current';
+  status=await reviewStatus(directory,state);
+  for(const run of state.stageRuns){
+    const old=previous?.stageRuns.find(r=>r.id===run.id);
+    const progressing=['active','done'].includes(run.progress)&&(!old||old.progress!==run.progress||old.resultRef!==run.resultRef||old.applicability==='needs-review'&&run.applicability==='current');
+    const recovering=old&&['needs-review','unknown'].includes(old.applicability)&&run.applicability==='current';
+    const currentEntry=recovering?await reviewStatus(directory,{...state,stageRuns:state.stageRuns.map(r=>r.id===run.id?{...r,approvalBasis:undefined}:r)}):status;
+    if((progressing||recovering)&&currentEntry.runs.find(r=>r.id===run.id).blockedBy.length)reject(`${run.id}: prerequisite completion, approval or affected work is unresolved.`);
+    const rs=status.runs.find(r=>r.id===run.id);
+    if(run.progress==='done'&&rs.ready&&!run.approvalBasis?.length){
+      const relevant=status.documents.filter(d=>['approved','adopted'].includes(d.status));
+      run.approvalBasis=relevant.map(d=>{const event=state.reviewHistory.findLast(h=>h.document===d.path&&h.digest===d.digest&&['approved','editorial','self-check'].includes(h.kind));return {document:d.path,digest:d.digest,recordId:event.id};});
+    }
   }
-  if (state.outcome.goal === 'met' && previous?.outcome.goal !== 'met' && status.runs.some(r => !r.ready)) reject('Resolve selected stages and document approvals before declaring the goal met.');
+  if (state.outcome.goal === 'met' && previous?.outcome.goal !== 'met' && status.runs.some(r => !r.ready&&!r.resolvedBy&&r.stage!=='verify')) reject('Resolve selected stages and document approvals before declaring the goal met.');
   return status;
 }

package/lib/cli.mjs

@@ -19,7 +19,7 @@ const HELP = {
     bind: 'Resolve active installation once. Returns immutable release/core/stage/CLI paths plus configured dataRoot, configPath and customPath. Source mode returns the default data root with null config/custom paths. No directories are created. Optional --home is for isolated testing.',
     init: 'init <dir> --input <json-file|-> --rules-version <version>. Create state once; input requires goal.summary, language (en or zh-CN) and saved .aimship/init.md; directory must be a child of bound dataRoot unless storage has an explicit local decisionRef; endpoint defaults to standard delivery; artifact conditions may remain null (unknown). Does not create templates.',
     read: 'read <dir> [--rules-version <version>] [--delivery-id <known-id>]. Read current delivery state without executing work.',
-    update: 'update <dir> --revision <N> --rules-version <version> --input <json-file|->. Recursively merge objects; arrays replace in full. Identity/history fields are managed. null is a literal value, not deletion.',
+    update: 'update <dir> --revision <N> --rules-version <version> --input <json-file|->. Merge ordinary metadata; record controlled facts with operations. Identity/history fields are managed. null is a literal value, not deletion.',
     check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Checks ordinary Markdown sections and searchable numbers in new local Markdown; reused and unsupported fragments are explicitly not checked. Does not prove semantics, remote access or validation results.',
     resume: 'resume <dir> [--rules-version <version>] [--delivery-id <known-id>]. Read state and return fixed rule paths, required inputs, warnings, and continuation text; never execute work or rewrite state.',
     recover: 'recover <dir> --revision <backup-revision> --rules-version <version>. Restore state.previous.json only over missing/corrupt state; preserve corrupted bytes. Inspect actual artifacts afterward; nothing reruns.',
@@ -32,8 +32,9 @@ const HELP = {
     protocolVersion: PROTOCOL_VERSION,
     documentReview: {reviewPolicy:1, reviewHistory:'Append-only {id,kind,document,version,digest,sourceRef,summary}. self-check requires result: passed|failed; approved requires decision: explicit-approval; editorial requires previousDigest. Read review.documents for current digests. Tools validate records, not user identity. See docs/cli.md#document-review-protocol.'},
     deliveryPolicy: 'New states default to {version:1}; partialRef identifies an explicitly limited scope, null restores standard scope with a new goal decision. Completion is derived separately from goal/acceptance.',
-    implementationWork: 'Optional implement-only workType: batch|repair and repairOf: preceding run IDs. They classify scope for display/advice, never omit implementation from review coverage. Without a purpose, pre-overall work retains legacy batch meaning; later work is unclassified until its actual basis is checked. No implicit state rewrite.',
-    sessions: 'run.sessionGroup is an advisory context group, auto-filled for new runs; reviewOf names implementation runs and overall:true identifies overall review. read/check/resume expose session/completion. Supplied PRD/prototype mode input uses the actual request basisRef and self-check, not human approval. next.questionRef identifies a concrete question on a blocked stage (clear with null). Completed work units stop with await-review, await-clarification or await-continue. Implementation checkpoints can return continue-implementation-review, and failed batch reviews continue-batch-repair within existing authorization, without starting the next batch. Overall review stops before verify; suggestNewSession is advisory. Failed view saving returns reconcile-save. No new approval or automatic execution.',
+    implementationWork: 'Started implementation requires workType batch|repair; business work has registered batchId. Repairs retain B identity and prior result references. Completed implement/review/verify records require objectKey SHA-256 for the actual object. reviewScope is batch|overall; reviewOf covers actual work. Formal verify declares coverageRefs and optional per-coverage results; historyResultRefs links rechecks/retests.',
+    operations: ['register-batches','record-run','remove-planned-run','record-review','record-change','record-outcome','set-current','set-applicability'],
+    sessions: 'One batch includes automatic batch review and authorized repair/recheck before stopping. After the last batch recommend a fresh session for the existing overall review, unless explicitly authorized here. Overall review stops before formal verification. Host delegation is conditional and adds no stage or business batch. Session advice executes nothing and grants no approval.',
     stages: STAGES,
     progress: ['planned', 'active', 'blocked', 'done'],
     result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
@@ -42,15 +43,16 @@ const HELP = {
     stageInstance: { id: 'stable-instance-id', stage: '<stage>', scope: 'batch or whole-delivery scope', progress: 'planned', inputRefs: [], outputRefs: [], resultRef: 'review.md#REV-001 (required when done)' },
     references: 'delivery-relative/path#optional-fragment, repo:<registered-id>/<repo-relative-path>#fragment, or HTTP(S) URL. Local paths cannot escape their root. Repository registration: {id, path: absolute-path, role}.',
     topLevel: {
-      managed: 'schemaVersion, protocolVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, documentDigests, writeResult. Do not supply these in init/update. rulesVersion records the last saving tool; protocolVersion identifies compatible delivery semantics. Legacy 17/18 without it map precisely to protocol 1. Reads never adopt metadata; the next normal save records current tool/protocol without rewriting documents or revoking unchanged approvals.',
+      managed: 'schemaVersion, protocolVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, documentDigests, writeResult. Do not supply these in init/update. rulesVersion records the last saving tool; protocolVersion identifies compatible delivery semantics. Legacy 17/18 without it map precisely to protocol 1. Reads never adopt metadata; protocol 2 does not continue schema4/protocol1 deliveries. No migration or version-field rewrite.',
       requiredInit: 'language: en|zh-CN and goal: {summary, endpoint?}; save nonempty initialization notes in .aimship/init.md before init. Defaults: endpoint standard delivery, goalRef .aimship/init.md, empty documents, and null documentPolicy conditions/authority. Register PRD and switch goalRef when drafted; no empty templates.',
       language: 'en or zh-CN from explicit user preference, otherwise this delivery conversation. Required in current state; retained on update/render/resume.',
       storage: 'Init-only {mode: explicit, decisionRef: delivery-relative-readable-file} for a user-selected location. Otherwise a strict child of configured dataRoot. Returned dataRoot is managed; ordinary workspace/material location is not a choice.',
-      stageRuns: 'Ordered array of stageInstance objects, default []. Every ID is unique; currentRun must match one of these IDs or be null. Stage types may repeat with distinct IDs.',
-      currentRun: 'Instance ID or null (default). Do not invent an ID without registering its instance in stageRuns.',
+      stageRuns: 'Ordered execution history, default []; update through record-run, not raw replacement. Every ID is unique; currentRun must match one of these IDs or be null. Stage types may repeat with distinct IDs.',
+      batches: 'Stable registered B definitions {id,definitionRef,taskRefs,dependsOn}; register-batches requires the current approved plan. Separate from implementation/repair runs.',
+      currentRun: 'Instance ID or null (default); update through set-current. Do not invent an ID without registering its instance in stageRuns.',
       repositories: 'Array of {id, path: absolute-path, role, ...optional-version-facts}, default []. No repository is required for a design-only goal.',
-      openChanges: 'Array of {id, ref, status: open|closed}, default []; close records rather than deleting history.',
-      outcome: 'Defaults to {goal: in-progress, acceptance: not-recorded}. A met goal needs goalConclusionRef; recorded acceptance needs acceptanceRef. Optional handoffRef, mergeRef, deploymentRef retain independent facts.',
+      openChanges: 'Array of {id,ref,status:open|closed,impactRef?,affectedRefs?}, default []; use record-change; close records rather than deleting history.',
+      outcome: 'Managed via record-outcome; defaults to {goal: in-progress, acceptance: not-recorded}. A met goal needs goalConclusionRef; recorded acceptance needs acceptanceRef. Optional handoffRef, mergeRef, deploymentRef retain independent facts.',
       next: '{action, inputRefs?: []}; defaults to continuing the confirmed arrangement.',
       cycle: 'Positive integer, default 1. A reopening increments by one, appends a closureRef and resets current acceptance.',
       closureRefs: 'Historical closure references, default []. Preserve them across reopenings.'

package/lib/delivery.mjs

@@ -22,42 +22,28 @@ export function arrangeSessions(state) {
   for (const r of state.stageRuns) {
     if (r.sessionGroup) continue;
     const category = ['frame','requirements'].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;
+    const batch = r.stage === 'review' && r.reviewScope==='batch' && 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=[]}={}) {
-  const runs=state.stageRuns, gaps=[];
-  if (state.goal.endpoint === null) gaps.push('Delivery endpoint remains unknown.');
-  if (state.documentPolicy.authority === null || unknownConditions(state.documentPolicy).length) gaps.push('Artifact conditions remain unknown.');
-  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=>r.stage==='requirements' && ready(r))) gaps.push('Missing reviewed requirements.');
-  if (((state.documentPolicy?.interface!=null && state.documentPolicy.interface!=='none') || state.documentPolicy?.databases?.length) && !has('contract')) gaps.push('Missing applicable interface/SQL contract.');
-  if (runs.some(r=>r.stage==='prototype') && !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=>!review.runs.find(x=>x.id===r.id)?.resolvedBy);
-  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:gaps.map(g=>completionMessage(state,g)),partialRef:state.deliveryPolicy.partialRef??null,scope:text(state,'Recorded structure, approvals and results only; not independent proof of test execution or semantic quality.','仅评估已记录的结构、审批和结果；不独立证明测试已执行或内容语义正确。')};
+export function completionStatus(state,review,{changed=[]}={}) {
+ const gaps=[],model=review.execution;
+ const has=stage=>state.stageRuns.some(r=>r.stage===stage&&review.runs.find(s=>s.id===r.id)?.ready);
+ if(state.goal.endpoint===null)gaps.push('Delivery endpoint remains unknown.');
+ if(state.documentPolicy.authority===null||unknownConditions(state.documentPolicy).length)gaps.push('Artifact conditions remain unknown.');
+ if(changed.length)gaps.push('Changed or missing registered documents require reconciliation.');
+ for(const stage of ['requirements','tech-design','test-design','plan','implement','verify','handoff'])if(!has(stage))gaps.push(`Missing current completed ${stage}.`);
+ if((state.documentPolicy.interface!==null&&state.documentPolicy.interface!=='none'||state.documentPolicy.databases?.length)&&!has('contract'))gaps.push('Missing applicable interface/SQL contract.');
+ if(state.stageRuns.some(r=>r.stage==='prototype')&&!has('prototype'))gaps.push('Missing applicable interaction prototype.');
+ if(!model?.batches.length||model.batches.some(b=>b.status!=='complete'))gaps.push('Business batches or their reviews remain unresolved.');
+ if(!model?.overall)gaps.push('Missing passing overall implementation review.');
+ const handoff=state.stageRuns.findLast(r=>r.stage==='handoff'&&review.runs.find(s=>s.id===r.id)?.ready);
+ if(handoff&&model?.verification.runIds.some(id=>state.stageRuns.findIndex(r=>r.id===id)>state.stageRuns.indexOf(handoff)))gaps.push('Handoff precedes verification.');
+ if(!model?.verification.passed)gaps.push('Independent verification is not fully recorded as passed after overall review.');
+ if(review.runs.some(s=>!s.ready&&!s.resolvedBy&&s.stage!=='verify'))gaps.push('Selected work or document approvals remain unresolved.');
+ if(state.openChanges.some(c=>c.status==='open'))gaps.push('Unresolved changes remain.');
+ const partial=!!state.deliveryPolicy.partialRef,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:gaps.map(g=>completionMessage(state,g)),partialRef:state.deliveryPolicy.partialRef??null,scope:text(state,'Recorded facts and current dependencies only; not proof of semantic quality.','仅评估记录与当前依赖；不证明业务质量。')};
 }
 // A display suggestion, never a scheduled run or authorization.
 export function suggestedNextStage(state) {
@@ -67,7 +53,7 @@ export function suggestedNextStage(state) {
   if(state.deliveryPolicy.partialRef)return null;
   if(!current)return 'requirements';
   const contracts=(state.documentPolicy.interface!=null && state.documentPolicy.interface!=='none') || state.documentPolicy.databases?.length;
-  return ({frame:'requirements',requirements:'tech-design',prototype:'tech-design','tech-design':contracts?'contract':'test-design',contract:'test-design','test-design':'plan',plan:'implement',implement:'review',review:current.overall?'verify':'review',verify:'handoff'})[current.stage]??null;
+  return ({frame:'requirements',requirements:'tech-design',prototype:'tech-design','tech-design':contracts?'contract':'test-design',contract:'test-design','test-design':'plan',plan:'implement',implement:'review',review:(current.reviewScope==='overall')?'verify':'review',verify:'handoff'})[current.stage]??null;
 }
 function majorSessionBoundary(state,current) {
   if (!current || current.progress !== 'done') return false;
@@ -77,7 +63,7 @@ function majorSessionBoundary(state,current) {
   if (['tech-design','contract'].includes(current.stage)) return next==='test-design';
   if (current.stage==='plan') return next==='implement';
   if (current.stage==='review' && current.result==='passed') {
-    return current.overall ? next==='verify' : !!current.reviewOf?.length && ['implement','review'].includes(next);
+    return (current.reviewScope==='overall') ? next==='verify' : !!current.reviewOf?.length && ['implement','review'].includes(next);
   }
   return false;
 }
@@ -101,7 +87,6 @@ export function sessionAdvice(directory,state,review,{saved=true}={}) {
   else if(!current && state.stageRuns.length && review.runs.every(r=>r.ready)) action=concluded?endAction:review.runs.some(r=>r.releaseReady===false)?'resolve-current':endAction;
   else if(current && ((!status?.resolvedBy && (['failed','mixed','unknown','not-run'].includes(current.result) || (current.stage==='review' && current.progress==='done' && !status?.releaseReady))) || current.progress==='blocked' || ['needs-review','unknown'].includes(current.applicability))) action=concluded && !next?'finished':'resolve-current';
   else if(status?.ready) action=!next?endAction:next.progress!=='planned'?'inspect-existing-work':'await-continue';
-  if (saved && !pending && state.deliveryPolicy?.version === 1 && status?.ready && next && review.runs.find(r=>r.id===next.id)?.blockedBy.length) action='resolve-current';
   // Internal checkpoints execute nothing and never release another batch.
   let reviewScope=null;
   if (saved && !concluded && !pending && !state.next.questionRef && status?.ready && current?.progress==='done' && !['needs-review','unknown'].includes(current.applicability)) {
@@ -111,7 +96,7 @@ export function sessionAdvice(directory,state,review,{saved=true}={}) {
       const selectedReview=next?.stage==='review' && next.reviewOf?.includes(current.id);
       if(reviewScope && !reviewed && (!state.deliveryPolicy.partialRef || selectedReview))action='continue-implementation-review';
       else if(!reviewScope && !reviewed && implementationType(state,current)==='repair')action='inspect-review-scope';
-    } else if(current.stage==='review' && !status.resolvedBy && current.overall!==true && current.reviewOf?.length && ['failed','mixed'].includes(current.result)) action='continue-batch-repair';
+    } else if(current.stage==='review' && !status.resolvedBy && (current.reviewScope==='overall')!==true && current.reviewOf?.length && ['failed','mixed'].includes(current.result)) action='continue-batch-repair';
   }
   const suggestNewSession=['await-review','await-continue'].includes(action) && majorSessionBoundary(state,current);
   let instruction=action==='await-clarification'?text(state,'Please answer the question listed below so this work can continue.','请回答下一步所列的具体问题，以便继续当前工作。'):action==='await-continue'?text(state,'This stage is saved. Say “continue” when ready.','本阶段已保存。准备好后可说“继续”。'):action==='assess-outcome'?text(state,'Review the handoff against the agreed goal and record the actual goal conclusion and acceptance; completed handoff alone does not end the delivery.','请对照约定目标审阅交付材料，记录实际目标结论和用户接受结果；完成交付文档不等于交付已结束。'):null;
@@ -120,5 +105,5 @@ export function sessionAdvice(directory,state,review,{saved=true}={}) {
   if(action==='continue-batch-repair')instruction=text(state,'Repair and recheck this batch within the existing authorization; stop for a scope, approval or permission dependency.','在已有授权内修复并复查本批；遇范围、审批或权限依赖时停在实际问题。');
   if(suggestNewSession) instruction=[instruction,action==='await-review'?text(state,'A new session is recommended to review this document; you can also review it here.','建议新开会话审阅本份文档，也可留在这里审核。'):text(state,'A new session is recommended for the next work; you can also continue here.','建议新开会话接续下一步，也可留在这里继续。')].filter(Boolean).join(' ');
   const continuation=['reconcile-save','await-review','await-clarification','assess-outcome','finished'].includes(action)?null:text(state,`Use Aimship to continue delivery ${JSON.stringify(path.resolve(directory))}; first read its current state and relevant formal documents, then continue the recorded work.${instruction?' '+instruction:''}`,`使用 Aimship 继续交付「${path.resolve(directory)}」，先读取当前状态和相关正式文档再接续。${instruction??''}`);
-  return {action,stop:!['continue-current','inspect-existing-work','continue-implementation-review','continue-batch-repair','inspect-review-scope'].includes(action),suggestNewSession,reviewScope,currentRun:current?.id??null,nextRun:action==='continue-implementation-review'?(next?.stage==='review' && next.reviewOf?.includes(current.id) && (reviewScope==='overall-recheck' ? next.overall===true : !next.overall)?next.id:null):['continue-batch-repair','inspect-review-scope'].includes(action)?null:next?.id??null,groups,continuation,instruction,advisory:true,note:text(state,'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.','会话边界不是阻塞或批准。用户要求时可在当前会话继续。每次续接都需核对交付身份、当前审批和未完成事项；本提示不授予权限。')};
+  return {action,stop:!['continue-current','inspect-existing-work','continue-implementation-review','continue-batch-repair','inspect-review-scope'].includes(action),suggestNewSession,reviewScope,currentRun:current?.id??null,nextRun:action==='continue-implementation-review'?(next?.stage==='review' && next.reviewOf?.includes(current.id) && (reviewScope==='overall-recheck' ? next.reviewScope==='overall' : next.reviewScope==='batch')?next.id:null):['continue-batch-repair','inspect-review-scope'].includes(action)?null:next?.id??null,groups,continuation,instruction,advisory:true,note:text(state,'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/documents.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { hash, inside, fail } from './io.mjs';
+import {strippedGenerated} from './projections.mjs';
 
 export async function artifactMap() {
   return JSON.parse(await fs.readFile(new URL('../skills/aimship/references/artifact-map.json', import.meta.url), 'utf8'));
@@ -130,14 +131,14 @@ export async function inspectDocuments(directory, state) {
   for (const kind of new Set(docs.map(d=>d.kind))) if (!['sql','source'].includes(kind) && docs.filter(d=>d.kind===kind).length>1) issues.push(`Register one current artifact for ${kind}; keep history through references.`);
   const requirementKind = 'prd';
   const find = kind => docs.find(d => d.kind === (kind === 'requirement' ? requirementKind : kind));
-  if (state.schemaVersion === 4) {
+  if (state.schemaVersion === 5) {
     try {
       const request = await safeRead(directory,state,'.aimship/init.md');
       if (!request?.trim()) issues.push('Missing or empty .aimship/init.md.');
       else digests['.aimship/init.md'] = hash(request);
     } catch { issues.push('Cannot read .aimship/init.md inside this delivery.'); }
   }
-  const preparing = state.schemaVersion === 4 && !find('requirement');
+  const preparing = state.schemaVersion === 5 && !find('requirement');
   if (preparing && state.goalRef !== '.aimship/init.md') issues.push('Before requirements exist, goalRef must point to .aimship/init.md.');
   if (!preparing && !find('requirement')) issues.push(`Register ${requirementKind} as the requirement entry.`);
   if (!preparing && policy.authority === null) issues.push('Select the requirement authority when registering PRD.');
@@ -154,7 +155,7 @@ export async function inspectDocuments(directory, state) {
     try { text = await safeRead(directory, state, doc.path); }
     catch (error) { issues.push(`Cannot read ${doc.path}: ${error.code}`); continue; }
     if (text === null) { unchecked.push(`${doc.path}: remote or unavailable repository; inspect adopted version using host tools (${doc.basisRef ?? 'missing basisRef'}).`); continue; }
-    digests[doc.path] = hash(text);
+    digests[doc.path] = hash(doc.mode==='new'?strippedGenerated(text,doc.kind):text);
     if (!text.trim()) issues.push(`${doc.path}: empty document.`);
     if (doc.mode !== 'new') {
       // Reuse is a current input option, not a historical document protocol.
@@ -178,7 +179,7 @@ export async function inspectDocuments(directory, state) {
   const runs = state.stageRuns;
   for (const [i, run] of state.stageRuns.entries()) {
     if (run.progress === 'planned') continue;
-    const contract = map.stages[run.stage], doc = find(contract.kind) ?? (run.stage === 'contract' && policy.interface === 'none' ? find('sql') : null);
+    const contract = map.stages[run.stage], formerAuthority=run.stage==='requirements'&&run.approvalBasis?.length&&state.goalHistory?.some(h=>h.goalRef?.split('#')[0]===run.resultRef?.split('#')[0])?docs.find(d=>d.kind==='source'&&d.path===run.resultRef?.split('#')[0]):null, doc = formerAuthority ?? find(contract.kind) ?? (run.stage === 'contract' && policy.interface === 'none' ? find('sql') : null);
     if (!doc && preparing && ['frame','requirements'].includes(run.stage) && run.progress !== 'done') continue;
     if (!doc) { issues.push(`${run.id}: missing registered ${contract.kind} artifact.`); continue; }
     if (run.stage === 'implement' && !state.stageRuns.slice(0,i).some(r => r.stage === 'plan' && r.progress === 'done')) issues.push(`${run.id}: complete plan before implementation.`);
@@ -207,7 +208,7 @@ export async function inspectDocuments(directory, state) {
       }
     }
   }
-  if (state.schemaVersion === 4) {
+  if (state.schemaVersion === 5) {
     const unknown = unknownConditions(policy);
     const dependent = runs.filter(r=>r.progress !== 'planned' && !['frame','requirements','diagnose'].includes(r.stage));
     if (preparing && dependent.length) issues.push('Prepare and review formal requirements before dependent work.');
@@ -263,7 +264,7 @@ export async function inspectDocuments(directory, state) {
 export async function documentChanges(directory, state) {
   const changes=[];
   for (const [ref, digest] of Object.entries(state.documentDigests ?? {})) {
-    try { const text = await safeRead(directory,state,ref); if (text === null || hash(text) !== digest) changes.push(ref); }
+    try { const text = await safeRead(directory,state,ref); const doc=state.documents.find(d=>d.path===ref);if (text === null || hash(doc?.mode==='new'?strippedGenerated(text,doc.kind):text) !== digest) changes.push(ref); }
     catch { changes.push(ref); }
   }
   return changes;