create-yss-spec 2.2.2 → 2.2.4

package/template/.cursor/skills/yss-tactical-design/scripts/validate-tactical-design.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+
+const 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"
+];
+const statuses = new Set(["draft", "ready-for-human", "approved", "blocked", "stale", "drift", "new_impacts", "not-applicable"]);
+const idPatterns = {
+  tactical_design_id: /^tactical-design\.[a-z0-9][a-z0-9-]*$/,
+  aggregate_id: /^aggregate\.[a-z0-9][a-z0-9-]*$/,
+  entity_id: /^entity\.[a-z0-9][a-z0-9-]*$/,
+  value_object_id: /^value-object\.[a-z0-9][a-z0-9-]*$/,
+  behavior_id: /^behavior\.[a-z0-9][a-z0-9-]*$/,
+  invariant_id: /^invariant\.[a-z0-9][a-z0-9-]*$/,
+  transition_id: /^transition\.[a-z0-9][a-z0-9-]*$/,
+  event_id: /^domain-event\.[a-z0-9][a-z0-9-]*$/,
+  gateway_id: /^gateway\.[a-z0-9][a-z0-9-]*$/,
+  seam_id: /^test-seam\.[a-z0-9][a-z0-9-]*$/,
+  version: /^v[0-9]+$/
+};
+
+const isObject = (value) => value && typeof value === "object" && !Array.isArray(value);
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+const list = (value) => Array.isArray(value);
+
+function unique(items, label, errors) {
+  const seen = new Set();
+  for (const item of items) {
+    if (seen.has(item)) errors.push(`${label} 重复: ${item}`);
+    seen.add(item);
+  }
+}
+
+function requireField(object, field, path, errors) {
+  if (!Object.prototype.hasOwnProperty.call(object ?? {}, field) || object[field] === null || object[field] === undefined) {
+    errors.push(`${path}.${field} 缺失`);
+  }
+}
+
+function requireString(object, field, path, errors) {
+  requireField(object, field, path, errors);
+  if (Object.prototype.hasOwnProperty.call(object ?? {}, field) && !nonEmpty(object[field])) errors.push(`${path}.${field} 必须是非空字符串`);
+}
+
+function requireArray(object, field, path, errors, minimum = 0) {
+  requireField(object, field, path, errors);
+  if (Object.prototype.hasOwnProperty.call(object ?? {}, field) && (!list(object[field]) || object[field].length < minimum)) {
+    errors.push(`${path}.${field} 必须是至少 ${minimum} 项的数组`);
+  }
+}
+
+function requireId(value, kind, path, errors) {
+  if (value !== undefined && value !== null && !idPatterns[kind].test(String(value))) errors.push(`${path} 格式非法`);
+}
+
+function refsExist(values, known, path, errors) {
+  for (const [index, value] of (values ?? []).entries()) {
+    if (!known.has(value)) errors.push(`${path}[${index}] 引用了未声明对象: ${value}`);
+  }
+}
+
+function validate(data) {
+  const errors = [];
+  if (!isObject(data)) return ["合同必须是对象"];
+  for (const field of required) requireField(data, field, "root", errors);
+  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
+  requireId(data.tactical_design_id, "tactical_design_id", "tactical_design_id", errors);
+  for (const field of ["tactical_version", "version"]) if (data[field] !== undefined && !idPatterns.version.test(String(data[field]))) errors.push(`${field} 必须形如 v1`);
+  if (data.status !== undefined && !statuses.has(data.status)) errors.push(`status 非法: ${data.status}`);
+  if (data.digest !== undefined && !/^sha256:[A-Fa-f0-9]{64}$/.test(String(data.digest))) errors.push("digest 必须为 sha256 加 64 位十六进制");
+
+  for (const field of ["aggregate_catalog", "entity_catalog", "behavior_catalog", "invariant_catalog", "state_transition_catalog", "gateway_catalog", "persistence_mapping", "test_seams"]) {
+    requireArray(data, field, "root", errors, 1);
+  }
+  for (const field of ["value_object_catalog", "domain_event_catalog", "adr_candidates", "evidence_refs"]) requireArray(data, field, "root", errors);
+  if (!isObject(data.consistency_policy)) errors.push("consistency_policy 必须是对象");
+  if (!isObject(data.upstream_impact)) errors.push("upstream_impact 必须是对象");
+  if (isObject(data.consistency_policy)) {
+    for (const field of ["transaction_boundary", "concurrency", "idempotency", "cross_aggregate_strategy"]) requireString(data.consistency_policy, field, "consistency_policy", errors);
+  }
+  if (isObject(data.upstream_impact)) {
+    for (const field of ["spec_ref", "strategic_ref", "api_ref", "data_ref"]) requireString(data.upstream_impact, field, "upstream_impact", errors);
+    if (data.upstream_impact.upstream_current === false && data.status !== "stale") errors.push("上游已过期时 status 必须为 stale");
+  }
+
+  const aggregates = list(data.aggregate_catalog) ? data.aggregate_catalog : [];
+  const entities = list(data.entity_catalog) ? data.entity_catalog : [];
+  const values = list(data.value_object_catalog) ? data.value_object_catalog : [];
+  const behaviors = list(data.behavior_catalog) ? data.behavior_catalog : [];
+  const invariants = list(data.invariant_catalog) ? data.invariant_catalog : [];
+  const transitions = list(data.state_transition_catalog) ? data.state_transition_catalog : [];
+  const events = list(data.domain_event_catalog) ? data.domain_event_catalog : [];
+  const gateways = list(data.gateway_catalog) ? data.gateway_catalog : [];
+  const mappings = list(data.persistence_mapping) ? data.persistence_mapping : [];
+  const seams = list(data.test_seams) ? data.test_seams : [];
+  const ids = (items, field, kind, label) => {
+    const result = new Set();
+    unique(items.map((item) => item?.[field]).filter(Boolean), label, errors);
+    for (const [index, item] of items.entries()) {
+      if (item?.[field]) { requireId(item[field], kind, `${label}[${index}].${field}`, errors); result.add(item[field]); }
+    }
+    return result;
+  };
+  const aggregateIds = ids(aggregates, "aggregate_id", "aggregate_id", "aggregate_id");
+  const entityIds = ids(entities, "entity_id", "entity_id", "entity_id");
+  const valueIds = ids(values, "value_object_id", "value_object_id", "value_object_id");
+  const behaviorIds = ids(behaviors, "behavior_id", "behavior_id", "behavior_id");
+  const invariantIds = ids(invariants, "invariant_id", "invariant_id", "invariant_id");
+  const transitionIds = ids(transitions, "transition_id", "transition_id", "transition_id");
+  const eventIds = ids(events, "event_id", "event_id", "event_id");
+  const gatewayIds = ids(gateways, "gateway_id", "gateway_id", "gateway_id");
+  ids(seams, "seam_id", "seam_id", "seam_id");
+
+  for (const [index, aggregate] of aggregates.entries()) {
+    const path = `aggregate_catalog[${index}]`;
+    if (!isObject(aggregate)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["aggregate_id", "name", "context_ref", "root_entity", "consistency_boundary"]) requireString(aggregate, field, path, errors);
+    requireArray(aggregate, "invariant_refs", path, errors, 1); requireArray(aggregate, "behavior_refs", path, errors, 1);
+    if (aggregate.model_origin === "strategic-concept") errors.push(`${path}.model_origin 不得直接把战略概念当作 Aggregate`);
+    if (aggregate.api_exposure !== "internal-only") errors.push(`${path}.api_exposure 必须为 internal-only`);
+    if (aggregate.root_entity && !entityIds.has(aggregate.root_entity)) errors.push(`${path}.root_entity 未引用 Entity`);
+    const rootEntity = entities.find((entity) => entity?.entity_id === aggregate.root_entity);
+    if (rootEntity && rootEntity.aggregate_id !== aggregate.aggregate_id) errors.push(`${path}.root_entity 的 aggregate_id 必须与当前 Aggregate 一致`);
+    refsExist(aggregate.invariant_refs, invariantIds, `${path}.invariant_refs`, errors);
+    refsExist(aggregate.behavior_refs, behaviorIds, `${path}.behavior_refs`, errors);
+  }
+  for (const [index, entity] of entities.entries()) {
+    const path = `entity_catalog[${index}]`;
+    if (!isObject(entity)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["entity_id", "name", "aggregate_id", "identity", "lifecycle"]) requireString(entity, field, path, errors);
+    if (entity.aggregate_id && !aggregateIds.has(entity.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+  }
+  for (const [index, value] of values.entries()) {
+    const path = `value_object_catalog[${index}]`;
+    if (!isObject(value)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["value_object_id", "name", "aggregate_id", "immutable"]) requireField(value, field, path, errors);
+    if (typeof value.immutable !== "boolean" || value.immutable !== true) errors.push(`${path}.immutable 必须为 true`);
+    if (value.aggregate_id && !aggregateIds.has(value.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+  }
+  for (const [index, behavior] of behaviors.entries()) {
+    const path = `behavior_catalog[${index}]`;
+    if (!isObject(behavior)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["behavior_id", "name", "aggregate_id", "command"]) requireString(behavior, field, path, errors);
+    for (const field of ["preconditions", "invariant_refs", "postconditions", "event_refs"]) requireArray(behavior, field, path, errors, field === "invariant_refs" ? 1 : 0);
+    if (behavior.aggregate_id && !aggregateIds.has(behavior.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+    refsExist(behavior.invariant_refs, invariantIds, `${path}.invariant_refs`, errors);
+    refsExist(behavior.event_refs, eventIds, `${path}.event_refs`, errors);
+  }
+  for (const [index, invariant] of invariants.entries()) {
+    const path = `invariant_catalog[${index}]`;
+    if (!isObject(invariant)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["invariant_id", "aggregate_id", "statement"]) requireString(invariant, field, path, errors);
+    if (invariant.aggregate_id && !aggregateIds.has(invariant.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+  }
+  for (const [index, transition] of transitions.entries()) {
+    const path = `state_transition_catalog[${index}]`;
+    if (!isObject(transition)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["transition_id", "aggregate_id", "from", "to", "behavior_id"]) requireString(transition, field, path, errors);
+    if (transition.aggregate_id && !aggregateIds.has(transition.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+    if (transition.behavior_id && !behaviorIds.has(transition.behavior_id)) errors.push(`${path}.behavior_id 未引用行为`);
+  }
+  for (const [index, event] of events.entries()) {
+    const path = `domain_event_catalog[${index}]`;
+    if (!isObject(event)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["event_id", "name", "aggregate_id", "delivery"]) requireString(event, field, path, errors);
+    requireArray(event, "consumers", path, errors, 0);
+    if (event.aggregate_id && !aggregateIds.has(event.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+  }
+  for (const [index, gateway] of gateways.entries()) {
+    const path = `gateway_catalog[${index}]`;
+    if (!isObject(gateway)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["gateway_id", "name", "context_ref", "layer"]) requireString(gateway, field, path, errors);
+    requireArray(gateway, "capabilities", path, errors, 1);
+    if (gateway.layer !== "Domain") errors.push(`${path}.layer 必须为 Domain，Infrastructure 只实现 Gateway`);
+  }
+  for (const [index, mapping] of mappings.entries()) {
+    const path = `persistence_mapping[${index}]`;
+    if (!isObject(mapping)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["aggregate_id", "storage_model", "notes"]) requireString(mapping, field, path, errors);
+    if (mapping.aggregate_id && !aggregateIds.has(mapping.aggregate_id)) errors.push(`${path}.aggregate_id 未引用 Aggregate`);
+  }
+  for (const [index, seam] of seams.entries()) {
+    const path = `test_seams[${index}]`;
+    if (!isObject(seam)) { errors.push(`${path} 必须是对象`); continue; }
+    for (const field of ["seam_id", "kind", "subject_ref", "assertion"]) requireString(seam, field, path, errors);
+    if (seam.subject_ref && !new Set([...aggregateIds, ...entityIds, ...valueIds, ...behaviorIds, ...invariantIds, ...transitionIds, ...gatewayIds]).has(seam.subject_ref)) errors.push(`${path}.subject_ref 未引用已声明领域对象`);
+  }
+  if (isObject(data.complexity) && data.complexity.escalate_to_standalone === true && !nonEmpty(data.complexity.standalone_ref)) errors.push("complexity.escalate_to_standalone 为 true 时必须提供 standalone_ref");
+  return errors;
+}
+
+async function main() {
+  const file = process.argv[2];
+  if (!file) throw new Error("用法: validate-tactical-design.mjs <contract.yaml>");
+  const source = await readFile(file, "utf8");
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new Error(`无法解析合同: ${document.errors[0].message}`);
+  const errors = validate(document.toJS({ maxAliasCount: 0 }));
+  if (errors.length) {
+    process.stderr.write(`${JSON.stringify({ result: "blocked", errors }, null, 2)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify({ result: "ready-for-lifecycle-review", tactical_design_id: document.get("tactical_design_id"), status: document.get("status") }, null, 2)}\n`);
+}
+
+main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/invalid-api-leaks-aggregate.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+tactical_design_id: tactical-design.invalid-api
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog: [{aggregate_id: aggregate.example, name: Example, context_ref: context.example, root_entity: entity.example-root, invariant_refs: [invariant.example], behavior_refs: [behavior.example], consistency_boundary: single, api_exposure: public-aggregate}]
+entity_catalog: [{entity_id: entity.example-root, name: Root, aggregate_id: aggregate.example, identity: id, lifecycle: active}]
+value_object_catalog: []
+behavior_catalog: [{behavior_id: behavior.example, name: Do, aggregate_id: aggregate.example, command: do, preconditions: [ready], invariant_refs: [invariant.example], postconditions: [done], event_refs: []}]
+invariant_catalog: [{invariant_id: invariant.example, aggregate_id: aggregate.example, statement: required}]
+state_transition_catalog: [{transition_id: transition.example, aggregate_id: aggregate.example, from: draft, to: done, behavior_id: behavior.example}]
+consistency_policy: {transaction_boundary: single, concurrency: optimistic, idempotency: guarded, cross_aggregate_strategy: none}
+domain_event_catalog: []
+gateway_catalog: [{gateway_id: gateway.example, name: Gateway, context_ref: context.example, layer: Domain, capabilities: [load]}]
+persistence_mapping: [{aggregate_id: aggregate.example, storage_model: example, notes: mapping}]
+test_seams: [{seam_id: test-seam.example, kind: domain, subject_ref: invariant.example, assertion: behavior}]
+adr_candidates: []
+upstream_impact: {spec_ref: spec@v1, strategic_ref: strategy@v1, api_ref: api@draft, data_ref: data@v1, upstream_current: true}
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: []

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/invalid-missing-consistency-policy.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+tactical_design_id: tactical-design.invalid-consistency
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog: [{aggregate_id: aggregate.example, name: Example, context_ref: context.example, root_entity: entity.example-root, invariant_refs: [invariant.example], behavior_refs: [behavior.example], consistency_boundary: single, api_exposure: internal-only}]
+entity_catalog: [{entity_id: entity.example-root, name: Root, aggregate_id: aggregate.example, identity: id, lifecycle: active}]
+value_object_catalog: []
+behavior_catalog: [{behavior_id: behavior.example, name: Do, aggregate_id: aggregate.example, command: do, preconditions: [ready], invariant_refs: [invariant.example], postconditions: [done], event_refs: []}]
+invariant_catalog: [{invariant_id: invariant.example, aggregate_id: aggregate.example, statement: required}]
+state_transition_catalog: [{transition_id: transition.example, aggregate_id: aggregate.example, from: draft, to: done, behavior_id: behavior.example}]
+consistency_policy: {}
+domain_event_catalog: []
+gateway_catalog: [{gateway_id: gateway.example, name: Gateway, context_ref: context.example, layer: Domain, capabilities: [load]}]
+persistence_mapping: [{aggregate_id: aggregate.example, storage_model: example, notes: mapping}]
+test_seams: [{seam_id: test-seam.example, kind: domain, subject_ref: invariant.example, assertion: behavior}]
+adr_candidates: []
+upstream_impact: {spec_ref: spec@v1, strategic_ref: strategy@v1, api_ref: api@draft, data_ref: data@v1, upstream_current: true}
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: []

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/invalid-missing-invariant.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+tactical_design_id: tactical-design.invalid-missing-invariant
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog: [{aggregate_id: aggregate.example, name: Example, context_ref: context.example, root_entity: entity.example-root, invariant_refs: [], behavior_refs: [behavior.example], consistency_boundary: single, api_exposure: internal-only}]
+entity_catalog: [{entity_id: entity.example-root, name: Root, aggregate_id: aggregate.example, identity: id, lifecycle: active}]
+value_object_catalog: []
+behavior_catalog: [{behavior_id: behavior.example, name: Do, aggregate_id: aggregate.example, command: do, preconditions: [], invariant_refs: [], postconditions: [], event_refs: []}]
+invariant_catalog: []
+state_transition_catalog: [{transition_id: transition.example, aggregate_id: aggregate.example, from: draft, to: done, behavior_id: behavior.example}]
+consistency_policy: {transaction_boundary: single, concurrency: optimistic, idempotency: guarded, cross_aggregate_strategy: none}
+domain_event_catalog: []
+gateway_catalog: [{gateway_id: gateway.example, name: Gateway, context_ref: context.example, layer: Domain, capabilities: [load]}]
+persistence_mapping: [{aggregate_id: aggregate.example, storage_model: example, notes: mapping}]
+test_seams: [{seam_id: test-seam.example, kind: domain, subject_ref: aggregate.example, assertion: behavior}]
+adr_candidates: []
+upstream_impact: {spec_ref: spec@v1, strategic_ref: strategy@v1, api_ref: api@draft, data_ref: data@v1, upstream_current: true}
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: []

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/invalid-stale-upstream-ref.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+tactical_design_id: tactical-design.invalid-stale
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog: [{aggregate_id: aggregate.example, name: Example, context_ref: context.example, root_entity: entity.example-root, invariant_refs: [invariant.example], behavior_refs: [behavior.example], consistency_boundary: single, api_exposure: internal-only}]
+entity_catalog: [{entity_id: entity.example-root, name: Root, aggregate_id: aggregate.example, identity: id, lifecycle: active}]
+value_object_catalog: []
+behavior_catalog: [{behavior_id: behavior.example, name: Do, aggregate_id: aggregate.example, command: do, preconditions: [ready], invariant_refs: [invariant.example], postconditions: [done], event_refs: []}]
+invariant_catalog: [{invariant_id: invariant.example, aggregate_id: aggregate.example, statement: required}]
+state_transition_catalog: [{transition_id: transition.example, aggregate_id: aggregate.example, from: draft, to: done, behavior_id: behavior.example}]
+consistency_policy: {transaction_boundary: single, concurrency: optimistic, idempotency: guarded, cross_aggregate_strategy: none}
+domain_event_catalog: []
+gateway_catalog: [{gateway_id: gateway.example, name: Gateway, context_ref: context.example, layer: Domain, capabilities: [load]}]
+persistence_mapping: [{aggregate_id: aggregate.example, storage_model: example, notes: mapping}]
+test_seams: [{seam_id: test-seam.example, kind: domain, subject_ref: invariant.example, assertion: behavior}]
+adr_candidates: []
+upstream_impact: {spec_ref: spec@v1, strategic_ref: strategy@v1, api_ref: api@draft, data_ref: data@v1, upstream_current: false}
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: []

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/invalid-strategic-as-tactical.yaml

@@ -0,0 +1,21 @@
+schema_version: 1
+tactical_design_id: tactical-design.invalid-strategic
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog: [{aggregate_id: aggregate.example, name: Example, context_ref: context.example, root_entity: entity.example-root, model_origin: strategic-concept, invariant_refs: [invariant.example], behavior_refs: [behavior.example], consistency_boundary: single, api_exposure: internal-only}]
+entity_catalog: [{entity_id: entity.example-root, name: Root, aggregate_id: aggregate.example, identity: id, lifecycle: active}]
+value_object_catalog: []
+behavior_catalog: [{behavior_id: behavior.example, name: Do, aggregate_id: aggregate.example, command: do, preconditions: [ready], invariant_refs: [invariant.example], postconditions: [done], event_refs: []}]
+invariant_catalog: [{invariant_id: invariant.example, aggregate_id: aggregate.example, statement: required}]
+state_transition_catalog: [{transition_id: transition.example, aggregate_id: aggregate.example, from: draft, to: done, behavior_id: behavior.example}]
+consistency_policy: {transaction_boundary: single, concurrency: optimistic, idempotency: guarded, cross_aggregate_strategy: none}
+domain_event_catalog: []
+gateway_catalog: [{gateway_id: gateway.example, name: Gateway, context_ref: context.example, layer: Domain, capabilities: [load]}]
+persistence_mapping: [{aggregate_id: aggregate.example, storage_model: example, notes: mapping}]
+test_seams: [{seam_id: test-seam.example, kind: domain, subject_ref: invariant.example, assertion: behavior}]
+adr_candidates: []
+upstream_impact: {spec_ref: spec@v1, strategic_ref: strategy@v1, api_ref: api@draft, data_ref: data@v1, upstream_current: true}
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: []

package/template/.cursor/skills/yss-tactical-design/tests/fixtures/valid-tactical-design.yaml

@@ -0,0 +1,80 @@
+schema_version: 1
+tactical_design_id: tactical-design.example-feature
+tactical_version: v1
+status: ready-for-human
+context_ref: context.example
+aggregate_catalog:
+  - aggregate_id: aggregate.example
+    name: ExampleAggregate
+    context_ref: context.example
+    root_entity: entity.example-root
+    invariant_refs: [invariant.example-required]
+    behavior_refs: [behavior.example-publish]
+    consistency_boundary: single-aggregate-transaction
+    api_exposure: internal-only
+entity_catalog:
+  - entity_id: entity.example-root
+    name: ExampleRoot
+    aggregate_id: aggregate.example
+    identity: stable-id
+    lifecycle: draft-published
+value_object_catalog:
+  - value_object_id: value-object.example-code
+    name: ExampleCode
+    aggregate_id: aggregate.example
+    immutable: true
+behavior_catalog:
+  - behavior_id: behavior.example-publish
+    name: Publish
+    aggregate_id: aggregate.example
+    command: publish
+    preconditions: ["状态为 draft"]
+    invariant_refs: [invariant.example-required]
+    postconditions: ["状态变为 published"]
+    event_refs: [domain-event.example-published]
+invariant_catalog:
+  - invariant_id: invariant.example-required
+    aggregate_id: aggregate.example
+    statement: "发布前必须满足业务前置条件"
+state_transition_catalog:
+  - transition_id: transition.example-publish
+    aggregate_id: aggregate.example
+    from: draft
+    to: published
+    behavior_id: behavior.example-publish
+consistency_policy:
+  transaction_boundary: single aggregate
+  concurrency: optimistic version check
+  idempotency: repeated publish is rejected by state guard
+  cross_aggregate_strategy: domain event with retry
+domain_event_catalog:
+  - event_id: domain-event.example-published
+    name: ExamplePublished
+    aggregate_id: aggregate.example
+    consumers: [downstream-context]
+    delivery: outbox-at-least-once
+gateway_catalog:
+  - gateway_id: gateway.example
+    name: ExampleGateway
+    context_ref: context.example
+    layer: Domain
+    capabilities: [save aggregate, load aggregate]
+persistence_mapping:
+  - aggregate_id: aggregate.example
+    storage_model: example_aggregate_snapshot
+    notes: "持久化结构不泄漏到领域模型"
+test_seams:
+  - seam_id: test-seam.example-invariant
+    kind: domain-behavior
+    subject_ref: invariant.example-required
+    assertion: "不满足前置条件时 publish 失败"
+adr_candidates: []
+upstream_impact:
+  spec_ref: docs/.scratch/example/spec.yaml@v1
+  strategic_ref: docs/.scratch/example/domain-strategy.yaml@v1
+  api_ref: docs/.scratch/example/openapi.yaml@draft
+  data_ref: docs/.scratch/example/data-architecture.md@v1
+  upstream_current: true
+version: v1
+digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+evidence_refs: [docs/.scratch/example/tactical-review.yaml]

package/template/.cursor/skills/yss-tactical-design/tests/run-scenarios.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const validator = join(root, "..", "scripts", "validate-tactical-design.mjs");
+const fixture = (name) => join(root, "fixtures", name);
+const run = (file) => spawnSync(process.execPath, [validator, file], { encoding: "utf8" });
+const pass = run(fixture("valid-tactical-design.yaml"));
+if (pass.status !== 0) throw new Error(`valid tactical design should pass: ${pass.stderr}`);
+
+const blockedCases = [
+  ["invalid-missing-invariant.yaml", "invariant_refs 必须是至少 1 项的数组"],
+  ["invalid-api-leaks-aggregate.yaml", "api_exposure 必须为 internal-only"],
+  ["invalid-stale-upstream-ref.yaml", "status 必须为 stale"],
+  ["invalid-strategic-as-tactical.yaml", "不得直接把战略概念当作 Aggregate"],
+  ["invalid-missing-consistency-policy.yaml", "consistency_policy.transaction_boundary 缺失"]
+];
+for (const [name, message] of blockedCases) {
+  const result = run(fixture(name));
+  if (result.status === 0 || !result.stderr.includes(message)) throw new Error(`${name} should be blocked: ${result.stderr}`);
+}
+
+const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-tactical-design-pressure-"));
+try {
+  const source = await readFile(fixture("valid-tactical-design.yaml"), "utf8");
+  const escalated = join(temporaryRoot, "missing-standalone-ref.yaml");
+  await writeFile(escalated, `${source}\ncomplexity:\n  escalate_to_standalone: true\n`);
+  const result = run(escalated);
+  if (result.status === 0 || !result.stderr.includes("standalone_ref")) throw new Error("complexity escalation without standalone_ref should be blocked");
+
+  const wrongGateway = join(temporaryRoot, "wrong-gateway-layer.yaml");
+  await writeFile(wrongGateway, source.replace("layer: Domain", "layer: Infrastructure"));
+  const gatewayResult = run(wrongGateway);
+  if (gatewayResult.status === 0 || !gatewayResult.stderr.includes("layer 必须为 Domain")) throw new Error("Infrastructure gateway should be blocked");
+
+  const crossAggregateRoot = join(temporaryRoot, "cross-aggregate-root.yaml");
+  await writeFile(crossAggregateRoot, source.replace("aggregate_id: aggregate.example\n    identity", "aggregate_id: aggregate.other\n    identity"));
+  const crossAggregateResult = run(crossAggregateRoot);
+  if (crossAggregateResult.status === 0 || !crossAggregateResult.stderr.includes("root_entity 的 aggregate_id 必须与当前 Aggregate 一致")) throw new Error("cross-aggregate root should be blocked");
+} finally {
+  await rm(temporaryRoot, { recursive: true, force: true });
+}
+process.stdout.write("DDD tactical design scenarios passed\n");

package/template/.hermes/skills/yss-domain/SKILL.md

@@ -5,7 +5,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 # yss-domain
 
-这是一个建模型 skill。核心目标是先把领域语义和边界建立清楚，再落代码。
+这是一个领域实现 skill。核心目标是消费已批准的战术模型，将领域行为落实为代码；战术模型的设计与批准由 `yss-tactical-design` 和 `yss-product-lifecycle` 负责。
 
 默认输出是新 DDD target profile；现有 YSS 组件仓库常见 `core/client/repository`、贫血对象和 VO 型 Gateway 只是 legacy profile，不得静默复制成新模块架构。
 
@@ -23,10 +23,10 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 工作方式
 
-1. 先抽业务术语、聚合边界和状态变化。
+1. 先读取批准且版本当前的 tactical-design contract 和 Slice Implementation Contract。
 2. 数据库字段只做补充，不直接决定领域对象结构。
-3. 先定义领域行为，再决定 Gateway 边界。
-4. 规则不清晰时，保留显式假设，不要静默猜测。
+3. 按合同实现领域行为、状态机、不变量和 Gateway 边界。
+4. 规则不清晰或模型需要扩展时，返回 `new_impacts` / `drift` 并停止，不要静默猜测。
 
 ## 产物范围
 
@@ -63,6 +63,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 ## 阶段 7 合同
 
 - 只消费生命周期已批准的 `Slice Implementation Contract` 和当前 `work_unit`；不得扩大 `allowed_write_paths`。
+- `Slice Implementation Contract` 必须引用批准且版本当前的 `tactical_design_ref`；不得在实现阶段重新批准或替换聚合、不变量和一致性策略。
 - 领域规则、状态机和不变量必须使用 `behavior-tdd`，先形成失败测试，再实现最小行为。
 - 完成后按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`：changed files、领域/测试证据、实际验证结果、偏离和新增影响。
 - 发现新 API、权限、状态机、数据模型或架构影响时填入 `new_impacts` 并暂停，不得静默扩张切片。

package/template/.hermes/skills/yss-product-lifecycle/SKILL.md

@@ -11,10 +11,10 @@ description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术
 
 1. 先读取 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产。
 2. `repository_mode=template-source` 只走模板维护流程；命中产品流程时返回 `blocked: template-source-product-artifact-forbidden`，不得生成产品 Spec、原型、OpenAPI 或切片 Ticket。
-3. `repository_mode=project-instance` 以 `docs/process/lifecycle-registry.yaml`、`harness-process-tailoring.md` 和本目录 references 为唯一阶段、门禁和裁剪事实源。
+3. `repository_mode=project-instance` 以 `docs/process/lifecycle-registry.yaml`、`harness-process-tailoring.md` 和本目录 references 为唯一阶段、门禁和裁剪事实源。数字人角色、阶段协作组、运行时绑定与会签级别以 `docs/agents/digital-human-roles.yaml` 为准；职称实例不另起编排器。
 4. 模式：`route` 只读规划；`orchestrate` 有界推进；`resume` 重建后推进；`audit` 严格只读。未明确时使用 `route`。
 
-Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在四类人工门禁暂停。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
+Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为显式兼容入口；默认路径是本 skill 持有的原生工作单元，由本编排器创建正式资产、维护状态并在会签门禁暂停（级别见数字人角色注册表）。兼容入口不得自动调用它们或代替其创建正式资产；Matt 只导航，不得写生命周期资产或改变门禁/Ticket 状态；任何写入前回交本编排器。
 
 ## 不可裁剪的主链
 
@@ -27,14 +27,14 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 | 阶段 | 必需产物/门禁 | 工作单元与技能 | 通过条件 |
 |---|---|---|---|
 | 入口分诊 | 身份、影响面、最近可信阶段 | `yss-product-lifecycle` | `yss-project.yaml` 合法且影响面可解释 |
-| 机会调研/需求分析 | Discovery、用户/MVP/非目标/成功标准、测试 seam | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，用户确认，无 runnable blocker |
-| Spec/功能架构 | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 人工批准后资产才为 `approved` 并进入下游 |
+| 机会调研/需求分析 | Discovery、用户/MVP/非目标/成功标准、测试 seam；命中 DDD 影响时补充领域战略设计与阶段决策包 | `work-unit.discovery-opportunity` + `work-unit.discovery-requirements` + `work-unit.domain-strategy-design` + `work-unit.stage-decision`；市场/竞品事实用 `competitive-intelligence`，技术/标准事实用 `research`；领域建模用 `domain-modeling`；`grill-with-docs` 为兼容入口 | 未决事实已 research 或 handoff，领域边界和统一语言可审查，阶段决策包完成必要批准 |
+| Spec/功能架构 | Spec、产品总体设计、功能架构；必要时 Spec Delta | 原生 `work-unit.spec-synthesis`；`to-spec` 为兼容入口 | 初稿先为 `ready-for-human`；只有 Spec baseline 会签批准后资产才为 `approved` 并进入下游 |
 | 原型设计 | 交互说明、低保真、状态矩阵、高保真 HTML、评审记录 | `yss-design-system` → `yss-prototype-stage` → `yss-antd-design`（仅原型事实）→ Codex `product-design:index`（非 Codex 交付等价合同）。前端落地改用 `yss-ui` | `gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` 均有证据 |
-| 技术分析 | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查 | `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-router` | API/架构契约冻结；无 API 影响有明确记录；脚手架策略满足 |
+| 技术分析 | OpenAPI Draft/Freeze、数据架构、工程基线、架构审查；按领域影响执行 Tactical DDD Check | `yss-openapi-governance` / `yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design`、`yss-router` | API/架构契约冻结；无 API 影响有明确记录；战术模型无未解释冲突；脚手架策略满足 |
 | Ticket 正式化 | 功能父 Ticket、垂直切片、Slice Implementation Contract | 原生 `work-unit.ticket-decomposition`；`to-tickets` 为兼容入口；生命周期复算 | 依赖、验收、测试 seam 可执行；合同已批准、持久化且为当前版本 |
-| 技术实现 | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`implement` 为兼容入口；前端按 `yss-ui` + `yss-page-module-development`，后端按 `yss-router` 最小闭包，业务行为统一 `tdd` | 只写允许路径；业务行为用 `behavior-tdd`；UI 影响必须有还原计划 |
+| 技术实现 | 前端/后端代码、TDD 证据、YSS Skill Execution Result | 原生 `work-unit.slice-implementation`；`implement` 为兼容入口；前端按 `yss-ui` + `yss-page-module-development`，后端按 `yss-router` 最小闭包，业务行为统一 `tdd` | 仅接收已完成 Ticket 正式化、已绑定垂直切片且 `ready-for-agent` 公式通过的输入；只写允许路径；业务行为用 `behavior-tdd`；UI 影响必须有还原计划 |
 | Review/验证 | 不可变候选快照、review 结论、fresh verification | `code-review`（独立于实现者）；UI 影响追加 `yss-ui` + `yss-design-system` 的 UI fidelity 轴 | findings 已处理；同一候选快照通过全部审查轴与验证 |
-| 发布/复盘 | 发布/回滚证据、复盘记录 | 生命周期自有工作单元 | fresh verification、独立审查和人工发布裁决齐全 |
+| 发布/复盘 | 发布/回滚证据、复盘记录 | 生命周期自有工作单元 | fresh verification、独立审查和发布裁决齐全；`gate.release-ready` 仍须生物人 |
 
 ## 前端实现还原硬检查
 
@@ -42,8 +42,8 @@ Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等保留为
 
 ## 结果与暂停
 
-每个工作单元必须返回 `Workflow Execution Result`（workflow reference、skill、changed files、evidence refs、actual verification、deferred seams、drift/new impacts）。缺少可读证据、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；“做完提交”等自然语言意向不构成上述结构化 Git 授权。
+凡主控向数字人角色或独立运行时正式派发生命周期工作单元，都必须通过结构化任务包派发，并返回 `Workflow Execution Result`（workflow reference、skill、changed files、evidence refs、actual verification、deferred seams、drift/new impacts）。任务包使用 `docs/process/schemas/digital-human-task-package.schema.json`，由 `scripts/verify-digital-human-task-package` 校验；其中 `role_id`、`runtime_id`、`execution_state`、`contract.kind/id/version`、允许写路径、预期证据和汇合引用必须完整。`slice-implementation` 任务包额外绑定批准且当前版本的 Slice Implementation Contract；Discovery、Spec、原型、技术分析、Ticket、Review、发布和模板维护分别绑定各自的生命周期资产或维护 checkpoint，不得伪造 Slice Contract。缺少可读证据、`stale`、`violation`、`drift`、`new_impacts` 或阻塞信号时不得标记 completed。实现授权不包含 Git commit/push 授权；“做完提交”等自然语言意向不构成上述结构化 Git 授权。
 
-输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。暂停时只提出一个具体人工决策，并给出推荐答案与恢复动作。
+输出固定包含：模式、当前阶段、影响面、资产/门禁状态、证据、Ticket 正式化状态、垂直切片引用、`ready-for-agent` 计算结果、阻塞项、本轮动作、下一工作单元、暂停/继续理由、Ticket 同步和 Git checkpoint 判断。原生路径未出现 `to-tickets` / `implement` 名称本身不构成异常；但没有完成 `work-unit.ticket-decomposition`、垂直切片仍为 `ready-for-human`、引用父 Ticket 或 `next_route` 越过 Ticket 正式化时必须返回 `blocked`。暂停会签时必须输出门禁 ID、指定 `role_id`、`runtime_id` 和会签文件路径（`docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`）。恢复前运行 `scripts/verify-approval-record`；错误会签记为 `blocked`，不得把该门禁标为 `approved`。任务包的 `core_skills` / `forbidden_skills` 必须从 `docs/agents/digital-human-roles.yaml` 复制（`taskPackageDefaults`），禁止手写第二套。
 
 详细执行循环、readiness、脚手架（包括 `controlled-generation`）、审查快照、状态传播和 Matt 边界见 [orchestration.md](references/orchestration.md)、[orchestration-contract.yaml](references/orchestration-contract.yaml)、[artifact-dependencies.md](references/artifact-dependencies.md) 和 [state-model.md](references/state-model.md)。

package/template/.hermes/skills/yss-product-lifecycle/references/artifact-dependencies.md

@@ -7,6 +7,8 @@ Discovery → Spec → Product Overview / Functional Architecture
 Spec + Product Overview → Product Design / Requirement Freeze
 Spec + Product Overview → API Impact / OpenAPI Draft
 Spec + Product Overview → System / Data Architecture
+System / Data Architecture + domain impact → Tactical DDD Check / tactical-design contract
+Tactical DDD contract → Architecture Review / Engineering Baseline / Slice Implementation Contract
 API impact = yes: Requirement Freeze + Design Review + Draft Review → OpenAPI Freeze
 API impact = no: API Impact Assessment approved → No-API-Impact record；Draft/Freeze gates = not-applicable
 Frozen Contract → Vertical Slice Tickets
@@ -30,3 +32,5 @@ Implementation → Independent Review → Fresh Verification → Release
 明确写入需求的认证、授权、租户隔离、敏感数据或合规行为变化不使用独立影响类型；按它实际改变的 UI 状态、API schema、状态机、数据模型或服务边界传播。普通 action 注册、SQL / DDL / 迁移和上传 / 下载只使用既有技术影响类型，不增加安全 / 权限传播。
 
 OpenAPI Freeze 后发生上游变化时，不得仅因父 Ticket 仍写阶段 6 就继续实现。先做影响分析，再精准更新相关资产和门禁。
+
+战术设计合同上游引用发生版本变化时，先将 tactical-design 标记为 `stale`，再传播到 Slice Contract；发现新的聚合、状态、不变量、一致性或 Gateway 影响时标记 `drift` / `new_impacts` 并重新路由。

package/template/.hermes/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -23,7 +23,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
-| 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始角色为 `ready-for-human` |
+| 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始 Ticket 状态为 `ready-for-human` |
 | 实现 | 原生 `work-unit.slice-implementation`；`implement`（用户显式兼容） | 当前合同批准并持久化后执行；内部使用 `tdd`，结果回交后再次核验 |
 | Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
 | 审查 | `code-review` | 唯一默认代码审查入口；审查者独立，结合 Spec、仓库治理规则和 YSS 标准 |
@@ -69,8 +69,8 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 | Matt flow | 进入条件 | 生命周期结果 |
 |---|---|---|
 | `to-spec`（用户显式） | Discovery work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
-| `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human` |
-| `implement`（用户显式） | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁 |
+| `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human`；必须留下 `ticket_decomposition_result_ref` 和 `vertical_slice_ticket_ref` |
+| `implement`（用户显式） | `ready-for-agent` 公式、Ticket 正式化结果、垂直切片引用/类型/状态、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁；父 Ticket、`ready-for-human` 切片或跳过 Ticket 正式化的 `next_route` 必须 `blocked` |
 
 `grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。