aimship 0.1.0-preview.4 → 0.1.0-preview.8

package/lib/documents.mjs

@@ -0,0 +1,156 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { exists, hash, inside, fail, readJSON, json } from './io.mjs';
+
+export async function artifactMap() {
+  return JSON.parse(await fs.readFile(new URL('../skills/aimship/references/artifact-map.json', import.meta.url), 'utf8'));
+}
+export function resolveRef(directory, state, ref) {
+  if (/^https?:\/\//.test(ref)) return null;
+  let base = path.resolve(directory), relative = ref.split('#')[0];
+  if (relative.startsWith('repo:')) {
+    const [, id, rest] = /^repo:([^/]+)\/(.*)$/.exec(relative) ?? [];
+    base = state.repositories.find(r => r.id === id)?.path;
+    if (!base) return null;
+    relative = rest;
+  }
+  const file = path.resolve(base, relative);
+  if (!inside(base, file)) fail('INVALID_REFERENCE', 'Reference escapes its root.', 'Repair the registered reference.');
+  return file;
+}
+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, 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'];
+const identityKind = d => d.kind ?? d.id.split('-')[0];
+// Migration exempts preserved execution facts, never future work under an old ID.
+export async function preservedLegacyRuns(directory,state) {
+  if (!state.legacyRunIds?.length) return new Set();
+  const journal=await readJSON(path.join(directory,'.aimship/migration.json'));
+  if (journal.protocol!==1 || hash(json(journal.target))!==journal.targetHash || journal.target.deliveryId!==state.deliveryId) fail('MIGRATION_CONFLICT','Cannot verify legacy run provenance.','Inspect the migration journal and original state.');
+  const basis=run=>{const {applicability,...facts}=run;return facts;};
+  return new Set(state.stageRuns.filter(run=>state.legacyRunIds.includes(run.id) && journal.target.stageRuns.some(old=>old.id===run.id && old.progress==='done' && isDeepStrictEqual(basis(old),basis(run)))).map(run=>run.id));
+}
+export function definitions(text, file) {
+  const markers=[...text.matchAll(/<!--\s*aimship:def\b/g)].length;
+  const validMarkers=[...text.matchAll(/<!--\s*aimship:def\s+(\{[^\n]*\})\s*-->/g)].length;
+  if (markers !== validMarkers) fail('DOCUMENT_METADATA', `Malformed definition marker in ${file}.`, 'Use a complete single-line aimship:def JSON comment.');
+  return [...text.matchAll(/<!--\s*aimship:def\s+(\{[^\n]*\})\s*-->/g)].map(m => {
+    try {
+      const d = JSON.parse(m[1]);
+      const namespace = d.namespace ?? 'local';
+      const validId=typeof d.id==='string' && (namespace==='local' ? /^[A-Za-z][A-Za-z0-9_-]*-\d+$/.test(d.id) : d.id.trim().length>0 && !/[:@\r\n]/.test(d.id));
+      if (!validId || !Number.isSafeInteger(d.version) || d.version < 1 || !['current','historical','retired'].includes(d.status) || !Array.isArray(d.refs) || !d.refs.every(x => typeof x === 'string' && /^[\w-]+:[^:@\r\n]+@[1-9]\d*$/.test(x)) || !/^[\w-]+$/.test(namespace) || (d.kind!==undefined && (!identityKinds.includes(d.kind) || (namespace==='local' && d.kind!==d.id.split('-')[0])))) throw new Error('Invalid identity metadata');
+      return { ...d, namespace, key: `${namespace}:${d.id}@${d.version}`, file };
+    } catch { fail('DOCUMENT_METADATA', `Invalid definition in ${file}.`, 'Use the documented aimship:def JSON syntax.'); }
+  });
+}
+export async function inspectDocuments(directory, state) {
+  if (state.schemaVersion !== 2 || !state.documentPolicy || state.documentPolicy.authority === 'legacy') return { issues: [], unchecked: ['Legacy documents require recorded compatibility review.'], digests: {}, identities: [], nextIds: {} };
+  const map = await artifactMap(), issues = [], unchecked = [], digests = {}, defs = [], documentAnchors = new Map();
+  const docs = state.documents ?? [];
+  const policy = state.documentPolicy;
+  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.`);
+  if (docs.some(d=>d.kind==='prd'&&d.mode==='new') && docs.some(d=>d.kind==='scope'&&d.mode==='new')) issues.push('Do not create competing new PRD and Scope entries.');
+  const requirementKind = policy.authority === 'adopted' ? 'scope' : 'prd';
+  const find = kind => docs.find(d => d.kind === (kind === 'requirement' ? requirementKind : kind));
+  if (!await exists(path.join(directory, 'source/request.md'))) issues.push('Missing source/request.md.');
+  if (!find('requirement')) issues.push(`Register ${requirementKind} as the requirement entry.`);
+  if (policy.authority !== 'editable' && state.goalRef.split('#')[0] !== `${requirementKind}.md`) issues.push('goalRef must point to the selected root PRD/Scope.');
+  if (find('requirement') && state.goalRef.split('#')[0]!==find('requirement').path) issues.push('goalRef must point to the registered requirement authority.');
+  for (const doc of docs) {
+    const spec = map.documents[doc.kind];
+    // Location rules apply even when content is remote or cannot be read.
+    if (doc.mode==='new') {
+      if (spec && doc.path!==spec.path) issues.push(`${doc.kind} must use ${spec.path}, not ${doc.path}.`);
+      if (doc.kind==='prototype' && (!doc.path.startsWith('prototype/') || (/\.html$/.test(doc.path) && doc.path!=='prototype/index.html'))) issues.push('New prototypes must stay in prototype/; HTML uses prototype/index.html.');
+      if (doc.kind==='source' && !doc.path.startsWith('source/')) issues.push('New source material must stay in source/.');
+    }
+    let text;
+    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);
+    if (doc.mode === 'reused') { unchecked.push(`${doc.path}: reused format/content; human/Agent basis ${doc.basisRef}.`); continue; }
+    if (spec) {
+      const ids = anchors(text); let previous = -1;
+      documentAnchors.set(doc.path,ids);
+      for (const id of spec.sections) {
+        const i = ids.indexOf(id);
+        if (i < 0 || i <= previous || ids.filter(x => x === id).length !== 1) issues.push(`${doc.path}: missing, duplicate or unordered section #${id}.`);
+        previous = i;
+      }
+      defs.push(...definitions(text, doc.path));
+    }
+  }
+  const legacyRuns=await preservedLegacyRuns(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) ?? (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') {
+      if (run.resultRef?.split('#')[0] !== doc.path) issues.push(`${run.id}: result must locate its mapped artifact ${doc.path}.`);
+      const section = contract.sectionByKind?.[doc.kind] ?? contract.section;
+      if (doc.mode==='new' && section && !['review','verify'].includes(run.stage) && run.resultRef !== `${doc.path}#${section}`) issues.push(`${run.id}: use the mapped #${section} result section.`);
+      if (map.documents[doc.kind] && doc.mode === 'new' && !run.resultRef?.includes('#')) issues.push(`${run.id}: result needs a precise section/record anchor.`);
+      if (map.documents[doc.kind] && doc.mode==='new' && (documentAnchors.get(doc.path)??[]).filter(id=>id===run.resultRef?.split('#')[1]).length!==1) issues.push(`${run.id}: missing or duplicate result anchor ${run.resultRef}.`);
+      if (!run.outputRefs.some(r => r.split('#')[0] === doc.path)) issues.push(`${run.id}: outputRefs must register ${doc.path}.`);
+      if (['review','verify'].includes(run.stage) && doc.mode==='new') {
+        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 === '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}.`);
+        }
+      }
+    }
+  }
+  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.');
+  }
+  if (policy.interaction && !policy.prototypeCovered && runs.some(r => r.stage === 'implement' && r.progress !== 'planned') && !state.stageRuns.some(r => r.stage === 'prototype' && r.progress === 'done')) issues.push('Uncovered interaction requires completed prototype before implementation.');
+  const seen = new Set(), current = new Set(), nextIds = {};
+  for (const d of defs) {
+    if (seen.has(d.key)) issues.push(`Duplicate definition ${d.key}.`); seen.add(d.key);
+    const identity = `${d.namespace}:${d.id}`;
+    if (d.status === 'current') { if (state.retiredIdentities?.includes(identity)) issues.push(`Retired identity cannot be reused: ${identity}.`); if (current.has(identity)) issues.push(`Multiple current definitions ${identity}.`); current.add(identity); }
+    const numeric=/^(.*)-(\d+)$/.exec(d.id);
+    if (numeric) {
+      const [,prefix,number]=numeric, group=`${d.namespace}:${prefix}`;
+      nextIds[group] = Math.max(nextIds[group] ?? 1, Number(number)+1);
+    }
+  }
+  const byKey=new Map(defs.map(d=>[d.key,d]));
+  for (const d of defs) {
+    for (const key of d.refs) if (!seen.has(key)) issues.push(`${d.key}: unresolved ${key}.`);
+    if (d.status !== 'current') continue;
+    const refersTo=kind=>d.refs.some(key=>byKey.has(key) && identityKind(byKey.get(key))===kind);
+    if (d.namespace === 'local' && identityKind(d)==='REQ' && !refersTo('AC')) issues.push(`${d.key}: missing acceptance reference.`);
+    if (identityKind(d)==='RUN' && !refersTo('TC')) issues.push(`${d.key}: missing versioned case reference.`);
+    if (identityKind(d)==='TC' && d.namespace === 'local' && !d.refs.length) issues.push(`${d.key}: missing acceptance or risk basis.`);
+    if (identityKind(d)==='AC' && runs.some(r => ['test-design','verify'].includes(r.stage) && r.progress === 'done') && !defs.some(t => t.status === 'current' && identityKind(t)==='TC' && t.refs.includes(d.key))) issues.push(`${d.key}: no current case coverage.`);
+  }
+  for (const key of state.identityHistory ?? []) if (!seen.has(key)) issues.push(`Preserve historical definition ${key}; retire it rather than deleting/reusing its identity.`);
+  return { retired:defs.filter(d=>d.status==='retired').map(d=>`${d.namespace}:${d.id}`), issues, unchecked, digests, identities: [...seen], nextIds };
+}
+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); }
+    catch { changes.push(ref); }
+  }
+  return changes;
+}

package/lib/migrate.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWrite, exists, fail, hash, json, noSymlinks, readJSON, withLock } from './io.mjs';
+import { statePaths, validateState, assertInstallationComplete, readState } from './state.mjs';
+import { savedResult } from './view.mjs';
+
+export async function migrateState(directory, revision, rulesVersion, runtime, input) {
+  assertInstallationComplete(runtime);
+  if (rulesVersion !== runtime.version || runtime.version !== runtime.activeVersion) fail('VERSION_MISMATCH','Migration requires the active tool.','Bind the active version.');
+  if (!input || Object.keys(input).length !== 1 || typeof input.compatibilityRef !== 'string' || !input.compatibilityRef.trim()) fail('USAGE','Migration input is {compatibilityRef}.','Record the assessment and old/new document disposition first.');
+  const old=statePaths(directory,true), modern=statePaths(directory);
+  await noSymlinks(modern.internal); await fs.mkdir(modern.internal,{recursive:true});
+  return withLock(old.lock,()=>withLock(modern.lock,async()=>{
+    const journalPath=path.join(modern.internal,'migration.json');
+    for (const file of [journalPath,old.statePath,old.backup,modern.statePath,path.join(modern.internal,'legacy/state.json'),path.join(modern.internal,'legacy/state.previous.json')]) await noSymlinks(file);
+    let journal;
+    if (await exists(journalPath)) {
+      journal=await readJSON(journalPath);
+      if (journal.protocol !== 1 || journal.revision !== revision || journal.compatibilityRef !== input.compatibilityRef) fail('MIGRATION_CONFLICT','Migration parameters or journal differ.','Inspect recorded migration; never overwrite the copies.');
+      if (journal.status==='complete') {
+        if (await exists(old.statePath)) fail('LAYOUT_CONFLICT','A root state reappeared after migration.','Inspect both states before proceeding.');
+        return {state:(await readState(directory)).state,migration:'already-complete'};
+      }
+    } else {
+      if (await exists(modern.statePath) || await exists(modern.backup)) fail('LAYOUT_CONFLICT','Target state/recovery already exists.','Inspect both layouts; do not merge by timestamp.');
+      await noSymlinks(old.statePath); await noSymlinks(old.backup);
+      const raw=await fs.readFile(old.statePath,'utf8'), state=JSON.parse(raw);
+      validateState(state);
+      if (state.schemaVersion!==1) fail('UNKNOWN_SCHEMA','Only schema 1 root state can migrate.','Keep unknown formats read-only.');
+      if (state.revision!==revision) fail('REVISION_CONFLICT','Legacy revision changed.','Read and reassess before migration.');
+      const next={...state,schemaVersion:2,revision:state.revision+1,updatedAt:new Date().toISOString(),documentPolicy:{authority:'legacy'},documents:[],legacyRunIds:state.stageRuns.map(r=>r.id),migration:{fromSchema:1,compatibilityRef:input.compatibilityRef}};
+      // validate the assessment reference with the ordinary state reference protocol.
+      validateState({...next,next:{...next.next,inputRefs:[input.compatibilityRef]}});
+      const backupRaw=await exists(old.backup)?await fs.readFile(old.backup,'utf8'):null;
+      journal={protocol:1,status:'prepared',revision,compatibilityRef:input.compatibilityRef,sourceHash:hash(raw),backupHash:backupRaw===null?null:hash(backupRaw),targetHash:hash(json(next)),target:next};
+      const legacyDir=path.join(modern.internal,'legacy'); await noSymlinks(legacyDir); await fs.mkdir(legacyDir,{recursive:true});
+      for (const [name,bytes] of [['state.json',raw],['state.previous.json',backupRaw]]) {
+        if(bytes===null) continue;
+        const file=path.join(legacyDir,name);
+        if(await exists(file) && hash(await fs.readFile(file))!==hash(bytes)) fail('MIGRATION_CONFLICT','Legacy backup differs.','Preserve all copies and resolve manually.');
+        if(!await exists(file)) await atomicWrite(file,bytes);
+      }
+      await atomicWrite(journalPath,json(journal));
+    }
+    validateState(journal.target);
+    if (hash(json(journal.target))!==journal.targetHash) fail('MIGRATION_CONFLICT','Migration target checksum changed.','Inspect journal and preserved source.');
+    const legacyCopy=path.join(modern.internal,'legacy/state.json');
+    if(hash(await fs.readFile(legacyCopy))!==journal.sourceHash) fail('MIGRATION_CONFLICT','Preserved source changed.','Recover the original source before resuming.');
+    const recoveryCopy=path.join(modern.internal,'legacy/state.previous.json');
+    if (journal.backupHash !== null && (!await exists(recoveryCopy) || hash(await fs.readFile(recoveryCopy))!==journal.backupHash)) fail('MIGRATION_CONFLICT','Preserved recovery copy is missing or changed.','Repair the preserved copy from the original recovery material before resuming.');
+    if(await exists(old.statePath) && hash(await fs.readFile(old.statePath))!==journal.sourceHash) fail('MIGRATION_CONFLICT','Legacy state changed during migration.','Reconcile facts; do not overwrite either copy.');
+    if(await exists(modern.statePath) && hash(await fs.readFile(modern.statePath))!==journal.targetHash) fail('MIGRATION_CONFLICT','Target state changed during migration.','Reconcile both states.');
+    if(await exists(old.backup) && hash(await fs.readFile(old.backup))!==journal.backupHash) fail('MIGRATION_CONFLICT','Legacy recovery copy changed.','Preserve both recovery copies.');
+    if(!await exists(modern.statePath)) await atomicWrite(modern.statePath,json(journal.target));
+    await fs.rm(old.statePath,{force:true}); await fs.rm(old.backup,{force:true});
+    await atomicWrite(journalPath,json({...journal,status:'complete'}));
+    return savedResult(directory,journal.target);
+  }));
+}
+
+// Discovery is intentionally bounded to named material roots, never the home or code tree.
+export async function scanDeliveries(root) {
+  const records=[],issues=[],seen=new Map();
+  for(const entry of await fs.readdir(root,{withFileTypes:true})) {
+    if(!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const directory=path.join(root,entry.name);
+    if(!await exists(path.join(directory,'state.json')) && !await exists(path.join(directory,'.aimship/state.json'))) continue;
+    try {
+      const read=await readState(directory), id=read.state.deliveryId;
+      if(read.conflict || read.readOnly) {issues.push({directory,reason:read.conflict?'layout-conflict':'unknown-schema',candidates:read.candidates}); continue;}
+      if(seen.has(id)) {issues.push({directory,reason:'duplicate-delivery-id',other:seen.get(id)}); continue;}
+      seen.set(id,directory);
+      records.push({directory,statePath:read.statePath,deliveryId:id,rulesVersion:read.state.rulesVersion,repositories:read.state.repositories,currentRun:read.state.currentRun,stageRuns:read.state.stageRuns,outcome:read.state.outcome,next:read.state.next,updatedAt:read.state.updatedAt,migration:read.migration?.status??null});
+    } catch(error) {issues.push({directory,reason:error.code??error.message});}
+  }
+  return {root:path.resolve(root),records,issues,limits:'Named root immediate children only. Records may be stale; unknown roots and non-Aimship work are outside this check. Agent must assess actual writing intent and checkout/worktree identity.'};
+}

package/lib/state.mjs

@@ -1,10 +1,13 @@
 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';
 import { randomUUID } from 'node:crypto';
 import { atomicWrite, exists, fail, inside, json, noSymlinks, readJSON, withLock } from './io.mjs';
 
-export const SCHEMA_VERSION = 1;
-export const STAGES = ['frame', 'requirements', 'prototype', 'scope', 'diagnose', 'tech-design', 'contract', 'plan', 'test-design', 'implement', 'review', 'verify', 'handoff'];
+export const SCHEMA_VERSION = 2;
+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'];
@@ -24,7 +27,22 @@ function unique(items, label) { requireThat(items.every(object), `${label} entri
 
 export function validateState(state) {
   requireThat(object(state), 'State must be an object.');
-  if (state.schemaVersion !== SCHEMA_VERSION) fail('UNKNOWN_SCHEMA', `Schema ${state.schemaVersion} is read-only for this tool.`, 'Preserve the file and use a compatible tool or an explicit, reviewed migration.');
+  if (![1, SCHEMA_VERSION].includes(state.schemaVersion)) fail('UNKNOWN_SCHEMA', `Schema ${state.schemaVersion} is read-only for this tool.`, 'Preserve the file and use a compatible tool or an explicit, reviewed migration.');
+  if (state.schemaVersion === 2) {
+    requireThat(object(state.documentPolicy) && ['authored','adopted','editable','legacy'].includes(state.documentPolicy.authority), 'documentPolicy.authority is required.');
+    if (state.documentPolicy.authority !== 'legacy') {
+      const p = state.documentPolicy;
+      requireThat(typeof p.interaction === 'boolean' && typeof p.prototypeCovered === 'boolean' && ['none','http','other'].includes(p.interface) && Array.isArray(p.databases) && p.databases.every(x => typeof x === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(x)) && new Set(p.databases).size === p.databases.length, 'Invalid documentPolicy conditions.');
+      requireThat(Array.isArray(state.documents), 'documents must be an array.');
+      const paths = new Set();
+      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'); }
+      }
+    }
+  }
   requireThat(Number.isSafeInteger(state.revision) && state.revision >= 0, 'revision must be a nonnegative integer.');
   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.');
@@ -57,19 +75,55 @@ 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.');
+  validateReviewState(state);
   return state;
 }
 
-export function statePaths(directory) {
-  const dir = path.resolve(directory);
-  return { dir, statePath: path.join(dir, 'state.json'), backup: path.join(dir, 'state.previous.json'), lock: path.join(dir, '.state.lock') };
+export function statePaths(directory, legacy = false) {
+  const dir = path.resolve(directory), internal = legacy ? dir : path.join(dir,'.aimship');
+  return { dir, internal, statePath:path.join(internal,'state.json'), backup:path.join(internal,'state.previous.json'), lock:path.join(internal,'.state.lock'), legacy };
+}
+export async function locateState(directory, writing = false) {
+  const modern=statePaths(directory), legacy=statePaths(directory,true);
+  const hasNew=await exists(modern.statePath), hasOld=await exists(legacy.statePath);
+  const journalPath=path.join(modern.internal,'migration.json');
+  const journal=await exists(journalPath) ? await readJSON(journalPath) : null;
+  if (hasNew && hasOld) {
+    if (writing) fail('LAYOUT_CONFLICT','Both state layouts exist.','Inspect both copies; resume a recorded migration explicitly.');
+    return {...modern,conflict:true,candidates:[legacy.statePath,modern.statePath],migration:journal};
+  }
+  if (writing && journal && journal.status !== 'complete') fail('MIGRATION_PENDING','Migration is incomplete.','Resume migrate with the original revision and compatibilityRef.');
+  return {...(hasOld || (!hasNew && await exists(legacy.backup)) ? legacy : modern),migration:journal};
 }
 export async function readState(directory) {
-  const paths = statePaths(directory); const state = await readJSON(paths.statePath);
-  requireThat(object(state), 'State must be an object.');
-  const readOnly = state.schemaVersion !== SCHEMA_VERSION;
+  const paths=await locateState(directory); const state=await readJSON(paths.statePath);
+  requireThat(object(state),'State must be an object.');
+  const layoutMismatch=(state.schemaVersion===1 && !paths.legacy)||(state.schemaVersion===2 && paths.legacy);
+  const readOnly=paths.conflict || layoutMismatch || ![1,SCHEMA_VERSION].includes(state.schemaVersion) || (state.reviewPolicy !== undefined && state.reviewPolicy !== 1);
   if (!readOnly) validateState(state);
-  return { ...paths, state, readOnly };
+  return {...paths,state,readOnly,layoutMismatch,review:readOnly ? null : await reviewStatus(directory,state),view:await viewStatus(directory,state),documentChanges:await documentChanges(directory,state)};
+}
+async function inspectForWrite(directory,state,previous) {
+  const inspected=await inspectDocuments(directory,state);
+  if (inspected.issues.length) fail('DOCUMENT_CHECK','Document structure or traceability needs repair.','Repair the specific documents; file presence is not semantic completion.',inspected);
+  // Historical migrated runs retain their old formats. New completed runs need resolvable results.
+  const legacyRuns=await preservedLegacyRuns(directory,state);
+  for (const run of state.stageRuns.filter(r=>r.progress==='done' && !legacyRuns.has(r.id))) {
+    if (previous?.stageRuns.some(r=>r.id===run.id && JSON.stringify(r)===JSON.stringify(run))) continue;
+    const results=await checkReferences(directory,{...state,goalRef:run.resultRef,next:{inputRefs:[]},stageRuns:[],currentRun:null});
+    if (results.some(r=>!['exists','not-checked'].includes(r.status))) fail('DOCUMENT_CHECK',`Cannot locate result for ${run.id}.`,'Fix the result reference.',{references:results});
+  }
+  state.documentDigests=inspected.digests;
+  state.retiredIdentities=[...new Set([...(previous?.retiredIdentities??[]),...inspected.retired??[]])];
+  state.identityHistory=[...new Set([...(previous?.identityHistory??[]),...inspected.identities])];
+}
+export async function renderState(directory,revision,rulesVersion,runtime,preserveEdits=false) {
+  const p=await locateState(directory,true);
+  return withLock(p.lock,async()=>{
+    const {state}=await readState(directory); validateState(state); checkRevision(state,revision); assertRules(state,rulesVersion,runtime);
+    if (p.legacy) fail('MIGRATION_REQUIRED','Migrate before rendering.','Use migrate, then adopt.');
+    return {revision:state.revision,stateSaved:false,view:await generateView(directory,state,preserveEdits)};
+  });
 }
 function checkRevision(state, revision) {
   if (!Number.isSafeInteger(revision) || revision !== state.revision) fail('REVISION_CONFLICT', `Expected revision ${revision}; current revision is ${state.revision}.`, 'Read state again and merge your intended changes; never retry with a guessed revision.', { expected: revision, actual: state.revision });
@@ -84,14 +138,15 @@ export function assertInstallationComplete(runtime) {
 export async function initState(directory, input, rulesVersion, runtime) {
   assertInstallationComplete(runtime);
   if (rulesVersion !== runtime.version || runtime.activeVersion !== runtime.version) fail('VERSION_MISMATCH', 'New delivery requires the active tool and rules version.', 'Bind the current installation and use its returned version.');
-  const p = statePaths(directory); await noSymlinks(p.dir); await fs.mkdir(p.dir, { recursive: true });
+  const p = statePaths(directory); await noSymlinks(p.internal); await fs.mkdir(p.internal, { recursive: true });
+  if (await exists(path.join(p.dir,'state.json')) || await exists(path.join(p.dir,'state.previous.json')) || await exists(p.backup) || await exists(path.join(p.internal,'migration.json'))) fail('ALREADY_EXISTS','Existing delivery or recovery material found.','Read/resume the existing delivery.');
   return withLock(p.lock, async () => {
     if (await exists(p.statePath)) fail('ALREADY_EXISTS', 'A delivery already exists here.', 'Read/resume this delivery or choose a different folder.');
-    const forbidden = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory'];
+    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); await atomicWrite(p.statePath, json(state)); return state;
+    const state = { reviewPolicy: 1, reviewHistory: [], cycle: 1, closureRefs: [], stageRuns: [], currentRun: null, openChanges: [], repositories: [], outcome: { goal: 'in-progress', acceptance: 'not-recorded' }, next: { action: 'Continue the confirmed arrangement.' }, ...input, schemaVersion: SCHEMA_VERSION, revision: 0, deliveryId: randomUUID(), rulesVersion, createdAt: now, updatedAt: now };
+    validateState(state); requireThat(state.documentPolicy.authority !== 'legacy', 'New deliveries cannot opt into legacy rules.'); await inspectForWrite(directory,state); await enforceReviews(directory,state); await atomicWrite(p.statePath, json(state)); return savedResult(directory,state);
   });
 }
 function merge(base, patch) {
@@ -120,9 +175,12 @@ function retainHistory(previous, next) {
 }
 export async function updateState(directory, patch, revision, rulesVersion, runtime, mode = 'update') {
   assertInstallationComplete(runtime);
-  const p = statePaths(directory);
+  const p = await locateState(directory,true);
   return withLock(p.lock, async () => {
-    const { state: previous } = await readState(directory); validateState(previous); checkRevision(previous, revision);
+    const read = await readState(directory);
+    if (read.layoutMismatch) fail('LAYOUT_CONFLICT','Schema and layout disagree.','Inspect the original layout; do not write through an inconsistent path.');
+    const previous = read.state; validateState(previous); checkRevision(previous, revision);
+    if (previous.schemaVersion === 1 && mode !== 'checkpoint') fail('MIGRATION_REQUIRED','Legacy layout/schema must migrate before rule adoption or updates.','Use migrate with a compatibility assessment, then adopt.');
     requireThat(object(patch), 'Update input must be an object.');
     if (mode === 'checkpoint') {
       if (rulesVersion !== previous.rulesVersion || runtime.version !== previous.rulesVersion) fail('VERSION_MISMATCH', 'Checkpoint must use the rules already bound to this state.', 'Use the compatible old tool or preserve facts outside state and resume with the active tool.');
@@ -138,7 +196,7 @@ export async function updateState(directory, patch, revision, rulesVersion, runt
     } else {
       assertRules(previous, rulesVersion, runtime);
     }
-    const immutable = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory'];
+    const immutable = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory', 'documentDigests', 'identityHistory', 'retiredIdentities', 'legacyRunIds', 'writeResult'];
     requireThat(!immutable.some(x => Object.hasOwn(patch, x)), 'Identity, revision, and historical metadata are tool-managed.');
     let next;
     if (mode === 'adopt') {
@@ -150,12 +208,15 @@ export async function updateState(directory, patch, revision, rulesVersion, runt
       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 }];
     }
+    requireThat(previous.documentPolicy?.authority === 'legacy' || next.documentPolicy?.authority !== 'legacy', 'Cannot downgrade a new delivery to legacy document rules.');
+    if (mode === 'update' && next.documentPolicy?.authority === 'legacy') requireThat(Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k)), 'Reconcile legacy documents and set the current documentPolicy before advancing stages or outcomes.');
+    if (mode === 'update') { await inspectForWrite(directory,next,previous); if (next.reviewPolicy === 1 || !Object.keys(patch).every(k=>['next','checkpoint','repositories'].includes(k))) await enforceReviews(directory,next,previous); }
     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;
+    validateState(next); await atomicWrite(p.backup, json(previous)); await atomicWrite(p.statePath, json(next)); return next.schemaVersion === 2 ? savedResult(directory,next) : next;
   });
 }
 export async function recoverState(directory, revision, rulesVersion, runtime) {
-  const p = statePaths(directory);
+  const p = await locateState(directory,true);
   return withLock(p.lock, async () => {
     const backup = await readJSON(p.backup); validateState(backup); checkRevision(backup, revision); assertRules(backup, rulesVersion, runtime);
     let corruptRevision = backup.revision + 1;
@@ -163,15 +224,16 @@ 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.schemaVersion !== SCHEMA_VERSION) fail('UNKNOWN_SCHEMA', 'Cannot recover over an unknown schema.', 'Use a compatible tool; preserve the newer state.');
+        if (parsed.reviewPolicy !== undefined && parsed.reviewPolicy !== 1) fail('UNKNOWN_SCHEMA','Cannot recover over an unknown review protocol.','Preserve the newer state and use a compatible tool.');
+        if (parsed.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.dir, `state.corrupt.${randomUUID()}.json`), raw);
+      await atomicWrite(path.join(p.internal, `state.corrupt.${randomUUID()}.json`), raw);
     }
     const next = { ...backup, revision: corruptRevision + 1, updatedAt: new Date().toISOString(), recovery: { fromRevision: backup.revision, action: 'Inspect actual artifacts and unfinished effects before proceeding; nothing has been re-executed.' } };
-    await atomicWrite(p.statePath, json(next)); return next;
+    await atomicWrite(p.statePath, json(next)); return next.schemaVersion === 2 ? savedResult(directory,next) : next;
   });
 }
 export async function checkReferences(directory, state, all = false) {
@@ -188,6 +250,8 @@ export async function checkReferences(directory, state, all = false) {
     }
     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) {
@@ -203,7 +267,15 @@ export async function checkReferences(directory, state, all = false) {
     try {
       const real = await fs.realpath(target); const realBase = await fs.realpath(base);
       if (!inside(realBase, real)) results.push({ ref: value, status: 'outside-root', path: target });
-      else { await fs.access(real, fs.constants.R_OK); results.push({ ref: value, status: 'exists', path: target, fragmentChecked: false }); }
+      else {
+        await fs.access(real, fs.constants.R_OK);
+        const fragment=value.split('#')[1], doc=state.documents?.find(d=>d.path===value.split('#')[0]);
+        if (fragment && doc?.mode==='new' && /\.md$/.test(relative)) {
+          const ids=anchors(await fs.readFile(real,'utf8'));
+          results.push({ref:value,status:ids.filter(x=>x===fragment).length===1?'exists':'missing-fragment',path:target,fragmentChecked:true});
+        } else if (fragment) results.push({ref:value,status:'not-checked',path:target,fragmentChecked:false,reason:'Nonstandard/reused fragment requires host inspection and recorded basis.'});
+        else results.push({ref:value,status:'exists',path:target,fragmentChecked:false});
+      }
     } catch (e) { results.push({ ref: value, status: e.code === 'ENOENT' ? 'missing' : 'inaccessible', path: target, reason: e.code }); }
   }
   return results;

package/lib/view.mjs

@@ -0,0 +1,75 @@
+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';
+
+const paths = dir => ({ view: path.join(dir,'status.md'), meta: path.join(dir,'.aimship/view.json') });
+export async function viewStatus(directory, state) {
+  if (state.schemaVersion !== 2) return { status:'legacy', recovery:'Explicitly migrate this delivery before generating its view.' };
+  const p=paths(directory);
+  try {
+    if (!await exists(p.view)) return { status:'missing', recovery:'Run render at the current revision.' };
+    await noSymlinks(p.view); await noSymlinks(p.meta);
+    if (!await exists(p.meta)) return { status:'modified', recovery:'No trusted generation digest; preserve edits with render --preserve-edits.' };
+    const meta=await readJSON(p.meta), raw=await fs.readFile(p.view,'utf8');
+    if (hash(raw)!==meta.hash) return { status:'modified', recovery:'Inspect the edits, then render --preserve-edits.' };
+    const current=meta.deliveryId===state.deliveryId && meta.revision===state.revision;
+    return { status:current?'current':'stale', revision:meta.revision, recovery:current?null:'Run render; do not replay the saved business update.' };
+  } catch(error) { return {status:'error',reason:error.code ?? error.message,recovery:'Inspect view/metadata paths; preserve untrusted content before render.'}; }
+}
+const cell = x => String(x ?? 'not recorded').replaceAll('|','\\|').replaceAll('\n',' ');
+const link = ref => `[${ref.replaceAll('[','\\[').replaceAll(']','\\]')}](${ref.replaceAll(' ','%20').replaceAll('(','%28').replaceAll(')','%29')})`;
+async function available(directory,state,ref) {
+  if (/^https?:\/\//.test(ref)) return true;
+  const p=resolveRef(directory,state,ref); return p && await exists(p);
+}
+export async function renderText(directory,state) {
+  const artifactLink=ref=> {
+    if (!ref.startsWith('repo:')) return link(ref);
+    const target=resolveRef(directory,state,ref);
+    const fragment=ref.includes('#')?'#'+ref.split('#')[1]:'';
+    return target ? `[${cell(ref)}](${encodeURI(target).replaceAll('(','%28').replaceAll(')','%29')}${fragment})` : cell(ref);
+  };
+  const lines=['# Delivery status','','Generated by Aimship. Edit formal documents and structured state, not this page.','', '## Goal and basis','', cell(state.goal.summary), '',`Endpoint: ${cell(state.goal.endpoint)}`,''];
+  if (await available(directory,state,state.goalRef)) lines.push(artifactLink(state.goalRef),'');
+  lines.push('## Associated engineering objects','','| ID | Actual checkout/worktree | Role |','| --- | --- | --- |');
+  for (const r of state.repositories) lines.push(`| ${cell(r.id)} | ${cell(r.path)} | ${cell(r.role)} |`);
+  if (!state.repositories.length) lines.push('| — | No repository registered | — |');
+  lines.push('','## Stage progress','','| Run / scope | Stage | Progress | Result | Applicability |','| --- | --- | --- | --- | --- |');
+  for (const r of state.stageRuns) lines.push(`| ${cell(r.id)} / ${cell(r.scope)} | ${r.stage} | ${r.progress} | ${cell(r.result)} | ${cell(r.applicability)} |`);
+  lines.push('','## Current work, blockers and next action','',`Current: ${cell(state.currentRun)}`, '',`Next: ${cell(state.next.action)}`);
+  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.', '');
+  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)}`);
+  lines.push('','## Independent outcomes and generation','',`Goal: ${state.outcome.goal}`,`Acceptance: ${state.outcome.acceptance}`,`Merge: ${state.outcome.mergeRef?link(state.outcome.mergeRef):'not recorded'}`,`Deployment: ${state.outcome.deploymentRef?link(state.outcome.deploymentRef):'not recorded'}`,'',`Delivery: ${state.deliveryId}`,`State revision: ${state.revision}`,`Rules: ${state.rulesVersion}`,`State saved: ${state.updatedAt}`,'','Matching revisions do not establish document semantics or authorization.','');
+  return lines.join('\n');
+}
+export async function generateView(directory,state,preserveEdits=false) {
+  const p=paths(directory); const diagnostic=await viewStatus(directory,state);
+  let preservedPath;
+  try {
+    if (['modified','error'].includes(diagnostic.status) && await exists(p.view)) {
+      if (!preserveEdits) return {...diagnostic,status:'protected'};
+      await noSymlinks(p.view);
+      preservedPath=path.join(directory,'.aimship',`status-edits-${randomUUID()}.md`);
+      await atomicWrite(preservedPath,await fs.readFile(p.view));
+    }
+    const text=await renderText(directory,state);
+    await atomicWrite(p.view,text);
+    await atomicWrite(p.meta,json({deliveryId:state.deliveryId,revision:state.revision,hash:hash(text)}));
+    return {status:'current',revision:state.revision,...(preservedPath?{preservedPath}:{})};
+  } catch(error) {return {status:'error',reason:error.code??error.message,...(preservedPath?{preservedPath}:{}),recovery:'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)}};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimship",
-  "version": "0.1.0-preview.4",
+  "version": "0.1.0-preview.8",
   "description": "Explicit, goal-driven delivery workflow for coding agents",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,8 @@
   "scripts": {
     "test": "node --test --test-concurrency=1",
     "check:package": "node scripts/check-package.mjs",
-    "prepack": "node scripts/check-package.mjs"
+    "prepack": "node scripts/check-package.mjs",
+    "check:docs": "node scripts/check-docs.mjs"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/aimship/SKILL.md

@@ -11,9 +11,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.
+4. Read the selected [stage reference](references/core.md#stage-references) when reaching it. Explain design choices and unresolved decisions. Follow [document review](references/document-review.md): generate, self-check, give the document entry/short summary/next stage and pause. Explicit approval releases the next authorized stage without another start question; questions, silence and viewing results do not approve. Authorized implementation/review/repair/retest can then continue.
 5. At stable results and before a manual session switch, save the state and give a short continuation prompt. Keep a compact binding: delivery ID, absolute delivery directory, state path, current run, rules version, and fixed core/tool paths. After compaction, reload these references if absent; do not assume the full skill survived.
 
-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) only for an artifact being produced.
+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.
 
 The agent handles meaning, engineering and evidence. The local tools protect structure and writes; a successful command or a file's existence cannot establish goal completion. This skill does not schedule agents, open conversations, merge, deploy, or execute database changes by default.