openxiangda-devkit-core 2.0.0-alpha.97 → 2.0.0

package/dist/app-spec.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, openSync, readSync, closeSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { SCHEMA_VERSIONS, } from "openxiangda-contracts";
 export const APP_SPEC_SCHEMAS = {
@@ -7,7 +7,8 @@ export const APP_SPEC_SCHEMAS = {
     capability: "openxiangda.appspec/capability/v1",
     change: "openxiangda.appspec/change/v1",
     decision: "openxiangda.appspec/decision/v1",
-    context: "openxiangda.appspec/context/v2",
+    design: "openxiangda.appspec/design/v1",
+    context: "openxiangda.appspec/context/v4",
 };
 export const APP_SPEC_LIMITS = {
     maximumFiles: 128,
@@ -49,8 +50,8 @@ export function initializeAppSpec(input) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled: true,
-        advisory: true,
-        releaseGate: false,
+        advisory: false,
+        releaseGate: true,
         created,
         existing,
     };
@@ -72,8 +73,8 @@ export function createAppSpecCapability(input) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled: true,
-        advisory: true,
-        releaseGate: false,
+        advisory: false,
+        releaseGate: true,
         created: relativePath(input.root, path),
     };
 }
@@ -82,6 +83,9 @@ export function createAppSpecChange(input) {
     if (!CHANGE_ID.test(input.id)) {
         throw stableError("APPSPEC_CHANGE_ID_INVALID", input.id);
     }
+    if (historyCandidates(input.root, input.id, 0, []).paths.some(path => basename(path) === `${input.id}.md`)) {
+        throw stableError('APPSPEC_HISTORY_CHANGE_EXISTS', input.id);
+    }
     if (!input.title.trim())
         throw stableError("APPSPEC_TITLE_REQUIRED", input.id);
     const risk = input.risk || "L1";
@@ -102,8 +106,8 @@ export function createAppSpecChange(input) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled: true,
-        advisory: true,
-        releaseGate: false,
+        advisory: false,
+        releaseGate: true,
         created: relativePath(input.root, path),
         risk,
         status: "draft",
@@ -171,8 +175,8 @@ export function closeAppSpecChange(input) {
         return {
             schemaVersion: APP_SPEC_SCHEMAS.context,
             enabled: true,
-            advisory: true,
-            releaseGate: false,
+            advisory: false,
+            releaseGate: true,
             archived: null,
             status: document.status,
             converged: false,
@@ -186,15 +190,15 @@ export function closeAppSpecChange(input) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled: true,
-        advisory: true,
-        releaseGate: false,
+        advisory: false,
+        releaseGate: true,
         archived: relativePath(input.root, target),
         status: "archived",
         converged: true,
         diagnostics,
     };
 }
-export function inspectAppSpec(root, contract, selector) {
+export function inspectAppSpec(root, contract, selector, historyOffset = 0) {
     const paths = appSpecPaths(root);
     if (!existsSync(paths.root))
         return emptyContext(contract, selector);
@@ -203,7 +207,7 @@ export function inspectAppSpec(root, contract, selector) {
         diagnostics.push(issue("error", "APPSPEC_ROOT_INVALID", "appspec 必须是普通目录，不能是符号链接", "appspec"));
         return emptyContext(contract, selector, diagnostics, true);
     }
-    const collection = collectDocuments(root, diagnostics);
+    const collection = collectDocuments(root, diagnostics, selector, historyOffset);
     const application = collection.app[0] || null;
     validateDocuments(collection, contract, diagnostics);
     const selected = selectContext(collection, selector, diagnostics);
@@ -213,9 +217,10 @@ export function inspectAppSpec(root, contract, selector) {
         ...collection.activeChanges,
         ...collection.history,
         ...collection.decisions,
+        ...collection.designs,
     ];
     const index = summarizeCollection(collection);
-    const workspaceDigest = digestDocuments(allDocuments, contract);
+    const workspaceDigest = digestDocuments(allDocuments.filter(document => !document.path.startsWith("appspec/changes/history/")), contract);
     const selectionDocuments = selectedDocuments(application, selected);
     const selectionDigest = allDocuments.length === 0
         ? null
@@ -227,8 +232,8 @@ export function inspectAppSpec(root, contract, selector) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled: true,
-        mode: "advisory",
-        releaseGate: false,
+        mode: "guided",
+        releaseGate: true,
         root: "appspec",
         selector: selector || null,
         contract,
@@ -238,16 +243,19 @@ export function inspectAppSpec(root, contract, selector) {
         activeChanges: budgeted.activeChanges,
         archivedChanges: budgeted.archivedChanges,
         decisions: budgeted.decisions,
+        designs: budgeted.designs,
+        historyPage: collection.historyPage,
         contextBudget: budgeted.contextBudget,
         stats: {
             files: allDocuments.length,
             bytes: collection.bytes,
             capabilities: collection.capabilities.length,
             activeChanges: collection.activeChanges.length,
-            historyChanges: collection.history.length,
+            historyChanges: collection.historyPage.total,
             decisions: collection.decisions.length,
-            requirements: unique(collection.capabilities.flatMap(document => document.requirementIds)).length,
-            acceptanceScenarios: unique(collection.capabilities.flatMap(document => document.acceptanceIds)).length,
+            designs: collection.designs.length,
+            requirements: unique([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.requirementIds)).length,
+            acceptanceScenarios: unique([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.acceptanceIds)).length,
         },
         workspaceDigest,
         selectionDigest,
@@ -259,7 +267,7 @@ export function advisoryAppSpecDiagnostics(diagnostics) {
         ...diagnostic,
         severity: diagnostic.severity === "error" ? "warning" : diagnostic.severity,
         remediation: diagnostic.remediation ||
-            "AppSpec 是辅助层；可运行 openxiangda spec check 获取完整诊断，应用 check/deploy 不受阻断",
+            "运行 openxiangda spec check 查看文档诊断；普通 check 可以继续，正式发布按阶段核对需求与验收",
     }));
 }
 export function summarizeAppSpecContext(context) {
@@ -269,6 +277,7 @@ export function summarizeAppSpecContext(context) {
         releaseGate: context.releaseGate,
         workspaceDigest: context.workspaceDigest,
         selectionDigest: context.selectionDigest,
+        historyPage: context.historyPage,
         contextBudget: context.contextBudget,
         stats: context.stats,
         diagnostics: {
@@ -285,8 +294,8 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
     return {
         schemaVersion: APP_SPEC_SCHEMAS.context,
         enabled,
-        mode: "advisory",
-        releaseGate: false,
+        mode: "guided",
+        releaseGate: true,
         root: "appspec",
         selector: selector || null,
         contract,
@@ -295,6 +304,7 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
             capabilities: [],
             activeChanges: [],
             decisions: [],
+            designs: [],
             history: [],
         },
         application: null,
@@ -302,6 +312,8 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
         activeChanges: [],
         archivedChanges: [],
         decisions: [],
+        designs: [],
+        historyPage: { offset: 0, limit: 50, total: 0, nextOffset: null },
         contextBudget: {
             maximumBytes: APP_SPEC_LIMITS.maximumContextBytes,
             contentBytes: 0,
@@ -315,6 +327,7 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
             activeChanges: 0,
             historyChanges: 0,
             decisions: 0,
+            designs: 0,
             requirements: 0,
             acceptanceScenarios: 0,
         },
@@ -323,7 +336,55 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
         diagnostics,
     };
 }
-function collectDocuments(root, diagnostics) {
+function historyCandidates(root, selector, offset, diagnostics) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw stableError('APPSPEC_HISTORY_OFFSET_INVALID', String(offset));
+    const directory = appSpecPaths(root).history;
+    const all = [];
+    let selected;
+    const started = Date.now();
+    if (existsSync(directory)) {
+        if (!isRegularDirectory(directory))
+            diagnostics.push(issue('error', 'APPSPEC_DIRECTORY_INVALID', '历史目录必须是普通目录', 'appspec/changes/history'));
+        else {
+            const years = readdirSync(directory, { withFileTypes: true }).sort((a, b) => b.name.localeCompare(a.name));
+            for (const year of years.slice(0, 256)) {
+                const path = join(directory, year.name);
+                if (year.isSymbolicLink()) {
+                    diagnostics.push(issue('error', 'APPSPEC_SYMLINK_FORBIDDEN', '历史记录不能使用符号链接', relativePath(root, path)));
+                    continue;
+                }
+                if (year.isFile() && year.name.endsWith('.md'))
+                    all.push(path);
+                else if (year.isDirectory()) {
+                    // 稳定 ID 的读取不依赖当前索引页；正文仍受单文件与上下文预算约束。
+                    const direct = selector && CHANGE_ID.test(selector) ? join(path, `${selector}.md`) : undefined;
+                    if (direct && existsSync(direct))
+                        selected = direct;
+                    if (all.length >= 100_000 || Date.now() - started > 5_000)
+                        continue;
+                    for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                        if (all.length >= 100_000)
+                            break;
+                        const file = join(path, entry.name);
+                        if (entry.isFile() && entry.name.endsWith('.md'))
+                            all.push(file);
+                        else if (entry.isSymbolicLink() || entry.isDirectory())
+                            diagnostics.push(issue('warning', 'APPSPEC_HISTORY_ENTRY_INVALID', '历史只索引 history/<year>/*.md 普通文件', relativePath(root, file)));
+                    }
+                }
+            }
+            if (years.length > 256 || all.length >= 100_000 || Date.now() - started > 5_000)
+                diagnostics.push(issue('warning', 'APPSPEC_HISTORY_INDEX_LIMIT', '历史索引达到读取预算；记录仍保留，可用稳定变更 ID 读取正文', 'appspec/changes/history'));
+        }
+    }
+    const paths = all.slice(offset, offset + 50);
+    const match = selected || (selector ? all.find(path => basename(path) === `${selector}.md`) : undefined);
+    if (match && !paths.includes(match))
+        paths.push(match);
+    return { paths, page: { offset, limit: 50, total: all.length, nextOffset: offset + 50 < all.length ? offset + 50 : null } };
+}
+function collectDocuments(root, diagnostics, selector, historyOffset = 0) {
     const paths = appSpecPaths(root);
     const result = {
         app: [],
@@ -331,7 +392,9 @@ function collectDocuments(root, diagnostics) {
         activeChanges: [],
         history: [],
         decisions: [],
+        designs: [],
         bytes: 0,
+        historyPage: { offset: historyOffset, limit: 50, total: 0, nextOffset: null },
     };
     const candidates = [];
     if (existsSync(paths.app))
@@ -342,19 +405,22 @@ function collectDocuments(root, diagnostics) {
     })), ...markdownFiles(paths.activeChanges, false, diagnostics, root).map(path => ({
         path,
         kind: "change",
-    })), ...markdownFiles(paths.history, true, diagnostics, root).map(path => ({
-        path,
-        kind: "change",
-        history: true,
     })), ...markdownFiles(paths.decisions, false, diagnostics, root).map(path => ({
         path,
         kind: "decision",
     })));
+    for (const directory of ['product', 'experience', 'design', 'reviews']) {
+        candidates.push(...markdownFiles(join(paths.root, directory), false, diagnostics, root).map(path => ({ path, kind: 'design' })));
+    }
     if (candidates.length > APP_SPEC_LIMITS.maximumFiles) {
         diagnostics.push(issue("error", "APPSPEC_FILE_LIMIT_EXCEEDED", `AppSpec 文件数 ${candidates.length} 超过上限 ${APP_SPEC_LIMITS.maximumFiles}`, "appspec"));
         candidates.splice(APP_SPEC_LIMITS.maximumFiles);
     }
-    for (const candidate of candidates.sort((left, right) => left.path.localeCompare(right.path))) {
+    const history = historyCandidates(root, selector, historyOffset, diagnostics);
+    result.historyPage = history.page;
+    candidates.push(...history.paths.map(path => ({ path, kind: "change", history: true })));
+    let historyBytes = 0;
+    for (const candidate of candidates.sort((left, right) => Number(!!left.history) - Number(!!right.history) || left.path.localeCompare(right.path))) {
         let stat;
         try {
             stat = lstatSync(candidate.path);
@@ -371,12 +437,30 @@ function collectDocuments(root, diagnostics) {
             diagnostics.push(issue("error", "APPSPEC_FILE_SIZE_EXCEEDED", `AppSpec 单文件超过 ${APP_SPEC_LIMITS.maximumFileBytes} 字节上限`, relativePath(root, candidate.path)));
             continue;
         }
-        if (result.bytes + stat.size > APP_SPEC_LIMITS.maximumTotalBytes) {
+        const indexOnly = candidate.history && basename(candidate.path) !== `${selector}.md`;
+        const readBytes = indexOnly ? Math.min(stat.size, 8192) : stat.size;
+        if ((candidate.history ? historyBytes : result.bytes) + readBytes > APP_SPEC_LIMITS.maximumTotalBytes) {
             diagnostics.push(issue("error", "APPSPEC_TOTAL_SIZE_EXCEEDED", `AppSpec 总大小超过 ${APP_SPEC_LIMITS.maximumTotalBytes} 字节上限`, "appspec"));
             break;
         }
-        result.bytes += stat.size;
-        const content = readFileSync(candidate.path, "utf8");
+        if (candidate.history)
+            historyBytes += readBytes;
+        else
+            result.bytes += readBytes;
+        let content;
+        if (indexOnly) {
+            const descriptor = openSync(candidate.path, 'r');
+            try {
+                const buffer = Buffer.alloc(readBytes);
+                const bytes = readSync(descriptor, buffer, 0, readBytes, 0);
+                content = buffer.subarray(0, bytes).toString('utf8').match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0] || '';
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        }
+        else
+            content = readFileSync(candidate.path, "utf8");
         const document = parseAppSpecDocument(root, candidate.path, candidate.kind, content, diagnostics);
         if (!document)
             continue;
@@ -384,6 +468,8 @@ function collectDocuments(root, diagnostics) {
             result.app.push(document);
         else if (candidate.kind === "capability")
             result.capabilities.push(document);
+        else if (candidate.kind === "design")
+            result.designs.push(document);
         else if (candidate.kind === "decision")
             result.decisions.push(document);
         else if (candidate.history)
@@ -411,12 +497,12 @@ function validateDocuments(collection, contract, diagnostics) {
             diagnostics.push(issue("error", "APPSPEC_HISTORY_CHANGE_STATUS_INVALID", `历史目录中的 ChangeSpec 必须是 archived 或 cancelled，当前为 ${document.status}`, document.path));
         }
     }
-    duplicateDiagnostics([...collection.capabilities, ...collection.activeChanges, ...collection.history, ...collection.decisions], document => document.id, "APPSPEC_DOCUMENT_ID_DUPLICATED", diagnostics);
-    duplicateDiagnostics(collection.capabilities.flatMap(document => document.requirementIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_REQUIREMENT_ID_DUPLICATED", diagnostics);
-    duplicateDiagnostics(collection.capabilities.flatMap(document => document.acceptanceIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_ACCEPTANCE_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics([...collection.capabilities, ...collection.activeChanges, ...collection.history, ...collection.decisions, ...collection.designs], document => document.id, "APPSPEC_DOCUMENT_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.requirementIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_REQUIREMENT_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.acceptanceIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_ACCEPTANCE_ID_DUPLICATED", diagnostics);
     const capabilityIds = new Set(collection.capabilities.map(document => document.id));
-    const requirementIds = new Set(collection.capabilities.flatMap(document => document.requirementIds));
-    const acceptanceIds = new Set(collection.capabilities.flatMap(document => document.acceptanceIds));
+    const requirementIds = new Set([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.requirementIds));
+    const acceptanceIds = new Set([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(document => document.acceptanceIds));
     const resourceCodes = new Set(contract.resourceCodes);
     const actionCodes = new Set(contract.actionCodes);
     const decisionIds = new Set(collection.decisions.map(document => document.id));
@@ -436,7 +522,7 @@ function validateDocuments(collection, contract, diagnostics) {
         }
         for (const id of document.references.requirements) {
             if (!requirementIds.has(id)) {
-                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_REQUIREMENT_UNKNOWN", `ChangeSpec 引用的需求 ${id} 尚未进入当前 CapabilitySpec`, document.path));
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_REQUIREMENT_UNKNOWN", `ChangeSpec 引用的需求 ${id} 尚未进入当前总纲或能力规格`, document.path));
             }
         }
         for (const id of document.references.decisions) {
@@ -460,13 +546,17 @@ function validateDocuments(collection, contract, diagnostics) {
     }
 }
 function validateCloseConvergence(document, collection, contract, diagnostics) {
+    for (const title of ['验证与发布', '交接']) {
+        if (!hasMeaningfulSection(document.content, [title], []))
+            diagnostics.push(issue('error', 'APPSPEC_HANDOFF_INCOMPLETE', `关闭前补齐“${title}”的实际结果；未发布或取消时明确原因`, `${document.path}#${title}`));
+    }
     const currentSpec = currentSpecStatus(document);
     if (currentSpec === "pending") {
         diagnostics.push(issue("error", "APPSPEC_CURRENT_SPEC_NOT_CONVERGED", "关闭前必须确认 currentSpec=merged 或 not-applicable；该检查只约束 spec close", document.path));
     }
     const capabilityIds = new Set(collection.capabilities.map(item => item.id));
-    const requirementIds = new Set(collection.capabilities.flatMap(item => item.requirementIds));
-    const acceptanceIds = new Set(collection.capabilities.flatMap(item => item.acceptanceIds));
+    const requirementIds = new Set([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(item => item.requirementIds));
+    const acceptanceIds = new Set([...collection.app, ...collection.capabilities, ...collection.designs].flatMap(item => item.acceptanceIds));
     const decisionIds = new Set(collection.decisions.map(item => item.id));
     for (const id of document.references.capabilities) {
         const matches = collection.capabilities.filter(item => item.id === id);
@@ -478,9 +568,9 @@ function validateCloseConvergence(document, collection, contract, diagnostics) {
         }
     }
     for (const id of document.references.requirements) {
-        const matches = collection.capabilities.filter(item => item.requirementIds.includes(id));
+        const matches = [...collection.app, ...collection.capabilities, ...collection.designs].filter(item => item.requirementIds.includes(id));
         if (!requirementIds.has(id)) {
-            diagnostics.push(issue("error", "APPSPEC_CHANGE_REQUIREMENT_UNKNOWN", `关闭前必须把需求 ${id} 合入当前 CapabilitySpec`, document.path));
+            diagnostics.push(issue("error", "APPSPEC_CHANGE_REQUIREMENT_UNKNOWN", `关闭前必须把需求 ${id} 合入当前总纲或能力规格`, document.path));
         }
         else if (matches.length > 1) {
             diagnostics.push(issue("error", "APPSPEC_REQUIREMENT_ID_DUPLICATED", `关闭前必须消除需求 ${id} 的重复定义`, document.path));
@@ -496,13 +586,13 @@ function validateCloseConvergence(document, collection, contract, diagnostics) {
         }
     }
     for (const id of document.requirementIds) {
-        const matches = collection.capabilities.filter(item => item.requirementIds.includes(id));
+        const matches = [...collection.app, ...collection.capabilities, ...collection.designs].filter(item => item.requirementIds.includes(id));
         if (matches.length > 1) {
             diagnostics.push(issue("error", "APPSPEC_REQUIREMENT_ID_DUPLICATED", `关闭前必须消除需求 ${id} 的重复定义`, document.path));
         }
     }
     for (const id of document.acceptanceIds) {
-        const matches = collection.capabilities.filter(item => item.acceptanceIds.includes(id));
+        const matches = [...collection.app, ...collection.capabilities, ...collection.designs].filter(item => item.acceptanceIds.includes(id));
         if (matches.length > 1) {
             diagnostics.push(issue("error", "APPSPEC_ACCEPTANCE_ID_DUPLICATED", `关闭前必须消除验收场景 ${id} 的重复定义`, document.path));
         }
@@ -514,12 +604,12 @@ function validateCloseConvergence(document, collection, contract, diagnostics) {
 function validateEmbeddedCurrentSpecIds(document, currentRequirementIds, currentAcceptanceIds, diagnostics) {
     for (const id of document.requirementIds) {
         if (!currentRequirementIds.has(id)) {
-            diagnostics.push(issue("error", "APPSPEC_CHANGE_REQUIREMENT_NOT_CURRENT", `ChangeSpec 中的长期需求 ${id} 尚未进入当前 CapabilitySpec`, document.path));
+            diagnostics.push(issue("error", "APPSPEC_CHANGE_REQUIREMENT_NOT_CURRENT", `ChangeSpec 中的长期需求 ${id} 尚未进入当前总纲或能力规格`, document.path));
         }
     }
     for (const id of document.acceptanceIds) {
         if (!currentAcceptanceIds.has(id)) {
-            diagnostics.push(issue("error", "APPSPEC_CHANGE_ACCEPTANCE_NOT_CURRENT", `ChangeSpec 中的验收场景 ${id} 尚未进入当前 CapabilitySpec`, document.path));
+            diagnostics.push(issue("error", "APPSPEC_CHANGE_ACCEPTANCE_NOT_CURRENT", `ChangeSpec 中的验收场景 ${id} 尚未进入当前总纲或能力规格`, document.path));
         }
     }
 }
@@ -575,7 +665,7 @@ function validateRiskSections(document, diagnostics) {
         }
     }
 }
-function selectContext(collection, selector, diagnostics) {
+function selectBaseContext(collection, selector, diagnostics) {
     if (!selector) {
         return {
             primary: collection.app[0] || null,
@@ -585,6 +675,9 @@ function selectContext(collection, selector, diagnostics) {
             decisions: [],
         };
     }
+    const design = collection.designs.find(document => document.id === selector);
+    if (design)
+        return { primary: design, capabilities: [], activeChanges: [], archivedChanges: [], decisions: [] };
     const change = collection.activeChanges.find(document => document.id === selector);
     if (change) {
         const capabilityIds = new Set(change.references.capabilities);
@@ -640,12 +733,43 @@ function selectContext(collection, selector, diagnostics) {
         decisions: [],
     };
 }
+function selectContext(collection, selector, diagnostics) {
+    const base = selectBaseContext(collection, selector, diagnostics);
+    const designs = [];
+    const selected = { ...base, capabilities: [...base.capabilities], decisions: [...base.decisions], designs };
+    if (!selector)
+        return selected;
+    const available = [...collection.app, ...collection.capabilities, ...collection.decisions, ...collection.designs];
+    const queue = [base.primary, ...base.capabilities, ...base.decisions].filter((item) => !!item);
+    const seen = new Set();
+    for (let index = 0; index < queue.length; index++) {
+        const document = queue[index];
+        if (seen.has(document.id))
+            continue;
+        seen.add(document.id);
+        if (document.kind === 'design')
+            designs.push(document);
+        if (document.kind === 'capability' && !selected.capabilities.includes(document))
+            selected.capabilities.push(document);
+        if (document.kind === 'decision' && !selected.decisions.includes(document))
+            selected.decisions.push(document);
+        for (const id of document.references.documents) {
+            const target = available.find(item => item.id === id);
+            if (!target)
+                diagnostics.push(issue('error', 'APPSPEC_DESIGN_REFERENCE_UNKNOWN', `设计引用 ${id} 不存在；先恢复资料或修正引用`, document.path));
+            else if (!seen.has(id))
+                queue.push(target);
+        }
+    }
+    return selected;
+}
 function summarizeCollection(collection) {
     return {
         application: collection.app[0] ? summarize(collection.app[0]) : null,
         capabilities: collection.capabilities.map(summarize),
         activeChanges: collection.activeChanges.map(summarize),
         decisions: collection.decisions.map(summarize),
+        designs: collection.designs.map(summarize),
         history: collection.history.map(summarize),
     };
 }
@@ -657,6 +781,7 @@ function selectedDocuments(application, selected) {
         ...selected.activeChanges,
         ...selected.archivedChanges,
         ...selected.decisions,
+        ...selected.designs,
     ]);
 }
 function applyContextBudget(application, selected) {
@@ -680,6 +805,7 @@ function applyContextBudget(application, selected) {
         activeChanges: keep(selected.activeChanges),
         archivedChanges: keep(selected.archivedChanges),
         decisions: keep(selected.decisions),
+        designs: keep(selected.designs),
         contextBudget: {
             maximumBytes: APP_SPEC_LIMITS.maximumContextBytes,
             contentBytes,
@@ -735,20 +861,24 @@ function parseAppSpecDocument(root, path, kind, content, diagnostics) {
             ? CAPABILITY_ID
             : kind === "decision"
                 ? DECISION_ID
-                : CHANGE_ID;
+                : kind === "design" ? /^DES-[A-Z0-9]+(?:-[A-Z0-9]+)*$/ : CHANGE_ID;
     if (!pattern.test(id)) {
-        diagnostics.push(issue("error", "APPSPEC_DOCUMENT_ID_INVALID", `无效 ${kind} id: ${id}`, pointer));
+        diagnostics.push(issue("error", "APPSPEC_DOCUMENT_ID_INVALID", `无效 ${kind} id: ${id}${kind === 'decision' ? '；请使用 ADR- 加四位数字，可选大写字母/数字后缀，例如 ADR-0001 或 ADR-0001-DATA-OWNER，参见 docs appspec' : ''}`, pointer));
     }
     const status = String(frontMatter.metadata.status || "draft");
     const validStatuses = {
         app: ["active", "retired"],
         capability: ["draft", "active", "retired"],
         change: ["draft", "confirmed", "implementing", "verified", "released", "archived", "cancelled"],
+        design: ["draft", "confirmed", "superseded", "rejected"],
         decision: ["proposed", "accepted", "superseded", "rejected"],
     };
     if (!validStatuses[kind].includes(status)) {
         diagnostics.push(issue("error", "APPSPEC_STATUS_INVALID", `${kind} status=${status} 不受支持`, pointer));
     }
+    if (kind === 'design' && !['sources', 'product', 'journey', 'page', 'visual', 'permissions', 'architecture', 'review'].includes(String(frontMatter.metadata.type))) {
+        diagnostics.push(issue('error', 'APPSPEC_DESIGN_TYPE_INVALID', '设计资料需要明确 type，参见 docs product-design', pointer));
+    }
     if (kind === "change") {
         const currentSpec = String(frontMatter.metadata.currentSpec || "pending");
         if (!["pending", "merged", "not-applicable"].includes(currentSpec)) {
@@ -774,6 +904,7 @@ function parseAppSpecDocument(root, path, kind, content, diagnostics) {
             resources: metadataStrings(frontMatter.metadata, "resources"),
             actions: metadataStrings(frontMatter.metadata, "actions"),
             decisions: metadataStrings(frontMatter.metadata, "decisions"),
+            documents: metadataStrings(frontMatter.metadata, "documents"),
         },
         content,
     };
@@ -984,7 +1115,7 @@ status: active
 ---
 # ${appName}
 
-AppSpec 是可选的业务意图辅助层，不是发布门禁。资源、字段、权限和动作仍以
+本文件是当前有效设计的总纲与目录。新应用先完成产品发现、详细设计与实际确认，形成评审基线后再制定实施计划；按 docs product-design 在 AppSpec 中建立相关材料。正式变更关联 ChangeSpec；测试发布前核对设计与验收计划，生产晋级前核对实际验收。资源、字段、权限和动作的实现以
 \`openxiangda.config.ts\` 与实时编译合同为准。
 
 ## 业务目标
@@ -1001,14 +1132,34 @@ AppSpec 是可选的业务意图辅助层，不是发布门禁。资源、字段
 
 ### 不包含
 
+## 设计资料目录
+
+<!-- 引用产品、旅程、页面、视觉、权限、架构与评审的稳定 ID；详细规则各有唯一归属。 -->
+
 ## 能力目录
 
-<!-- 复杂业务再在 capabilities/ 下增加 CAP-*；小应用可以只维护本文件。 -->
+<!-- 复杂业务再在 capabilities/ 下增加 CAP-*；简单应用的稳定规则直接写在本文件。 -->
 
 ## 术语
 
 ## 跨能力约束
 
+## 架构与数据关系
+
+<!-- 写明领域边界、核心模型关系、平台能力与自定义动作的归属、状态转换与不变量。 -->
+
+## 业务任务与页面
+
+<!-- 按用户任务规划管理端、PC、移动入口与数据关系；辅助表不必有页面。 -->
+
+## 权限矩阵与确认
+
+<!-- 记录角色、页面、操作、行范围、字段和多角色组合；写明需求依据与未明确的边界。 -->
+
+## 性能与容量预算
+
+<!-- 记录数据量及增长、并发、分页与索引、请求次数、延迟目标和测量口径；区分估算、目标与实测。 -->
+
 ## 未确认问题
 
 - 无。
@@ -1040,9 +1191,9 @@ actions: ${JSON.stringify(input.actions)}
 
 #### AC-DOMAIN-001-01 正向或反向场景
 
-- Given 已知前置条件
-- When 用户或系统执行动作
-- Then 观察到明确结果
+- 前置：已知条件
+- 操作：用户或系统执行动作
+- 预期：观察到明确结果
 -->
 
 ## 状态与异常
@@ -1072,6 +1223,22 @@ decisions: []
 
 ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->"}
 
+## 需求依据
+
+<!-- 记录用户原始需求或当前规格引用、已明确规则与假设；不代替用户编造确认。 -->
+
+## 方案与影响
+
+<!-- 说明能力所有者、模型/页面/权限/状态影响，引用已有架构决定。 -->
+
+## 任务与实现
+
+<!-- 用稳定需求 ID 关联实施任务、源码/声明路径与验收场景；实施后更新实际结果。 -->
+
+## 性能与容量预算
+
+<!-- 引用总纲默认预算，或记录本次数据规模、查询/分页/批量/超时/并发和延迟目标。 -->
+
 ## 变更
 
 - ADDED：
@@ -1084,6 +1251,8 @@ ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->
 - [ ] 一个可观察的正向结果
 - [ ] 需要时补充拒绝、异常或权限反例
 
+<!-- 使用 #### AC-领域-编号 给场景稳定 ID；写明角色、前置、操作、预期和拒绝路径。测试部署后再记录实际观察。 -->
+
 ## 数据与权限
 
 - 无，或说明资源、字段、角色和数据范围变化。
@@ -1100,6 +1269,14 @@ ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->
 
 - L3 如涉及 ADR，在 front matter 的 decisions 中引用。
 
+## 验证与发布
+
+<!-- 记录检查结果、源码提交、测试/生产运行 ID、包摘要、验收报告路径、未覆盖项和恢复入口。区分本地通过、部署成功与业务验收。 -->
+
+## 交接
+
+<!-- 写明持续有效规则已更新的位置、剩余问题与下一步；无需复制当前规格全文。 -->
+
 ## 未确认问题
 
 - 无。
@@ -1170,8 +1347,8 @@ function issue(severity, code, message, path) {
         path,
         retryable: false,
         remediation: severity === "error"
-            ? "修正 AppSpec 后重新运行 openxiangda spec check；普通应用 check/deploy 不受阻断"
-            : "按当前变更风险决定是否补充；AppSpec 质量建议不阻断应用交付",
+            ? "修正记录后运行 openxiangda spec check；普通 check 可继续，正式发布按阶段核对"
+            : "按实际变化范围补充；确定性缺口会在相应发布阶段核对",
     };
 }
 function summarize(document) {
@@ -1198,9 +1375,11 @@ function withoutHtmlComments(content) {
 }
 function validateMetadata(kind, metadata, pointer, diagnostics) {
     const allowed = {
-        app: new Set(["schema", "app", "title", "status"]),
+        app: new Set(["schema", "app", "title", "status", "documents"]),
+        design: new Set(["schema", "id", "title", "status", "type", "documents", "scope", "baselineDigest", "confirmedBy", "confirmedAt", "confirmationSource", "capabilities", "requirements", "resources", "actions", "decisions"]),
         capability: new Set([
             "schema",
+            "documents",
             "id",
             "title",
             "status",
@@ -1209,6 +1388,7 @@ function validateMetadata(kind, metadata, pointer, diagnostics) {
         ]),
         change: new Set([
             "schema",
+            "documents",
             "id",
             "title",
             "status",
@@ -1224,6 +1404,7 @@ function validateMetadata(kind, metadata, pointer, diagnostics) {
         ]),
         decision: new Set([
             "schema",
+            "documents",
             "id",
             "title",
             "status",