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

package/lib/approvals.mjs

@@ -0,0 +1,153 @@
+import { isDeepStrictEqual } from 'node:util';
+import { artifactMap, safeRead, anchors } from './documents.mjs';
+import { fail, hash } from './io.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.');
+const kinds = ['self-check', 'approved', 'changes-requested', 'editorial'];
+export function validateReviewState(state) {
+  if (state.reviewPolicy === undefined) return;
+  if (state.reviewPolicy !== 1 || !Array.isArray(state.reviewHistory)) reject('Unsupported review policy or missing reviewHistory.');
+  const ids = new Set();
+  for (const r of state.reviewHistory) {
+    if (!r || !text(r.id) || ids.has(r.id) || !kinds.includes(r.kind) || !text(r.document) || !text(r.version) || !/^[a-f0-9]{64}$/.test(r.digest ?? '') || !text(r.sourceRef) || !text(r.summary)) reject('Review records need unique ID, kind, document, version, digest, sourceRef and summary.');
+    ids.add(r.id);
+    if (r.kind === 'self-check' && !['passed','failed'].includes(r.result)) reject('Self-check records must distinguish passed from failed.');
+    if (r.kind === 'approved' && r.decision !== 'explicit-approval') reject('Approval requires an explicit user approval decision; questions, silence and requests to see results are not approval.');
+    if (r.kind === 'editorial' && !/^[a-f0-9]{64}$/.test(r.previousDigest ?? '')) reject('Editorial reconciliation needs the previous approved digest.');
+  }
+  for (const [index, run] of state.stageRuns.entries()) {
+    if (run.dependsOn !== undefined && (!Array.isArray(run.dependsOn) || new Set(run.dependsOn).size !== run.dependsOn.length || !run.dependsOn.every(id => state.stageRuns.slice(0, index).some(r => r.id === id)))) reject(`${run.id}: dependencies must be unique preceding run IDs.`);
+  }
+}
+// Shared execution/result sections are outside the approved design surface.
+// Reused formats have no inferred boundary: the entire pinned file is reviewed.
+export async function reviewFingerprint(directory, state, doc) {
+  const stop = doc.mode === 'new' ? { plan: 'execution', testing: 'runs' }[doc.kind] : null;
+  let body = await safeRead(directory, state, doc.path, stop ? 'utf8' : null);
+  if (body === null) return null;
+  if (stop) {
+    const at = body.search(new RegExp(`<a\\s+id=["']${stop}["']\\s*><\\/a>`));
+    if (at < 0) return null;
+    body = body.slice(0, at);
+  }
+  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);
+}
+function decisionFor(state, doc, digest) {
+  let approved = null, checked = null, latest = null;
+  for (const r of state.reviewHistory ?? []) {
+    if (r.document !== doc.path) continue;
+    if (r.kind === 'changes-requested') { approved = null; checked = null; }
+    if (['approved','editorial'].includes(r.kind)) approved = r;
+    if (r.version === doc.version && r.digest === digest) {
+      latest = r;
+      if (r.kind === 'self-check') { checked = r.result === 'passed' ? r : null; if (r.result === 'failed') approved = null; }
+    }
+  }
+  if (approved?.version !== doc.version || approved?.digest !== digest) approved = null;
+  return { approved, checked, latest };
+}
+export async function reviewStatus(directory, state) {
+  if (state.reviewPolicy !== 1) return { compatibility: 'review-adoption-required', canProceed: false, pending: [], runs: [], documents: [], instruction: 'Preserve old results. Enable reviewPolicy: 1 with an empty reviewHistory after compatibility assessment; no historical approval is inferred.' };
+  const map = await artifactMap(), documents = [], evidenceIssues = [], evidenceCache = new Map();
+  for (const r of state.reviewHistory ?? []) {
+    if (!evidenceCache.has(r.sourceRef)) { try { evidenceCache.set(r.sourceRef,await evidence(directory,state,r.sourceRef)); } catch { evidenceCache.set(r.sourceRef,null); } }
+    if (!r.sourceDigest || evidenceCache.get(r.sourceRef) !== r.sourceDigest) evidenceIssues.push(r.id);
+  }
+  for (const doc of state.documents ?? []) {
+    if (['source','change-log','review','handoff'].includes(doc.kind)) continue;
+    let digest = null;
+    try { digest = await reviewFingerprint(directory, state, doc); } catch { /* Missing input remains blocked. */ }
+    const { approved, checked, latest } = decisionFor(state, doc, digest);
+    documents.push({ path: doc.path, version: doc.version, digest, selfCheck: checked?.id ?? null, approval: approved?.id ?? null, status: !digest ? 'unavailable' : approved && (evidenceIssues.includes(approved.id) || (checked && evidenceIssues.includes(checked.id))) ? 'evidence-changed' : approved ? 'approved' : latest?.kind === 'changes-requested' ? 'changes-requested' : latest?.kind === 'self-check' && latest.result === 'failed' ? 'self-check-failed' : checked ? 'pending' : 'self-check-required' });
+  }
+  const runs = [], requirement = state.documentPolicy?.authority === 'adopted' ? 'scope' : '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','scope','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 dependsOn = [...new Set([...declared, ...producers, ...prerequisites])];
+    const blockedBy = dependsOn.filter(id => !runs.find(r => r.id === id)?.ready);
+    const waiting = required.filter(file => documents.find(d => d.path === file)?.status !== 'approved');
+    const ready = run.progress === 'done' && !['needs-review','unknown'].includes(run.applicability) && !blockedBy.length && !waiting.length && (!spec?.humanReview || required.length > 0);
+    runs.push({ id: run.id, stage: run.stage, progress: run.progress, applicability: run.applicability, documents: required, waiting, dependsOn, blockedBy, ready });
+  }
+  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: current ? !current.blockedBy.length && !(current.progress === 'done' && !current.ready) && current.progress !== 'blocked' && !['needs-review','unknown'].includes(current.applicability) : !pending.length && !runs.some(r=>r.progress==='blocked' || ['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.');
+  let body;
+  try { body = await safeRead(directory, state, ref); } catch { reject(`Cannot read review evidence ${ref}.`); }
+  if (!text(body)) reject(`Preserve locally readable review evidence for ${ref}.`);
+  const fragment = ref.split('#')[1];
+  if (fragment && !anchors(body).includes(fragment)) reject(`Review evidence anchor not found: ${ref}.`);
+  return hash(body);
+}
+export async function enforceReviews(directory, state, previous) {
+  validateReviewState(state);
+  if (state.reviewPolicy !== 1) reject('Adopt the review protocol before workflow updates; old results remain readable but are not approvals.');
+  const oldHistory = previous?.reviewHistory ?? [];
+  for (const old of previous?.documents ?? []) if (oldHistory.some(r=>r.document===old.path) && !state.documents.some(d=>d.path===old.path && d.kind===old.kind)) reject(`Preserve reviewed document registration ${old.path}.`);
+  if (state.reviewHistory.length < oldHistory.length || !oldHistory.every((r, i) => isDeepStrictEqual(r, state.reviewHistory[i]))) reject('Preserve review history unchanged and in order.');
+  const prefix = { ...state, reviewHistory: [...oldHistory] };
+  for (const r of state.reviewHistory.slice(oldHistory.length)) {
+    const doc = state.documents.find(d => d.path === r.document);
+    if (!doc || r.version !== doc.version || r.digest !== await reviewFingerprint(directory, state, doc)) reject(`${r.id}: review must bind the current registered document version and content.`);
+    const prior = decisionFor(prefix, doc, r.digest);
+    if (r.kind === 'approved' && !prior.checked) reject(`${r.id}: self-check the same content before recording approval.`);
+    if (r.kind === 'editorial' && (!prior.checked || !decisionFor(prefix, doc, r.previousDigest).approved)) reject(`${r.id}: editorial reconciliation needs a self-check and the previous approval at the same version.`);
+    r.sourceDigest = await evidence(directory, state, r.sourceRef);
+    prefix.reviewHistory.push(r);
+  }
+  // Only the initial selected development sequence is ordered; later rework can recur.
+  const order = ['requirements','scope','tech-design','contract','test-design','plan','implement'];
+  const first = stage => state.stageRuns.findIndex(r => r.stage === stage);
+  for (let i = 0; i < order.length; i++) for (let j = i + 1; j < order.length; j++) {
+    const a = first(order[i]), b = first(order[j]);
+    if (order[i] === 'requirements' && order[j] === 'scope') continue;
+    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();
+  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)).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 && now.status === 'approved' && 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);
+  }
+  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.`);
+  }
+  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.');
+  return status;
+}

package/lib/cli.mjs

@@ -16,10 +16,10 @@ const HELP = {
     status: 'status [--home <dir>]. Read only Aimship-managed paths and fixed entries. Report registration, shared entry presence/integrity, active version, pending work and config problems. Host loading, login and access permissions remain unverified; no directories are created.',
     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, endpoint} and goalRef. Does not create templates.',
-    read: 'read <dir> [--rules-version <version>]. Read-only JSON access; unknown schemas remain readable.',
+    read: 'read <dir> [--rules-version <version>] [--delivery-id <known-id>]. Read-only JSON access; unknown schemas remain readable.',
     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.',
     check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Checks explicit anchors/identity metadata 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>]. Read state and return fixed rule paths, required inputs, warnings, and continuation text; never execute work or rewrite state.',
+    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.',
     checkpoint: 'checkpoint <dir> --revision <N> --rules-version <old-version> --input <json-file|->. Save only checkpoint {summary, ref?} and next when a version mismatch interrupts ongoing work. Cannot complete work.',
     adopt: 'adopt <dir> --revision <N> --rules-version <active-version> --input <json-file|->. Input is {compatibilityRef}; records the assessed stable-point rule switch without changing business history.',
     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.',
@@ -29,6 +29,9 @@ const HELP = {
   },
   stateProtocol: {
     schemaVersion: SCHEMA_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. Legacy absence remains historical-unassessed; explicit adoption requires compatibilityRef. Completion is derived separately from goal/acceptance.',
+    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; writeResult.session is withheld on failed view saving. No session gate or automatic execution.',
     stages: STAGES,
     progress: ['planned', 'active', 'blocked', 'done'],
     result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
@@ -66,7 +69,7 @@ function parse(argv) {
     const item = argv[i];
     if (!item.startsWith('--')) { positional.push(item); continue; }
     const name = item.slice(2);
-    if (!['help', 'version', 'all', 'preserve-edits', 'input', 'rules-version', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
+    if (!['help', 'version', 'all', 'preserve-edits', 'input', 'rules-version', 'delivery-id', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
     const value = ['help', 'version', 'all', 'preserve-edits'].includes(name) ? true : argv[++i];
     if (value === undefined || (typeof value === 'string' && value.startsWith('--'))) fail('USAGE', `Missing value for ${item}`, 'Provide the option value.');
     if (name === 'host') (options.hosts ??= []).push(value);
@@ -118,7 +121,7 @@ async function binding(runtime) {
 }
 function allowed(command, options) {
   const common = ['help', 'version'];
-  const perCommand = { render: ['revision','rules-version','preserve-edits','home'], migrate:['revision','rules-version','input','home'], scan:['home'], status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
+  const perCommand = { render: ['revision','rules-version','preserve-edits','home'], migrate:['revision','rules-version','input','home'], scan:['home'], status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'delivery-id', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'delivery-id', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
   for (const key of Object.keys(options)) if (![...common, ...(perCommand[command] ?? [])].includes(key)) fail('USAGE', `Option --${key} is not valid for ${command}.`, `Run help ${command}.`);
 }
 export async function run(argv, context) {
@@ -152,9 +155,10 @@ export async function run(argv, context) {
   if (['update', 'checkpoint', 'adopt'].includes(command)) return { command, data: await updateState(directory, await inputJSON(options.input), revisionOf(options.revision), rulesVersion, runtime, command) };
   if (command === 'recover') return { command, data: await recoverState(directory, revisionOf(options.revision), rulesVersion, runtime) };
   const read = await readState(directory);
+  if (options['delivery-id'] && options['delivery-id'] !== read.state.deliveryId) fail('DELIVERY_ID_MISMATCH','This directory is not the bound delivery.','Locate the intended delivery; do not guess the latest one.');
   let mismatch = null;
   if (!read.readOnly) { try { assertRules(read.state, rulesVersion, runtime); } catch (error) { mismatch = { code: error.code, ...error.details, recovery: error.recovery }; } }
-  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: read.statePath, view: read.view, documentChanges: read.documentChanges, layoutConflict:read.conflict??false, layoutMismatch:read.layoutMismatch??false, candidates:read.candidates, migration:read.migration?.status??null } };
+  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: read.statePath, review:read.review, completion:read.completion, session:read.session, view: read.view, documentChanges: read.documentChanges, layoutConflict:read.conflict??false, layoutMismatch:read.layoutMismatch??false, candidates:read.candidates, migration:read.migration?.status??null } };
   if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: read.conflict?'Conflicting state layouts require explicit reconciliation.':'Unknown schema: no structure checking, mutation, or automatic work is permitted.', candidates:read.candidates } };
   validateState(read.state); const references = await checkReferences(directory, read.state, options.all);
   const documents=await inspectDocuments(directory,read.state);
@@ -163,9 +167,9 @@ export async function run(argv, context) {
     if (missing.length) fail('REFERENCE_CHECK', 'Required references are missing or inaccessible.', 'Repair the specific registered paths; do not scan the disk or overwrite source materials.', { references, versionMismatch: mismatch });
     if (mismatch) fail('VERSION_MISMATCH', 'State is structurally valid, but rules are not bound consistently.', mismatch.recovery, mismatch);
     if (documents.issues.length) fail('DOCUMENT_CHECK','Document mapping or identities need repair.','Inspect listed issues.',documents);
-    return { command, data: { structure: 'valid', references, documents, view:read.view, documentChanges:read.documentChanges, semantics: 'not-checked' } };
+    return { command, data: { structure: 'valid', review:read.review, completion:read.completion, session:read.session, references, documents, view:read.view, documentChanges:read.documentChanges, semantics: 'not-checked' } };
   }
   const currentRun = read.state.stageRuns.find(x => x.id === read.state.currentRun) ?? null;
   const blocked = currentRun?.progress === 'blocked';
-  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, canProceed: read.state.documentPolicy?.authority !== 'legacy' && !mismatch && missing.length === 0 && !blocked && !documents.issues.length && !read.documentChanges.length && read.view.status === 'current' && (!read.migration || read.migration.status === 'complete'), statePath:read.statePath, view:read.view, documentChanges:read.documentChanges, documents, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read ${read.statePath} and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, review:read.review, completion:read.completion, session:read.session, canProceed: read.review.canProceed && read.state.documentPolicy?.authority !== 'legacy' && !mismatch && missing.length === 0 && !blocked && !documents.issues.length && !read.documentChanges.length && read.view.status === 'current' && (!read.migration || read.migration.status === 'complete'), statePath:read.statePath, view:read.view, documentChanges:read.documentChanges, documents, versionMismatch: mismatch, references, currentRun, continuation: !mismatch && !missing.length && !documents.issues.length ? read.session?.continuation ?? null : null, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
 }

package/lib/delivery.mjs

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

package/lib/documents.mjs

@@ -19,13 +19,13 @@ export function resolveRef(directory, state, ref) {
   if (!inside(base, file)) fail('INVALID_REFERENCE', 'Reference escapes its root.', 'Repair the registered reference.');
   return file;
 }
-export async function safeRead(directory, state, ref) {
+export async function safeRead(directory, state, ref, encoding = 'utf8') {
   const file = resolveRef(directory, state, ref);
   if (!file) return null;
   const real = await fs.realpath(file);
   const base = ref.startsWith('repo:') ? state.repositories.find(r => r.id === /^repo:([^/]+)/.exec(ref)[1]).path : directory;
   if (!inside(await fs.realpath(base), real)) fail('INVALID_REFERENCE', 'Reference resolves outside its root.', 'Repair the symbolic link or reference.');
-  return fs.readFile(real, 'utf8');
+  return fs.readFile(real, encoding);
 }
 export const anchors = text => [...text.matchAll(/<a\s+id=["']([^"']+)["']\s*><\/a>/g)].map(m => m[1]);
 const identityKinds = ['REQ','AC','B','TASK','TC','REV','RUN','CHG','Q','PAGE'];
@@ -94,7 +94,7 @@ export async function inspectDocuments(directory, state) {
   const runs = state.stageRuns.filter(r => !legacyRuns.has(r.id));
   for (const [i, run] of state.stageRuns.entries()) {
     if (!runs.includes(run) || run.progress === 'planned') continue;
-    const contract = map.stages[run.stage], doc = find(contract.kind);
+    const contract = map.stages[run.stage], doc = find(contract.kind) ?? (run.stage === 'contract' && policy.interface === 'none' ? find('sql') : null);
     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.`);
     if (run.progress === 'done') {
@@ -108,7 +108,7 @@ export async function inspectDocuments(directory, state) {
         const prefix=run.stage==='review'?'REV-':'RUN-';
         if (!defs.some(d=>d.file===doc.path && d.namespace==='local' && d.id.startsWith(prefix) && d.run===run.id && `${doc.path}#${d.id.toLowerCase()}-v${d.version}`===run.resultRef)) issues.push(`${run.id}: result must locate its own versioned REV/RUN definition with matching run field.`);
       }
-      if (run.stage === 'tech-design') {
+      if (run.stage === 'contract') {
         for (const db of policy.databases) {
           const file = policy.databases.length === 1 ? 'database.sql' : `database-${db}.sql`;
           if (!docs.some(d => d.kind === 'sql' && d.path === file) || !await exists(path.join(directory,file))) issues.push(`${run.id}: missing independent ${file}.`);
@@ -116,6 +116,7 @@ export async function inspectDocuments(directory, state) {
       }
     }
   }
+  if (state.reviewPolicy === 1 && (policy.interface !== 'none' || policy.databases.length) && runs.some(r=>['test-design','plan','implement'].includes(r.stage) && r.progress !== 'planned') && !runs.some(r=>r.stage==='contract' && r.progress==='done')) issues.push('Complete the applicable interface/SQL contract before test design, plan or implementation.');
   if (policy.interface === 'http') {
     const doc=find('contract');
     if (doc?.mode === 'new' && doc.path !== 'openapi.yaml') issues.push('New HTTP contract must be openapi.yaml.');

package/lib/state.mjs

@@ -1,4 +1,6 @@
+import { validateDelivery, arrangeSessions, completionStatus, sessionAdvice } from './delivery.mjs';
 import fs from 'node:fs/promises';
+import { validateReviewState, enforceReviews, reviewStatus } from './approvals.mjs';
 import path from 'node:path';
 import { inspectDocuments, documentChanges, anchors, preservedLegacyRuns } from './documents.mjs';
 import { savedResult, viewStatus, generateView } from './view.mjs';
@@ -6,7 +8,7 @@ import { randomUUID } from 'node:crypto';
 import { atomicWrite, exists, fail, inside, json, noSymlinks, readJSON, withLock } from './io.mjs';
 
 export const SCHEMA_VERSION = 2;
-export const STAGES = ['frame', 'requirements', 'prototype', 'scope', 'diagnose', 'tech-design', 'contract', 'plan', 'test-design', 'implement', 'review', 'verify', 'handoff'];
+export const STAGES = ['frame', 'requirements', 'prototype', 'scope', 'diagnose', 'tech-design', 'contract', 'test-design', 'plan', 'implement', 'review', 'verify', 'handoff'];
 const PROGRESS = ['planned', 'active', 'blocked', 'done'];
 const RESULTS = ['passed', 'failed', 'not-run', 'unknown', 'mixed'];
 const OUTCOME_REFS = ['goalConclusionRef', 'acceptanceRef', 'mergeRef', 'deploymentRef', 'handoffRef'];
@@ -37,6 +39,7 @@ export function validateState(state) {
       for (const d of state.documents) {
         requireThat(object(d) && ['prd','scope','tech-design','plan','testing','review','diagnosis','handoff','change-log','prototype','contract','sql','source'].includes(d.kind) && ['new','reused'].includes(d.mode) && string(d.version), 'Invalid document registration.');
         ref(d.path, 'documents.path'); requireThat(!d.path.includes('#') && !paths.has(d.path), 'Document paths must be unique and have no fragment.'); paths.add(d.path);
+        if (d.assetRefs !== undefined) refs(d.assetRefs, 'documents.assetRefs');
         if (d.mode === 'reused') { ref(d.basisRef, 'documents.basisRef'); }
       }
     }
@@ -45,6 +48,7 @@ export function validateState(state) {
   requireThat(string(state.deliveryId) && string(state.rulesVersion), 'deliveryId and rulesVersion are required.');
   requireThat(object(state.goal) && string(state.goal.summary) && string(state.goal.endpoint), 'goal.summary and goal.endpoint are required.');
   ref(state.goalRef, 'goalRef');
+  if (state.compatibilityRef !== undefined) ref(state.compatibilityRef, 'compatibilityRef');
   if (state.goal.decisionRef !== undefined) ref(state.goal.decisionRef, 'goal.decisionRef');
   requireThat(Number.isSafeInteger(state.cycle) && state.cycle >= 1, 'cycle must be a positive integer.');
   refs(state.closureRefs, 'closureRefs');
@@ -73,6 +77,9 @@ export function validateState(state) {
   if (state.next.inputRefs !== undefined) refs(state.next.inputRefs, 'next.inputRefs');
   if (state.goalHistory !== undefined) requireThat(Array.isArray(state.goalHistory), 'goalHistory must be an array.');
   if (state.rulesHistory !== undefined) requireThat(Array.isArray(state.rulesHistory), 'rulesHistory must be an array.');
+  validateDelivery(state);
+  if (state.deliveryPolicy?.partialRef) ref(state.deliveryPolicy.partialRef, 'deliveryPolicy.partialRef');
+  validateReviewState(state);
   return state;
 }
 
@@ -96,9 +103,11 @@ export async function readState(directory) {
   const paths=await locateState(directory); const state=await readJSON(paths.statePath);
   requireThat(object(state),'State must be an object.');
   const layoutMismatch=(state.schemaVersion===1 && !paths.legacy)||(state.schemaVersion===2 && paths.legacy);
-  const readOnly=paths.conflict || layoutMismatch || ![1,SCHEMA_VERSION].includes(state.schemaVersion);
+  const readOnly=paths.conflict || layoutMismatch || ![1,SCHEMA_VERSION].includes(state.schemaVersion) || (state.reviewPolicy !== undefined && state.reviewPolicy !== 1) || (state.deliveryPolicy !== undefined && state.deliveryPolicy?.version !== 1);
   if (!readOnly) validateState(state);
-  return {...paths,state,readOnly,layoutMismatch,view:await viewStatus(directory,state),documentChanges:await documentChanges(directory,state)};
+  const review=readOnly ? null : await reviewStatus(directory,state);
+  const view=await viewStatus(directory,state), changes=await documentChanges(directory,state);
+  return {...paths,state,readOnly,layoutMismatch,review,completion:review ? completionStatus(state,review,{changed:changes}) : null,session:review ? sessionAdvice(directory,state,review,{saved:view.status==='current' && !changes.length}) : null,view,documentChanges:changes};
 }
 async function inspectForWrite(directory,state,previous) {
   const inspected=await inspectDocuments(directory,state);
@@ -142,8 +151,8 @@ export async function initState(directory, input, rulesVersion, runtime) {
     const forbidden = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory', 'documentDigests', 'identityHistory', 'retiredIdentities', 'legacyRunIds', 'writeResult'];
     requireThat(object(input) && !forbidden.some(x => Object.hasOwn(input, x)), 'init input must not set tool-managed identity/version fields.');
     const now = new Date().toISOString();
-    const state = { cycle: 1, closureRefs: [], stageRuns: [], currentRun: null, openChanges: [], repositories: [], outcome: { goal: 'in-progress', acceptance: 'not-recorded' }, next: { action: 'Continue the confirmed arrangement.' }, ...input, schemaVersion: SCHEMA_VERSION, revision: 0, deliveryId: randomUUID(), rulesVersion, createdAt: now, updatedAt: now };
-    validateState(state); requireThat(state.documentPolicy.authority !== 'legacy', 'New deliveries cannot opt into legacy rules.'); await inspectForWrite(directory,state); await atomicWrite(p.statePath, json(state)); return savedResult(directory,state);
+    const state = { deliveryPolicy: {version:1}, reviewPolicy: 1, reviewHistory: [], cycle: 1, closureRefs: [], stageRuns: [], currentRun: null, openChanges: [], repositories: [], outcome: { goal: 'in-progress', acceptance: 'not-recorded' }, next: { action: 'Continue the confirmed arrangement.' }, ...input, schemaVersion: SCHEMA_VERSION, revision: 0, deliveryId: randomUUID(), rulesVersion, createdAt: now, updatedAt: now };
+    arrangeSessions(state); validateState(state); requireThat(state.deliveryPolicy?.version === 1, 'New deliveries require deliveryPolicy version 1.'); requireThat(state.documentPolicy.authority !== 'legacy', 'New deliveries cannot opt into legacy rules.'); await inspectForWrite(directory,state); await enforceReviews(directory,state); await enforceCompletion(directory,state); await atomicWrite(p.statePath, json(state)); return savedResult(directory,state);
   });
 }
 function merge(base, patch) {
@@ -200,14 +209,22 @@ export async function updateState(directory, patch, revision, rulesVersion, runt
       next = { ...previous, rulesVersion, rulesHistory: [...(previous.rulesHistory ?? []), { from: previous.rulesVersion, to: rulesVersion, ref: patch.compatibilityRef, at: new Date().toISOString() }] };
     } else next = merge(previous, patch);
     if (mode === 'checkpoint') next.checkpoint.activeVersion = runtime.activeVersion;
-    validateState(next);
+    requireThat(previous.deliveryPolicy === undefined || next.deliveryPolicy?.version === previous.deliveryPolicy.version, 'Cannot remove or downgrade deliveryPolicy.');
+    if (previous.deliveryPolicy === undefined && next.deliveryPolicy !== undefined) {
+      requireThat(string(next.compatibilityRef) && patch.compatibilityRef !== undefined, 'Explicit delivery-policy adoption needs compatibilityRef; preserve historical outcomes.');
+      const basis = await checkReferences(directory,{...next,goalRef:next.compatibilityRef,next:{inputRefs:[]},stageRuns:[],currentRun:null});
+      requireThat(basis.every(r=>['exists','not-checked'].includes(r.status)), 'Compatibility assessment must be accessible before policy adoption.');
+    }
+    arrangeSessions(next); validateState(next);
     if (JSON.stringify(previous.goal) !== JSON.stringify(next.goal) || previous.goalRef !== next.goalRef) {
       requireThat(string(next.goal.decisionRef) && next.goal.decisionRef !== previous.goal.decisionRef, 'Goal revision requires a new explicit decisionRef; viewing results does not revise a goal.');
-      next.goalHistory = [...(previous.goalHistory ?? []), { goal: previous.goal, goalRef: previous.goalRef, outcome: previous.outcome, revision: previous.revision }];
+      next.goalHistory = [...(previous.goalHistory ?? []), { goal: previous.goal, goalRef: previous.goalRef, deliveryPolicy: previous.deliveryPolicy, outcome: previous.outcome, revision: previous.revision }];
     }
     requireThat(previous.documentPolicy?.authority === 'legacy' || next.documentPolicy?.authority !== 'legacy', 'Cannot downgrade a new delivery to legacy document rules.');
     if (mode === 'update' && next.documentPolicy?.authority === 'legacy') requireThat(Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k)), 'Reconcile legacy documents and set the current documentPolicy before advancing stages or outcomes.');
-    if (mode === 'update') await inspectForWrite(directory,next,previous);
+    if (mode === 'update') { await inspectForWrite(directory,next,previous); if (next.reviewPolicy === 1 || !Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k))) await enforceReviews(directory,next,previous); }
+    if (previous.deliveryPolicy?.partialRef !== next.deliveryPolicy?.partialRef && previous.deliveryPolicy !== undefined) requireThat(string(next.goal.decisionRef) && next.goal.decisionRef !== previous.goal.decisionRef, 'Scope changes need a new explicit goal decision.');
+    if (mode === 'update' && next.deliveryPolicy && previous.deliveryPolicy && JSON.stringify(previous.outcome)!==JSON.stringify(next.outcome)) await enforceCompletion(directory,next);
     retainHistory(previous, next); next.revision = previous.revision + 1; next.updatedAt = new Date().toISOString();
     validateState(next); await atomicWrite(p.backup, json(previous)); await atomicWrite(p.statePath, json(next)); return next.schemaVersion === 2 ? savedResult(directory,next) : next;
   });
@@ -221,9 +238,10 @@ export async function recoverState(directory, revision, rulesVersion, runtime) {
       const raw = await fs.readFile(p.statePath, 'utf8');
       let parsed; try { parsed = JSON.parse(raw); } catch { /* Corruption is preserved below. */ }
       if (parsed) {
+        if ((parsed.deliveryPolicy !== undefined && parsed.deliveryPolicy?.version !== 1) || (parsed.reviewPolicy !== undefined && parsed.reviewPolicy !== 1)) fail('UNKNOWN_SCHEMA','Cannot recover over an unknown review protocol.','Preserve the newer state and use a compatible tool.');
         if (parsed.schemaVersion !== backup.schemaVersion) fail('UNKNOWN_SCHEMA', 'Cannot recover over an unknown schema.', 'Use a compatible tool; preserve the newer state.');
         try { validateState(parsed); fail('STATE_VALID', 'Current state is valid; refusing rollback.', 'Use a normal revision-checked update to reconcile facts.'); }
-        catch (e) { if (e.code !== 'INVALID_STATE') throw e; }
+        catch (e) { if (!['INVALID_STATE','REVIEW_CHECK'].includes(e.code)) throw e; }
         if (Number.isSafeInteger(parsed.revision)) corruptRevision = Math.max(corruptRevision, parsed.revision);
       }
       await atomicWrite(path.join(p.internal, `state.corrupt.${randomUUID()}.json`), raw);
@@ -240,12 +258,16 @@ export async function checkReferences(directory, state, all = false) {
     state.openChanges.forEach(x => values.add(x.ref)); state.closureRefs.forEach(x => values.add(x));
     const add = value => { if (value !== undefined) { ref(value, 'registered reference'); values.add(value); } };
     const addOutcome = outcome => { for (const key of OUTCOME_REFS) add(outcome?.[key]); };
+    if (state.deliveryPolicy?.partialRef != null) add(state.deliveryPolicy.partialRef);
+    add(state.compatibilityRef);
     add(state.goal.decisionRef); addOutcome(state.outcome);
     for (const history of state.goalHistory ?? []) {
       add(history?.goalRef); add(history?.goal?.decisionRef); addOutcome(history?.outcome);
     }
     for (const history of state.rulesHistory ?? []) add(history?.ref);
     add(state.checkpoint?.ref);
+    for (const r of state.reviewHistory ?? []) add(r.sourceRef);
+    for (const d of state.documents ?? []) for (const r of d.assetRefs ?? []) add(r);
   }
   const results = [];
   for (const value of values) {
@@ -274,3 +296,11 @@ export async function checkReferences(directory, state, all = false) {
   }
   return results;
 }
+
+async function enforceCompletion(directory,state) {
+  if (state.deliveryPolicy?.version !== 1 || state.outcome.goal !== 'met') return;
+  const completion=completionStatus(state,await reviewStatus(directory,state));
+  if (!state.deliveryPolicy.partialRef && !completion.readyForAcceptance) fail('DELIVERY_INCOMPLETE','Standard delivery evidence is incomplete.','Keep the goal in progress, or record the explicitly limited scope without claiming standard completion.',completion);
+  const refs=await checkReferences(directory,state,true);
+  if (refs.some(r=>!['exists','not-checked'].includes(r.status))) fail('DELIVERY_INCOMPLETE','Completion references are missing.','Repair evidence references without inventing results.',{references:refs});
+}

package/lib/view.mjs

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

package/package.json

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

package/skills/aimship/SKILL.md

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