openxiangda-devkit-core 2.0.0-alpha.115 → 2.0.0-alpha.118

package/dist/app-spec.d.ts

@@ -4,7 +4,7 @@ export declare const APP_SPEC_SCHEMAS: {
     readonly capability: "openxiangda.appspec/capability/v1";
     readonly change: "openxiangda.appspec/change/v1";
     readonly decision: "openxiangda.appspec/decision/v1";
-    readonly context: "openxiangda.appspec/context/v2";
+    readonly context: "openxiangda.appspec/context/v3";
 };
 export declare const APP_SPEC_LIMITS: {
     readonly maximumFiles: 128;
@@ -57,8 +57,8 @@ export interface AppSpecDocumentSummary {
 export interface AppSpecContext {
     schemaVersion: typeof APP_SPEC_SCHEMAS.context;
     enabled: boolean;
-    mode: "advisory";
-    releaseGate: false;
+    mode: "guided";
+    releaseGate: true;
     root: "appspec";
     selector: string | null;
     contract: AppSpecContractIndex;
@@ -74,6 +74,12 @@ export interface AppSpecContext {
     activeChanges: AppSpecDocument[];
     archivedChanges: AppSpecDocument[];
     decisions: AppSpecDocument[];
+    historyPage: {
+        offset: number;
+        limit: number;
+        total: number;
+        nextOffset: number | null;
+    };
     contextBudget: {
         maximumBytes: number;
         contentBytes: number;
@@ -123,7 +129,7 @@ export interface CloseAppSpecChangeInput {
     contract: AppSpecContractIndex;
 }
 export declare function initializeAppSpec(input: InitializeAppSpecInput): {
-    schemaVersion: "openxiangda.appspec/context/v2";
+    schemaVersion: "openxiangda.appspec/context/v3";
     enabled: boolean;
     advisory: boolean;
     releaseGate: boolean;
@@ -131,14 +137,14 @@ export declare function initializeAppSpec(input: InitializeAppSpecInput): {
     existing: string[];
 };
 export declare function createAppSpecCapability(input: CreateAppSpecCapabilityInput): {
-    schemaVersion: "openxiangda.appspec/context/v2";
+    schemaVersion: "openxiangda.appspec/context/v3";
     enabled: boolean;
     advisory: boolean;
     releaseGate: boolean;
     created: string;
 };
 export declare function createAppSpecChange(input: CreateAppSpecChangeInput): {
-    schemaVersion: "openxiangda.appspec/context/v2";
+    schemaVersion: "openxiangda.appspec/context/v3";
     enabled: boolean;
     advisory: boolean;
     releaseGate: boolean;
@@ -147,7 +153,7 @@ export declare function createAppSpecChange(input: CreateAppSpecChangeInput): {
     status: string;
 };
 export declare function closeAppSpecChange(input: CloseAppSpecChangeInput): {
-    schemaVersion: "openxiangda.appspec/context/v2";
+    schemaVersion: "openxiangda.appspec/context/v3";
     enabled: boolean;
     advisory: boolean;
     releaseGate: boolean;
@@ -156,7 +162,7 @@ export declare function closeAppSpecChange(input: CloseAppSpecChangeInput): {
     converged: boolean;
     diagnostics: Diagnostic[];
 } | {
-    schemaVersion: "openxiangda.appspec/context/v2";
+    schemaVersion: "openxiangda.appspec/context/v3";
     enabled: boolean;
     advisory: boolean;
     releaseGate: boolean;
@@ -165,7 +171,7 @@ export declare function closeAppSpecChange(input: CloseAppSpecChangeInput): {
     converged: boolean;
     diagnostics: Diagnostic[];
 };
-export declare function inspectAppSpec(root: string, contract: AppSpecContractIndex, selector?: string): AppSpecContext;
+export declare function inspectAppSpec(root: string, contract: AppSpecContractIndex, selector?: string, historyOffset?: number): AppSpecContext;
 export declare function advisoryAppSpecDiagnostics(diagnostics: Diagnostic[]): {
     severity: "info" | "warning";
     remediation: string;
@@ -179,10 +185,16 @@ export declare function advisoryAppSpecDiagnostics(diagnostics: Diagnostic[]): {
 }[];
 export declare function summarizeAppSpecContext(context: AppSpecContext): {
     enabled: boolean;
-    mode: "advisory";
-    releaseGate: false;
+    mode: "guided";
+    releaseGate: true;
     workspaceDigest: string | null;
     selectionDigest: string | null;
+    historyPage: {
+        offset: number;
+        limit: number;
+        total: number;
+        nextOffset: number | null;
+    };
     contextBudget: {
         maximumBytes: number;
         contentBytes: number;

package/dist/app-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-spec.d.ts","sourceRoot":"","sources":["../src/app-spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-spec.d.ts","sourceRoot":"","sources":["../src/app-spec.ts"],"names":[],"mappings":"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"}

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,7 @@ 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",
+    context: "openxiangda.appspec/context/v3",
 };
 export const APP_SPEC_LIMITS = {
     maximumFiles: 128,
@@ -49,8 +49,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 +72,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 +82,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 +105,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 +174,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 +189,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 +206,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);
@@ -215,7 +218,7 @@ export function inspectAppSpec(root, contract, selector) {
         ...collection.decisions,
     ];
     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 +230,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 +241,17 @@ export function inspectAppSpec(root, contract, selector) {
         activeChanges: budgeted.activeChanges,
         archivedChanges: budgeted.archivedChanges,
         decisions: budgeted.decisions,
+        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,
+            requirements: unique([...collection.app, ...collection.capabilities].flatMap(document => document.requirementIds)).length,
+            acceptanceScenarios: unique([...collection.app, ...collection.capabilities].flatMap(document => document.acceptanceIds)).length,
         },
         workspaceDigest,
         selectionDigest,
@@ -259,7 +263,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 +273,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 +290,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,
@@ -302,6 +307,7 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
         activeChanges: [],
         archivedChanges: [],
         decisions: [],
+        historyPage: { offset: 0, limit: 50, total: 0, nextOffset: null },
         contextBudget: {
             maximumBytes: APP_SPEC_LIMITS.maximumContextBytes,
             contentBytes: 0,
@@ -323,7 +329,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: [],
@@ -332,6 +386,7 @@ function collectDocuments(root, diagnostics) {
         history: [],
         decisions: [],
         bytes: 0,
+        historyPage: { offset: historyOffset, limit: 50, total: 0, nextOffset: null },
     };
     const candidates = [];
     if (existsSync(paths.app))
@@ -342,10 +397,6 @@ 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",
@@ -354,7 +405,11 @@ function collectDocuments(root, diagnostics) {
         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 +426,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;
@@ -412,11 +485,11 @@ function validateDocuments(collection, contract, diagnostics) {
         }
     }
     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.app, ...collection.capabilities].flatMap(document => document.requirementIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_REQUIREMENT_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics([...collection.app, ...collection.capabilities].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].flatMap(document => document.requirementIds));
+    const acceptanceIds = new Set([...collection.app, ...collection.capabilities].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 +509,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 +533,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].flatMap(item => item.requirementIds));
+    const acceptanceIds = new Set([...collection.app, ...collection.capabilities].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 +555,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].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 +573,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].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].filter(item => item.acceptanceIds.includes(id));
         if (matches.length > 1) {
             diagnostics.push(issue("error", "APPSPEC_ACCEPTANCE_ID_DUPLICATED", `关闭前必须消除验收场景 ${id} 的重复定义`, document.path));
         }
@@ -514,12 +591,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));
         }
     }
 }
@@ -984,7 +1061,7 @@ status: active
 ---
 # ${appName}
 
-AppSpec 是可选的业务意图辅助层，不是发布门禁。资源、字段、权限和动作仍以
+本文件保存当前有效目标与设计约束。正式变更关联 ChangeSpec；测试发布前核对设计与验收计划，生产晋级前核对实际验收。资源、字段、权限和动作的实现以
 \`openxiangda.config.ts\` 与实时编译合同为准。
 
 ## 业务目标
@@ -1003,12 +1080,28 @@ AppSpec 是可选的业务意图辅助层，不是发布门禁。资源、字段
 
 ## 能力目录
 
-<!-- 复杂业务再在 capabilities/ 下增加 CAP-*；小应用可以只维护本文件。 -->
+<!-- 复杂业务再在 capabilities/ 下增加 CAP-*；简单应用的稳定规则直接写在本文件。 -->
 
 ## 术语
 
 ## 跨能力约束
 
+## 架构与数据关系
+
+<!-- 写明领域边界、核心模型关系、平台能力与自定义动作的归属、状态转换与不变量。 -->
+
+## 业务任务与页面
+
+<!-- 按用户任务规划管理端、PC、移动入口与数据关系；辅助表不必有页面。 -->
+
+## 权限矩阵与确认
+
+<!-- 记录角色、页面、操作、行范围、字段和多角色组合；写明需求依据与未明确的边界。 -->
+
+## 性能与容量预算
+
+<!-- 记录数据量及增长、并发、分页与索引、请求次数、延迟目标和测量口径；区分估算、目标与实测。 -->
+
 ## 未确认问题
 
 - 无。
@@ -1040,9 +1133,9 @@ actions: ${JSON.stringify(input.actions)}
 
 #### AC-DOMAIN-001-01 正向或反向场景
 
-- Given 已知前置条件
-- When 用户或系统执行动作
-- Then 观察到明确结果
+- 前置：已知条件
+- 操作：用户或系统执行动作
+- 预期：观察到明确结果
 -->
 
 ## 状态与异常
@@ -1072,6 +1165,22 @@ decisions: []
 
 ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->"}
 
+## 需求依据
+
+<!-- 记录用户原始需求或当前规格引用、已明确规则与假设；不代替用户编造确认。 -->
+
+## 方案与影响
+
+<!-- 说明能力所有者、模型/页面/权限/状态影响，引用已有架构决定。 -->
+
+## 任务与实现
+
+<!-- 用稳定需求 ID 关联实施任务、源码/声明路径与验收场景；实施后更新实际结果。 -->
+
+## 性能与容量预算
+
+<!-- 引用总纲默认预算，或记录本次数据规模、查询/分页/批量/超时/并发和延迟目标。 -->
+
 ## 变更
 
 - ADDED：
@@ -1084,6 +1193,8 @@ ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->
 - [ ] 一个可观察的正向结果
 - [ ] 需要时补充拒绝、异常或权限反例
 
+<!-- 使用 #### AC-领域-编号 给场景稳定 ID；写明角色、前置、操作、预期和拒绝路径。测试部署后再记录实际观察。 -->
+
 ## 数据与权限
 
 - 无，或说明资源、字段、角色和数据范围变化。
@@ -1100,6 +1211,14 @@ ${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->
 
 - L3 如涉及 ADR，在 front matter 的 decisions 中引用。
 
+## 验证与发布
+
+<!-- 记录检查结果、源码提交、测试/生产运行 ID、包摘要、验收报告路径、未覆盖项和恢复入口。区分本地通过、部署成功与业务验收。 -->
+
+## 交接
+
+<!-- 写明持续有效规则已更新的位置、剩余问题与下一步；无需复制当前规格全文。 -->
+
 ## 未确认问题
 
 - 无。
@@ -1170,8 +1289,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) {