aimship 0.0.0-stage → 0.1.0-preview.7

package/lib/cli.mjs

@@ -0,0 +1,171 @@
+import { migrateState, scanDeliveries } from './migrate.mjs';
+import { inspectDocuments } from './documents.mjs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { exists, fail, noSymlinks, readJSON } from './io.mjs';
+import { install, installPaths, installationStatus, installationVersion, readConfig, uninstall } from './install.mjs';
+import { SCHEMA_VERSION, STAGES, renderState, assertInstallationComplete, assertRules, checkReferences, initState, readState, recoverState, updateState, validateState } from './state.mjs';
+
+const HELP = {
+  usage: 'node <aimship.mjs> <command> [delivery-directory] [options]',
+  commands: {
+    render: 'render <dir> --revision <N> --rules-version <version> [--preserve-edits]. Explicitly rebuild status.md; preserve manual edits before replacement. Does not replay a state update.',
+    migrate: 'migrate <dir> --revision <old-N> --rules-version <active-version> --input <json-file|->. Input {compatibilityRef}; preserve legacy state then move to schema 2. Adopt rules separately; documents require reviewed reconciliation.',
+    scan: 'scan <material-root>. Read immediate delivery directories in both layouts, deduplicate IDs and report conflicts/unknown records. No global search or write.',
+    status: 'status [--home <dir>]. Read only Aimship-managed paths and fixed entries. Report registration, shared entry presence/integrity, active version, pending work and config problems. Host loading, login and access permissions remain unverified; no directories are created.',
+    bind: 'Resolve active installation once. Returns immutable release/core/stage/CLI paths plus configured dataRoot, configPath and customPath. Source mode returns the default data root with null config/custom paths. No directories are created. Optional --home is for isolated testing.',
+    init: 'init <dir> --input <json-file|-> --rules-version <version>. Create state once; input requires goal {summary, endpoint} and goalRef. Does not create templates.',
+    read: 'read <dir> [--rules-version <version>]. Read-only JSON access; unknown schemas remain readable.',
+    update: 'update <dir> --revision <N> --rules-version <version> --input <json-file|->. Recursively merge objects; arrays replace in full. Identity/history fields are managed. null is a literal value, not deletion.',
+    check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Checks explicit anchors/identity metadata in new local Markdown; reused and unsupported fragments are explicitly not checked. Does not prove semantics, remote access or validation results.',
+    resume: 'resume <dir> [--rules-version <version>]. Read state and return fixed rule paths, required inputs, warnings, and continuation text; never execute work or rewrite state.',
+    checkpoint: 'checkpoint <dir> --revision <N> --rules-version <old-version> --input <json-file|->. Save only checkpoint {summary, ref?} and next when a version mismatch interrupts ongoing work. Cannot complete work.',
+    adopt: 'adopt <dir> --revision <N> --rules-version <active-version> --input <json-file|->. Input is {compatibilityRef}; records the assessed stable-point rule switch without changing business history.',
+    recover: 'recover <dir> --revision <backup-revision> --rules-version <version>. Restore state.previous.json only over missing/corrupt state; preserve corrupted bytes. Inspect actual artifacts afterward; nothing reruns.',
+    install: 'install --host <codex|cursor|claude-code> [--host ...] [--data-root <dir>] [--home <dir>]. Explicitly copy the whole release into .aimship. Repeated installs retain registered hosts. Installed tools default to their owning home; explicit --home overrides it for isolated testing. Data root is configured, never created.',
+    uninstall: 'uninstall [--host <host> ...] [--home <dir>]. --host disconnects selected hosts, retaining shared core even when no hosts remain. Omit --host for full product uninstall. Delivery data, config, custom and modified/unowned files are retained. Installed tools default to their owning home; explicit --home overrides it.',
+    help: 'help [command]. Every command supports --help. --version reports the executing tool version and installed active version separately. install is the only installation/update entry; update modifies delivery state.'
+  },
+  stateProtocol: {
+    schemaVersion: SCHEMA_VERSION,
+    stages: STAGES,
+    progress: ['planned', 'active', 'blocked', 'done'],
+    result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
+    applicability: ['current', 'needs-review', 'unknown'],
+    outcome: { goal: ['in-progress', 'met', 'not-met', 'unknown'], acceptance: ['not-recorded', 'accepted', 'declined', 'unknown'] },
+    stageInstance: { id: 'stable-instance-id', stage: '<stage>', scope: 'batch or whole-delivery scope', progress: 'planned', inputRefs: [], outputRefs: [], resultRef: 'review.md#rev-001-v1 (required when done)' },
+    references: 'delivery-relative/path#optional-fragment, repo:<registered-id>/<repo-relative-path>#fragment, or HTTP(S) URL. Local paths cannot escape their root. Repository registration: {id, path: absolute-path, role}.',
+    topLevel: {
+      managed: 'schemaVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, rulesHistory, documentDigests, identityHistory, retiredIdentities, legacyRunIds, writeResult. Do not supply these in init/update.',
+      requiredInit: 'goal: {summary, endpoint}; goalRef: current requirements or Scope reference. Save source/request.md and the registered PRD/Scope draft before init; documentPolicy and documents are required.',
+      stageRuns: 'Ordered array of stageInstance objects, default []. Every ID is unique; currentRun must match one of these IDs or be null. Stage types may repeat with distinct IDs.',
+      currentRun: 'Instance ID or null (default). Do not invent an ID without registering its instance in stageRuns.',
+      repositories: 'Array of {id, path: absolute-path, role, ...optional-version-facts}, default []. No repository is required for a design-only goal.',
+      openChanges: 'Array of {id, ref, status: open|closed}, default []; close records rather than deleting history.',
+      outcome: 'Defaults to {goal: in-progress, acceptance: not-recorded}. A met goal needs goalConclusionRef; recorded acceptance needs acceptanceRef. Optional handoffRef, mergeRef, deploymentRef retain independent facts.',
+      next: '{action, inputRefs?: []}; defaults to continuing the confirmed arrangement.',
+      cycle: 'Positive integer, default 1. A reopening increments by one, appends a closureRef and resets current acceptance.',
+      closureRefs: 'Historical closure references, default []. Preserve them across reopenings.'
+    },
+    minimalInit: {
+      goal: { summary: 'Repair the search empty-state message', endpoint: 'Implement, review, and verify the agreed repair' },
+      goalRef: 'prd.md',
+      documentPolicy: {authority:'authored',interaction:false,prototypeCovered:false,interface:'none',databases:[]},
+      documents: [{kind:'prd',path:'prd.md',mode:'new',version:'1'}],
+      stageRuns: [{ id: 'requirements-1', stage: 'requirements', scope: 'Search empty-state repair', progress: 'planned', inputRefs: ['prd.md'], outputRefs: [] }],
+      currentRun: 'requirements-1',
+      next: { action: 'Draft the confirmed requirements', inputRefs: ['prd.md'] }
+    },
+    safety: 'Done is execution progress only. Results, applicability, goal attainment, acceptance, merge, and deployment are independent. Preserve old result references with priorResultRef/historyResultRefs. Goal revision needs a new goal.decisionRef; prior goals are retained automatically.'
+  }
+};
+function parse(argv) {
+  const positional = []; const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const item = argv[i];
+    if (!item.startsWith('--')) { positional.push(item); continue; }
+    const name = item.slice(2);
+    if (!['help', 'version', 'all', 'preserve-edits', 'input', 'rules-version', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
+    const value = ['help', 'version', 'all', 'preserve-edits'].includes(name) ? true : argv[++i];
+    if (value === undefined || (typeof value === 'string' && value.startsWith('--'))) fail('USAGE', `Missing value for ${item}`, 'Provide the option value.');
+    if (name === 'host') (options.hosts ??= []).push(value);
+    else { if (Object.hasOwn(options, name)) fail('USAGE', `Repeated option: ${item}`, 'Provide one value; only --host is repeatable.'); options[name] = value; }
+  }
+  return { positional, options };
+}
+async function inputJSON(file) {
+  if (!file) fail('USAGE', '--input is required.', 'Use a JSON file or --input - to read stdin.');
+  if (file !== '-') return readJSON(path.resolve(file));
+  try { let raw = ''; for await (const chunk of process.stdin) raw += chunk; return JSON.parse(raw); } catch (e) { fail('INVALID_JSON', 'Cannot parse JSON from stdin.', 'Provide one valid JSON object.', { cause: e.message }); }
+}
+function revisionOf(value) {
+  if (!/^(0|[1-9][0-9]*)$/.test(value ?? '') || !Number.isSafeInteger(Number(value))) fail('USAGE', '--revision requires a nonnegative integer.', 'Use the exact revision returned by read (backup revision for recover).');
+  return Number(value);
+}
+function installedRoot(sourceRoot) { return path.basename(path.dirname(sourceRoot)) === 'releases' ? path.dirname(path.dirname(sourceRoot)) : null; }
+async function runtimeFor(sourceRoot, options, explicitRoot) {
+  const pkg = await readJSON(path.join(sourceRoot, 'package.json'));
+  const root = explicitRoot ?? installedRoot(sourceRoot) ?? (options.home ? installPaths(options.home).root : null);
+  let activeVersion = pkg.version;
+  let installPending = null;
+  if (root) {
+    const manifest = await readJSON(path.join(root, 'install-manifest.json'));
+    if (manifest.schemaVersion !== 1 || manifest.product !== 'aimship') fail('INSTALL_FORMAT', 'Unknown installation manifest.', 'Use a compatible installer.');
+    installPending = manifest.pending ?? null;
+    if (await exists(path.join(root, 'active.json'))) {
+      const active = await readJSON(path.join(root, 'active.json'));
+      if (active.launcherProtocol !== 1 || typeof active.version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.-]+)?$/.test(active.version)) fail('INSTALL_FORMAT', 'Active pointer has an unsupported protocol or version.', 'Reinstall the exact complete package.');
+      activeVersion = active.version;
+    } else if (!installPending) fail('NOT_INSTALLED', 'No active installation exists.', 'Install the exact package explicitly.');
+  }
+  return { version: pkg.version, activeVersion, installPending, releaseRoot: sourceRoot, installRoot: root, launcher: root ? path.join(root, 'bin', 'aimship.mjs') : path.join(sourceRoot, 'bin', 'aimship.mjs') };
+}
+async function binding(runtime) {
+  assertInstallationComplete(runtime);
+  const root = runtime.installRoot ? path.join(runtime.installRoot, 'releases', runtime.activeVersion) : runtime.releaseRoot;
+  await noSymlinks(root);
+  const pkg = await readJSON(path.join(root, 'package.json'));
+  if (pkg.version !== runtime.activeVersion) fail('RELEASE_CONFLICT', 'Active pointer and release package version differ.', 'Repair installation before continuing.');
+  const corePath = path.join(root, 'skills', 'aimship', 'references', 'core.md');
+  if (!await exists(corePath)) fail('INCOMPLETE_RELEASE', 'The bound core is missing.', 'Repair the exact installation before continuing.');
+  const configPath = runtime.installRoot ? path.join(runtime.installRoot, 'config.json') : null;
+  let dataRoot = path.join(os.homedir(), 'Aimship');
+  if (configPath) {
+    dataRoot = (await readConfig(configPath)).dataRoot;
+  }
+  return { version: pkg.version, schemaVersion: SCHEMA_VERSION, launcherProtocol: 1, releaseRoot: root, corePath, stageDirectory: path.join(root, 'skills', 'aimship', 'references', 'stages'), cliPath: path.join(root, 'bin', 'aimship.mjs'), launcherPath: runtime.launcher, nodePath: process.execPath, dataRoot, configPath, customPath: runtime.installRoot ? path.join(runtime.installRoot, 'custom') : null, configurationStatus: runtime.installRoot ? 'installed' : 'source-default' };
+}
+function allowed(command, options) {
+  const common = ['help', 'version'];
+  const perCommand = { render: ['revision','rules-version','preserve-edits','home'], migrate:['revision','rules-version','input','home'], scan:['home'], status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
+  for (const key of Object.keys(options)) if (![...common, ...(perCommand[command] ?? [])].includes(key)) fail('USAGE', `Option --${key} is not valid for ${command}.`, `Run help ${command}.`);
+}
+export async function run(argv, context) {
+  if (Number(process.versions.node.split('.')[0]) < 22) fail('NODE_VERSION', 'Aimship requires Node.js 22 or later.', 'Install a maintained Node LTS release and rerun this exact package.');
+  const { positional, options } = parse(argv); const command = positional[0] ?? 'help';
+  const pkg = await readJSON(path.join(context.sourceRoot, 'package.json'));
+  const owningInstallRoot = context.installRoot ?? installedRoot(context.sourceRoot);
+  const installHome = options.home ?? (owningInstallRoot ? path.dirname(owningInstallRoot) : undefined);
+  if (options.version) {
+    const installed = await installationVersion({ home: installHome });
+    return { command: 'version', data: { version: pkg.version, toolVersion: pkg.version, installedActiveVersion: installed.installedActiveVersion, installation: installed.installation, pendingVersion: installed.pending?.version ?? null, node: process.version, integrity: 'Use status for managed-file and config integrity; host loading, login and permissions are not verified.', issues: [installed.manifest.error, installed.active.error].filter(Boolean) } };
+  }
+  if (command === 'help' || options.help) {
+    const subject = command === 'help' ? positional[1] : command;
+    if (subject && !HELP.commands[subject]) fail('USAGE', `Unknown command: ${subject}`, 'Run help.');
+    return { command: 'help', data: subject ? { usage: HELP.commands[subject], stateProtocol: HELP.stateProtocol } : HELP };
+  }
+  if (!HELP.commands[command]) fail('USAGE', `Unknown command: ${command}`, 'Run help.');
+  allowed(command, options);
+  if (['install', 'uninstall', 'bind', 'status'].includes(command) ? positional.length !== 1 : positional.length !== 2) fail('USAGE', 'Unexpected or missing positional arguments.', `Run help ${command}.`);
+  if (command === 'status') return { command, data: { toolVersion: pkg.version, ...await installationStatus({ home: installHome }) } };
+  if (command === 'install') return { command, data: await install(context.sourceRoot, { home: installHome, hosts: options.hosts, dataRoot: options['data-root'] }) };
+  if (command === 'uninstall') return { command, data: await uninstall({ home: installHome, hosts: options.hosts }) };
+  if (command === 'scan') return {command,data:await scanDeliveries(path.resolve(positional[1]))};
+  const runtime = await runtimeFor(context.sourceRoot, options, context.installRoot);
+  if (command === 'bind') return { command, data: await binding(runtime) };
+  const directory = path.resolve(positional[1]); const rulesVersion = options['rules-version'];
+  if (command === 'render') return {command,data:await renderState(directory,revisionOf(options.revision),rulesVersion,runtime,options['preserve-edits'])};
+  if (command === 'migrate') return {command,data:await migrateState(directory,revisionOf(options.revision),rulesVersion,runtime,await inputJSON(options.input))};
+  if (command === 'init') return { command, data: await initState(directory, await inputJSON(options.input), rulesVersion, runtime) };
+  if (['update', 'checkpoint', 'adopt'].includes(command)) return { command, data: await updateState(directory, await inputJSON(options.input), revisionOf(options.revision), rulesVersion, runtime, command) };
+  if (command === 'recover') return { command, data: await recoverState(directory, revisionOf(options.revision), rulesVersion, runtime) };
+  const read = await readState(directory);
+  let mismatch = null;
+  if (!read.readOnly) { try { assertRules(read.state, rulesVersion, runtime); } catch (error) { mismatch = { code: error.code, ...error.details, recovery: error.recovery }; } }
+  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: read.statePath, view: read.view, documentChanges: read.documentChanges, layoutConflict:read.conflict??false, layoutMismatch:read.layoutMismatch??false, candidates:read.candidates, migration:read.migration?.status??null } };
+  if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: read.conflict?'Conflicting state layouts require explicit reconciliation.':'Unknown schema: no structure checking, mutation, or automatic work is permitted.', candidates:read.candidates } };
+  validateState(read.state); const references = await checkReferences(directory, read.state, options.all);
+  const documents=await inspectDocuments(directory,read.state);
+  const missing = references.filter(x => !['exists', 'not-checked'].includes(x.status));
+  if (command === 'check') {
+    if (missing.length) fail('REFERENCE_CHECK', 'Required references are missing or inaccessible.', 'Repair the specific registered paths; do not scan the disk or overwrite source materials.', { references, versionMismatch: mismatch });
+    if (mismatch) fail('VERSION_MISMATCH', 'State is structurally valid, but rules are not bound consistently.', mismatch.recovery, mismatch);
+    if (documents.issues.length) fail('DOCUMENT_CHECK','Document mapping or identities need repair.','Inspect listed issues.',documents);
+    return { command, data: { structure: 'valid', references, documents, view:read.view, documentChanges:read.documentChanges, semantics: 'not-checked' } };
+  }
+  const currentRun = read.state.stageRuns.find(x => x.id === read.state.currentRun) ?? null;
+  const blocked = currentRun?.progress === 'blocked';
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, canProceed: read.state.documentPolicy?.authority !== 'legacy' && !mismatch && missing.length === 0 && !blocked && !documents.issues.length && !read.documentChanges.length && read.view.status === 'current' && (!read.migration || read.migration.status === 'complete'), statePath:read.statePath, view:read.view, documentChanges:read.documentChanges, documents, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read ${read.statePath} and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
+}

package/lib/documents.mjs

@@ -0,0 +1,155 @@
+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) {
+  const file = resolveRef(directory, state, ref);
+  if (!file) return null;
+  const real = await fs.realpath(file);
+  const base = ref.startsWith('repo:') ? state.repositories.find(r => r.id === /^repo:([^/]+)/.exec(ref)[1]).path : directory;
+  if (!inside(await fs.realpath(base), real)) fail('INVALID_REFERENCE', 'Reference resolves outside its root.', 'Repair the symbolic link or reference.');
+  return fs.readFile(real, 'utf8');
+}
+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);
+    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 === 'tech-design') {
+        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 (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;
+}