aimship 0.1.0-preview.11 → 0.1.0-preview.13

package/lib/documents.mjs

@@ -1,7 +1,6 @@
 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';
+import { hash, inside, fail } 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'));
@@ -27,51 +26,118 @@ export async function safeRead(directory, state, ref, encoding = 'utf8') {
   if (!inside(await fs.realpath(base), real)) fail('INVALID_REFERENCE', 'Reference resolves outside its root.', 'Repair the symbolic link or reference.');
   return fs.readFile(real, encoding);
 }
-export const anchors = text => [...text.matchAll(/<a\s+id=["']([^"']+)["']\s*><\/a>/g)].map(m => m[1]);
-const identityKinds = ['REQ','AC','B','TASK','TC','REV','RUN','CHG','Q','PAGE'];
-const identityKind = d => d.kind ?? d.id.split('-')[0];
-// Migration exempts preserved execution facts, never future work under an old ID.
-export async function preservedLegacyRuns(directory,state) {
-  if (!state.legacyRunIds?.length) return new Set();
-  const journal=await readJSON(path.join(directory,'.aimship/migration.json'));
-  if (journal.protocol!==1 || hash(json(journal.target))!==journal.targetHash || journal.target.deliveryId!==state.deliveryId) fail('MIGRATION_CONFLICT','Cannot verify legacy run provenance.','Inspect the migration journal and original state.');
-  const basis=run=>{const {applicability,...facts}=run;return facts;};
-  return new Set(state.stageRuns.filter(run=>state.legacyRunIds.includes(run.id) && journal.target.stageRuns.some(old=>old.id===run.id && old.progress==='done' && isDeepStrictEqual(basis(old),basis(run)))).map(run=>run.id));
+// Read ordinary Markdown, ignoring examples and comments. Offsets are retained
+// so the same parser defines document checks and approval boundaries.
+export function markdownText(text) {
+  let fence = null;
+  return text.replace(/<!--[^]*?-->/g, m => m.replace(/[^\n]/g, ' ')).split('\n').map(line => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+      return ' '.repeat(line.length);
+    }
+    return fence || /^(?: {4}|\t| *>)/.test(line) ? ' '.repeat(line.length) : line;
+  }).join('\n');
 }
-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.'); }
+const normalizeHeading = value => value.replace(/^\d+(?:\.\d+)*[.)、]?\s*/, '').trim().toLowerCase();
+export function headings(text) {
+  return [...markdownText(text).matchAll(/^ {0,3}(#{1,6})[ \t]+(.+?)\s*#*$/gm)].map(m => ({title:m[2], key:normalizeHeading(m[2]), level:m[1].length, start:m.index, end:m.index+m[0].length}));
+}
+export function sections(text, spec) {
+  const all=headings(text);
+  return spec.sections.map((id,i) => {
+    const names=Object.values(spec.headings).map(titles=>normalizeHeading(titles[i]));
+    const matches=all.filter(h=>h.level===2 && names.includes(h.key));
+    const h=matches.length===1?matches[0]:null;
+    const end=h ? (all.find(next=>next.start>h.start && next.level<=2)?.start ?? text.length) : null;
+    return {id, count:matches.length, start:h?.start, end, body:h?markdownText(text.slice(h.end,end)).trim():null};
+  });
+}
+const ID = '(?:REQ|AC|B|TASK|TC|REV|RUN|CHG|Q|PAGE)-[0-9]{3,}';
+export const numberedIds = text => [...new Set(markdownText(text).match(new RegExp('\\b'+ID+'\\b','g'))??[])];
+// A file-qualified Markdown citation names its own readable source. It does not
+// create a second local definition or a namespace/index.
+function qualifiedCitations(text) {
+  const references=[];
+  // A displayed link-syntax example is not a link. Keep ordinary `REQ-001`
+  // references visible to the number check.
+  const prose=markdownText(text).replace(/(`+)([^\n]*?)\1/g,(span,ticks,body)=>/\[[^\]]*\]\(/.test(body)?' '.repeat(span.length):span);
+  const local=prose.replace(/\[([^\]\n]*)\]\(([^()\s]+\.md)(?:#([^()\s]+))?\)/gi,(match,label,file,fragment)=>{
+    const locator=fragment??label.trim(),target=`${file}#${locator}`;
+    if (!new RegExp('^'+ID+'$').test(locator)) return match;
+    references.push({target,locator});
+    return label.replaceAll(locator,'');
   });
+  return {references,local};
+}
+const definitionSections={REQ:['requirements','adoption'],AC:['acceptance'],B:['batches'],TASK:['tasks'],TC:['cases']};
+const referenceHeading=title=>/\b(?:coverage|summary|references|conclusion|notes)\b|覆盖|总结|汇总|引用|结论|备注/i.test(title);
+export function definitions(text, file, spec) {
+  const lines=markdownText(text).split('\n'), result=[], context=[];
+  const areas=spec?sections(text,spec):[];
+  let offset=0;
+  for(let i=0;i<lines.length;i++) {
+    const line=lines[i], start=offset; offset+=line.length+1;
+    const heading=/^ {0,3}(#{1,6})[ \t]+(.+)$/.exec(line);
+    if(heading) {
+      while(context.length && context.at(-1).level>=heading[1].length)context.pop();
+      context.push({level:heading[1].length,title:heading[2]});
+    }
+    const structured=/^\s*(?:\||#{1,6}\s+|[-*+]\s+)/.test(line);
+    if(!structured && !new RegExp('^'+ID+'[:：]').test(line)) continue;
+    const candidate=line.trim().replace(/^\|\s*/, '').replace(/^(?:#{1,6}\s+|[-*+]\s+)/,'').replace(/^[*`]+/,'');
+    const match=new RegExp('^('+ID+')(?![A-Za-z0-9_-])(?:[*`]*)(?:\\s*[|:：—–-]\\s*|\\s+|$)(.*)$').exec(candidate);
+    if(!match) continue;
+    let body=match[2];
+    // A readable heading/list may put its explanation on following lines.
+    if(!/^\s*\|/.test(line)) {
+      for(let j=i+1;j<lines.length;j++) {
+        if(/^\s*(?:#{1,6}\s+|\||[-*+]\s+)/.test(lines[j]) || new RegExp('^'+ID+'[:：]').test(lines[j])) break;
+        body+='\n'+lines[j];
+      }
+    }
+    const primary=areas.some(area=>definitionSections[match[1].split('-')[0]]?.includes(area.id) && start>=area.start && start<area.end);
+    result.push({id:match[1],file,body,refs:numberedIds(body).filter(id=>id!==match[1]),primary,reference:context.some(h=>referenceHeading(h.title))});
+  }
+  // Definitions remain unique in their existing owning sections. Repeating an
+  // established number in a summary, coverage table or execution log cites it.
+  // Unstructured sources use their ordinary summary/coverage headings; two
+  // substantive definitions elsewhere are still a conflict, never first-wins.
+  return result.filter(d=>!result.some(other=>other.id===d.id && other!==d &&
+    ((!d.primary && other.primary) || (d.primary===other.primary && d.reference && !other.reference))))
+    .map(({primary,reference,...record})=>record);
+}
+export function meaningful(text) {
+  const body=markdownText(text).replace(new RegExp(ID,'g'),'').replace(/[\s|:*`_#.—–-]/g,'');
+  return body.length>=3 && !/^(?:TBD|TODO|N\/A|待补充|待填写|未填写|\.{3})$/i.test(body)
+    && !/Replace guidance with actual content|<deliveryId from init>|<revision>/.test(text);
+}
+// A fragment is a search locator, not a renderer-dependent hyperlink anchor.
+export function hasLocator(text, locator, spec) {
+  if(spec && spec.sections.includes(locator)) return sections(text,spec).find(s=>s.id===locator)?.count===1;
+  if(new RegExp('^'+ID+'$').test(locator)) return definitions(text,'',spec).filter(d=>d.id===locator).length===1;
+  return headings(text).filter(h=>h.title===locator || h.key===normalizeHeading(locator)).length===1;
 }
 export function unknownConditions(policy) {
   return ['interaction','interface','databases', ...(policy.interaction === false ? [] : ['prototypeCovered'])].filter(key=>policy[key] === null);
 }
 export async function inspectDocuments(directory, state) {
-  if (![2,3].includes(state.schemaVersion) || !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 map = await artifactMap(), issues = [], unchecked = [], digests = {}, defs = [], documentSections = 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 (state.schemaVersion === 3) {
+  if (state.schemaVersion === 4) {
     try {
       const request = await safeRead(directory,state,'source/request.md');
       if (!request?.trim()) issues.push('Missing or empty source/request.md.');
       else digests['source/request.md'] = hash(request);
     } catch { issues.push('Cannot read source/request.md inside this delivery.'); }
-  } else if (!await exists(path.join(directory,'source/request.md'))) issues.push('Missing source/request.md.');
-  const preparing = state.schemaVersion === 3 && !find('requirement');
+  }
+  const preparing = state.schemaVersion === 4 && !find('requirement');
   if (preparing && state.goalRef !== 'source/request.md') issues.push('Before requirements exist, goalRef must point to source/request.md.');
   if (!preparing && !find('requirement')) issues.push(`Register ${requirementKind} as the requirement entry.`);
   if (!preparing && policy.authority === null) issues.push('Select the requirement authority when registering PRD/Scope.');
@@ -90,22 +156,29 @@ export async function inspectDocuments(directory, state) {
     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 (!text.trim()) issues.push(`${doc.path}: empty document.`);
+    if (doc.mode === 'reused') {
+      // Reuse is a current input option, not a historical document protocol.
+      // Read ordinary IDs from the explicitly registered requirement authority;
+      // do not impose our outline or infer that arbitrary source formats passed.
+      if (doc === find('requirement') && /\.md$/i.test(doc.path)) defs.push(...definitions(text,doc.path).filter(d=>/^(REQ|AC|PAGE|Q)-/.test(d.id)));
+      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;
+      const records=sections(text,spec); let previous=-1;
+      documentSections.set(doc.path,records);
+      for(const record of records) {
+        if(record.count!==1 || record.start<=previous) issues.push(`${doc.path}: missing, duplicate or unordered section ${record.id}.`);
+        previous=record.start;
+        if(record.count===1 && !record.body) issues.push(`${doc.path}: empty section ${record.id}.`);
       }
-      defs.push(...definitions(text, doc.path));
+      const owned={prd:['REQ','AC','PAGE'],scope:['REQ','AC','PAGE'],plan:['B','TASK'],testing:['TC','RUN'],review:['REV'],'change-log':['CHG']}[doc.kind]??[];
+      defs.push(...definitions(text, doc.path, spec).filter(d=>owned.includes(d.id.split('-')[0]) || d.id.startsWith('Q-')));
     }
   }
-  const legacyRuns=await preservedLegacyRuns(directory,state);
-  const runs = state.stageRuns.filter(r => !legacyRuns.has(r.id));
+  const runs = state.stageRuns;
   for (const [i, run] of state.stageRuns.entries()) {
-    if (!runs.includes(run) || run.progress === 'planned') continue;
+    if (run.progress === 'planned') continue;
     const contract = map.stages[run.stage], doc = find(contract.kind) ?? (run.stage === 'contract' && policy.interface === 'none' ? find('sql') : null);
     if (!doc && preparing && ['frame','requirements','scope'].includes(run.stage) && run.progress !== 'done') continue;
     if (!doc) { issues.push(`${run.id}: missing registered ${contract.kind} artifact.`); continue; }
@@ -114,22 +187,28 @@ export async function inspectDocuments(directory, state) {
       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(map.documents[doc.kind] && doc.mode==='new') {
+        const body=await safeRead(directory,state,doc.path).catch(()=>'');
+        if(!run.resultRef?.includes('#') || !hasLocator(body,run.resultRef.split('#')[1],map.documents[doc.kind])) issues.push(`${run.id}: missing or ambiguous result locator ${run.resultRef}.`);
+        const used=documentSections.get(doc.path)?.find(s=>s.id===section);
+        if(used && !meaningful(used.body??'')) issues.push(`${run.id}: replace template guidance with substantive ${section} content.`);
+      }
       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.`);
+        const record=defs.find(d=>d.file===doc.path && d.id.startsWith(prefix) && `${doc.path}#${d.id}`===run.resultRef);
+        if(!record || !meaningful(record.body)) issues.push(`${run.id}: result must locate a substantive ${prefix} record.`);
+        if(state.stageRuns.some(other=>other.id!==run.id && other.progress==='done' && other.resultRef===run.resultRef)) issues.push(`${run.id}: use a distinct result record for each execution.`);
       }
       if (run.stage === 'contract') {
         for (const db of policy.databases ?? []) {
           const file = policy.databases.length === 1 ? 'database.sql' : `database-${db}.sql`;
-          if (!docs.some(d => d.kind === 'sql' && d.path === file) || !await exists(path.join(directory,file))) issues.push(`${run.id}: missing independent ${file}.`);
+          if (!docs.some(d => d.kind === 'sql' && d.path === file) || !(await safeRead(directory,state,file).catch(()=>null))) issues.push(`${run.id}: missing independent ${file}.`);
         }
       }
     }
   }
-  if (state.schemaVersion === 3) {
+  if (state.schemaVersion === 4) {
     const unknown = unknownConditions(policy);
     const dependent = runs.filter(r=>r.progress !== 'planned' && !['frame','requirements','scope','diagnose'].includes(r.stage));
     if (preparing && dependent.length) issues.push('Prepare and review formal requirements before dependent work.');
@@ -142,29 +221,44 @@ export async function inspectDocuments(directory, state) {
     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 seen=new Set();
+  for(const d of defs) {
+    if(seen.has(d.id)) issues.push(`Duplicate definition ${d.id}.`);
+    seen.add(d.id);
+    if(!meaningful(d.body)) issues.push(`${d.id}: empty or placeholder definition.`);
+  }
+  for(const doc of docs.filter(d=>d.mode==='new' && map.documents[d.kind])) {
+    const body=await safeRead(directory,state,doc.path).catch(()=>null);
+    if(!body) continue;
+    const citations=qualifiedCitations(body);
+    for(const {target,locator} of citations.references) {
+      try {
+        const source=await safeRead(directory,state,decodeURI(target));
+        const sourcePath=decodeURI(target).split('#')[0], registered=docs.find(d=>d.path===sourcePath && d.mode==='new');
+        const records=source===null?[]:definitions(source,sourcePath,map.documents[registered?.kind]).filter(d=>d.id===locator);
+        if(records.length!==1 || !meaningful(records[0].body)) issues.push(`${doc.path}: missing, ambiguous or empty source locator ${target}.`);
+      } catch { issues.push(`${doc.path}: unreadable source citation ${target}.`); }
     }
+    for(const id of numberedIds(citations.local)) if(!seen.has(id)) issues.push(`${doc.path}: undefined reference ${id}.`);
   }
-  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 doc of docs.filter(d=>d.mode==='new' && map.documents[d.kind])) {
+    const ready=runs.some(r=>r.progress==='done' && (find(map.stages[r.stage].kind)?.path===doc.path))
+      || (state.reviewHistory??[]).some(r=>r.document===doc.path && r.version===doc.version && (r.kind==='approved' || (r.kind==='self-check' && r.result==='passed')));
+    const records=documentSections.get(doc.path)??[];
+    if(ready) {
+      for(const section of records) if(!meaningful(section.body??'')) issues.push(`${doc.path}: replace template guidance with substantive ${section.id} content.`);
+      for(const prefix of ({prd:['REQ','AC'],scope:['REQ','AC'],testing:['TC'],plan:['TASK']}[doc.kind]??[])) {
+        if(!defs.some(d=>d.file===doc.path && d.id.startsWith(prefix+'-'))) issues.push(`${doc.path}: include substantive ${prefix} records.`);
+      }
+    }
+    // Design obligations cannot hide in an unapproved execution surface.
+    const design=({plan:[['TASK','tasks'],['B','batches']],testing:[['TC','cases']]})[doc.kind]??[];
+    for(const [prefix,section] of design) {
+      const allowed=definitions(records.find(r=>r.id===section)?.body??'',doc.path).map(d=>d.id);
+      for(const d of defs.filter(d=>d.file===doc.path && d.id.startsWith(prefix+'-'))) if(!allowed.includes(d.id)) issues.push(`${doc.path}: define ${d.id} in ${section}, not execution records.`);
+    }
   }
-  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 };
+  return {issues,unchecked,digests};
 }
 export async function documentChanges(directory, state) {
   const changes=[];

package/lib/install.mjs

@@ -19,7 +19,7 @@ export function fileKey(relative, paths = path) {
 }
 function managedFile(file) {
   const normalized = file.replaceAll('\\', '/');
-  return relativeFile(file) && (normalized === '.aimship/bin/aimship.mjs' || /^\.(agents|claude|cursor)\/skills\/aimship\/(SKILL\.md|agents\/.+)$/.test(normalized));
+  return relativeFile(file) && (normalized === '.aimship/bin/aimship.mjs' || /^\.(agents|claude)\/skills\/aimship\/(SKILL\.md|agents\/.+)$/.test(normalized));
 }
 function validateManifest(manifest) {
   if (!object(manifest) || manifest.schemaVersion !== 1 || manifest.product !== 'aimship' || !object(manifest.managed) || !object(manifest.releases) || !Array.isArray(manifest.hosts)) fail('INSTALL_FORMAT', 'Unknown or invalid installation manifest.', 'Preserve the installation and use a compatible installer.');

package/lib/language.mjs

@@ -0,0 +1,41 @@
+// Delivery display language only. Stable identifiers and existing user content stay unchanged.
+export const languageOf = state => state.language;
+export const text = (state, english, chinese) => languageOf(state) === 'zh-CN' ? chinese : english;
+const labels = {
+ 'not recorded':'未记录', unknown:'未知', null:'未知', true:'是', false:'否', none:'不适用', http:'HTTP', other:'其他',
+ technical:'技术与契约', unrecorded:'未分组', unavailable:'不可用', 'assess-outcome':'核对交付结论与接受结果', frame:'目标梳理', requirements:'需求', scope:'范围确认', prototype:'原型', 'tech-design':'技术设计', contract:'接口与 SQL', 'test-design':'测试设计', plan:'实施计划', implement:'实施', review:'审查', verify:'验证', handoff:'交付验收', diagnose:'调查',
+ planned:'待开始', active:'进行中', blocked:'受阻', done:'已完成记录', passed:'通过', failed:'失败', 'not-run':'未执行', mixed:'部分通过', current:'当前有效', 'needs-review':'待复核',
+ 'in-progress':'进行中', met:'已达成', 'not-met':'未达成', 'not-recorded':'未记录', accepted:'已接受', declined:'未接受',
+ approved:'已批准', pending:'待审核', 'self-check-required':'待自检', 'self-check-failed':'自检失败', 'changes-requested':'需修改', 'evidence-changed':'审批依据已变化',
+ 'partial-scope':'明确限定范围', 'standard-complete':'标准交付已完成', 'ready-for-acceptance':'待验收', incomplete:'未完成',
+ 'continue-current':'继续当前工作', 'continue-group':'继续当前组工作', 'suggest-new-session':'建议新开会话', 'inspect-existing-work':'检查已有工作', 'resolve-current':'先处理当前问题', 'await-review':'等待审核', 'reconcile-save':'核对保存结果', finished:'当前约定目标已结束', 'arrange-next':'确认并记录下一项工作',
+ 'requirements preparation':'需求准备', supported:'已启用', enforced:'已启用',
+ interaction:'交互变化', prototypeCovered:'已有原型覆盖', interface:'接口变化', databases:'数据库变化'
+};
+export function displayValue(state,value) {
+ const raw=String(value ?? 'not recorded');
+ return languageOf(state)==='zh-CN' ? (labels[raw] ?? raw) : raw;
+}
+const explanations = {
+ 'Endpoint or artifact conditions remain unknown.':'交付终点或产物适用条件尚未明确。',
+ 'Changed or missing registered documents require reconciliation.':'已登记文档有变化或缺失，需要核对。',
+ 'Missing reviewed requirements / Scope.':'缺少已完成审核的需求或范围文档。',
+ 'Missing applicable interface/SQL contract.':'缺少本次适用的接口或 SQL 契约。',
+ 'Missing applicable interaction prototype.':'缺少本次适用的交互原型。',
+ 'Selected work or document approvals remain unresolved.':'已安排工作或文档审批仍有未完成项。',
+ 'Implementation results remain unresolved.':'实施结果仍有未解决项。',
+ 'Review results remain unresolved.':'审查结果仍有未解决项。',
+ 'Missing passing overall implementation review.':'缺少通过的整体实施审查。',
+ 'Independent verification is not fully recorded as passed after overall review.':'整体审查之后的独立验证尚未完整记录为通过。',
+ 'Handoff precedes verification.':'交付记录早于验证。',
+ 'Unresolved changes remain.':'仍有未处理的变更。'
+};
+export function completionMessage(state,message) {
+ if(languageOf(state)!=='zh-CN')return message;
+ if(explanations[message])return explanations[message];
+ const stage=/^Missing current completed (.+)\.$/.exec(message);
+ if(stage)return `缺少当前有效且已完成的${displayValue(state,stage[1])}记录。`;
+ const batch=/^Missing passing batch review for (.+)\.$/.exec(message);
+ if(batch)return `批次 ${batch[1]} 缺少通过的批内审查。`;
+ return message;
+}

package/lib/location.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fail, inside, noSymlinks } from './io.mjs';
+
+const recovery = 'Use a delivery folder under the configured dataRoot, or preserve the user’s explicit location decision in a local source file. Do not fall back to the current workspace.';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Resolve existing ancestors without creating a directory or following a managed
+// symlink. Appended missing components retain their intended location.
+async function location(target, writable = false) {
+  await noSymlinks(target);
+  let ancestor = target;
+  const missing = [];
+  while (true) {
+    let stat;
+    try { stat = await fs.stat(ancestor); }
+    catch (error) {
+      if (error.code !== 'ENOENT') fail('LOCATION_ACCESS', `Cannot inspect the delivery location: ${ancestor}`, recovery, { cause: error.code });
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) fail('LOCATION_ACCESS', `Cannot locate an existing parent: ${target}`, recovery);
+      missing.unshift(path.basename(ancestor)); ancestor = parent; continue;
+    }
+    if (!stat.isDirectory()) fail('LOCATION_PATH', `The location or its parent is not a directory: ${ancestor}`, recovery);
+    try {
+      if (writable) await fs.access(ancestor, fs.constants.R_OK | fs.constants.W_OK | fs.constants.X_OK);
+      return path.join(await fs.realpath(ancestor), ...missing);
+    } catch (error) { fail('LOCATION_ACCESS', `Cannot access the delivery location: ${ancestor}`, recovery, { cause: error.code }); }
+  }
+}
+
+async function explicitDecision(directory, reference) {
+  if (typeof reference !== 'string' || !reference.trim() || reference.includes('\0') || reference.includes('\\') || reference.includes('#') || reference.includes(':') || path.isAbsolute(reference) || reference.split('/').includes('..')) {
+    fail('INVALID_STORAGE', 'An explicit location needs a delivery-relative local decisionRef.', recovery);
+  }
+  const file = path.resolve(directory, reference);
+  if (file === directory || !inside(directory, file)) fail('INVALID_STORAGE', 'The location decision must be a file inside this delivery.', recovery);
+  await noSymlinks(file);
+  try {
+    if (!(await fs.stat(file)).isFile() || !(await fs.readFile(file, 'utf8')).trim()) fail('INVALID_STORAGE', 'The location decision must be a nonempty readable file.', recovery);
+  } catch (error) {
+    if (error.code === 'INVALID_STORAGE') throw error;
+    fail('LOCATION_DECISION', `Cannot read the explicit location decision: ${reference}`, recovery, { cause: error.code });
+  }
+}
+
+/** New initialization only. Existing deliveries keep their saved identity/location. */
+export async function validateInitLocation(directory, input, runtime = {}) {
+  const root = runtime.dataRoot === undefined ? path.join(os.homedir(), 'Aimship') : runtime.dataRoot;
+  if (typeof root !== 'string' || !root.trim() || root.includes('\0') || !path.isAbsolute(root)) fail('INVALID_STORAGE', 'The configured dataRoot must be an absolute path.', recovery);
+  if (typeof directory !== 'string' || !directory.trim() || directory.includes('\0')) fail('INVALID_STORAGE', 'A delivery location is required.', recovery);
+  const storage = input?.storage;
+  if (storage !== undefined && (!object(storage) || !['configured','explicit'].includes(storage.mode) || Object.keys(storage).some(key => !['mode','decisionRef'].includes(key)) || (storage.mode === 'configured' && storage.decisionRef !== undefined))) {
+    fail('INVALID_STORAGE', 'storage accepts only a location mode and an explicit decisionRef; dataRoot is tool-managed.', recovery);
+  }
+  const dataRoot = await location(path.resolve(root));
+  const target = await location(path.resolve(directory), true);
+  if (target === dataRoot) fail('INIT_LOCATION_ROOT', 'A delivery needs its own folder; dataRoot itself is not a delivery.', recovery);
+  if (storage?.mode === 'explicit') {
+    await explicitDecision(target, storage.decisionRef);
+    return { mode: 'explicit', dataRoot, decisionRef: storage.decisionRef };
+  }
+  if (!inside(dataRoot, target)) fail('INIT_LOCATION_REQUIRED', 'The initialization target is outside the configured dataRoot and has no explicit location decision.', recovery, { directory: target, dataRoot });
+  return { mode: 'configured', dataRoot };
+}