aimship 0.1.0-preview.4 → 0.1.0-preview.7

package/lib/state.mjs

@@ -1,9 +1,11 @@
 import fs from 'node:fs/promises';
 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 SCHEMA_VERSION = 2;
 export const STAGES = ['frame', 'requirements', 'prototype', 'scope', 'diagnose', 'tech-design', 'contract', 'plan', 'test-design', 'implement', 'review', 'verify', 'handoff'];
 const PROGRESS = ['planned', 'active', 'blocked', 'done'];
 const RESULTS = ['passed', 'failed', 'not-run', 'unknown', 'mixed'];
@@ -24,7 +26,21 @@ 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.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.');
@@ -60,16 +76,51 @@ export function validateState(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);
   if (!readOnly) validateState(state);
-  return { ...paths, state, readOnly };
+  return {...paths,state,readOnly,layoutMismatch,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 +135,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;
+    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);
   });
 }
 function merge(base, patch) {
@@ -120,9 +172,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 +193,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 +205,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);
     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 +221,15 @@ 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.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; }
         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) {
@@ -203,7 +261,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,69 @@
+import fs from 'node:fs/promises';
+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)}`);
+  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.7",
   "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

@@ -14,6 +14,6 @@ Activate only when the user explicitly asks to start or resume Aimship. Ordinary
 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.
 
-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.

package/skills/aimship/references/artifact-map.json

@@ -0,0 +1,163 @@
+{
+  "version": 1,
+  "documents": {
+    "prd": {
+      "path": "prd.md",
+      "sections": [
+        "info",
+        "goals",
+        "scope",
+        "requirements",
+        "states",
+        "acceptance",
+        "arrangement"
+      ]
+    },
+    "scope": {
+      "path": "scope.md",
+      "sections": [
+        "info",
+        "goals",
+        "adoption",
+        "exclusions",
+        "decisions",
+        "acceptance",
+        "arrangement"
+      ]
+    },
+    "tech-design": {
+      "path": "tech-design.md",
+      "sections": [
+        "basis",
+        "architecture",
+        "modules",
+        "data",
+        "errors",
+        "risks",
+        "coverage"
+      ]
+    },
+    "plan": {
+      "path": "plan.md",
+      "sections": [
+        "basis",
+        "batches",
+        "tasks",
+        "validation",
+        "execution",
+        "remaining"
+      ]
+    },
+    "testing": {
+      "path": "testing.md",
+      "sections": [
+        "basis",
+        "environment",
+        "cases",
+        "coverage",
+        "runs",
+        "conclusion"
+      ]
+    },
+    "review": {
+      "path": "review.md",
+      "sections": [
+        "basis",
+        "reviews",
+        "conclusion"
+      ]
+    },
+    "diagnosis": {
+      "path": "diagnosis.md",
+      "sections": [
+        "goals",
+        "symptoms",
+        "environment",
+        "evidence",
+        "causes",
+        "unknowns",
+        "conclusion"
+      ]
+    },
+    "handoff": {
+      "path": "handoff.md",
+      "sections": [
+        "goals",
+        "artifacts",
+        "usage",
+        "results",
+        "limits",
+        "outcomes"
+      ]
+    },
+    "change-log": {
+      "path": "change-log.md",
+      "sections": [
+        "changes",
+        "remaining"
+      ]
+    }
+  },
+  "stages": {
+    "frame": {
+      "kind": "requirement",
+      "section": "goals"
+    },
+    "requirements": {
+      "kind": "requirement",
+      "section": "requirements",
+      "sectionByKind": {
+        "prd": "requirements",
+        "scope": "adoption"
+      }
+    },
+    "scope": {
+      "kind": "requirement",
+      "section": "scope",
+      "sectionByKind": {
+        "prd": "scope",
+        "scope": "goals"
+      }
+    },
+    "prototype": {
+      "kind": "prototype",
+      "section": null
+    },
+    "diagnose": {
+      "kind": "diagnosis",
+      "section": "conclusion"
+    },
+    "tech-design": {
+      "kind": "tech-design",
+      "section": "coverage"
+    },
+    "contract": {
+      "kind": "contract",
+      "section": null
+    },
+    "plan": {
+      "kind": "plan",
+      "section": "tasks"
+    },
+    "test-design": {
+      "kind": "testing",
+      "section": "cases"
+    },
+    "implement": {
+      "kind": "plan",
+      "section": "execution"
+    },
+    "review": {
+      "kind": "review",
+      "section": "reviews"
+    },
+    "verify": {
+      "kind": "testing",
+      "section": "runs"
+    },
+    "handoff": {
+      "kind": "handoff",
+      "section": "outcomes"
+    }
+  }
+}

package/skills/aimship/references/core.md

@@ -4,7 +4,7 @@
 
 A delivery has one centralized material directory, a preserved original request, current requirements or adopted sources plus Scope, an endpoint, and a state record. Code stays in its existing locations. A single repository and several repositories use the same model; there is no project registration step, repository count limit, or route classification.
 
-Understand the intended result, supplied evidence, authorized changes and endpoint. Record known answers instead of asking again. Clarify only gaps that affect this work, with a recommendation and its consequence. Do not promote assumptions into user decisions. A design-only commission may have no repository. A short bug fix still needs its original report, context, expected behavior, scope and acceptance criteria, but not a full PRD.
+Understand the intended result, supplied evidence, authorized changes and endpoint. Record known answers instead of asking again. Clarify only gaps that affect this work, with a recommendation and its consequence. Do not promote assumptions into user decisions. A design-only commission may have no repository. A short bug fix still needs its original report, context, expected behavior, scope and acceptance criteria, with a concise prd.md using the fixed outline.
 
 Use the configured material root (default `~/Aimship`), with one identifiable directory per delivery. Do not create it during installation. Before creating a new directory, use the user's explicit target or check a possible existing match; ambiguous candidates need selection, not a global “latest” pointer. If access fails, retain the request and intended location in the conversation and say what has not been saved. Continue the same delivery after access is restored.
 
@@ -16,7 +16,7 @@ Several independent deliveries may progress at the same time, each with its own
 
 Check when code scope is associated or changed, before entering implementation, or when an actual code working directory changes. Do not repeat it every turn or stage. Once the code scope is known:
 
-1. Enumerate all delivery directories in the accessible configured material root and any other explicitly known/authorized material roots or delivery locations. Read their `state.json` summaries; do not limit the search to recent folders. Do not scan the whole disk, code trees, processes, PRDs or full histories. Do not discover unknown custom roots by searching the home directory. Report roots checked and inaccessible, invalid or unknown-format records; unseen custom roots and non-Aimship work remain outside the check.
+1. Enumerate all delivery directories in the accessible configured material root and any other explicitly known/authorized material roots or delivery locations. Use `scan <known-root>` or read both legacy `state.json` and new `.aimship/state.json` summaries; deduplicate deliveryId and report conflicting copies; do not limit the search to recent folders. Do not scan the whole disk, code trees, processes, PRDs or full histories. Do not discover unknown custom roots by searching the home directory. Report roots checked and inaccessible, invalid or unknown-format records; unseen custom roots and non-Aimship work remain outside the check.
 2. Exclude this delivery by `deliveryId`. Compare `repositories[].path` (the actual checkout/worktree root), role, `currentRun`, relevant `stageRuns` scope/progress, `outcome`, `next` and recorded update time. Repository IDs are local to each delivery and are not global repository identity. Use already recorded repository identity; when needed and accessible, read only local Git root/common-directory metadata for the associated paths to distinguish linked worktrees. Normalize existing paths to their actual location; nested paths in one checkout are not independent isolation. Distinct independent checkouts may share a recorded repository identity even with different Git directories. If identity/location cannot be established, report it as unknown rather than assuming separation.
 3. Include older active, blocked or uncertain deliveries. A `done` stage, completed handoff, old timestamp or declined acceptance alone does not close a delivery. A recorded met goal with no recorded remaining code work is ended; otherwise use the existing explicit closing conclusion if needed. `not-met` or `unknown` is not automatically ended. Read only the relevant Scope/plan/conclusion section when state summaries cannot establish writing intent or closure. Do not rewrite another delivery's state. Ended deliveries are not active writers, although their unmerged results or known dependencies can still matter.
 4. Compare actual writing intent and locations using the table below. A stage label alone is not permission to write code. Keep one brief result in the existing Scope/plan or results section, linked from the current delivery's existing references when needed: check occasion, roots/limits, relevant delivery IDs and recorded stages, actual directories, known dependencies and chosen arrangement. State stays authoritative; do not add a registry, index, second progress ledger or service.
@@ -33,7 +33,7 @@ Records can be stale and cannot detect all other work. Do not switch another ses
 
 ## Agree an ordered arrangement
 
-Choose stages from the responsibilities below based on the goal and existing inputs. Requirements and scope alignment are always needed; they may be one short conversation and one document. Adopt adequate existing artifacts as inputs without claiming their stages were newly executed. Do not create empty stage runs or templates.
+Choose stages from the responsibilities below based on the goal and existing inputs. Requirements and scope alignment are always needed; use the fixed PRD/Scope conditions in [document patterns](document-patterns.md). Adopt adequate existing artifacts as inputs without claiming their stages were newly executed. Do not create empty stage runs or templates.
 
 Show the selected order and endpoint. If the user already specified or accepted this arrangement, record the decision and proceed. An unanswered proposal remains a proposal. Once agreed, follow the order; adding, dropping or reordering work needs a reason and an updated record. Important changes follow [change flow](sources-and-changes.md). A stage may recur as distinct instances with stable IDs and explicit scopes.
 
@@ -77,8 +77,12 @@ Use the installed tool's documented state protocol. Read the current revision be
 
 Important semantic changes retain historical review and test facts, mark affected conclusions for review and update the current editable authority. Do not overwrite external adopted sources. See [sources and change flow](sources-and-changes.md).
 
-At stable results save the state, remaining issues and next action. On a session switch give: “Use Aimship to continue <absolute delivery directory>; read state.json, the current goal/Scope and next-step inputs; <specific blocker if any>.” A new session reloads the same delivery, not the whole transcript. Use [recovery](recovery.md) for mismatch or uncertainty. Keep one active writing session per delivery.
+At stable results save the state, remaining issues and next action. On a session switch give: “Use Aimship to continue <absolute delivery directory>; read the actual statePath returned by read (new: .aimship/state.json), the current goal/Scope and next-step inputs; <specific blocker if any>.” A new session reloads the same delivery, not the whole transcript. Use [recovery](recovery.md) for mismatch or uncertainty. Keep one active writing session per delivery.
 
 End when the current confirmed goal is met. For design work this means the agreed design, not code execution. For development it includes agreed review and verification. “Show me the result” does not shorten the goal. If the user explicitly changes the endpoint, preserve the old goal, decision and unfinished work, update the arrangement, and assess the revised goal. An incomplete handoff is allowed but is not goal completion.
 
 Small corrections within the original goal can reopen the same delivery: preserve its previous closure and result basis, increment the cycle, and review/verify affected work. A separate goal or substantial redesign starts a related delivery; retain the defect or source relationship without introducing parent/child scheduling. Prepared, accepted, merged and deployed are independent facts.
+
+## Formal artifacts and generated status
+
+Read [document patterns](document-patterns.md) when establishing or revising the arrangement. All new formal documents use its fixed outlines and [artifact map](artifact-map.json). status.md is generated from structured state; tasks remain in plan.md. read/check/resume are read-only; inspect view and document-change warnings, and use explicit render to repair a stale/missing view. Preserve edits before rebuilding; never infer a business decision from hand-edited display text. After partial view failure use the saved revision, not a repeated business update.

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

@@ -1,19 +1,39 @@
-# Optional document patterns
+# Delivery documents and traceability
 
-Use only the needed sections and artifacts. These are prompts for useful content, not empty files to generate automatically. Small work may combine diagnosis, test design, review, verification and handoff in `results.md`, with distinct referenced sections.
+[artifact-map.json](artifact-map.json) is the shared mapping for stages, templates and checks. Use [templates](templates/prd.md) for newly authored documents; preserve section order and anchors, translate visible headings freely, and explain inapplicable sections. Templates are drafting guidance, not empty artifacts to generate for every delivery.
 
-**Requirements / Scope:** original request or adopted source; background; current goal and endpoint; included/excluded scope; authorized objects and constraints; requirements and acceptance criteria; source mapping; conflicts/decisions and open questions. Keep original input separate from revised current content.
+One request has one directory. Formal documents are at its root. `source/request.md` preserves the original commission or source entry; other adopted versions stay in `source/` without overwriting. State, recovery copies, necessary evidence and generated host configuration belong under `.aimship/`. Generated `status.md` is the reading entry; no default INDEX, docs/sql hierarchy, AI copy, transcript or full export. A requested export is a dated object/version snapshot, never an editing authority.
 
-**Technical design:** current requirement basis; engineering constraints; chosen structure and alternatives/tradeoffs; interface links; data and compatibility; failure/recovery; risks and open decisions. For database changes link the independent SQL and its dialect/version, existing schema basis and execution conditions.
+## Input and output conditions
 
-**Plan:** batch ID and goal; requirement coverage; files/repositories and boundary; dependencies and interface; each batch review scope; overall review and independent verification. State tracks progress, so do not create a competing progress table.
+Author current requirements in `prd.md`, including scope. Adopt an authoritative PRD/prototype through `scope.md`, preserving source/version/original IDs and gaps. Prior authorship does not make an adopted source editable. Only explicit maintenance of an editable authoritative PRD that completely expresses this commission's scope/authorization/endpoint permits registered reuse without another PRD/Scope. Scattered ideas/screenshots/reference cases are inputs to a PRD, not automatically authoritative requirements.
 
-**Verification plan:** requirement/risk → scenario and observable expected result; environment/data/tools; normal, error, boundary and relevant regression cases; known execution gaps. Keep missing-condition cases visible.
+Interaction changes require a prototype when existing adopted material does not cover them and that work lies within the commissioned endpoint. New HTML uses `prototype/index.html`; register other agreed formats or reused entries. No interaction change means no invented prototype. Investigation/clarification-only requirements describe that commission and leave future development undefined.
 
-**Review record:** actor/source and date; exact objects/versions/differences; batch/overall/affected scope; requirements/design basis; findings, disposition and conclusion. A single-batch review explicitly covers both batch and overall responsibilities.
+`plan` must finish before first implementation, even one small batch. `plan.md` holds both planned TASK/B records and actual execution, distinctly; state holds stage progress. `testing.md` holds cases/coverage and appended RUN records; verification follows overall review. Verify-only may register existing cases with version/coverage, without claiming test-design occurred. Review-only does not require implementation/tests. No arbitrary small-task merging, `implementation.md`, `test-plan.md`, `verification.md`, or `results.md` for new work.
 
-**Verification record:** actor/source and date; case version; tested code/build and environment; executed commands/operations; assertions and actual results; pass/fail/not-run/unknown; evidence locations; missing conditions and recovery action. Append a retest rather than rewriting the earlier failure.
+Use `tech-design.md`. HTTP changes use `openapi.yaml` or the registered engineering authority; no extra contract wrapper. Non-HTTP formats are explicitly registered. Database changes require independent `database.sql` (one target) or `database-<id>.sql` per target before tech-design completes. SQL headers identify target/dialect/version/schema basis/conditions; ordered sections cite requirements/design. Never substitute a Markdown block or migration reference, or execute/change migration mechanisms without authorization.
 
-**Change:** stable ID; reason and decision source; old/new meaning; affected artifacts/runs; remaining uncertainty; work completed and review/verification result. One important decision affecting several artifacts remains one record.
+`diagnosis.md` belongs only to an explicitly selected independent investigation. Known-cause bugs and ordinary development debugging do not add diagnose. Major unknowns require a recorded stage adjustment; hold dependent work. Implementation defects go to implementation, design errors to design, requirement gaps to PRD/Scope, incorrect expectations to versioned cases.
 
-**Handoff:** current goal (and explicit revision if any); completed deliverables and links; how to use/check; actual review and verification scope; limitations/remaining work; goal achievement, acceptance, merge and deployment as separate facts; continuation if incomplete.
+## Identities and references
+
+New local identities: REQ (type distinguishes functional, shared rule, permission, technical or quality), AC, B, TASK, TC, REV, RUN, CHG, Q, PAGE. Start at 001, increment after the historical maximum (including retired), never reuse an identity for another obligation. Shared rules, independent acceptance and single-role access/performance requirements must not disappear inside generic feature prose. Preserve external prefixes and source/version namespace. Splits/merges receive new identities and map old to new; classification changes retain identity.
+
+One effective definition per namespace/ID; historical versions are explicitly labeled. Keep ordinary repeated citations as references, not duplicate definitions. New local Markdown uses explicit anchors and definition metadata beside the actual table row/section:
+
+```markdown
+<a id="req-001-v1"></a>
+<!-- aimship:def {"id":"REQ-001","version":1,"status":"current","refs":["local:AC-001@1"]} -->
+REQ-001 | functional | ... actual obligation and source ...
+```
+
+Optional `namespace` defaults to `local`; source identity may use `source-v1`. External IDs keep their original spelling (including nonnumeric forms such as `acceptance.login`); `:` and `@` are reserved reference delimiters. For an external ID without a recognized prefix, set `kind` to REQ, AC, B, TASK, TC, REV, RUN, CHG, Q or PAGE when its role is needed for coverage checks, for example `{"namespace":"source-v1","id":"acceptance.login","kind":"AC","version":1,"status":"current","refs":[]}`. Reference it as `source-v1:acceptance.login@1`; do not renumber the source. `status` is current/historical/retired. `refs` uses namespace:ID@version (no implicit latest). Put metadata at the single definition; table/Markdown citations elsewhere may repeat. Retain old TC definitions or necessary prior meaning and increment versions for semantic changes. RUN metadata cites exact TC versions; its prose binds code/build, actual command/assertion/result/evidence. Tools check metadata resolution and basic coverage; Agent checks whether it truly covers every assertion.
+
+REQ/source → AC → design/operation/SQL, TASK → actual repository object → REV, and AC → TC@version → RUN@object. Relationships live in those documents, not a trace.md or a second state matrix. Q is defined once in the discovering document with impact/needed decision/status/source; resolving it also updates the affected formal authority, linked to one CHG if meaning changes. Old review/test facts remain; only affected current applicability becomes needs-review.
+
+## Saving and checking
+
+Register `documentPolicy` and `documents` per [CLI](../../../docs/cli.md). Draft at stage start; completion requires the mapped artifact and precise result anchor, not merely a filename. New Markdown anchors/metadata are machine-checkable; reused/remote/binary material needs recorded basis and explicit unchecked scope. Local references remain relative to delivery root even though JSON moved internally.
+
+Save unfinished intent, update formal documents, inspect them, then revision-check state. A matching status revision does not prove documents unchanged. Read/check/resume diagnose only. A saved state with a failed view must be repaired using render at the returned revision, never replayed. Preserve hand-edited status before rebuilding and interpret intent against existing authority; it cannot confer acceptance or publishing permission.

package/skills/aimship/references/hosts.md

@@ -5,11 +5,13 @@ Reuse the current session's access when normal file operations succeed. Do not c
 When access is missing, name the exact delivery/repository path and the needed operation. Retain the original request and continuation context. Do not disable host permission controls, grant the entire home directory or silently move materials into the repository.
 
 - Codex: explicitly select Aimship (CLI `$aimship`). If CLI startup is needed, verify the executable/version/help and use its supported `--cd` and repeated `--add-dir` syntax for the needed writable directories. For desktop, rely on the actual current interface or official guidance; never invent a directory button or claim a prepared path has been granted access.
-- Cursor: explicitly use `/aimship`. When useful, prepare `host/cursor.code-workspace` inside the delivery with `folders` entries only, referencing materials and repositories; preserve an existing workspace's settings. The user opens/adds folders when necessary. For CLI verify the exact executable (do not assume bare `agent` is Cursor) and current `--workspace` / `--add-dir` support.
+- Cursor: explicitly use `/aimship`. When useful, prepare `.aimship/host/cursor.code-workspace` inside the delivery with absolute `folders[].path` entries only, referencing materials and repositories; preserve an existing workspace's settings. The user opens/adds folders when necessary. For CLI verify the exact executable (do not assume bare `agent` is Cursor) and current `--workspace` / `--add-dir` support.
 - Claude Code: explicitly use `/aimship`; verify current `/add-dir` or `--add-dir` behavior when additional access is needed. Do not fork the skill or start a subagent.
 
 Installation discovery, actual selection, model behavior, directory access and continuation are separate evidence levels. Codex/Cursor share the managed `.agents/skills/aimship` entry; Claude Code uses `.claude/skills/aimship`. A host may discover both, including when it is not registered with Aimship. Registration controls installer-managed connections, not another host’s compatibility scanning. Managed entries must point to the same stable installation; do not assume duplicate precedence or delete unrelated entries. Record duplicates as observed, and consult the published support matrix for tested surfaces.
 
 After compaction or manual switching, reload the fixed-version core, state and current-stage inputs if missing. Do not rely on a host retaining all skill text. If even the binding location is absent, request the delivery path. Re-invoking an entry to restore context continues the existing delivery; it does not create another one.
 
-When changing hosts, use the same delivery directory and state; do not duplicate requirements, Scope or design to establish a new session. Permissions must be granted separately in each host. Keep one writing host/session for the delivery. User-facing entry/reload and lifecycle instructions are in [the installation guide](../../../docs/installation.md).
+When changing hosts, use the same delivery directory and state; do not duplicate requirements, Scope or design to establish a new session. Permissions must be granted separately in each host. Keep one writing host/session for the delivery. User-facing entry/reload and lifecycle instructions are in [the user guide](../../../docs/guide.md#hosts).
+
+When reconciling an old Aimship-created workspace, resolve relative folders against its old file location before writing the new internal file. Verify actual checkout/worktree identity. Do not move or replace a user-owned existing workspace.

package/skills/aimship/references/recovery.md

@@ -11,3 +11,11 @@ A tool/version mismatch stops new stage advancement. Save only in-progress facts
 Unknown newer formats remain readable as files but must not be overwritten or silently downgraded. Structural migrations require a supported conversion, necessary backup, clear description and validation. If no migration exists, preserve the materials and state the gap; do not invent historical stages. Compatible rules updates do not require new goal approval. Never sweep ended deliveries during install; only assess an ended delivery when it is reopened.
 
 Installation and data are separate. Explicit install manages product-owned files and host entries. Preserve user customizations and unrelated same-name skills; report the exact conflict. Uninstall retains delivery materials, customization and necessary configuration. Recovery retains a bounded previous installation, not every runtime forever. Consult the CLI help for implemented operations; do not bypass checks with raw state edits to obtain a success result.
+
+## Schema 1 to schema 2
+
+Read reports the actual statePath and layout. Use migrate on one explicitly selected delivery, with the old revision and a compatibilityRef; then adopt active rules at the returned revision. The migration journal and byte-preserved source copies stay under .aimship. A pending journal requires the original migrate parameters, not a normal update. Conflicting dual layouts and unknown schemas never accept normal writes.
+
+Migration converts state layout/schema only. Reconcile legacy requirements/design/implementation/test-plan/verification by their actual role, retaining original text and versioned results. Register legacy files as reused with a compatibility basis; create missing new plan/testing content for future work without inventing historical stages. Move necessary evidence and Aimship-created host files only with a concrete mapping, rewrite report links, and resolve workspace relative folders from the old location. Ordinary business source is never overwritten.
+
+State is authoritative for stages; status is generated. JSON may have saved while view generation failed: use returned revision and render, never repeat update. Read/check/resume never repair implicitly. Inspect changed registered documents even when view revision matches. render --preserve-edits retains a modified status before replacing it; interpret intent and update the formal authority separately.