aimship 0.1.0-preview.12 → 0.1.0-preview.13

package/README.md

@@ -43,7 +43,7 @@ Confirm npm's package installation prompt. `@preview` selects the published prev
 To install an exact published version, for example:
 
 ```sh
-npx aimship@0.1.0-preview.7 install --host codex
+npx aimship@0.1.0-preview.13 install --host codex
 ```
 
 If you already have an Aimship `.tgz` package, replace `VERSION` with its actual version and run from the directory containing it:

package/README.zh-CN.md

@@ -43,7 +43,7 @@ npx aimship@preview install --host codex --host claude-code
 安装指定的已发布版本，例如：
 
 ```sh
-npx aimship@0.1.0-preview.7 install --host codex
+npx aimship@0.1.0-preview.13 install --host codex
 ```
 
 如果已有 Aimship 的 `.tgz` 安装包，将 `VERSION` 替换为实际版本号，在包所在目录执行：

package/lib/documents.mjs

@@ -60,7 +60,10 @@ export const numberedIds = text => [...new Set(markdownText(text).match(new RegE
 // create a second local definition or a namespace/index.
 function qualifiedCitations(text) {
   const references=[];
-  const local=markdownText(text).replace(/\[([^\]\n]*)\]\(([^()\s]+\.md)(?:#([^()\s]+))?\)/gi,(match,label,file,fragment)=>{
+  // 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});
@@ -68,10 +71,20 @@ function qualifiedCitations(text) {
   });
   return {references,local};
 }
-export function definitions(text, file) {
-  const lines=markdownText(text).split('\n'), result=[];
+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], structured=/^\s*(?:\||#{1,6}\s+|[-*+]\s+)/.test(line);
+    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);
@@ -84,9 +97,16 @@ export function definitions(text, file) {
         body+='\n'+lines[j];
       }
     }
-    result.push({id:match[1],file,body,refs:numberedIds(body).filter(id=>id!==match[1])});
+    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))});
   }
-  return result;
+  // 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,'');
@@ -96,7 +116,7 @@ export function meaningful(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,'').filter(d=>d.id===locator).length===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) {
@@ -153,7 +173,7 @@ export async function inspectDocuments(directory, state) {
         if(record.count===1 && !record.body) issues.push(`${doc.path}: empty section ${record.id}.`);
       }
       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).filter(d=>owned.includes(d.id.split('-')[0]) || d.id.startsWith('Q-')));
+      defs.push(...definitions(text, doc.path, spec).filter(d=>owned.includes(d.id.split('-')[0]) || d.id.startsWith('Q-')));
     }
   }
   const runs = state.stageRuns;
@@ -214,7 +234,8 @@ export async function inspectDocuments(directory, state) {
     for(const {target,locator} of citations.references) {
       try {
         const source=await safeRead(directory,state,decodeURI(target));
-        const records=source===null?[]:definitions(source,target.split('#')[0]).filter(d=>d.id===locator);
+        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}.`); }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimship",
-  "version": "0.1.0-preview.12",
+  "version": "0.1.0-preview.13",
   "description": "Explicit, goal-driven delivery workflow for coding agents",
   "license": "MIT",
   "type": "module",

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

@@ -22,7 +22,7 @@ Use `tech-design.md`. HTTP changes use `openapi.yaml` or the registered engineer
 
 Use readable IDs for different entities: REQ for requirements, AC for acceptance, TASK/B for implementation, TC for cases, REV/RUN for review/execution records, and CHG/Q/PAGE where useful. Start each kind at 001. Keep the same obligation's ID across documents; do not give different entities the same ID. Users should be able to search an ID in ordinary Markdown. Do not require hyperlinks or any reader's HTML support.
 
-Define each ID once in its owning document, in a table's first column, a heading or a bullet, with substantive content: REQ/AC and optional PAGE mappings in PRD or Scope, TASK/B in plan, TC/RUN in testing, REV in review, CHG in change log. Other documents may cite those numbers in prose or tables; these citations do not redefine them. Q records may be defined where the question is resolved. For example:
+Define each ID once in its owning document, in a table's first column, a heading or a bullet, with substantive content: REQ/AC and optional PAGE mappings in PRD or Scope, TASK/B in plan, TC/RUN in testing, REV in review, CHG in change log. Put requirements, acceptance, batches, tasks and cases in their existing corresponding sections. The same document's coverage, summaries and execution records, as well as other documents, may cite those numbers in prose or tables without redefining them. Q records may be defined where the question is resolved. For example:
 
 ```markdown
 | ID | Requirement | Acceptance |

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

@@ -22,4 +22,4 @@ Use [the shared core](../core.md) for state, evidence and continuation rules. Re
 
 Use plan.md. Preserve the ordinary template headings and section order. Follow [document patterns](../document-patterns.md) and the single [artifact map](../artifact-map.json). Keep this run independent even when its document is shared. New runs need a precise result location; adopted work is not a newly executed stage.
 
-Update TASK/B status and actual execution in the existing plan.md, preserving planned versus actual and code versions. Do not generate implementation.md.
+Update TASK/B status and actual execution in plan.md's execution section, citing the existing task/batch numbers. Keep approved task definitions unchanged unless the plan itself changes; preserve planned versus actual and code versions. Do not generate implementation.md.

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

@@ -12,7 +12,7 @@ B ID, goal, dependencies and integration arrangement. Replace guidance with actu
 
 ## Tasks and completion criteria
 
-TASK, batch, REQ/AC or risk, repository ID, file/module, planned change, completion criteria, status, artifact ref. Replace guidance with actual content; explain inapplicability, never prefill a result.
+TASK, batch, REQ/AC or risk, repository ID, file/module, planned change and completion criteria. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
 ## Review and independent verification arrangement
 
@@ -20,7 +20,7 @@ Each batch review, overall review then independent verification; no per-batch fu
 
 ## Task status and execution records
 
-Actual changes and object versions by TASK/B; preserve original plan and distinguish pre-existing changes. Replace guidance with actual content; explain inapplicability, never prefill a result.
+Current status, actual changes, artifact references and object versions by existing TASK/B; preserve the approved tasks above and distinguish pre-existing changes. Record progress here, for example a table of Task | Status | Actual result. Replace guidance with actual content; explain inapplicability, never prefill a result.
 
 ## Deviations, blockers and remaining work