create-yss-spec 3.1.3 → 3.2.0

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

@@ -6,6 +6,8 @@
 
 ## 输出
 
+以下 v1 结构作为新 Technical Design Contract v2 的 DDD `design` 内容使用。旧独立 v1 文件保持显式只读兼容；新合同共同头与战略交接绑定由 `yss-technical-design` 持有，分支不重复保存。
+
 ```yaml
 schema_version: 1
 tactical_design_id: tactical-design.<feature>
@@ -40,4 +42,4 @@ evidence_refs: []
 6. 复杂跨聚合一致性、并发、幂等、事件补偿或持久化错位必须写明策略，必要时升级独立文档。
 7. 实现发现新影响时必须阻断并回到生命周期重新路由。
 
-跨仓快照消费另须 `strategic_handoff`；字段与实际命令以 `docs/process/strategic-handoff-package.md` 为准。
+跨仓快照消费在 v2 共同头（旧独立 v1 则为根对象）绑定 `strategic_handoff`；字段与实际命令以 `docs/process/strategic-handoff-package.md` 为准。

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import process from "node:process";
+import { pathToFileURL } from "node:url";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 
 import { parseArgs } from "node:util";
@@ -68,7 +69,7 @@ function refsExist(values, known, path, errors) {
   }
 }
 
-function validate(data) {
+export function validate(data) {
   const errors = [];
   if (!isObject(data)) return ["合同必须是对象"];
   for (const field of required) requireField(data, field, "root", errors);
@@ -218,4 +219,4 @@ async function main() {
   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; });
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });

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

@@ -0,0 +1,31 @@
+---
+name: yss-technical-design
+description: 在 YSS 技术分析中统一承接需求与战略输入，按已确认的 DDD 或传统 MVC 架构组织设计合同。
+---
+
+# YSS 技术设计
+
+由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
+
+## 输入与架构选择
+
+先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。
+
+按项目绑定架构选择的来源及摘要。新工程复用 `scaffold-architecture-decisions.yaml` 的用户确认决定，先确认再进入分支，后续脚手架消费同一决定；既有工程沿用已登记架构，架构转换另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD。具体 Profile 及模块边界消费技能注册表与 `docs/agents/backend-architecture-profiles.md`。
+
+- `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
+- `layered-mvc`：调用 `yss-mvc-design`，不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。
+
+已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
+
+## 合同与验证
+
+新产物使用 schema v2 Technical Design Contract：共同头记录架构来源、输入版本与摘要、规则/场景承接、评审证据和状态，`design` 保存架构专属内容。合同格式与兼容规则见 `references/technical-design-contract.md`，Schema 见 `references/technical-design.schema.json`。
+
+运行 `node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs <合同> --root <项目根>`。整体存在延期或冲突即阻断整体；相关切片可带 `--slice <切片ID>` 按依赖核验，仍须合同已批准。校验成功只返回审查输入，不批准、不设置 `ready-for-agent`。
+
+schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，不能解释为 MVC。迁移不自动批准，输入或架构变化必须重新校验并按现有门禁审查。新合同使用 `artifact.technical-design` / `evidence.technical-design-review`；旧 DDD 稳定 ID 保留原含义。
+
+## 交接
+
+按现有架构审查门禁进行独立评审。批准且版本当前后交回生命周期，再交编译器；DDD 实现使用 `yss-domain`，MVC 实现按已登记 Profile 的能力与 Recipe 路由。发现 `stale`、`drift`、`new_impacts` 或路径越界时回交重路由。需要图示时按用户或合同要求调用 `archify`，图只作派生证据。

package/template/.agents/skills/yss-technical-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS 技术设计"
+  short_description: "按已确认 DDD 或 MVC 架构组织技术设计合同"
+  default_prompt: "基于当前批准输入和已确认架构，按已确认 DDD 或 MVC 架构组织技术设计合同，返回待生命周期审查的结果。"

package/template/.agents/skills/yss-technical-design/references/technical-design-common.schema.json

@@ -0,0 +1,290 @@
+{
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "const": 2
+    },
+    "technical_design_id": {
+      "type": "string",
+      "pattern": "^technical-design\\.[a-z0-9][a-z0-9-]*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^v[1-9][0-9]*$"
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "ready-for-human",
+        "approved",
+        "blocked",
+        "stale",
+        "drift",
+        "new_impacts"
+      ]
+    },
+    "context_ref": {
+      "const": "CONTEXT.md"
+    },
+    "architecture": {
+      "type": "object",
+      "properties": {
+        "family": {
+          "enum": [
+            "domain-driven",
+            "layered-mvc"
+          ]
+        },
+        "project_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source_kind": {
+          "enum": [
+            "scaffold-decision",
+            "existing-registration"
+          ]
+        },
+        "decision_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "decision_digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "family",
+        "project_id",
+        "source_kind",
+        "decision_ref",
+        "decision_digest"
+      ],
+      "additionalProperties": false
+    },
+    "inputs": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "properties": {
+          "ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "kind": {
+            "enum": [
+              "context",
+              "spec",
+              "rules",
+              "scenarios",
+              "api",
+              "adr",
+              "engineering",
+              "strategic"
+            ]
+          }
+        },
+        "required": [
+          "ref",
+          "version",
+          "digest",
+          "kind"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "source_items": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "properties": {
+          "source_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "enum": [
+              "rule",
+              "scenario"
+            ]
+          },
+          "critical": {
+            "type": "boolean"
+          },
+          "source_ref": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "source_id",
+          "kind",
+          "critical",
+          "source_ref"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "traceability": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "source_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "disposition": {
+            "enum": [
+              "implemented",
+              "deferred",
+              "not-applicable",
+              "pending",
+              "conflict"
+            ]
+          },
+          "tactical_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "test_seam_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "evidence_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "dependency_status": {
+            "enum": [
+              "known",
+              "unknown"
+            ]
+          },
+          "dependent_slice_refs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "scenario_tests": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "outcome": {
+                  "enum": [
+                    "success",
+                    "failure"
+                  ]
+                },
+                "seam_ref": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "outcome",
+                "seam_ref"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "risk": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "followup_ticket_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "verification_plan": {
+            "type": "string",
+            "minLength": 1
+          },
+          "target_version": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "source_id",
+          "disposition",
+          "dependency_status",
+          "dependent_slice_refs"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "strategic_handoff": {
+      "type": "object"
+    },
+    "design": {
+      "type": "object"
+    },
+    "evidence_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  },
+  "required": [
+    "schema_version",
+    "technical_design_id",
+    "version",
+    "status",
+    "context_ref",
+    "architecture",
+    "inputs",
+    "source_items",
+    "traceability",
+    "design",
+    "evidence_refs",
+    "digest"
+  ],
+  "additionalProperties": false,
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/technical-design-v2.json",
+  "title": "YSS Technical Design Contract v2",
+  "$comment": "共同合同权威；完整分支 Schema 由 scripts/generate-schema.mjs 派生。"
+}

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

@@ -0,0 +1,31 @@
+# Technical Design Contract v2
+
+共同合同字段由 `technical-design-common.schema.json` 定义，完整 `technical-design.schema.json` 通过 `scripts/generate-schema.mjs` 合并专项 Schema 派生，使用 `--check` 检查同步，`design` 按 `architecture.family` 校验：`domain-driven` 沿用 DDD v1 内容结构，`layered-mvc` 使用 `yss-mvc-design/references/mvc-design.schema.json`。DDD 内层的 schema/version/status 是分支内容版本，status 必须与共同头一致；战略交接绑定只写共同头，避免双重维护。
+
+## 共同头
+
+- `schema_version: 2`、`technical_design_id: technical-design.<name>`、`version: vN`、`status`、`context_ref: CONTEXT.md`。
+- `architecture`：`family`、`project_id`、`source_kind: scaffold-decision | existing-registration`、`decision_ref`、`decision_digest`。新项目引用正式且 current 的脚手架决定，所选项目必须已由用户确认；既有登记引用当前 `project_id` 和 `architecture_identity.architecture_family`，也可从登记的 `repositories` 数组按项目解析。架构来源变化须重新绑定和审查，不能改合同字段冒充用户改选。
+- `inputs`：每行 `{kind, ref, version, digest}`，kind 为 context/spec/rules/scenarios/api/adr/engineering/strategic；至少包含根 CONTEXT.md 与 Spec。适用的工程/API 约束同样绑定。无 API 影响理由记录在需求或工程输入中。DDD 另须 strategic 输入，MVC 不要求。
+- `source_items`：无战略包时从批准需求提取稳定规则和场景 `{source_id, kind: rule | scenario, critical, source_ref}`。source_ref 必须对应 inputs，不复制源正文成为第二事实源。
+- `traceability`：逐项对应 source_items。沿用 `tactical_refs` 字段名以兼容承接协议，其值在新合同中可指向 MVC 用例、规则或 DDD 对象；其他字段与战略承接 rows 相同。implemented 仅表示设计承接已落实，不表示代码已实现。
+- 有战略包时追加 `strategic_handoff`，按 `docs/process/strategic-handoff-package.md` 绑定导入收据、摘要、正式对账及 rows；本地补充规则仍可写 source_items / traceability，但不能重复维护包内来源。
+- `evidence_refs`：现有审查证据的可读取路径。approved 状态必须有评审证据，真正批准仍由生命周期核验适用批准记录；本校验器不产生批准。
+- `digest`：删除根 digest 后按键排序、数组保持顺序的 canonical JSON SHA-256，前缀 `sha256:`。来源文件的 digest 使用原始字节 SHA-256；这两种摘要不可混用。
+
+所有仓内引用相对 `--root` 解析；不接受越界或符号链接。输入摘要不匹配、未知架构、悬空落点、缺少关键场景成功/失败测试均阻断。延期与冲突按已声明的切片依赖阻断，依赖未知时整体阻断。
+
+## 设计与实现交接
+
+```bash
+node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs docs/design/technical-design.yaml --root <项目根>
+node .agents/skills/yss-technical-design/scripts/validate-technical-design.mjs docs/design/technical-design.yaml --root <项目根> --slice <切片ID>
+```
+
+编译器输入与 resolution 使用 `technical_design: {ref, version, digest}`，digest 是已持久化整个合同的原始字节摘要，并绑定 `slice_id`。命中 `backend-technical-design-impact` 或已有领域/状态/一致性影响条件时必须提供；编译与 freshness 检查重新执行验证，并核对架构族。没有相关设计影响的编译继续消费原有最小合同。
+
+schema v1 仅配合 `--legacy-ddd`（编译器绑定 `legacy_ddd: true`）读取为 DDD。旧 DDD 校验入口保留，不改变旧批准或历史文件。新写合同一律 v2；格式迁移不代表批准，架构、输入或设计变化走现有门禁重审。
+
+## MVC 示例
+
+可执行示例见 `../tests/fixtures.mjs` 的 `mvcFixture`：在临时项目绑定需求与现有登记，定义 server → service → repository、提交用例、规则、事务、存储映射和成功/失败 seam。它只用于模板验证，不生成产品实例 Spec。