create-yss-spec 3.5.6 → 3.5.9

package/template/.agents/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs

@@ -6,6 +6,7 @@ import process from "node:process";
 import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecord } from "../../../../scripts/lib/approval-record.mjs";
+import { approvalExpectationForBoundAsset } from "../../../../scripts/lib/approval-consumption.mjs";
 import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.mjs";
 import { parseAsset, validateAssetStructure } from '../../../../scripts/lib/structured-assets.mjs';
 
@@ -51,7 +52,7 @@ function requireArray(object, field, path, errors, min = 0, itemKind = "string")
   if (field in object && list(object[field]) && itemKind === "string") object[field].forEach((item, index) => { if (!nonEmpty(item)) errors.push(`${path}.${field}[${index}] 必须是非空字符串`); });
 }
 
-function validate(data, contextRoot) {
+function validate(data, contextRoot, currentRef) {
   validateAssetStructure(data, 'domain-strategy');
   const errors = [];
   if (data?.traceability_version !== undefined) { try { extractTraceability(data); } catch(error) { errors.push(error.message); } }
@@ -199,9 +200,11 @@ function validate(data, contextRoot) {
     if (contexts.some((context) => context.status !== "confirmed")) errors.push("approved 合同要求所有上下文 status=confirmed");
     if (approval.current_version !== data.domain_version) errors.push("approval.current_version 必须等于 domain_version");
     try {
-      const approvalPath = resolveApprovalRef(approval.approval_ref);
-      const record = loadApprovalRecord(approvalPath, "check.domain-strategy-approved");
-      validateApprovalRecord(record, { requireApproved: true });
+      const options = { root: contextRoot, review_package: false };
+      const approvalPath = resolveApprovalRef(approval.approval_ref, currentRef, options);
+      const expected = approvalExpectationForBoundAsset("check.domain-strategy-approved", { ref: currentRef }, options);
+      const record = loadApprovalRecord(approvalPath, "check.domain-strategy-approved", options);
+      validateApprovalRecord(record, { ...options, requireApproved: true, expected });
       if (record.gate_id !== "check.domain-strategy-approved") errors.push("approval.approval_ref 的 gate_id 必须为 check.domain-strategy-approved");
       if (record.role_id !== approval.approver) errors.push("approval.approver 必须与会签记录 role_id 一致");
     } catch (error) { errors.push(`approval.approval_ref 会签记录无效: ${error.message}`); }
@@ -218,7 +221,7 @@ else {
     assertCurrentAssetReference(values.root, path.relative(path.resolve(values.root), path.resolve(file)));
     const source = await readFile(file, "utf8");
     {
-      const errors = validate(parseAsset(source, file), values.root);
+      const errors = validate(parseAsset(source, file), values.root, path.resolve(file));
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }

package/template/.agents/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs

@@ -8,6 +8,7 @@ import process from "node:process";
 import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecord } from "../../../../scripts/lib/approval-record.mjs";
+import { approvalExpectationForBoundAsset } from "../../../../scripts/lib/approval-consumption.mjs";
 import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.mjs";
 import { parseAsset, validateAssetStructure } from '../../../../scripts/lib/structured-assets.mjs';
 
@@ -27,7 +28,7 @@ function unique(items, label, errors) { const seen = new Set(); for (const item
 function canonical(value) { if (Array.isArray(value)) return value.map(canonical); if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])); return value; }
 function digest(value) { return `sha256:${createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex")}`; }
 
-async function validate(data, contextRoot) {
+async function validate(data, contextRoot, currentRef) {
   validateAssetStructure(data, 'stage-decision-package');
   const errors = [];
   if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
@@ -132,9 +133,11 @@ async function validate(data, contextRoot) {
   if (unresolved.some((item) => item?.type === "blocker") && data.status === "approved") errors.push("存在 blocker 未决项时不得 approved");
   if (data.status === "approved" && nonEmpty(approval.approval_ref)) {
     try {
-      const approvalPath = resolveApprovalRef(approval.approval_ref);
-      const record = loadApprovalRecord(approvalPath, "check.stage-decision-package-approved");
-      validateApprovalRecord(record, { requireApproved: true });
+      const options = { root: contextRoot, review_package: false };
+      const approvalPath = resolveApprovalRef(approval.approval_ref, currentRef, options);
+      const expected = approvalExpectationForBoundAsset("check.stage-decision-package-approved", { ref: currentRef }, options);
+      const record = loadApprovalRecord(approvalPath, "check.stage-decision-package-approved", options);
+      validateApprovalRecord(record, { ...options, requireApproved: true, expected });
       if (record.gate_id !== "check.stage-decision-package-approved") errors.push("approval_ref 的 gate_id 必须为 check.stage-decision-package-approved");
       if (record.role_id !== approval.approver) errors.push("approval.approver 必须与会签记录 role_id 一致");
     } catch (error) { errors.push(`approval_ref 会签记录无效: ${error.message}`); }
@@ -151,7 +154,7 @@ else {
     assertCurrentAssetReference(values.root, path.relative(path.resolve(values.root), path.resolve(file)));
     const source = await readFile(file, "utf8");
     {
-      const errors = await validate(parseAsset(source, file), values.root);
+      const errors = await validate(parseAsset(source, file), values.root, path.resolve(file));
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }

package/template/.agents/skills/yss-stage-decision/tests/run-scenarios.mjs

@@ -35,6 +35,40 @@ function parseYaml(source) {
   return document.toJS({ maxAliasCount: 0 });
 }
 
+const hashBytes = source => createHash("sha256").update(source).digest("hex");
+// This independent, test-only consumer context is never reconstructed from a record.
+function bindSource(source, file, approvalRef, contextDigest) {
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new Error(document.errors[0].message);
+  document.setIn(["approval", "approval_ref"], approvalRef);
+  document.setIn(["approval", "persisted_ref"], file);
+  document.set("approval_context", {
+    subject_ref: file,
+    approval_scope: ["feature.supplier-admission"],
+    basis: [{ ref: "CONTEXT.md", digest: contextDigest }],
+    drafter_principal_ref: "instance:role.requirements-manager"
+  });
+  return document.toString();
+}
+
+function fixtureApproval(gateId, file, source, contextDigest) {
+  return {
+    schema_version: 1, gate_id: gateId, decision: "approved", actor_kind: "digital-human",
+    role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager",
+    drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager",
+    subject_ref: file, subject_digest: hashBytes(source), approval_scope: ["feature.supplier-admission"],
+    basis: [{ ref: "CONTEXT.md", digest: contextDigest }], evidence_refs: [file, "CONTEXT.md"]
+  };
+}
+
+async function writeApprovedFixture(source, file, gateId, contextDigest) {
+  const approvalRef = `${file}.approval.json`;
+  const bound = bindSource(source, file, approvalRef, contextDigest);
+  await writeFile(file, bound);
+  await writeFile(approvalRef, JSON.stringify(fixtureApproval(gateId, file, bound, contextDigest), null, 2));
+  return bound;
+}
+
 function toV2Domain(source) {
   const value = structuredClone(parseYaml(source));
   value.schema_version = 2;
@@ -115,18 +149,18 @@ try {
   if (contextResult.status !== 0) throw new Error(`context fixture should pass: ${contextResult.stderr}`);
   const context = JSON.parse(contextResult.stdout);
 
-  const domainSource = (await readFile(validTemplate, "utf8"))
+  const domainTemplateSource = (await readFile(validTemplate, "utf8"))
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest);
   const domainFile = join(temporaryRoot, "domain-strategy.yaml");
-  await writeFile(domainFile, domainSource);
+  const contextDigest = hashBytes(contextSource);
+  const domainSource = await writeApprovedFixture(domainTemplateSource, domainFile, "check.domain-strategy-approved", contextDigest);
   const pass = run(validator, domainFile, temporaryRoot);
   if (pass.status !== 0) throw new Error(`valid v3 fixture should pass: ${pass.stderr}`);
 
   const v2Domain = toV2Domain(domainSource);
-  const v2DomainSource = JSON.stringify(v2Domain, null, 2);
   const v2DomainFile = join(temporaryRoot, "domain-strategy-v2.yaml");
-  await writeFile(v2DomainFile, v2DomainSource);
+  const v2DomainSource = await writeApprovedFixture(JSON.stringify(v2Domain, null, 2), v2DomainFile, "check.domain-strategy-approved", contextDigest);
   const v2Pass = run(validator, v2DomainFile, temporaryRoot);
   if (v2Pass.status !== 0) throw new Error(`read-only v2 fixture should pass: ${v2Pass.stderr}`);
 
@@ -192,12 +226,12 @@ try {
   await writeFile(unknownContext, domainSource.replace("to_context: ComplianceReview", "to_context: UnknownContext"));
   expectBlocked(run(validator, unknownContext, temporaryRoot), /未引用已声明上下文|未在领域战略中登记/, "unknown context");
 
-  const packageSource = (await readFile(validPackageTemplate, "utf8"))
+  const packageTemplateSource = (await readFile(validPackageTemplate, "utf8"))
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest)
     .replace("<domain-strategy-digest>", digestYaml(domainSource));
   const packageFile = join(temporaryRoot, "stage-decision.yaml");
-  await writeFile(packageFile, packageSource);
+  const packageSource = await writeApprovedFixture(packageTemplateSource, packageFile, "check.stage-decision-package-approved", contextDigest);
   const packagePass = run(packageValidator, packageFile, temporaryRoot);
   if (packagePass.status !== 0) throw new Error(`valid v3 stage decision package should pass: ${packagePass.stderr}`);
   for (const format of ['yaml', 'json']) {
@@ -215,16 +249,14 @@ try {
 
   const bundleFile = join(temporaryRoot, "plan-review-bundle.json");
   const bundledDomainValue = parseYaml(domainSource);
-  bundledDomainValue.approval.approval_ref = bundleFile;
-  const bundledDomainSource = JSON.stringify(bundledDomainValue, null, 2);
   const bundledDomainFile = join(temporaryRoot, "domain-strategy-bundled.yaml");
+  const bundledDomainSource = bindSource(JSON.stringify(bundledDomainValue, null, 2), bundledDomainFile, bundleFile, contextDigest);
   await writeFile(bundledDomainFile, bundledDomainSource);
   const bundledPackageValue = parseYaml(packageSource);
   bundledPackageValue.domain_strategy_ref.persisted_ref = "domain-strategy-bundled.yaml";
   bundledPackageValue.domain_strategy_ref.digest = digestYaml(bundledDomainSource);
-  bundledPackageValue.approval.approval_ref = bundleFile;
-  const bundledPackageSource = JSON.stringify(bundledPackageValue, null, 2);
   const bundledPackageFile = join(temporaryRoot, "stage-decision-bundled.yaml");
+  const bundledPackageSource = bindSource(JSON.stringify(bundledPackageValue, null, 2), bundledPackageFile, bundleFile, contextDigest);
   await writeFile(bundledPackageFile, bundledPackageSource);
   await writeFile(bundleFile, JSON.stringify({
     schema_version: 1,
@@ -237,8 +269,8 @@ try {
     runtime_id: "runtime.generic",
     principal_ref: "instance:role.product-manager",
     reviews: [
-      { schema_version: 1, gate_id: "check.domain-strategy-approved", decision: "approved", actor_kind: "digital-human", role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager", drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager", subject_ref: bundledDomainFile, subject_digest: digestYaml(bundledDomainSource).slice(7), approval_scope: ["feature.supplier-admission"], evidence_refs: [bundledDomainFile] },
-      { schema_version: 1, gate_id: "check.stage-decision-package-approved", decision: "approved", actor_kind: "digital-human", role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager", drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager", subject_ref: bundledPackageFile, subject_digest: digestYaml(bundledPackageSource).slice(7), approval_scope: ["feature.supplier-admission"], evidence_refs: [bundledPackageFile] }
+      fixtureApproval("check.domain-strategy-approved", bundledDomainFile, bundledDomainSource, contextDigest),
+      fixtureApproval("check.stage-decision-package-approved", bundledPackageFile, bundledPackageSource, contextDigest)
     ]
   }, null, 2));
   const bundledDomainPass = run(validator, bundledDomainFile, temporaryRoot);
@@ -246,9 +278,47 @@ try {
   const bundledPackagePass = run(packageValidator, bundledPackageFile, temporaryRoot);
   if (bundledPackagePass.status !== 0) throw new Error(`stage decision should select its conclusion from Plan review-bundle: ${bundledPackagePass.stderr}`);
 
+  // Both consumers reject coherent record edits unless independently current inputs match.
+  for (const [kind, command, source, gateId] of [
+    ["domain", validator, domainSource, "check.domain-strategy-approved"],
+    ["stage", packageValidator, packageSource, "check.stage-decision-package-approved"]
+  ]) {
+    for (const [label, mutateAsset, mutateRecord, pattern] of [
+      ["missing-context", value => { delete value.approval_context; }, null, /APPROVAL_CONTEXT_REQUIRED/],
+      ["context-missing-basis", value => { value.approval_context.basis = []; }, null, /APPROVAL_CONTEXT_REQUIRED/],
+      ["context-stale-basis", value => { value.approval_context.basis[0].digest = "0".repeat(64); }, null, /当前消费上下文.*证据过期/],
+      ["context-missing-drafter", value => { delete value.approval_context.drafter_principal_ref; }, null, /独立起草者来源/],
+      ["context-drafter", value => { value.approval_context.drafter_principal_ref = "instance:other-drafter"; }, null, /起草者身份.*不匹配/],
+      ["context-scope", value => { value.approval_context.approval_scope.push("feature.other"); }, null, /审查范围不匹配/],
+      ["record-subject", null, record => { record.subject_ref = domainFile; }, /审查对象不匹配/],
+      ["record-scope", null, record => { record.approval_scope.push("feature.other"); }, /审查范围不匹配/],
+      ["record-drafter", null, record => { record.drafter_principal_ref = "instance:other-drafter"; }, /起草者身份.*不匹配/],
+      ["record-self-sign", null, record => { record.principal_ref = record.drafter_principal_ref; }, /起草者自签/],
+      ["record-missing-basis", null, record => { record.basis = []; }, /批准记录.*缺少当前证据摘要/],
+      ["record-stale-basis", null, record => { record.basis[0].digest = "0".repeat(64); }, /批准记录.*证据过期/],
+      ["record-semantic-digest", null, record => { record.subject_digest = digestYaml(record.fixtureSource).slice(7); }, /审查资产摘要不匹配/]
+    ]) {
+      const file = join(temporaryRoot, `${kind}-${label}.yaml`);
+      let bound = await writeApprovedFixture(source, file, gateId, contextDigest);
+      if (mutateAsset) {
+        const value = parseYaml(bound); mutateAsset(value);
+        bound = JSON.stringify(value, null, 2);
+        await writeFile(file, bound);
+      }
+      const record = fixtureApproval(gateId, file, bound, contextDigest);
+      // Keep the raw bytes current even for consumer-context changes: an unrelated stale
+      // subject must not be what makes the current-context negative pass.
+      if (mutateRecord) {
+        record.fixtureSource = bound; mutateRecord(record); delete record.fixtureSource;
+      }
+      await writeFile(`${file}.approval.json`, JSON.stringify(record, null, 2));
+      expectBlocked(run(command, file, temporaryRoot), pattern, `${kind} ${label}`);
+    }
+  }
+
   const v2Stage = toV2Stage(packageSource, digestYaml(v2DomainSource));
   const v2StageFile = join(temporaryRoot, "stage-decision-v2.yaml");
-  await writeFile(v2StageFile, JSON.stringify(v2Stage, null, 2));
+  await writeApprovedFixture(JSON.stringify(v2Stage, null, 2), v2StageFile, "check.stage-decision-package-approved", contextDigest);
   const v2StagePass = run(packageValidator, v2StageFile, temporaryRoot);
   if (v2StagePass.status !== 0) throw new Error(`read-only v2 stage decision package should pass: ${v2StagePass.stderr}`);
 

package/template/.agents/skills/yss-tactical-design/SKILL.md

@@ -34,7 +34,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 批准且版本当前的战术设计合同由 `Slice Implementation Contract` 引用，再由 `yss-domain` 使用 `behavior-tdd` 实现。`yss-domain` 不得静默重新定义聚合或不变量；发现新的 API、状态、数据或架构影响时必须返回 `new_impacts` / `drift` 并重新路由。
 
-合同、Schema、校验规则和示例见 `references/`；使用 `scripts/validate-tactical-design.mjs` 做只读验证。该 skill 不生成 Java、Repository、Controller、DTO、OpenAPI Freeze、实现 Ticket 或生产代码。
+起草 DDD `design` 时读取 [战术合同](references/tactical-design-contract.md)，按 [验证规则](references/validation-rules.md) 执行 `scripts/validate-tactical-design.mjs` 的只读校验；需要正文结构时读取 [输出模板](references/output-template.md)，不批量加载整个 references 目录。该 Skill 不生成 Java、Repository、Controller、DTO、OpenAPI Freeze、实现 Ticket 或生产代码。
 
 ## 战略交接快照包
 

package/template/.agents/skills/yss-tactical-design/references/output-template.md

@@ -5,7 +5,7 @@ owner: ai
 
 # <功能名称> Tactical DDD Design
 
-仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。MVC 使用 `yss-technical-design` 的 `layered-mvc` 分支。
+仅用于已确认 domain-driven 分支的阅读视图；引用 Technical Design Contract v2 的 design，不复制共同输入与审批状态。交接来源及可接受版本按 [输入合同](tactical-design-contract.md) 核对并绑定实际 ref/version/digest。MVC 使用 `yss-technical-design` 的 `layered-mvc` 分支。
 
 ## 上游引用
 
@@ -13,8 +13,8 @@ owner: ai
 |---|---|---|---|
 | Spec |  |  |  |
 | Strategic DDD |  |  |  |
-| Strategic Design Handoff v3 |  |  |  |
-| Visual Baseline Bundle v1 |  |  |  |
+| Strategic Design Handoff / 交付包（适用时） |  |  |  |
+| 原型或 existing UI baseline（按交接来源） |  |  |  |
 | Strategic Context Import / Context Reconciliation |  |  |  |
 | 状态矩阵 |  |  |  |
 | OpenAPI / 无 API 影响记录 |  |  |  |

package/template/.agents/skills/yss-tactical-design/references/tactical-design-contract.md

@@ -2,7 +2,7 @@
 
 ## 输入
 
-必须引用批准且版本当前的 Spec、功能架构、战略 DDD、原型状态矩阵、OpenAPI Draft / Freeze（或无 API 影响记录）、ADR 和工程约束。来自 Strategic Design Handoff 时，额外要求 v3 交接包、`strategic_context_import_ref` 和目标仓 `context_reconciliation_ref`；目标根 `CONTEXT.md` 未完成增量对账前返回 `blocked`。所有引用都必须带版本或 digest；不可读或过期引用返回 `blocked` / `stale`。
+必须引用批准且版本当前的 Spec、功能架构、战略 DDD、适用 UI 状态矩阵、OpenAPI Draft / Freeze（或无 API 影响记录）、ADR 和工程约束。来自 Strategic Design Handoff 时，按仓库 `.template-spec/process/strategic-handoff-package.md` 的版本与消费者规则绑定交接包、`strategic_context_import_ref` 和目标仓 `context_reconciliation_ref`；历史 v3/v4 只按冻结 schema 兼容读取，新交付使用 v5。原型或 existing UI baseline 须符合该包的来源分支；目标根 `CONTEXT.md` 未完成增量对账前返回 `blocked`。所有引用都必须带版本或 digest；不可读或过期引用返回 `blocked` / `stale`。
 
 ## 输出
 

package/template/.agents/skills/yss-technical-design/SKILL.md

@@ -9,17 +9,18 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+## 文档输出
 
-## 文档写作
-
-起草或修订技术设计解释正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+起草或修订技术设计解释正文时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引。作用域仅限当前产物，分支派发传递条件及引用；结构化合同保持原 schema 和验证要求。
 
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。
 
-按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `.template-spec/agents/backend-architecture-profiles.md`。
+按项目绑定架构来源及摘要，架构族只允许 `domain-driven` 与 `layered-mvc`；不从目录推断或默认架构、Spring Boot 版本。具体 Profile 与模块边界消费技能注册表及 `.template-spec/agents/backend-architecture-profiles.md`。
+
+- 新工程先通过 `gate.backend-architecture-platform-approved`：展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java，用户在同一次决定确认架构与平台。决定持久化到 `scaffold-architecture-decisions.yaml`，设计与后续脚手架消费同一决定。
+- 既有工程核验并沿用当前登记架构及固定工程基线/POM 的实际 Spring Boot；该门禁记录带依据的 `not-applicable`，不重复询问。架构转换或平台升级单独立项。
 
 - `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
 - `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `.template-spec/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。

package/template/.agents/skills/yss-ui/SKILL.md

@@ -22,7 +22,11 @@ description: "选择和核验 YSS Vue 生产页面组件及 Ant Design Vue 兼
 
 ## 2. 执行前版本预检
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时：
+
+- 按 `.template-spec/process/frontend-backend-delivery.md` 核验战略与后端联合交付；缺任一输入只能诊断和回交。
+- 输入通过后准备计划 / 合同；正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。
+- 接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 进入实现前从前端工程根目录执行：
 
@@ -32,6 +36,8 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
 
+本次输入还包括批准合同、页面 / 交互范围和实际适用的专项技能；UI 切片使用已校验的 `frontend_implementation_plan`，实现后补 `frontend_implementation_verification`。输入缺失、摘要漂移或组件事实无法确认时，停止受影响的实现并回交原所有者。
+
 产品设计使用的 Antdv Next 或 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止把原型 props、events、slots、hook 或组件写法当作生产合同。原型统一使用 HTML/CSS/JavaScript；原型阶段不得调用本技能。只有进入前端实现计划、已批准切片的生产实现或实现还原验证后，才从目标 lockfile、类型、本地文档和既有用法取得真实组件事实。
 
 ## 3. 组件选型门禁

package/template/.agents/skills/yss-ui/assets/docs/guide/gitlab-ci-integration.md

@@ -162,5 +162,5 @@ git push -f origin dev
 
 ## 相关文档
 
-- [发版工作流指南](./guide/release-workflow.md)
-- [Commit 规范说明](./guide/release-workflow.md#-commit-message-规范必须遵守)
+- [发版工作流指南](./release-workflow.md)
+- [Commit 规范说明](./release-workflow.md#-commit-message-规范必须遵守)

package/template/.agents/skills/yss-ui/references/checklist.md

@@ -1,110 +1,52 @@
-# yss-ui Checklist
+# YSS UI 交付检查
 
-## 使用方式
+开发时按当前页面和影响面自检，联调时核对数据链路，交付时重新绑定当前 Slice 的实现计划、实现还原验证与实际执行证据。未命中项按原合同记录原因；命中但未验证的项保留阻塞，不能用清单勾选替代执行。
 
-- 开发阶段：按页面类型逐项自检。
-- 联调阶段：重点执行“数据链路与交互”清单。
-- 提交前：至少完成“通用基线”+ 当前页面类型清单。
+## 通用基线
 
----
+- [ ] 已从目标工程用 `pnpm why` 确认 Vue、YSS UI、AntDV、VXE 实际版本及 lockfile。
+- [ ] 组件选型符合 [组件路由](component-routing.md)，已导出的组件 / Hook / Utils 使用真实包来源；受控回退有能力缺口、版本和验证证据。
+- [ ] 使用 Vue 3 Composition API 与 `<script setup lang="ts">`，未引入不存在的 Y 前缀组件或违规 `@formily/antd*` UI。
+- [ ] 页面编排、业务 Hook、纯配置和样式按职责组织；容器的间距与可计算高度符合工程基线。
+- [ ] 适用实现已对照匹配版本的组件文档和已验证 Demo；`pending-verification` 示例不作为推荐依据。
+- [ ] loading、empty、error、disabled/no-access 和实际依赖的 selected 状态都有反馈与恢复路径。
 
-## 通用基线（所有页面必查）
+## 主题、Locale、浮层和可访问性
 
-- [ ] 已用 `pnpm why` 确认 Vue、YSS UI、AntDV、VXE 实际版本
-- [ ] 组件选型已对照 `component-routing.md`，AntDV 回退已记录原因
-- [ ] 使用 Vue 3 Composition API + `<script setup lang="ts">`
-- [ ] 优先使用 `@yss-ui/components`，缺失能力再回退 `ant-design-vue`
-- [ ] 未引入不存在的 Y 前缀组件
-- [ ] 无 `@formily/antd*` 违规导入
-- [ ] 页面容器具备统一布局（padding/margin/min-height）
-- [ ] 状态展示与危险操作颜色保持一致
-- [ ] 关键交互具备成功/失败反馈（`message`）
-- [ ] 关键实现至少对照一个 docs demo（`../assets/demos/*`）
-- [ ] 推荐 Demo 不含 `pending-verification`
+- [ ] 通过项目 ConfigProvider、YSS theme 或语义 Token 消费主题，未新增页面级主题色、任意 z-index；状态不只用颜色表达。
+- [ ] locale、时区、日期和金额格式化复用统一能力；Popup/Teleport 目标与宿主、微应用容器一致。
+- [ ] 图标按钮有可访问名称，表单 label 与错误提示有语义关联；主要动作支持键盘，Tab 顺序合理。
+- [ ] Modal/Drawer 打开后焦点合理，关闭时清理状态并恢复触发元素焦点。
+- [ ] 窄屏布局、表格横向滚动、操作收敛及实际采用的大数据 / 搜索 / 按需加载策略已验证。
 
-## 主题、Locale 与浮层
+## 列表与选择
 
-- [ ] 页面通过项目 ConfigProvider/YSS theme/语义 token 消费主题
-- [ ] 未新增页面级主题色和任意 z-index
-- [ ] locale、时区、日期和金额格式化沿用项目统一能力
-- [ ] Popup/Teleport 目标适配宿主和微应用容器
-- [ ] Modal/Drawer 关闭时清理状态并恢复触发元素焦点
+配置 YTable 时由已安装的 `ytable-usage` 核对专项规则，组件公开 API 见 [YTable 文档](../assets/docs/components/table.md)；没有多选或分页的页面不需要引入对应能力。公共包未附的专项及缺失时的停止、恢复条件见 [专项技能的可用性](quick-recipes.md#专项技能的可用性)，组件文档不能替代必要专项。
 
-## 可访问性、响应式与性能
+- [ ] 列使用 `YTableColumn` 与 `field/type`；行键配置实际业务主键和 `useKey: true`。
+- [ ] 自定义单元格与表头使用真实字段插槽，不用 `bodyCell` 分支冒充 YTable 主渲染模式；DOM 模板中的插槽按 kebab-case。
+- [ ] 远程分页使用 `pageable + v-model:pagination`，状态为 `current/pageSize/total/remote`，监听 `@page-change` 的 `{ current, pageSize }`。
+- [ ] 多选场景配置 Checkbox、受控选择和空选择禁用；批量操作成功后受控字段与可见勾选同时清空。
+- [ ] 远程查询由业务 Hook 执行，未把实例 `refresh()` 当作接口重查；危险操作使用组件确认或邻近 `Popconfirm`。
 
-- [ ] 图标按钮有可访问名称，状态不只依赖颜色
-- [ ] 表单 label、错误提示与控件建立语义关联
-- [ ] 主要操作可通过键盘完成，Tab 顺序合理
-- [ ] 窄屏布局、表格横向滚动和操作收敛已检查
-- [ ] 大数据 Table/Tree、远程搜索和复杂组件采用项目已验证的性能策略
+## 抽屉与步骤
 
----
+- [ ] 抽屉开关与当前记录有单一来源，打开前完成回填，关闭时清理临时输入，Tab 切换不引入脏数据。
+- [ ] 抽屉内列表沿用 YTable 列和分页合同；底部危险操作按批准交互设置确认，不默认使用居中 `Modal.confirm`。
+- [ ] 步骤状态有单一来源，当前实例校验成功才前进；跨步骤数据与弹层编辑回填都保留。
+- [ ] 上一步、下一步、取消与完成按钮的状态和文案正确；完成后提供反馈并进入合同约定的目标页面。
 
-## 列表页清单（YTable）
+## API、Mock、路由与菜单
 
-- [ ] 列定义使用 `YTableColumn`，主字段走 `field/type`
-- [ ] 启用 `:row-config="{ keyField: 'id' }"` 或业务主键
-- [ ] 需要选择行时已配置 `type: 'checkbox'`
-- [ ] 自定义单元格走字段插槽（如 `#status`、`#action`）
-- [ ] DOM 模板（JSP/HTML）下插槽命名使用 kebab-case（如 `#toolbar-left`）
-- [ ] 避免以 `bodyCell` 分支作为主渲染模式
-- [ ] 分页状态包含 `current/pageSize/total`
-- [ ] `@change` 中同步更新分页并触发刷新
-- [ ] 加载态与空态行为正确
+- [ ] API 经项目统一 mutator，导入当前真实生成函数与 DTO；URL 未重复拼接 `/api`。
+- [ ] 请求分页、筛选和响应映射均匹配冻结合同；Mock 路径、字段、状态码和包装复现同一 wire shape，不另定通用包装。
+- [ ] 查询回第一页，翻页保留筛选；API 失败只由 mutator 提示，Hook 维护状态与恢复，不重复错误 Toast。
+- [ ] 路由位于实际模块层级，`meta.title` 和唯一 `name` 符合页面语义；已有工程采用 `MENU_TYPE.INNER_MENU` 时，详情 / 创建页沿用其配置。
 
----
+## 实际验证与限制
 
-## 抽屉详情页清单
-
-- [ ] 抽屉开关状态单一来源（`ref<boolean>`）
-- [ ] 打开抽屉前正确设置当前记录
-- [ ] 抽屉关闭时清理临时输入/评论等状态
-- [ ] Tab 切换不引入脏数据
-- [ ] 抽屉内表格优先使用 YTable（列同样遵循 `field/type`）
-- [ ] 底部操作按钮具备确认机制（如 `Modal.confirm`）
-
----
-
-## 步骤页清单（Create/Step）
-
-- [ ] 步骤状态由单一 `currentStep` 管理
-- [ ] 第一步表单校验通过后再进入下一步
-- [ ] 步骤二列表推荐使用 YTable 承载节点信息
-- [ ] 节点编辑弹层（Drawer/Modal）保存后回填源数据
-- [ ] 上一步/下一步/取消/完成按钮状态与文案正确
-- [ ] 完成动作后有明确反馈并返回目标页面
-
----
-
-## 数据链路与联调清单（API + Mock）
-
-- [ ] API 请求通过项目统一实例（`mutator.ts`）发起
-- [ ] URL 未重复拼接 `/api` 前缀
-- [ ] 列表请求参数包含 `page/pageSize` 与筛选参数
-- [ ] Mock 路由与前端请求路径一致
-- [ ] Mock 返回结构为 `{ code, message, data: { list, total, page, pageSize } }`
-- [ ] 查询行为会重置页码到第一页
-- [ ] 分页行为会沿用筛选条件重新请求
-- [ ] 异常时正确提示并兜底空数据
-
----
-
-## 路由与菜单清单
-
-- [ ] 页面路由挂载在正确模块 `children` 下
-- [ ] `meta.title` 与页面语义一致
-- [ ] 详情/创建页使用 `menuType: MENU_TYPE.INNER_MENU`
-- [ ] 路由名称（name）语义清晰且唯一
-
----
-
-## 交付前核查清单
-
-- [ ] 关键文件已补充必要类型定义
-- [ ] 无调试输出（如 `console.info`）遗留
-- [ ] 运行格式化命令并确认无格式问题
-- [ ] 目标文件 IDE 诊断无新增错误
-- [ ] 若 lint/type-check 失败，已明确标注环境原因
-- [ ] 如需 AI 辅助生成代码，优先加载 `llms-full.txt` 上下文
-- [ ] 必要的组件测试、E2E、视觉回归已执行；未适用项记录原因
-- [ ] 浏览器 console 无新增 warning/error
+- [ ] 类型、静态检查和目标文件诊断没有新增问题；无调试输出遗留。格式检查优先使用工程现有检查模式，避免重写无关文件。
+- [ ] 适用组件测试、关键交互、E2E、响应式与视觉回归已执行，浏览器 console 无新增 warning/error。
+- [ ] `frontend_implementation_plan` / `frontend_implementation_verification` 绑定当前输入；视觉场景按 `case_id` 配对基准图、实现图、diff/mask 与差异解释。
+- [ ] 验证记录含工作目录、实际命令、退出码、环境及证据。失败报告实际现象和已确认原因；原因未知时保留未知，未执行项不写通过。
+- [ ] 文档查询按 [组件来源判定](component-routing.md#导入来源判定)选择 MCP、匹配版本的本地资料或源码，不因生成代码就预读完整 `llms-full.txt`。

package/template/.agents/skills/yss-ui/references/component-routing.md

@@ -15,7 +15,7 @@
 | 条件构建 | `YConditionBuilder` | YSS domain component | required | 标准模型与校验边界见 `specialized-components.md` |
 | 月历 | `YMonthCalendar` | YSS domain component | required | 日期、月份、高度与事件边界见 `specialized-components.md` |
 | Cron | `YCron` | YSS domain component | required | 七段表达式边界见 `specialized-components.md` |
-| 图表 | `YssEcharts` | ECharts | required | 主题、更新和尺寸边界见 `specialized-components.md` |
+| 图表 | `YEcharts` | ECharts | required | 主题、更新和尺寸边界见 `specialized-components.md` |
 | 编辑器 | `YMonaco` / `YMonacoDiff` | Monaco | required | 按需加载和尺寸治理见 `specialized-components.md` |
 | Sheet | `YSheet` | Univer | required | Facade、释放和依赖边界见 `specialized-components.md` |
 | 输入、选择、日期 | 无独立通用 Wrapper | AntDV Input/Select/DatePicker 等 | fallback | 读取实际 AntDV 版本；服从 theme/locale/popup 规则 |
@@ -23,6 +23,8 @@
 | 服务式反馈 | 无统一 Wrapper | message/notification | fallback | 检查 App/ConfigProvider 上下文 |
 | 布局与导航 | 按项目现状 | AntDV Layout/Grid/Menu/Tabs 等 | fallback | 不复制 React Ant Design v6 API |
 
+图表名称按本地快照的 [Vue Demo 导入](../assets/demos/echarts/line.vue) 使用 `YEcharts`；文档标题中的旧名称不作为导出依据。目标工程仍须按 lockfile、类型和真实导出核验。
+
 ## 受控回退
 
 YSS `required` wrapper 缺少必要能力时，记录组件、能力缺口、依赖版本、替代方案、主题/locale/浮层影响和验证证据。没有记录不得回退。