aimship 0.0.0-stage → 0.1.0-preview.4

package/lib/state.mjs

@@ -0,0 +1,210 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, exists, fail, inside, json, noSymlinks, readJSON, withLock } from './io.mjs';
+
+export const SCHEMA_VERSION = 1;
+export const STAGES = ['frame', 'requirements', 'prototype', 'scope', 'diagnose', 'tech-design', 'contract', 'plan', 'test-design', 'implement', 'review', 'verify', 'handoff'];
+const PROGRESS = ['planned', 'active', 'blocked', 'done'];
+const RESULTS = ['passed', 'failed', 'not-run', 'unknown', 'mixed'];
+const OUTCOME_REFS = ['goalConclusionRef', 'acceptanceRef', 'mergeRef', 'deploymentRef', 'handoffRef'];
+const object = x => x !== null && typeof x === 'object' && !Array.isArray(x);
+const string = x => typeof x === 'string' && x.trim().length > 0;
+function requireThat(condition, message) { if (!condition) fail('INVALID_STATE', message, 'Correct the input without overwriting the current state; read help for the state protocol.'); }
+function ref(value, field) {
+  requireThat(string(value), `${field} must be a nonempty reference string.`);
+  requireThat(!value.includes('\0'), `${field} contains a null byte.`);
+  if (/^https?:\/\//.test(value)) { try { new URL(value); } catch { requireThat(false, `${field} is not a URL.`); } return; }
+  requireThat(!value.includes('\\') && (!value.startsWith('repo:') || /^repo:[^/#]+\/.+/.test(value)), `${field} must use slash-separated relative paths and a valid repository ID.`);
+  const local = value.replace(/^repo:[^/]+\//, '').split('#')[0];
+  requireThat(string(local) && !path.isAbsolute(local) && !/^[a-zA-Z]:/.test(local) && !local.split(/[\\/]/).includes('..'), `${field} must be delivery-relative, repo:<id>/<path>, or an HTTP(S) URL.`);
+}
+function refs(value, field) { requireThat(Array.isArray(value), `${field} must be an array.`); value.forEach(x => ref(x, field)); }
+function unique(items, label) { requireThat(items.every(object), `${label} entries must be objects.`); const ids = items.map(x => x.id); requireThat(ids.every(string) && new Set(ids).size === ids.length, `${label} IDs must be nonempty and unique.`); }
+
+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.');
+  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.');
+  ref(state.goalRef, 'goalRef');
+  if (state.goal.decisionRef !== undefined) ref(state.goal.decisionRef, 'goal.decisionRef');
+  requireThat(Number.isSafeInteger(state.cycle) && state.cycle >= 1, 'cycle must be a positive integer.');
+  refs(state.closureRefs, 'closureRefs');
+  requireThat(Array.isArray(state.stageRuns), 'stageRuns must be an array.'); unique(state.stageRuns, 'Stage instance');
+  for (const run of state.stageRuns) {
+    requireThat(STAGES.includes(run.stage), `Unknown stage: ${run.stage}`);
+    requireThat(string(run.scope) && PROGRESS.includes(run.progress), `Invalid scope or progress in ${run.id}.`);
+    refs(run.inputRefs, `${run.id}.inputRefs`); refs(run.outputRefs, `${run.id}.outputRefs`);
+    for (const key of ['resultRef', 'priorResultRef']) if (run[key] !== undefined) ref(run[key], `${run.id}.${key}`);
+    if (run.historyResultRefs !== undefined) refs(run.historyResultRefs, `${run.id}.historyResultRefs`);
+    if (run.result !== undefined) requireThat(RESULTS.includes(run.result), `Invalid result in ${run.id}.`);
+    if (run.applicability !== undefined) requireThat(['current', 'needs-review', 'unknown'].includes(run.applicability), `Invalid applicability in ${run.id}.`);
+    if (run.progress === 'done') requireThat(string(run.resultRef), `Completed instance ${run.id} requires resultRef; file existence does not establish semantic completion.`);
+  }
+  requireThat(state.currentRun === null || state.stageRuns.some(x => x.id === state.currentRun), 'currentRun must refer to a stage instance or be null.');
+  requireThat(Array.isArray(state.openChanges), 'openChanges must be an array.'); unique(state.openChanges, 'Change');
+  for (const change of state.openChanges) { ref(change.ref, 'change.ref'); requireThat(['open', 'closed'].includes(change.status), 'Invalid change status.'); }
+  requireThat(Array.isArray(state.repositories), 'repositories must be an array.'); unique(state.repositories, 'Repository');
+  for (const repo of state.repositories) requireThat(path.isAbsolute(repo.path ?? '') && string(repo.role), 'Repository path must be absolute and role nonempty.');
+  requireThat(object(state.outcome) && ['in-progress', 'met', 'not-met', 'unknown'].includes(state.outcome.goal), 'Invalid outcome.goal.');
+  requireThat(['not-recorded', 'accepted', 'declined', 'unknown'].includes(state.outcome.acceptance), 'Invalid outcome.acceptance.');
+  for (const key of OUTCOME_REFS) if (state.outcome[key] !== undefined) ref(state.outcome[key], `outcome.${key}`);
+  if (state.outcome.goal === 'met') requireThat(string(state.outcome.goalConclusionRef), 'A met goal requires an explicit goalConclusionRef.');
+  if (['accepted', 'declined'].includes(state.outcome.acceptance)) requireThat(string(state.outcome.acceptanceRef), 'Acceptance requires a separate decision reference.');
+  requireThat(object(state.next) && string(state.next.action), 'next.action is required.');
+  if (state.next.inputRefs !== undefined) refs(state.next.inputRefs, 'next.inputRefs');
+  if (state.goalHistory !== undefined) requireThat(Array.isArray(state.goalHistory), 'goalHistory must be an array.');
+  if (state.rulesHistory !== undefined) requireThat(Array.isArray(state.rulesHistory), 'rulesHistory must be an array.');
+  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 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;
+  if (!readOnly) validateState(state);
+  return { ...paths, state, readOnly };
+}
+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 });
+}
+export function assertRules(state, rulesVersion, runtime) {
+  assertInstallationComplete(runtime);
+  if (!rulesVersion || rulesVersion !== state.rulesVersion || rulesVersion !== runtime.version || runtime.activeVersion !== runtime.version) fail('VERSION_MISMATCH', 'The session, state, tool, and active installation must use the same rules version.', 'Save only unfinished facts with checkpoint if available; bind the active version, reload its core and current stage, then adopt at a stable point.', { session: rulesVersion, state: state.rulesVersion, tool: runtime.version, active: runtime.activeVersion, launcher: runtime.launcher });
+}
+export function assertInstallationComplete(runtime) {
+  if (runtime.installPending) fail('INSTALL_PENDING', 'The installation is incomplete; new workflow writes and bindings are suspended.', 'Read state without progressing, then rerun install from the same exact pending package. After recovery, bind and reload its fixed core before continuing.', { pendingVersion: runtime.installPending.version, activeVersion: runtime.activeVersion, launcher: runtime.launcher });
+}
+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 });
+  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'];
+    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;
+  });
+}
+function merge(base, patch) {
+  const result = structuredClone(base);
+  for (const [key, value] of Object.entries(patch)) {
+    requireThat(!['__proto__', 'constructor', 'prototype'].includes(key), `Unsafe property: ${key}`);
+    result[key] = object(value) && object(result[key]) ? merge(result[key], value) : structuredClone(value);
+  }
+  return result;
+}
+function retainHistory(previous, next) {
+  for (const old of previous.stageRuns) {
+    const current = next.stageRuns.find(x => x.id === old.id);
+    if (!current) requireThat(old.progress === 'planned' && !old.resultRef, `Cannot remove started instance ${old.id}; preserve historical execution.`);
+    else {
+      requireThat(current.stage === old.stage, `Cannot change stage type for ${old.id}.`);
+      const oldRefs = [old.resultRef, old.priorResultRef, ...(old.historyResultRefs ?? [])].filter(Boolean);
+      const currentRefs = [current.resultRef, current.priorResultRef, ...(current.historyResultRefs ?? [])];
+      requireThat(oldRefs.every(x => currentRefs.includes(x)), `Preserve historical result references for ${old.id}.`);
+    }
+  }
+  requireThat(previous.closureRefs.every(x => next.closureRefs.includes(x)), 'Preserve historical closure references.');
+  requireThat(previous.openChanges.every(old => next.openChanges.some(x => x.id === old.id && x.ref === old.ref)), 'Preserve change records, using closed status when resolved.');
+  requireThat(next.cycle >= previous.cycle && next.cycle <= previous.cycle + 1, 'cycle may stay unchanged or increase by one.');
+  if (next.cycle > previous.cycle) requireThat(next.closureRefs.length > previous.closureRefs.length && next.outcome.acceptance === 'not-recorded', 'Reopening requires a previous closure reference and reset current acceptance.');
+}
+export async function updateState(directory, patch, revision, rulesVersion, runtime, mode = 'update') {
+  assertInstallationComplete(runtime);
+  const p = statePaths(directory);
+  return withLock(p.lock, async () => {
+    const { state: previous } = await readState(directory); validateState(previous); checkRevision(previous, revision);
+    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.');
+      requireThat(Object.keys(patch).every(x => ['next', 'checkpoint'].includes(x)) && object(patch.checkpoint) && string(patch.checkpoint.summary), 'Checkpoint may save only next and checkpoint.summary/ref facts; it cannot complete stages or outcomes.');
+      if (runtime.activeVersion === runtime.version) fail('CHECKPOINT_NOT_NEEDED', 'Rules match; use a normal update for unfinished facts.', 'Save current work with update.');
+      if (previous.checkpoint?.activeVersion === runtime.activeVersion) fail('CHECKPOINT_ALREADY_SAVED', 'A checkpoint for this active version already exists.', 'Reload active rules and adopt at the recorded stable point.');
+      if (patch.checkpoint.ref !== undefined) ref(patch.checkpoint.ref, 'checkpoint.ref');
+    } else if (mode === 'adopt') {
+      requireThat(runtime.version === runtime.activeVersion && rulesVersion === runtime.version, 'Adoption requires the active rules and tool.');
+      requireThat(previous.rulesVersion !== rulesVersion, 'Rules are already adopted; no version change is needed.');
+      requireThat(Object.keys(patch).length === 1 && string(patch.compatibilityRef), 'Adoption input must contain only compatibilityRef documenting the stable point and compatibility assessment.');
+      ref(patch.compatibilityRef, 'compatibilityRef');
+    } else {
+      assertRules(previous, rulesVersion, runtime);
+    }
+    const immutable = ['schemaVersion', 'revision', 'deliveryId', 'rulesVersion', 'createdAt', 'updatedAt', 'goalHistory', 'rulesHistory'];
+    requireThat(!immutable.some(x => Object.hasOwn(patch, x)), 'Identity, revision, and historical metadata are tool-managed.');
+    let next;
+    if (mode === 'adopt') {
+      next = { ...previous, rulesVersion, rulesHistory: [...(previous.rulesHistory ?? []), { from: previous.rulesVersion, to: rulesVersion, ref: patch.compatibilityRef, at: new Date().toISOString() }] };
+    } else next = merge(previous, patch);
+    if (mode === 'checkpoint') next.checkpoint.activeVersion = runtime.activeVersion;
+    validateState(next);
+    if (JSON.stringify(previous.goal) !== JSON.stringify(next.goal) || previous.goalRef !== next.goalRef) {
+      requireThat(string(next.goal.decisionRef) && next.goal.decisionRef !== previous.goal.decisionRef, 'Goal revision requires a new explicit decisionRef; viewing results does not revise a goal.');
+      next.goalHistory = [...(previous.goalHistory ?? []), { goal: previous.goal, goalRef: previous.goalRef, outcome: previous.outcome, revision: previous.revision }];
+    }
+    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;
+  });
+}
+export async function recoverState(directory, revision, rulesVersion, runtime) {
+  const p = statePaths(directory);
+  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;
+    if (await exists(p.statePath)) {
+      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.');
+        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);
+    }
+    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;
+  });
+}
+export async function checkReferences(directory, state, all = false) {
+  const current = state.stageRuns.find(x => x.id === state.currentRun);
+  const values = new Set([state.goalRef, ...(state.next.inputRefs ?? []), ...(current?.inputRefs ?? [])]);
+  if (all) {
+    for (const run of state.stageRuns) { for (const value of [...run.inputRefs, ...run.outputRefs, run.resultRef, run.priorResultRef, ...(run.historyResultRefs ?? [])].filter(Boolean)) values.add(value); }
+    state.openChanges.forEach(x => values.add(x.ref)); state.closureRefs.forEach(x => values.add(x));
+    const add = value => { if (value !== undefined) { ref(value, 'registered reference'); values.add(value); } };
+    const addOutcome = outcome => { for (const key of OUTCOME_REFS) add(outcome?.[key]); };
+    add(state.goal.decisionRef); addOutcome(state.outcome);
+    for (const history of state.goalHistory ?? []) {
+      add(history?.goalRef); add(history?.goal?.decisionRef); addOutcome(history?.outcome);
+    }
+    for (const history of state.rulesHistory ?? []) add(history?.ref);
+    add(state.checkpoint?.ref);
+  }
+  const results = [];
+  for (const value of values) {
+    if (/^https?:\/\//.test(value)) { results.push({ ref: value, status: 'not-checked', reason: 'Remote access and adopted version require the host.' }); continue; }
+    let base = path.resolve(directory); let relative = value.split('#')[0];
+    if (value.startsWith('repo:')) {
+      const match = /^repo:([^/]+)\/(.*)$/.exec(relative); const repo = state.repositories.find(x => x.id === match?.[1]);
+      if (!repo) { results.push({ ref: value, status: 'missing', reason: 'Repository ID is not registered.' }); continue; }
+      base = repo.path; relative = match[2];
+    }
+    const target = path.resolve(base, relative);
+    if (!inside(base, target)) fail('INVALID_REFERENCE', `Reference escapes its root: ${value}`, 'Use a path within its registered root.');
+    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 }); }
+    } catch (e) { results.push({ ref: value, status: e.code === 'ENOENT' ? 'missing' : 'inaccessible', path: target, reason: e.code }); }
+  }
+  return results;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "aimship",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-preview.4",
+  "description": "Explicit, goal-driven delivery workflow for coding agents",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "aimship": "bin/aimship.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "README.zh-CN.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1",
+    "check:package": "node scripts/check-package.mjs",
+    "prepack": "node scripts/check-package.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "tag": "preview",
+    "access": "public"
+  },
+  "author": {
+    "name": "clsx"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clsx/aimship.git"
+  },
+  "bugs": {
+    "url": "https://github.com/clsx/aimship/issues"
+  },
+  "homepage": "https://github.com/clsx/aimship#readme"
+}

package/skills/aimship/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: aimship
+description: Guide an explicitly requested Aimship software delivery, or resume an existing Aimship delivery, from its recorded goal through the agreed stages and handoff.
+disable-model-invocation: true
+---
+
+# Aimship
+
+Activate only when the user explicitly asks to start or resume Aimship. Ordinary conversation does not create a delivery. Once activated, continue the same delivery across turns without asking the user to invoke every stage.
+
+1. Run `"{{AIMSHIP_NODE}}" "{{AIMSHIP_LAUNCHER}}" bind` to resolve the installed version. Read the returned fixed-version core and CLI help. Use that fixed version's tools, carrying its rules version and the current state revision. If this is a source checkout rather than an installed entry, use `node bin/aimship.mjs bind` from the package root.
+2. Read the core at the path returned by `bind`. Resolve all supporting links below against that same fixed release, even if a cached entry mentions an older path. [The shared core](references/core.md) is the source-checkout reference. For an existing delivery, read its state and the current goal/Scope plus only the next step's required references. Do not create a replacement delivery, reset its plan, or infer a new goal from “continue”.
+3. For new work, use the binding’s configured `dataRoot` unless the user supplied a delivery location; do not infer it from the code root. Preserve the original request, identify the authorized endpoint and code locations, and propose the necessary ordered stages. After associating code scope, follow the core’s recorded-overlap check for independent deliveries. Existing explicit authorization and agreed arrangements remain valid. No answer is not acceptance. Create records only for an actual request.
+4. Read the selected [stage reference](references/core.md#stage-references) when reaching it. Explain design choices and unresolved decisions, then continue authorized work. Only material missing facts or choices block their dependent work.
+5. At stable results and before a manual session switch, save the state and give a short continuation prompt. Keep a compact binding: delivery ID, absolute delivery directory, state path, current run, rules version, and fixed core/tool paths. After compaction, reload these references if absent; do not assume the full skill survived.
+
+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.
+
+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/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Aimship"
+  short_description: "Carry a software goal through a clear delivery"
+  default_prompt: "Use $aimship to start or resume my software delivery."
+policy:
+  allow_implicit_invocation: false

package/skills/aimship/references/core.md

@@ -0,0 +1,84 @@
+# Shared delivery core
+
+## Start from the commission
+
+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.
+
+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.
+
+Read repository instructions and existing tools for the relevant work. Record relevant pre-existing modifications and distinguish them from the delivery's changes. Do not clean a working tree, initialize Git, modify an unrelated repository, or expand write access merely to simplify the workflow.
+
+## Independent deliveries and recorded overlap
+
+Several independent deliveries may progress at the same time, each with its own material directory, goal, stages and state. One writing session **per delivery** is not a product-wide single-task limit. This check is workspace preparation based on records, not a cross-session lock or scheduler.
+
+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.
+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.
+
+| Recorded situation | Action |
+| --- | --- |
+| No known overlap | Continue without a new confirmation. Say “no overlap found among the recorded deliveries checked,” never guarantee there is no conflict. |
+| Same repository, current work is requirements/design or explicitly read-only | Briefly identify related delivery and scope; continue that non-writing work and record any known business/interface dependency. Recheck before implementation. |
+| Multiple deliveries preparing to modify the same actual checkout | Do not silently write concurrently. Identify the deliveries and recorded stages; use the user's existing choice of sequential implementation or a separate worktree/checkout. If unresolved, propose those choices and hold only the affected code writes. A recorded blocked writer does not prove its workspace has been released. |
+| Same repository, distinct existing worktrees/checkouts | Reuse the existing isolation, do not create it again. File isolation does not guarantee conflict-free merging or compatible business changes. Record integration dependencies where known. |
+| Different repositories with known shared API/database/test data/service | Record dependency and necessary sequencing or use arrangement in the existing plan. Do not operate real shared environments without authorization or build automatic dependency analysis. |
+
+Records can be stale and cannot detect all other work. Do not switch another session's branch, stash, overwrite or clean unknown changes. The state tool's short write lock/revision check protects an individual state update; it does not reserve a checkout or enforce this workflow across sessions.
+
+## 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.
+
+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.
+
+Explain each design's key decisions, why they fit the requirements, tradeoffs, artifact location and remaining questions. Ordinary internal implementation choices stay with the agent. Ask for material changes to goals, scope, external behavior, compatibility, significant cost, data handling or an explicit technical commitment. Honor an agreed human review point, without adding approvals to every document.
+
+## Stage references
+
+Read the reference for the current responsibility, not all thirteen on every turn.
+
+| Responsibility | Read when | Reference |
+| --- | --- | --- |
+| frame | Clarifying a problem or exploring a goal | [frame](stages/frame.md) |
+| requirements | Defining or refining requirements | [requirements](stages/requirements.md) |
+| prototype | Designing interaction and its states | [prototype](stages/prototype.md) |
+| scope | Adopting inputs and aligning this commission | [scope](stages/scope.md) |
+| diagnose | Investigating cause or feasibility | [diagnose](stages/diagnose.md) |
+| tech-design | Choosing an engineering approach | [tech-design](stages/tech-design.md) |
+| contract | Defining interfaces and exchanged data | [contract](stages/contract.md) |
+| plan | Splitting implementation into dependent batches | [plan](stages/plan.md) |
+| test-design | Mapping acceptance and risks to checks | [test-design](stages/test-design.md) |
+| implement | Carrying out an authorized implementation batch | [implement](stages/implement.md) |
+| review | Reviewing a batch, all batches, or affected rework | [review](stages/review.md) |
+| verify | Executing the agreed checks and recording evidence | [verify](stages/verify.md) |
+| handoff | Delivering against the current goal or handing over incomplete work | [handoff](stages/handoff.md) |
+
+Each run records its scope, required inputs, results and progress. A result may be a section in a shared document. Proceed when this run's requirements are met, the next inputs exist, authorization covers it and no relevant unresolved issue blocks it. An issue blocks only dependent work; changing the order to continue other work is still an explicit plan change.
+
+## Implementation and evidence
+
+For multiple batches: implement batch → review batch, repeat; after every batch is complete and reviewed, review the whole change, then independently verify. For one batch, one review record may explicitly cover both batch and whole-change scopes. Do not create a complete testing gate after every batch. Planned tests can be written with implementation; writing them does not mean they passed.
+
+Record review and verification against actual objects: repository ID, commit if any, relevant uncommitted/untracked paths and content digests or necessary patch, scope and baseline. Distinguish pre-existing changes. A branch name alone is insufficient. For documents record file/section and the content basis; preserve necessary old excerpts when a digest would not explain the reviewed meaning.
+
+Each conclusion identifies who/what produced it, date, object/version, scope, basis, result and evidence. Distinguish user review, agent review, actual execution and user-reported results. Actual verification also records commands or operations, environment/data, case version and unexecuted checks. If the object changes during testing, determine which results remain applicable and retest affected checks.
+
+Execution progress (`planned`, `active`, `blocked`, `done`) is separate from pass/fail/not-run/unknown, current applicability, goal achievement and user acceptance. A finished failed verification is still failed. Review is not runtime testing. Neither the presence of a report nor successful tool exit proves the goal.
+
+## State and stopping
+
+Use the installed tool's documented state protocol. Read the current revision before a write and provide the expected revision; never bypass a conflict by blindly increasing it. State stores summaries and references, not copies of requirements or test reports. Persist the unfinished intent before changing multiple documents, then verify the artifacts before recording completion. No cross-file transaction is promised.
+
+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.
+
+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.

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

@@ -0,0 +1,19 @@
+# Optional document patterns
+
+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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.

package/skills/aimship/references/hosts.md

@@ -0,0 +1,15 @@
+# Host access
+
+Reuse the current session's access when normal file operations succeed. Do not create probe files, rescan all permissions every stage or treat a second project as permission for the current conversation. Keep the materials directory separate from repository roots and set the correct working directory for engineering commands.
+
+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.
+- 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).

package/skills/aimship/references/recovery.md

@@ -0,0 +1,13 @@
+# Resume, recover and update
+
+Start by locating the same delivery. Read state, current goal/Scope and next-step references. Verify actual artifacts or related changes only when needed to act or reuse a conclusion. Restoring context is not a new test result. If the directory is ambiguous, ask for the missing location, not already recorded goals and decisions.
+
+A revision conflict means another writer or manual change intervened. Read and reconcile; do not force overwrite. One writing session per delivery remains the supported workflow. On malformed state, preserve the damaged file, inspect the last recovery copy and actual subsequent artifacts, then explicitly recover only the trustworthy facts. If no reliable copy exists, reconstruct from readable requirements/change/results, marking uncertain authorization and results unknown. Never rerun a side effect just because state is incomplete.
+
+A path move requires the provided new location and identity evidence, not a disk-wide name search. Keep IDs stable. Repair references after checking the relevant repository/delivery; do not move or copy code. Preserve manual document edits and assess their intent and downstream impact before updating state.
+
+A tool/version mismatch stops new stage advancement. Save only in-progress facts through the documented limited checkpoint if safe; it cannot finish a stage or declare a goal met. At a stable boundary read the current complete installation's core, current stage and state, handle any compatibility needs, then explicitly adopt the current rules version. Keep the same goal, decisions and history. If the old context cannot reliably refresh, give the manual continuation prompt; do not open a new conversation automatically.
+
+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.

package/skills/aimship/references/sources-and-changes.md

@@ -0,0 +1,28 @@
+# Sources, artifacts and change flow
+
+## Adopt without rewriting the source
+
+Preserve the original request once. For external PRDs, prototypes and images keep the original and necessary adopted version read-only. Keep referenced HTML/Markdown assets when needed to understand that version. A mutable URL alone cannot establish what was adopted. Record origin, location, version/digest, adopted sections and reading gaps. Do not claim visual understanding from text extraction or file storage.
+
+Use existing requirement IDs. If none exist, assign local IDs mapped to source sections, pages, prototype screens or short excerpts. Scope records the current goal, inclusion/exclusion, source mappings, acceptance, constraints, conflicts and adopted decisions. Do not transcribe an entire adequate PRD or create a second one merely to fit a template. Self-owned requirements may also carry Scope.
+
+A prototype and PRD can disagree; neither file type nor modification date automatically wins. Record the conflict and decision authority. Pause dependent work when a material answer is missing, while continuing independent authorized work. Do not contact the external author automatically. If a new version arrives, adopt it separately, assess relevant differences and retain the old basis. Indicate any external document still awaiting its author's correction.
+
+## Artifact boundaries
+
+Use relative references within the delivery. Identify engineering files by repository ID and repository-relative path; keep local repository locations in the user's delivery state, not public product content. Record role, authorization and relevant working version. Do not store credential-bearing remote URLs.
+
+For HTTP interfaces, reuse the engineering repository's authoritative OpenAPI; only create a delivery-local contract when none exists. Other protocols use the appropriate engineering format. Explain decisions in technical design and link details rather than duplicating the contract. No interface change means no mandatory contract.
+
+When the design changes a table, column, index or data, produce a separate SQL file in the delivery directory, with technical design describing dialect/version, existing schema basis, preconditions, sequence and relevant data impact. SQL is an ordinary formal artifact, with the same review/change rules as designs and tests. A code block or reference to an engineering migration does not replace it. Default scope does not edit migration files or execute SQL. Explicitly authorized integration/execution is handled within its environment and recorded file version; prepared, reviewed, tested and production-applied remain distinct. Missing dialect/schema details prevent an implementation-ready claim.
+
+Markdown/HTML are principal carriers, not a format whitelist. Images, screenshots, wireframes and diagrams can be sources or outputs. Record separately text reading, visual inspection, interaction checks, generation and native-format editing. PDF/DOCX/online inputs depend on available tools and access. Missing tools require an honest gap and a feasible alternative; changing agreed output requires a decision. A still image does not establish interactions, error states, permissions or responsiveness. Never add a universal conversion service to the task.
+
+## One record for an important change
+
+1. Persist the reason, old/new intent, decision/source or open question, affected artifacts/runs and uncertainties in one change record.
+2. Update editable requirements/Scope, design, contracts, independent SQL, plan and test cases where affected. Preserve external sources and necessary old excerpts.
+3. Mark affected conclusions as needing review; historical records keep their original object and outcome. Leave unrelated results intact.
+4. Review affected work and execute affected verification as required by the goal, then close the same change with its result and remaining issues.
+
+Formatting/typo corrections do not require semantic re-review. Implementation bugs are fixed against the requirements; do not weaken the requirements to match the bug. Tools detect structural problems, not every semantic dependency. State uncertainty in the impact analysis rather than claiming complete automatic coverage.

package/skills/aimship/references/stages/contract.md

@@ -0,0 +1,19 @@
+# Define interfaces
+
+## Basis
+
+Read the current requirements, technical design and existing engineering contracts.
+
+## Work and result
+
+Update/reuse the authoritative HTTP OpenAPI when applicable; create a delivery-local OpenAPI only if the engineering authority is absent. Specify operations, schemas, errors, compatibility and consumer expectations. Use appropriate formats for messages/non-HTTP interfaces. Link design and test requirements.
+
+## Continue when
+
+The cooperating parties have an unambiguous applicable contract consistent with the current requirements/design. No relevant interface change means this responsibility need not be selected.
+
+## Decisions and blockers
+
+A breaking interface/compatibility decision needs its proper authority. Missing consumers or schemas remain stated gaps, not fabricated agreements.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.

package/skills/aimship/references/stages/diagnose.md

@@ -0,0 +1,19 @@
+# Investigate cause or feasibility
+
+## Basis
+
+Read reported symptoms, expected behavior, relevant code/material and reproducible evidence.
+
+## Work and result
+
+Investigate within authorized objects. Record observations, reproduction or supporting evidence, probable/established causes and remaining uncertainty. Keep incidental behavior changes out of a refactor.
+
+## Continue when
+
+The investigation goal is met, or the inability to determine a cause and a concrete next step are accurately stated. A hypothesis is not a confirmed root cause.
+
+## Decisions and blockers
+
+If the apparent small fix expands into behavior or scope changes, explain the impact before dependent implementation.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.

package/skills/aimship/references/stages/frame.md

@@ -0,0 +1,19 @@
+# Clarify the problem
+
+## Basis
+
+Read the original request, background, constraints and available evidence.
+
+## Work and result
+
+Establish the problem, intended outcome, non-goals and assumptions worth checking. Separate known facts from hypotheses; a short section in requirements is enough.
+
+## Continue when
+
+The commissioned exploration has a clear objective and its uncertainty is visible. Do not force this stage when the goal is already clear.
+
+## Decisions and blockers
+
+A missing business objective or incompatible expected outcomes needs a user decision; independent evidence gathering may continue.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.

package/skills/aimship/references/stages/handoff.md

@@ -0,0 +1,19 @@
+# Deliver against the goal
+
+## Basis
+
+Read the current goal/Scope, explicit goal revisions, deliverables, applicable review/verification and unresolved work.
+
+## Work and result
+
+Provide deliverable links, use/check instructions, actual validation scope and limits, goal changes and unfinished items. Identify each actual code checkout/worktree, branch and commit when available, relevant uncommitted changes, and whether integration/merge is still pending (including target/dependencies if known). A completed branch is not a merged change. Independently record goal achievement, user acceptance, merge and deployment. Save next-step context when incomplete.
+
+## Continue when
+
+The report honestly matches the current commissioned endpoint. Complete the delivery only when its actual completion criteria are satisfied. A user-authorized partial endpoint preserves the old goal and remaining work.
+
+## Decisions and blockers
+
+Showing results does not revise the endpoint. Required blocked verification means incomplete acceptance, even when code is ready. Small later corrections reopen with preserved closure; independent goals create related deliveries.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.

package/skills/aimship/references/stages/implement.md

@@ -0,0 +1,19 @@
+# Implement one batch
+
+## Basis
+
+Read this run’s scope, current requirements/design/contracts, relevant repository instructions and pre-existing changes.
+
+## Work and result
+
+Before entering implementation, or when a code working directory changes, apply the [recorded-overlap check](../core.md#independent-deliveries-and-recorded-overlap). Reuse an existing user-selected sequence or isolated checkout; unresolved same-checkout writing overlap holds the affected code writes, not independent design work. Complete this batch using the existing engineering stack. Write planned test code where appropriate. Preserve user work and external sources. Record deviations and route semantic changes through the current authority, including SQL when affected. Engineering commands use the repository working directory.
+
+## Continue when
+
+The planned batch is implemented and known deviations are resolved or explicitly routed. Move to this batch’s review; running a complete test suite is not a new batch gate.
+
+## Decisions and blockers
+
+Expanded external behavior, data handling or authorization needs return to the relevant decision. A rejected permission remains blocked and is not retried through another host.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.

package/skills/aimship/references/stages/plan.md

@@ -0,0 +1,19 @@
+# Plan implementation batches
+
+## Basis
+
+Read current Scope, applicable design/contracts and relevant repository boundaries.
+
+## Work and result
+
+Define executable batches, each goal and requirement coverage, dependencies, authorized file/repository scope and interfaces. Arrange batch implementation/review, overall review, then independent verification. Include known cross-delivery interface, database, test-data/service and integration dependencies in this same plan, with necessary sequencing or use arrangements. Keep test-code development in appropriate batches; do not add per-batch full testing gates.
+
+## Continue when
+
+Batches can be executed in order and together cover the delivery goal. Small work may keep a concise ordered arrangement in state rather than a separate plan.
+
+## Decisions and blockers
+
+A material change in scope/endpoint needs a decision; routine task splitting does not. Record the reason if changing the existing order.
+
+Use [the shared core](../core.md) for state, evidence and continuation rules. Record meaningful results in an artifact or referenced section; a file alone is not completion.