create-yss-spec 3.3.7 → 3.3.8

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

@@ -24,6 +24,8 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
 
+既有身份 v2 的纯工程变更可显式使用 `design_scope: engineering-only`；按 `references/engineering-design.schema.json` 绑定真实构建单元、写路径、只读依赖、失败处理与测试 seam。不得更改登记业务边界、领域模型、业务规则/状态、持久化、数据库 schema 或 UI；命中这些影响回原架构设计。缺省仍保留原 DDD/MVC 规则，不自动降级。工程分支仍需当前 Spec/API/工程依据、逐条承接、独立技术审查及正式 Slice 批准。
+
 ## 合同与验证
 
 新产物使用 schema v2 Technical Design Contract：共同头记录架构来源、输入版本与摘要、规则/场景承接、评审证据和状态，`design` 保存架构专属内容。合同格式与兼容规则见 `references/technical-design-contract.md`，Schema 见 `references/technical-design.schema.json`。

package/template/.codex/skills/yss-technical-design/references/engineering-design.schema.json

@@ -0,0 +1,224 @@
+{
+  "type": "object",
+  "properties": {
+    "scope_reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "impact_assessment": {
+      "type": "object",
+      "properties": {
+        "domain_model": {
+          "const": "none"
+        },
+        "business_state": {
+          "const": "none"
+        },
+        "business_rules": {
+          "const": "none"
+        },
+        "business_persistence": {
+          "const": "none"
+        },
+        "schema_migration": {
+          "const": "none"
+        },
+        "ui_change": {
+          "const": "none"
+        },
+        "architecture_boundary_change": {
+          "const": "none"
+        }
+      },
+      "required": [
+        "domain_model",
+        "business_state",
+        "business_rules",
+        "business_persistence",
+        "schema_migration",
+        "ui_change",
+        "architecture_boundary_change"
+      ],
+      "additionalProperties": false
+    },
+    "component_catalog": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "component_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "responsibility": {
+            "type": "string",
+            "minLength": 1
+          },
+          "build_unit_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "write_paths": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "depends_on": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "required": [
+          "component_id",
+          "responsibility",
+          "build_unit_ref",
+          "write_paths",
+          "depends_on"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "allowed_write_paths": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "read_dependencies": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^sha256:[a-f0-9]{64}$"
+          },
+          "purpose": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "ref",
+          "digest",
+          "purpose"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "flow": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "failure_handling": {
+      "type": "string",
+      "minLength": 1
+    },
+    "consistency_policy": {
+      "type": "object",
+      "properties": {
+        "read_only": {
+          "const": "read-only"
+        },
+        "transaction_boundary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "concurrency": {
+          "type": "string",
+          "minLength": 1
+        },
+        "idempotency": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cross_database_limit": {
+          "type": "string",
+          "minLength": 1
+        },
+        "timeouts": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recovery": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "read_only",
+        "transaction_boundary",
+        "concurrency",
+        "idempotency",
+        "cross_database_limit",
+        "timeouts",
+        "recovery"
+      ],
+      "additionalProperties": false
+    },
+    "test_seams": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "seam_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "minLength": 1
+          },
+          "subject_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "assertion": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "seam_id",
+          "kind",
+          "subject_ref",
+          "assertion"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "scope_reason",
+    "impact_assessment",
+    "component_catalog",
+    "allowed_write_paths",
+    "read_dependencies",
+    "flow",
+    "failure_handling",
+    "consistency_policy",
+    "test_seams"
+  ],
+  "additionalProperties": false,
+  "title": "既有工程的受控工程技术设计"
+}

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

@@ -266,6 +266,12 @@
     "digest": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "design_scope": {
+      "enum": [
+        "architecture-specific",
+        "engineering-only"
+      ]
     }
   },
   "required": [

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

@@ -266,6 +266,12 @@
     "digest": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "design_scope": {
+      "enum": [
+        "architecture-specific",
+        "engineering-only"
+      ]
     }
   },
   "required": [
@@ -290,15 +296,31 @@
   "allOf": [
     {
       "if": {
-        "properties": {
-          "architecture": {
+        "allOf": [
+          {
+            "not": {
+              "required": [
+                "design_scope"
+              ],
+              "properties": {
+                "design_scope": {
+                  "const": "engineering-only"
+                }
+              }
+            }
+          },
+          {
             "properties": {
-              "family": {
-                "const": "domain-driven"
+              "architecture": {
+                "properties": {
+                  "family": {
+                    "const": "domain-driven"
+                  }
+                }
               }
             }
           }
-        }
+        ]
       },
       "then": {
         "properties": {
@@ -427,15 +449,31 @@
     },
     {
       "if": {
-        "properties": {
-          "architecture": {
+        "allOf": [
+          {
+            "not": {
+              "required": [
+                "design_scope"
+              ],
+              "properties": {
+                "design_scope": {
+                  "const": "engineering-only"
+                }
+              }
+            }
+          },
+          {
             "properties": {
-              "family": {
-                "const": "layered-mvc"
+              "architecture": {
+                "properties": {
+                  "family": {
+                    "const": "layered-mvc"
+                  }
+                }
               }
             }
           }
-        }
+        ]
       },
       "then": {
         "properties": {
@@ -754,6 +792,246 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "required": [
+          "design_scope"
+        ],
+        "properties": {
+          "design_scope": {
+            "const": "engineering-only"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "design": {
+            "type": "object",
+            "properties": {
+              "scope_reason": {
+                "type": "string",
+                "minLength": 1
+              },
+              "impact_assessment": {
+                "type": "object",
+                "properties": {
+                  "domain_model": {
+                    "const": "none"
+                  },
+                  "business_state": {
+                    "const": "none"
+                  },
+                  "business_rules": {
+                    "const": "none"
+                  },
+                  "business_persistence": {
+                    "const": "none"
+                  },
+                  "schema_migration": {
+                    "const": "none"
+                  },
+                  "ui_change": {
+                    "const": "none"
+                  },
+                  "architecture_boundary_change": {
+                    "const": "none"
+                  }
+                },
+                "required": [
+                  "domain_model",
+                  "business_state",
+                  "business_rules",
+                  "business_persistence",
+                  "schema_migration",
+                  "ui_change",
+                  "architecture_boundary_change"
+                ],
+                "additionalProperties": false
+              },
+              "component_catalog": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "responsibility": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "build_unit_ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "write_paths": {
+                      "type": "array",
+                      "minItems": 1,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "depends_on": {
+                      "type": "array",
+                      "minItems": 0,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "required": [
+                    "component_id",
+                    "responsibility",
+                    "build_unit_ref",
+                    "write_paths",
+                    "depends_on"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "allowed_write_paths": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "read_dependencies": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "digest": {
+                      "type": "string",
+                      "pattern": "^sha256:[a-f0-9]{64}$"
+                    },
+                    "purpose": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "ref",
+                    "digest",
+                    "purpose"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "flow": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "failure_handling": {
+                "type": "string",
+                "minLength": 1
+              },
+              "consistency_policy": {
+                "type": "object",
+                "properties": {
+                  "read_only": {
+                    "const": "read-only"
+                  },
+                  "transaction_boundary": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "concurrency": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "idempotency": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "cross_database_limit": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "timeouts": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "recovery": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "read_only",
+                  "transaction_boundary",
+                  "concurrency",
+                  "idempotency",
+                  "cross_database_limit",
+                  "timeouts",
+                  "recovery"
+                ],
+                "additionalProperties": false
+              },
+              "test_seams": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "seam_id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "kind": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "subject_ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "assertion": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "seam_id",
+                    "kind",
+                    "subject_ref",
+                    "assertion"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": [
+              "scope_reason",
+              "impact_assessment",
+              "component_catalog",
+              "allowed_write_paths",
+              "read_dependencies",
+              "flow",
+              "failure_handling",
+              "consistency_policy",
+              "test_seams"
+            ],
+            "additionalProperties": false,
+            "title": "既有工程的受控工程技术设计"
+          }
+        }
+      }
     }
   ]
 }

package/template/.codex/skills/yss-technical-design/scripts/engineering-design.mjs

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import {readFileSync} from 'node:fs';
+import {ensure,read,safe,hash} from '../../../../scripts/lib/strategic-handoff-io.mjs';
+const beneath=(ref,scope)=>ref===scope||ref.startsWith(`${scope}/`);
+export function validateEngineeringDesign(data,{root}) {
+ const registration=read(safe(root,data.architecture.decision_ref));
+ ensure(registration.architecture_identity?.schema_version===2&&registration.architecture_identity.source_kind==='existing-registration','工程设计分支只承接既有工程身份 v2');
+ const binding=registration.architecture_evidence.engineering_baseline;
+ ensure(hash(readFileSync(safe(root,binding.ref)))===binding.digest,'工程设计基线摘要漂移');
+ const baseline=read(safe(root,binding.ref)),design=data.design;
+ ensure(data.inputs.some(x=>x.kind==='engineering'&&x.ref===binding.ref&&x.digest===binding.digest),'工程设计未绑定当前基线输入');
+ ensure(data.inputs.some(x=>x.kind==='api'),'工程设计需当前API或经审查的无API依据');
+ const ids=new Set(design.component_catalog.map(x=>x.component_id));
+ ensure(ids.size===design.component_catalog.length,'工程组件ID重复');
+ const paths=new Set();
+ for(const component of design.component_catalog){
+  const unit=baseline.build_units.find(x=>x.id===component.build_unit_ref);ensure(unit,'工程组件引用未登记的实际构建单元');
+  ensure(component.depends_on.every(id=>ids.has(id)),'工程组件依赖悬空');
+  for(const ref of component.write_paths){
+   ensure(!path.isAbsolute(ref)&&ref.split('/').every(p=>p&&p!=='.'&&p!=='..')&&!ref.includes('\\'),'工程写路径不安全');
+   ensure(registration.allowed_write_paths.some(scope=>beneath(ref,scope)),'工程组件写路径超出登记范围');
+   ensure(!baseline.boundary_scope.some(scope=>beneath(ref,scope)||beneath(scope,ref)),'工程分支不能改已登记业务架构边界');
+   const unitRoot=path.posix.dirname(unit.pom_ref);
+   ensure(unitRoot==='.'||beneath(ref,unitRoot),'工程组件写路径与实际构建单元不符');paths.add(ref);
+  }
+ }
+ ensure(design.allowed_write_paths.length===paths.size&&design.allowed_write_paths.every(ref=>paths.has(ref)),'工程设计写范围与组件闭包不一致');
+ ensure(data.source_items.length&&data.traceability.every(row=>row.disposition==='implemented'),'工程设计必须逐条承接当前范围，不得全标不适用或延期');
+ for(const input of design.read_dependencies)ensure(data.inputs.some(x=>x.ref===input.ref&&x.digest===input.digest),'工程只读依赖未绑定当前输入');
+}

package/template/.codex/skills/yss-technical-design/scripts/generate-schema.mjs

@@ -10,8 +10,9 @@ const branches = [
 schema.$comment = 'Generated by scripts/generate-schema.mjs from common and specialist schemas. Do not hand-edit.';
 schema.allOf = branches.map(([family, ref]) => {
   const branch = load(ref); delete branch.$id; delete branch.$schema;
-  return { if: { properties: { architecture: { properties: { family: { const: family } } } } }, then: { properties: { design: branch } } };
+  return { if: { allOf: [{ not: { required: ['design_scope'], properties: { design_scope: { const: 'engineering-only' } } } }, { properties: { architecture: { properties: { family: { const: family } } } } }] }, then: { properties: { design: branch } } };
 });
+schema.allOf.push({if:{required:['design_scope'],properties:{design_scope:{const:'engineering-only'}}},then:{properties:{design:load('../references/engineering-design.schema.json')}}});
 const output = fileURLToPath(new URL('../references/technical-design.schema.json', import.meta.url));
 const bytes = `${JSON.stringify(schema, null, 2)}\n`;
 if (process.argv.includes('--check')) {