create-yss-spec 2.2.3 → 2.2.4

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import process from "node:process";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecordFile } from "../../../../scripts/lib/approval-record.mjs";
+
+const required = ["schema_version", "stage_decision_id", "package_version", "status", "problem_statement", "target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "unresolved_items", "terminology_refs", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"];
+const idPattern = /^stage-decision\.[a-z0-9][a-z0-9-]*$/;
+
+function fail(errors) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", errors }, null, 2)}\n`);
+  process.exitCode = 1;
+}
+function nonEmpty(value) { return typeof value === "string" && value.trim().length > 0; }
+function requireField(object, field, path, errors) { if (!(field in object) || object[field] === null || object[field] === undefined) errors.push(`${path}.${field} 缺失`); }
+function requireString(object, field, path, errors) { requireField(object, field, path, errors); if (field in object && !nonEmpty(object[field])) errors.push(`${path}.${field} 必须是非空字符串`); }
+function requireArray(object, field, path, errors, min = 0) { requireField(object, field, path, errors); if (field in object && (!Array.isArray(object[field]) || object[field].length < min)) errors.push(`${path}.${field} 必须是至少 ${min} 项的数组`); if (field in object && Array.isArray(object[field])) object[field].forEach((item, index) => { if (!nonEmpty(item)) errors.push(`${path}.${field}[${index}] 必须是非空字符串`); }); }
+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) {
+  const errors = [];
+  if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
+  for (const field of required) requireField(data, field, "root", errors);
+  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
+  if (!idPattern.test(String(data.stage_decision_id ?? ""))) errors.push("stage_decision_id 格式非法");
+  if (!/^v[0-9]+$/.test(String(data.package_version ?? ""))) errors.push("package_version 必须形如 v1");
+  if (!["draft", "ready-for-human", "approved", "stale", "blocked"].includes(data.status)) errors.push("status 非法");
+  for (const field of ["problem_statement"]) requireString(data, field, "root", errors);
+  for (const field of ["target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "terminology_refs", "evidence_refs"]) requireArray(data, field, "root", errors, ["target_users", "mvp", "success_criteria", "test_seams", "confirmed_decisions", "evidence_refs"].includes(field) ? 1 : 0);
+
+  const unresolved = Array.isArray(data.unresolved_items) ? data.unresolved_items : [];
+  for (const [index, item] of unresolved.entries()) {
+    const path = `unresolved_items[${index}]`;
+    for (const field of ["item", "type", "owner", "next_action", "target_version"]) requireString(item ?? {}, field, path, errors);
+    if (item?.type && !["blocker", "deferred"].includes(item.type)) errors.push(`${path}.type 非法`);
+  }
+  const domainRef = data.domain_strategy_ref ?? {};
+  for (const field of ["domain_strategy_id", "domain_version", "digest", "status", "persisted_ref"]) requireString(domainRef, field, "domain_strategy_ref", errors);
+  if (domainRef.status && !["approved", "stale", "blocked"].includes(domainRef.status)) errors.push("domain_strategy_ref.status 非法");
+  if (data.status === "approved" && domainRef.status !== "approved") errors.push("approved 阶段包必须引用 approved 的 domain strategy");
+  if (nonEmpty(domainRef.persisted_ref)) {
+    try {
+      const strategySource = await readFile(resolve(process.cwd(), domainRef.persisted_ref), "utf8");
+      const strategyDocument = parseDocument(strategySource, { maxAliasCount: 0, uniqueKeys: true });
+      if (strategyDocument.errors.length) errors.push(`domain_strategy_ref.persisted_ref YAML 非法: ${strategyDocument.errors[0].message}`);
+      else {
+        const strategy = strategyDocument.toJS({ maxAliasCount: 0 });
+        if (strategy.domain_strategy_id !== domainRef.domain_strategy_id) errors.push("domain_strategy_ref.domain_strategy_id 与实际文件不一致");
+        if (strategy.domain_version !== domainRef.domain_version) errors.push("domain_strategy_ref.domain_version 与实际文件不一致");
+        if (strategy.status !== domainRef.status) errors.push("domain_strategy_ref.status 与实际文件不一致");
+        if (domainRef.digest !== digest(strategy)) errors.push("domain_strategy_ref.digest 与实际领域战略内容不一致");
+      }
+    } catch (error) { errors.push(`domain_strategy_ref.persisted_ref 无法读取: ${error.message}`); }
+  }
+
+  const impact = data.impact_assessment ?? {};
+  for (const field of ["ui", "api", "data", "backend", "frontend", "cross_repo", "high_risk"]) {
+    requireField(impact, field, "impact_assessment", errors);
+    if (field in impact && typeof impact[field] !== "boolean") errors.push(`impact_assessment.${field} 必须是 boolean`);
+  }
+  const mappings = Array.isArray(data.downstream_mapping) ? data.downstream_mapping : [];
+  if (mappings.length < 1) errors.push("downstream_mapping 至少需要一项");
+  for (const [index, mapping] of mappings.entries()) {
+    const path = `downstream_mapping[${index}]`;
+    for (const field of ["domain_change", "consumer", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
+    if (mapping?.propagation && !["direct", "transitive", "not-applicable", "stale"].includes(mapping.propagation)) errors.push(`${path}.propagation 非法`);
+  }
+  const approval = data.approval ?? {};
+  for (const field of ["approval_ref", "approver", "persisted_ref", "current_version"]) requireString(approval, field, "approval", errors);
+  if (data.status === "approved" && approval.current_version !== data.package_version) errors.push("approval.current_version 必须等于 package_version");
+  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);
+      validateApprovalRecordFile(approvalPath, { requireApproved: true });
+      const record = loadApprovalRecord(approvalPath);
+      if (record.gate_id !== "gate.stage-decision-package-approved") errors.push("approval_ref 的 gate_id 必须为 gate.stage-decision-package-approved");
+      if (record.role_id !== approval.approver) errors.push("approval.approver 必须与会签记录 role_id 一致");
+    } catch (error) { errors.push(`approval_ref 会签记录无效: ${error.message}`); }
+  }
+  return errors;
+}
+
+const file = process.argv[2];
+if (!file) fail(["用法: validate-stage-decision-package.mjs <package.yaml>"]);
+else {
+  try {
+    const source = await readFile(file, "utf8");
+    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length) fail([document.errors[0].message]);
+    else {
+      const errors = await validate(document.toJS({ maxAliasCount: 0 }));
+      if (errors.length) fail(errors);
+      else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
+    }
+  } catch (error) { fail([error.message]); }
+}

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+gate_id: gate.domain-strategy-approved
+decision: approved
+actor_kind: digital-human
+role_id: role.product-manager
+runtime_id: runtime.generic
+runtime_instance_ref: "runtime.generic:role.product-manager"
+principal_ref: "instance:role.product-manager"
+drafter_role_id: role.requirements-manager
+countersigner_role_ids:
+  - role.product-manager
+evidence_refs:
+  - evidence.domain-strategy-review.supplier
+biological_veto: false
+notes: DDD 战略设计由需求经理起草，产品经理独立会签。

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/invalid-direction.yaml

@@ -0,0 +1,58 @@
+schema_version: 1
+domain_strategy_id: domain-strategy.invalid-direction
+domain_version: v1
+status: ready-for-human
+contexts:
+  - context_id: A
+    name: A
+    responsibilities: [rule]
+    non_responsibilities: []
+    subdomain_type: Supporting Subdomain
+    owner: owner
+    status: confirmed
+  - context_id: B
+    name: B
+    responsibilities: [consume]
+    non_responsibilities: []
+    subdomain_type: Supporting Subdomain
+    owner: owner
+    status: confirmed
+subdomains:
+  - subdomain_id: subdomain.a
+    name: A
+    type: Supporting Subdomain
+    rationale: test
+    evidence_refs: [e]
+relationships:
+  - relationship_id: relationship.a-b
+    from_context: A
+    to_context: B
+    relationship_pattern: Published Language
+    semantic_upstream: A
+    semantic_downstream: B
+    business_authority: A
+    model_change_impact: B adapts
+    transport_direction: B calls A
+    translation_responsibility: B
+    direction_explanation: ""
+scenarios:
+  - scenario_id: scenario.test
+    actor: actor
+    preconditions: []
+    commands: [command]
+    rules: [rule]
+    events: []
+    failure_results: [failure]
+    responsible_context: A
+    consumers: [B]
+    status: confirmed
+concept_candidates: []
+invariants: []
+terminology_refs: [t]
+downstream_mapping: []
+evidence_refs: [e]
+approval:
+  approval_ref: a
+  approver: a
+  persisted_ref: p
+  current_version: v1

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/invalid-stage-decision-blocker.yaml

@@ -0,0 +1,44 @@
+schema_version: 1
+stage_decision_id: stage-decision.invalid-blocker
+package_version: v1
+status: approved
+problem_statement: 示例
+target_users: [用户]
+mvp: [功能]
+non_goals: []
+success_criteria: [标准]
+test_seams: [seam]
+confirmed_decisions: [决定]
+assumptions: []
+constraints: []
+unresolved_items:
+  - item: 规则所有权未确认
+    type: blocker
+    owner: role.product-manager
+    next_action: 召开领域评审
+    target_version: 2026-Q4
+terminology_refs: [CONTEXT.md#Example]
+domain_strategy_ref:
+  domain_strategy_id: domain-strategy.invalid
+  domain_version: v1
+  digest: sha256:invalid
+  status: approved
+impact_assessment:
+  ui: false
+  api: false
+  data: false
+  backend: true
+  frontend: false
+  cross_repo: false
+  high_risk: false
+downstream_mapping:
+  - domain_change: example
+    consumer: spec-synthesis
+    propagation: direct
+    reapproval_condition: 规则确认
+evidence_refs: [evidence.invalid]
+approval:
+  approval_ref: docs/.scratch/invalid/gate.yaml
+  approver: role.lifecycle-orchestrator
+  persisted_ref: docs/.scratch/invalid/package.yaml
+  current_version: v1

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+gate_id: gate.stage-decision-package-approved
+decision: approved
+actor_kind: digital-human
+role_id: role.product-manager
+runtime_id: runtime.generic
+runtime_instance_ref: "runtime.generic:role.product-manager"
+principal_ref: "instance:role.product-manager"
+drafter_role_id: role.requirements-manager
+countersigner_role_ids:
+  - role.product-manager
+evidence_refs:
+  - evidence.stage-decision-package.supplier
+biological_veto: false
+notes: 阶段决策包由需求经理起草，产品经理独立会签。

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/valid-stage-decision-package.yaml

@@ -0,0 +1,49 @@
+schema_version: 1
+stage_decision_id: stage-decision.supplier-admission
+package_version: v1
+status: approved
+problem_statement: 合规准入决定分散，采购无法稳定判断当前有效资格。
+target_users: [采购专员、合规专员]
+mvp: [提交供应商申请、合规准入决定、采购侧有效性校验]
+non_goals: [供应商结算、采购付款、通用工作流平台]
+success_criteria: [新采购订单 100% 校验当前有效准入决定]
+test_seams: [supplier-application-submit, admission-validity-check]
+confirmed_decisions: [ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定]
+assumptions: [供应商已有唯一 subject_ref]
+constraints: [保留现有采购订单流程]
+unresolved_items:
+  - item: 供应商历史资料迁移范围
+    type: deferred
+    owner: role.product-manager
+    next_action: 在 Spec synthesis 前完成数据盘点
+    target_version: 2026-Q4
+terminology_refs: [CONTEXT.md#SupplierAdmission]
+domain_strategy_ref:
+  domain_strategy_id: domain-strategy.supplier-admission
+  domain_version: v1
+  digest: sha256:a1a4df23fdb59ab8b4433cedba8271c8a7f11bc8a38abe675d3c7b645d51d7a1
+  status: approved
+  persisted_ref: .agents/skills/yss-stage-decision/tests/fixtures/valid-supplier-domain.yaml
+impact_assessment:
+  ui: true
+  api: true
+  data: true
+  backend: true
+  frontend: true
+  cross_repo: false
+  high_risk: false
+downstream_mapping:
+  - domain_change: admission-decision-validity
+    consumer: spec-synthesis
+    propagation: direct
+    reapproval_condition: 领域策略版本或有效性规则变化
+  - domain_change: admission-decision-validity
+    consumer: ticket-decomposition
+    propagation: transitive
+    reapproval_condition: Spec 基线变更
+evidence_refs: [evidence.discovery.supplier, evidence.domain-strategy-review.supplier]
+approval:
+  approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml
+  approver: role.product-manager
+  persisted_ref: docs/.scratch/supplier/stage-decision/stage-decision-package-v1.yaml
+  current_version: v1

package/template/.cursor/skills/yss-stage-decision/tests/fixtures/valid-supplier-domain.yaml

@@ -0,0 +1,108 @@
+schema_version: 1
+domain_strategy_id: domain-strategy.supplier-admission
+domain_version: v1
+status: approved
+contexts:
+  - context_id: SupplierManagement
+    name: 供应商管理
+    responsibilities: [供应商申请、资料生命周期]
+    non_responsibilities: [合规决定、采购订单]
+    subdomain_type: Supporting Subdomain
+    owner: requirements-manager
+    status: confirmed
+  - context_id: ComplianceReview
+    name: 合规审查
+    responsibilities: [资质审查、准入决定、有效期]
+    non_responsibilities: [供应商主档、采购订单]
+    subdomain_type: Core Domain
+    owner: product-manager
+    status: confirmed
+  - context_id: ProcurementExecution
+    name: 采购执行
+    responsibilities: [采购选择、采购订单履行]
+    non_responsibilities: [合规规则、供应商申请]
+    subdomain_type: Supporting Subdomain
+    owner: project-manager
+    status: confirmed
+subdomains:
+  - subdomain_id: subdomain.supplier-management
+    name: Supplier Management
+    type: Supporting Subdomain
+    rationale: 管理申请与资料生命周期，不承载差异化合规决策。
+    evidence_refs: [evidence.discovery.supplier]
+  - subdomain_id: subdomain.compliance-review
+    name: Compliance Review
+    type: Core Domain
+    rationale: 核心价值候选是企业自有的合规判断和风险规则。
+    evidence_refs: [evidence.discovery.compliance]
+relationships:
+  - relationship_id: relationship.supplier-to-compliance
+    from_context: SupplierManagement
+    to_context: ComplianceReview
+    relationship_pattern: Customer/Supplier
+    semantic_upstream: SupplierManagement
+    semantic_downstream: ComplianceReview
+    business_authority: SupplierManagement owns applicant facts
+    model_change_impact: applicant schema changes require review adaptation
+    transport_direction: SubmitSupplierForComplianceReview command
+    translation_responsibility: ComplianceReview ACL
+    direction_explanation: 申请资料由 SupplierManagement 拥有，但技术请求方向不代表合规规则所有权。
+  - relationship_id: relationship.compliance-to-procurement
+    from_context: ComplianceReview
+    to_context: ProcurementExecution
+    relationship_pattern: Published Language
+    semantic_upstream: ComplianceReview
+    semantic_downstream: ProcurementExecution
+    business_authority: ComplianceReview owns admission validity
+    model_change_impact: decision validity changes invalidate procurement acceptance
+    transport_direction: admission decision events
+    translation_responsibility: ProcurementExecution local projection
+    direction_explanation: 合规决定是语义上游；采购侧可通过事件接收并在下单时实时校验。
+scenarios:
+  - scenario_id: scenario.supplier-submits
+    actor: supplier
+    preconditions: [供应商资料可编辑]
+    commands: [SubmitSupplierApplication]
+    rules: [申请材料必须完整]
+    events: [SupplierApplicationSubmitted]
+    failure_results: [材料不完整时拒绝提交]
+    responsible_context: SupplierManagement
+    consumers: [ComplianceReview]
+    status: confirmed
+  - scenario_id: scenario.admission-expires
+    actor: compliance-officer
+    preconditions: [批准决定存在]
+    commands: [EvaluateAdmissionValidity]
+    rules: [过期决定不得支持新采购订单]
+    events: [SupplierAdmissionExpired]
+    failure_results: [采购下单时资格校验失败]
+    responsible_context: ComplianceReview
+    consumers: [SupplierManagement, ProcurementExecution]
+    status: confirmed
+concept_candidates:
+  - concept_id: domain-concept.admission-decision
+    name: AdmissionDecision
+    context_id: ComplianceReview
+    identity_features: [decision_id、subject_ref、rule_version]
+    lifecycle: [proposed、approved、rejected、expired、revoked]
+    possible_tactical_role: Entity candidate
+    confidence: high
+    status: confirmed
+invariants:
+  - invariant_id: invariant.current-admission-required
+    statement: 新采购订单必须引用当前有效的准入决定。
+    responsible_context: ComplianceReview
+    scenario_refs: [scenario.admission-expires]
+    verification_method: 领域场景测试和事件版本校验
+terminology_refs: [contexts/SupplierManagement/CONTEXT.md, contexts/ComplianceReview/CONTEXT.md]
+downstream_mapping:
+  - domain_change: admission-decision-validity
+    impacts: [spec, openapi, procurement-acceptance-tests]
+    propagation: stale
+    reapproval_condition: ComplianceReview 决定和有效期重新批准
+evidence_refs: [evidence.discovery.supplier, evidence.discovery.compliance]
+approval:
+  approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml
+  approver: role.product-manager
+  persisted_ref: docs/.scratch/supplier/domain/domain-strategy-v1.yaml
+  current_version: v1

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const validator = join(root, "..", "scripts", "validate-domain-strategy.mjs");
+const packageValidator = join(root, "..", "scripts", "validate-stage-decision-package.mjs");
+const valid = join(root, "fixtures", "valid-supplier-domain.yaml");
+const invalid = join(root, "fixtures", "invalid-direction.yaml");
+const validPackage = join(root, "fixtures", "valid-stage-decision-package.yaml");
+const invalidPackage = join(root, "fixtures", "invalid-stage-decision-blocker.yaml");
+const run = (file) => spawnSync(process.execPath, [validator, file], { encoding: "utf8" });
+const pass = run(valid);
+if (pass.status !== 0) throw new Error(`valid fixture should pass: ${pass.stderr}`);
+const fail = run(invalid);
+if (fail.status === 0 || !fail.stderr.includes("direction_explanation")) throw new Error("invalid direction fixture should be blocked");
+const packagePass = spawnSync(process.execPath, [packageValidator, validPackage], { encoding: "utf8" });
+if (packagePass.status !== 0) throw new Error(`valid stage decision package should pass: ${packagePass.stderr}`);
+const packageFail = spawnSync(process.execPath, [packageValidator, invalidPackage], { encoding: "utf8" });
+if (packageFail.status === 0 || !packageFail.stderr.includes("blocker")) throw new Error("blocker package should be blocked");
+
+const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-stage-decision-pressure-"));
+try {
+  const validSource = await readFile(valid, "utf8");
+  const sharedKernel = join(temporaryRoot, "shared-kernel.yaml");
+  await writeFile(sharedKernel, validSource.replace("relationship_pattern: Customer/Supplier", "relationship_pattern: Shared Kernel"));
+  const sharedKernelResult = run(sharedKernel);
+  if (sharedKernelResult.status === 0 || !sharedKernelResult.stderr.includes("shared_kernel_approval_ref")) throw new Error("unapproved Shared Kernel should be blocked");
+  const unknownContext = join(temporaryRoot, "unknown-context.yaml");
+  await writeFile(unknownContext, validSource.replace("to_context: ComplianceReview", "to_context: UnknownContext"));
+  const unknownContextResult = run(unknownContext);
+  if (unknownContextResult.status === 0 || !unknownContextResult.stderr.includes("未引用已声明上下文")) throw new Error("unknown context should be blocked");
+  const wrongArrayType = join(temporaryRoot, "wrong-array-type.yaml");
+  await writeFile(wrongArrayType, validSource.replace("responsibilities: [供应商申请、资料生命周期]", "responsibilities: [42]"));
+  const wrongArrayTypeResult = run(wrongArrayType);
+  if (wrongArrayTypeResult.status === 0 || !wrongArrayTypeResult.stderr.includes("responsibilities[0]")) throw new Error("non-string array item should be blocked");
+  const missingSubdomainType = join(temporaryRoot, "missing-subdomain-type.yaml");
+  await writeFile(missingSubdomainType, validSource.replace("    subdomain_type: Supporting Subdomain\n", ""));
+  const missingSubdomainTypeResult = run(missingSubdomainType);
+  if (missingSubdomainTypeResult.status === 0 || !missingSubdomainTypeResult.stderr.includes("subdomain_type 缺失")) throw new Error("missing subdomain type should be blocked");
+  const wrongReferenceType = join(temporaryRoot, "wrong-reference-type.yaml");
+  await writeFile(wrongReferenceType, validSource.replace("terminology_refs: [contexts/SupplierManagement/CONTEXT.md, contexts/ComplianceReview/CONTEXT.md]", "terminology_refs: [42]"));
+  const wrongReferenceTypeResult = run(wrongReferenceType);
+  if (wrongReferenceTypeResult.status === 0 || !wrongReferenceTypeResult.stderr.includes("terminology_refs[0]")) throw new Error("non-string terminology reference should be blocked");
+  const emptyDomainCollections = join(temporaryRoot, "empty-domain-collections.yaml");
+  await writeFile(emptyDomainCollections, validSource.replace(/contexts:\n[\s\S]*?subdomains:/, "contexts: []\nsubdomains:").replace(/subdomains:\n[\s\S]*?relationships:/, "subdomains: []\nrelationships:").replace(/scenarios:\n[\s\S]*?concept_candidates:/, "scenarios: []\nconcept_candidates:"));
+  const emptyDomainCollectionsResult = run(emptyDomainCollections);
+  if (emptyDomainCollectionsResult.status === 0 || !emptyDomainCollectionsResult.stderr.includes("contexts 必须是至少 1 项的数组")) throw new Error("empty DDD collections should be blocked");
+  const wrongDomainApproval = join(temporaryRoot, "wrong-domain-approval.yaml");
+  await writeFile(wrongDomainApproval, validSource.replace("approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml", "approval_ref: docs/.scratch/does-not-exist.yaml"));
+  const wrongDomainApprovalResult = run(wrongDomainApproval);
+  if (wrongDomainApprovalResult.status === 0 || !wrongDomainApprovalResult.stderr.includes("approval.approval_ref")) throw new Error("unreadable domain approval ref should be blocked");
+  const packageSource = await readFile(validPackage, "utf8");
+  const packageWrongArrayType = join(temporaryRoot, "package-wrong-array-type.yaml");
+  await writeFile(packageWrongArrayType, packageSource.replace("target_users: [采购专员、合规专员]", "target_users: [42]"));
+  const packageWrongArrayTypeResult = spawnSync(process.execPath, [packageValidator, packageWrongArrayType], { encoding: "utf8" });
+  if (packageWrongArrayTypeResult.status === 0 || !packageWrongArrayTypeResult.stderr.includes("target_users[0]")) throw new Error("package non-string array item should be blocked");
+  const packageWrongApproval = join(temporaryRoot, "package-wrong-approval.yaml");
+  await writeFile(packageWrongApproval, packageSource.replace("approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml", "approval_ref: docs/.scratch/does-not-exist.yaml"));
+  const packageWrongApprovalResult = spawnSync(process.execPath, [packageValidator, packageWrongApproval], { encoding: "utf8" });
+  if (packageWrongApprovalResult.status === 0 || !packageWrongApprovalResult.stderr.includes("approval_ref")) throw new Error("unreadable approval ref should be blocked");
+} finally {
+  await rm(temporaryRoot, { recursive: true, force: true });
+}
+process.stdout.write("DDD strategic design scenarios passed\n");

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

@@ -0,0 +1,33 @@
+---
+name: yss-tactical-design
+description: 在 YSS 技术分析阶段将批准的战略领域输入细化为可审查的聚合、行为、一致性和 Gateway 设计；不生成生产代码。
+---
+
+# yss-tactical-design
+
+本 skill 负责 DDD 战术设计，不新增生命周期主阶段，也不替代 `yss-stage-decision` 或 `yss-domain`。
+
+## 适用边界
+
+- 由 `yss-product-lifecycle` 在 `work-unit.technical-analysis` 中按领域影响条件调度。
+- 输入必须是版本当前的 Spec、功能架构、战略 DDD、状态矩阵、OpenAPI Draft / Freeze、ADR 和工程约束。
+- 默认将结果写入系统概要设计 / 数据架构中的 Tactical DDD Check；聚合、状态机、一致性或持久化映射复杂到无法清楚表达时，才升级为独立战术设计文档。
+- 没有聚合、状态、不变量、一致性或领域边界影响时返回 `not-applicable` 及原因，不生成空设计。
+
+## 设计内容
+
+必须明确 Aggregate Root、Entity、Value Object、领域行为、状态转换、不变量、一致性 / 事务、幂等 / 并发、Domain Event、Gateway、持久化映射和 Domain / Application 测试 seam。
+
+数据库表、HTTP 调用链或菜单结构不能单独决定聚合边界；OpenAPI 不得暴露内部聚合、Repository 或持久化表结构。
+
+## 输出与状态
+
+输出结构化 tactical-design contract、验证结果、评审引用和影响标记。状态使用 `draft`、`ready-for-human`、`approved`、`blocked`、`stale`、`drift`、`new_impacts`。
+
+本 skill 不能自行批准资产、设置 `ready-for-agent`、创建 Ticket 或修改生命周期状态。批准由 `yss-product-lifecycle` 维护；独立架构评审使用 `evidence.tactical-design-review`。
+
+## 与实现交接
+
+批准且版本当前的战术设计合同由 `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 或生产代码。

package/template/.cursor/skills/yss-tactical-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS Tactical DDD Design"
+  short_description: "聚合、不变量、状态机、一致性与 Gateway 的战术设计"
+  default_prompt: "基于批准且版本当前的上游资产，完成可审查的 YSS DDD 战术设计并返回结构化验证结果。"

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

@@ -0,0 +1,28 @@
+pipeline: <feature-id>
+stage: system-data-engineering
+status: draft
+owner: ai
+
+# <功能名称> Tactical DDD Design
+
+## 上游引用
+
+| 资产 | ref | version / digest | 状态 |
+|---|---|---|---|
+| Spec |  |  |  |
+| Strategic DDD |  |  |  |
+| 状态矩阵 |  |  |  |
+| OpenAPI / 无 API 影响记录 |  |  |  |
+
+## Tactical DDD Check
+
+| 限界上下文 | 聚合根 | Entity / Value Object | 行为与不变量 | 一致性边界 | Gateway | 测试 seam |
+|---|---|---|---|---|---|---|
+|  |  |  |  |  |  |  |
+
+## 结论
+
+- 复杂度升级：是 / 否
+- API / 数据 / 状态新增影响：是 / 否
+- 评审结论：Approved / Blocked
+- 下一步：

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

@@ -0,0 +1,41 @@
+# Tactical DDD Design Contract
+
+## 输入
+
+必须引用批准且版本当前的 Spec、功能架构、战略 DDD、原型状态矩阵、OpenAPI Draft / Freeze（或无 API 影响记录）、ADR 和工程约束。所有引用都必须带版本或 digest；不可读或过期引用返回 `blocked` / `stale`。
+
+## 输出
+
+```yaml
+schema_version: 1
+tactical_design_id: tactical-design.<feature>
+tactical_version: v1
+status: draft | ready-for-human | approved | blocked | stale | drift | new_impacts | not-applicable
+context_ref: <限界上下文引用>
+aggregate_catalog: []
+entity_catalog: []
+value_object_catalog: []
+behavior_catalog: []
+invariant_catalog: []
+state_transition_catalog: []
+consistency_policy: {}
+domain_event_catalog: []
+gateway_catalog: []
+persistence_mapping: []
+test_seams: []
+adr_candidates: []
+upstream_impact: {}
+version: v1
+digest: sha256:<digest>
+evidence_refs: []
+```
+
+## 设计规则
+
+1. 聚合边界由业务行为和不变量决定，不由数据库表或外键自动推导。
+2. 每个聚合根必须列出行为、不变量和一致性边界。
+3. 状态转换必须绑定领域行为，禁止只有状态字段而没有行为语义。
+4. Gateway 接口属于 Domain，Repository / Mapper / GatewayImpl 属于 Infrastructure。
+5. OpenAPI schema 使用上下文公开语言，不泄漏内部聚合或持久化结构。
+6. 复杂跨聚合一致性、并发、幂等、事件补偿或持久化错位必须写明策略，必要时升级独立文档。
+7. 实现发现新影响时必须阻断并回到生命周期重新路由。

package/template/.cursor/skills/yss-tactical-design/references/tactical-design.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/tactical-design.schema.json",
+  "title": "YSS Tactical DDD Design Contract",
+  "type": "object",
+  "required": ["schema_version", "tactical_design_id", "tactical_version", "status", "context_ref", "aggregate_catalog", "entity_catalog", "value_object_catalog", "behavior_catalog", "invariant_catalog", "state_transition_catalog", "consistency_policy", "domain_event_catalog", "gateway_catalog", "persistence_mapping", "test_seams", "adr_candidates", "upstream_impact", "version", "digest", "evidence_refs"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "tactical_design_id": {"type": "string", "pattern": "^tactical-design\\.[a-z0-9][a-z0-9-]*$"},
+    "tactical_version": {"type": "string", "pattern": "^v[0-9]+$"},
+    "status": {"enum": ["draft", "ready-for-human", "approved", "blocked", "stale", "drift", "new_impacts", "not-applicable"]},
+    "context_ref": {"type": "string", "minLength": 1},
+    "aggregate_catalog": {"type": "array", "minItems": 1},
+    "entity_catalog": {"type": "array", "minItems": 1},
+    "value_object_catalog": {"type": "array"},
+    "behavior_catalog": {"type": "array", "minItems": 1},
+    "invariant_catalog": {"type": "array", "minItems": 1},
+    "state_transition_catalog": {"type": "array", "minItems": 1},
+    "consistency_policy": {"type": "object", "minProperties": 1},
+    "domain_event_catalog": {"type": "array"},
+    "gateway_catalog": {"type": "array", "minItems": 1},
+    "persistence_mapping": {"type": "array", "minItems": 1},
+    "test_seams": {"type": "array", "minItems": 1},
+    "adr_candidates": {"type": "array"},
+    "upstream_impact": {"type": "object", "minProperties": 1},
+    "version": {"type": "string", "pattern": "^v[0-9]+$"},
+    "digest": {"type": "string", "pattern": "^sha256:[A-Fa-f0-9]{64}$"},
+    "evidence_refs": {"type": "array", "items": {"type": "string"}}
+  },
+  "additionalProperties": true
+}

package/template/.cursor/skills/yss-tactical-design/references/validation-rules.md

@@ -0,0 +1,13 @@
+# Tactical DDD Validation Rules
+
+- 根对象必须包含合同要求的字段，状态只能使用生命周期状态集合。
+- `aggregate_catalog`、`behavior_catalog`、`invariant_catalog`、`state_transition_catalog`、`consistency_policy` 和 `test_seams` 不能为空。
+- 聚合、Entity、Value Object、行为、不变量、状态转换、事件和 Gateway ID 必须唯一且引用已声明对象。
+- 聚合根必须是 Entity；Entity 和 Value Object 不得跨聚合隐式共享身份。
+- 每个行为至少引用一个聚合和一个不变量；每个状态转换必须引用已声明行为。
+- `api_exposure: internal-only` 是内部聚合的唯一允许值；其他值需要回到 API 影响分析。
+- Gateway 的 `layer` 必须为 `Domain`，持久化实现不得出现在 Domain 目录。
+- `consistency_policy` 必须说明事务边界、并发、幂等和跨聚合策略。
+- 上游引用发生版本变化时，设计标记为 `stale`，不得进入 `approved` 或 `ready-for-agent`。
+- 若合同标记 `model_origin: strategic-concept`，必须阻断并要求完成战术细化。
+- 当 `complexity.escalate_to_standalone` 为真时，必须提供独立文档引用；否则仅允许作为嵌入式 Tactical DDD Check 消费。