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

package/docs/installation.md

@@ -1,117 +1,24 @@
-# Installation and lifecycle
+# Installation guide moved
 
-## Installation layout
+Installation and lifecycle instructions now live in the complete user guide. This page preserves the old entry point.
 
-Aimship installs fixed releases under `~/.aimship/` and a stable launcher at `~/.aimship/bin/aimship.mjs`. User configuration and custom content are separate from release files. A current release and at most one ordinary recovery release are retained; changed or unowned files are preserved and reported.
+- [English guide](guide.md#install)
+- [中文使用指南](guide.zh-CN.md#install)
 
-Choose `codex`, `cursor` or `claude-code` using repeatable `--host`. Registered hosts use one core and rules version. No per-project install, administrator privilege, npm global install, background updater or resident process is required. Source checkout, local tarball and registry examples all invoke this same installer; choose the appropriate source, do not stack them as separate host installations or add manual skill copies alongside managed entries. Installing software, connecting a host and starting a delivery are separate actions. Installation never creates `~/Aimship` or an empty delivery and never changes code repositories.
+<a id="installation-layout"></a>
+<a id="source-and-local-packages"></a>
+<a id="isolated-trial"></a>
+<a id="registry-installation-after-publication"></a>
+Installation layout, source/local packages and isolated trials: [English](guide.md#install) · [中文](guide.zh-CN.md#install).
 
-Node 22+ and npm are required. Installation and tool behavior have been checked on macOS arm64 with Node 24 and 26. Node 22 and other operating systems are not yet verified. Shell examples below use a POSIX shell. Preserve any existing installation before resolving conflicts.
+<a id="host-entry-and-reload"></a>
+Host entry and reload: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts).
 
-## Source and local packages
+<a id="add-a-host-inspect-and-update"></a>
+Add a host and inspect the installation: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts). Update software: [English](guide.md#update) · [中文](guide.zh-CN.md#update).
 
-From the source checkout:
+<a id="disconnect-or-uninstall"></a>
+Disconnect or uninstall: [English](guide.md#uninstall) · [中文](guide.zh-CN.md#uninstall).
 
-```sh
-node bin/aimship.mjs install --host codex
-```
-
-From the directory containing a supplied tarball:
-
-```sh
-npx --offline file:./aimship-0.1.0-preview.4.tgz install --host codex
-```
-
-Run these against your real home only when you intend to install. Repeat `--host` to connect multiple hosts in that operation. No login to npm is needed to consume a local tarball; npm still needs a writable cache. The installer reports the installation home, previous/target version, action/result, registered hosts and entry locations. A zero exit status is not proof that a host has loaded the skill.
-
-### Isolated trial
-
-These commands use one disposable installation and npm cache, not your real configuration. Put the candidate tarball in your current directory first:
-
-```sh
-trial=$(mktemp -d)
-trial=$(cd "$trial" && pwd -P)
-npx --yes --offline --cache "$trial/npm-cache" file:./aimship-0.1.0-preview.4.tgz install --home "$trial/home" --host codex
-node "$trial/home/.aimship/bin/aimship.mjs" --version
-node "$trial/home/.aimship/bin/aimship.mjs" status
-node "$trial/home/.aimship/bin/aimship.mjs" install --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall --host cursor
-node "$trial/home/.aimship/bin/aimship.mjs" uninstall
-```
-
-`--home` redirects only Aimship's managed installation. It does not make the running host discover this home, log in, or inherit permissions. The installed launcher and fixed release CLI default later management operations to their own installation home. An explicit `--home` overrides that target. After inspection, the disposable directory can be removed by its owner; do not substitute a real home for this temporary variable.
-
-## Registry installation after publication
-
-This candidate has not been published. After the maintainer confirms the package identity and publishes this exact preview, the proposed initial command is:
-
-```sh
-npx aimship@preview install --host codex
-```
-
-The `preview` tag selects the preview channel. To select an exact version, replace `@preview` with its version number. Confirm the package installation when npm prompts. npm obtains the installer; it copies a complete local release, so subsequent use does not depend on that npm cache. Do not use an unversioned command and assume it selects the preview channel. A missing package/version is a distribution failure, not a successful installation.
-
-## Host entry and reload
-
-| Host | Managed entry | Explicit use | After install, update or disconnect |
-| --- | --- | --- | --- |
-| Codex | `~/.agents/skills/aimship/` with `agents/openai.yaml` | Select Aimship; CLI `$aimship` | Start a new conversation or restart the CLI, then inspect its actual skill selector. If stale, restart the app. |
-| Cursor | Same `.agents/skills/aimship/` entry | `/aimship` | Start a new agent session; inspect Customize → Skills in the editor. Restart the host if the list remains stale. |
-| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | Start a new session and inspect slash-command discovery; restart the host if stale. |
-
-These host integrations are experimental; end-to-end host behavior and cross-host continuation have not yet been verified. Check skill discovery and directory access in your host before starting a delivery. Each host needs its own authentication, model availability and permission to access materials and code. Do not disable permission controls or grant unrelated directories. No cloud synchronization is installed or enabled.
-
-Codex and Cursor share the managed entry. Cursor also documents compatibility discovery from Claude/Codex directories. Aimship registers only selected hosts; it cannot guarantee that an unselected compatible host will not display an entry. If two same-name entries appear, inspect their paths and installation version rather than deleting unrelated files. Shared entry presence is distinct from registration, host discovery, login and permission. See the official [Cursor directories](https://cursor.com/docs/skills) and [Codex skill locations](https://learn.chatgpt.com/docs/build-skills).
-
-After an update, a running conversation may retain old rules. Save current facts, reload the bound core and current stage at a stable point, and use the existing compatibility/adoption process; start a new conversation if context cannot reliably refresh. Version mismatch stops new workflow writes. Never infer that installation instantly changed an active conversation.
-
-## Add a host, inspect and update
-
-Reuse the installed core without fetching another package:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
-node "$HOME/.aimship/bin/aimship.mjs" --version
-node "$HOME/.aimship/bin/aimship.mjs" status
-```
-
-Repeating the same install is safe for unchanged managed files. Adding a host preserves existing registrations. `status` reads Aimship's known installation files and managed entries; it does not scan projects or query host accounts. It separates registered hosts, missing/modified files, shared entries, pending installation and active version from unverified host capabilities. It is diagnostic, not a semantic delivery validator.
-
-To update from a new local release, run that release's `install` command with the same installation home. No `--host` is necessary for an existing installation: registered hosts are retained, and a core whose last host was disconnected remains a core-only installation. After publication, the explicit preview-channel update is:
-
-```sh
-npx aimship@preview install
-```
-
-There is one installation/update operation: `install`. `update` in the low-level CLI modifies delivery state and is **not** a software updater. The installer reports old and target versions and the result, updates the shared core and selected entries, and preserves configuration, custom content and every delivery. Completed deliveries are not traversed or rewritten. No automatic update runs in the background.
-
-## Disconnect or uninstall
-
-Disconnect one host, leaving the core and other registrations usable:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
-```
-
-If another registered host needs a shared entry, that file is retained and reported. Disconnecting the last host retains the core so version/status and later host connection remain available. A compatible host may still discover an entry used by another host; this command does not change that host's settings.
-
-Remove all managed programs and entries:
-
-```sh
-node "$HOME/.aimship/bin/aimship.mjs" uninstall
-```
-
-Full uninstall retains all delivery materials, user code, custom files and necessary configuration. Modified/unowned files are preserved and listed. No option purges delivery history. The launcher is removed on complete removal; inspect the returned result. Restart existing host sessions to discard cached rules.
-
-## Troubleshooting and recovery
-
-- **Foreign or modified entry/release:** read the reported path, keep its contents and resolve ownership or merge customizations explicitly. Do not force-overwrite it to obtain a successful exit status.
-- **Partial installation:** `status` can identify pending work. Rerun the exact pending package against the same home after correcting the reported cause. Binding/new workflow writes remain suspended until recovery completes. Do not choose a different version mid-recovery.
-- **Launcher unavailable:** run `node bin/aimship.mjs status --home <installation-home>` from the exact source/package installer. A missing launcher or damaged diagnostic module cannot diagnose itself. `status` reports facts without repairing them; only after inspecting the cause should you rerun the exact installer or reconcile retained files.
-- **Unexpected version:** use the stable launcher for the installed active version. A CLI inside an older release can report a different tool version; reload the current binding before continuing. A source checkout is not automatically an installed release.
-- **Package not found/authentication error:** confirm the exact package/version and public registry. Installation of a public release does not itself prove publish rights. Do not paste credentials into a bug report.
-- **Skill absent or duplicated:** inspect the actual host selector and returned entry paths after reloading. A file check alone cannot diagnose host discovery; retain this as unverified until observed.
-- **Directory denied:** authorize only the needed delivery/code roots in that host. Shared material storage does not share permissions. Report the exact denied operation rather than relocating user materials or changing security settings.
-- **Different host/session:** explicitly resume the same absolute delivery directory and inspect state/current inputs. Do not copy materials, reset the goal or run two writers. See [the user guide](guide.md).
-
-The initial data root can be selected with `--data-root` on installation. Existing configuration is retained on later installs; no language setting or second installation mode is introduced. Low-level state/version/recovery contracts are in [the CLI protocol](cli.md).
+<a id="troubleshooting-and-recovery"></a>
+Troubleshooting and recovery: [English](guide.md#troubleshoot) · [中文](guide.zh-CN.md#troubleshoot).

package/lib/cli.mjs

@@ -1,19 +1,24 @@
+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, assertInstallationComplete, assertRules, checkReferences, initState, readState, recoverState, updateState, validateState } from './state.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). Does not prove semantics, anchor contents, remote access, or validation results.',
+    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.',
@@ -29,11 +34,11 @@ const HELP = {
     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: 'results.md#unique-historical-section (required when done)' },
+    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. Do not supply these in init/update.',
-      requiredInit: 'goal: {summary, endpoint}; goalRef: current requirements or Scope reference. Save the original request in that referenced document before init.',
+      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.',
@@ -45,10 +50,12 @@ const HELP = {
     },
     minimalInit: {
       goal: { summary: 'Repair the search empty-state message', endpoint: 'Implement, review, and verify the agreed repair' },
-      goalRef: 'requirements.md',
-      stageRuns: [{ id: 'diagnose-1', stage: 'diagnose', scope: 'Search empty-state repair', progress: 'planned', inputRefs: ['requirements.md'], outputRefs: [] }],
-      currentRun: 'diagnose-1',
-      next: { action: 'Reproduce and diagnose the reported message', inputRefs: ['requirements.md'] }
+      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.'
   }
@@ -59,8 +66,8 @@ function parse(argv) {
     const item = argv[i];
     if (!item.startsWith('--')) { positional.push(item); continue; }
     const name = item.slice(2);
-    if (!['help', 'version', 'all', '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'].includes(name) ? true : argv[++i];
+    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; }
@@ -111,7 +118,7 @@ async function binding(runtime) {
 }
 function allowed(command, options) {
   const common = ['help', 'version'];
-  const perCommand = { status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
+  const perCommand = { render: ['revision','rules-version','preserve-edits','home'], migrate:['revision','rules-version','input','home'], scan:['home'], status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', '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) {
@@ -135,25 +142,30 @@ export async function run(argv, context) {
   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: path.join(directory, 'state.json') } };
-  if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: 'Unknown schema: no structure checking, mutation, or automatic work is permitted.' } };
+  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);
-    return { command, data: { structure: 'valid', references, semantics: 'not-checked' } };
+    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: !mismatch && missing.length === 0 && !blocked, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read state.json and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, 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;
+}

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.'};
+}