create-yss-spec 2.1.0 → 2.1.2

package/README.md

@@ -33,7 +33,7 @@ npx create-yss-spec@latest
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
 
-本次新增能力按 `2.1.0` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次新增能力按 `2.1.2` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
     "template.snapshot.json"
   ],
   "bin": {
-    "create-yss-spec": "./bin/create-yss-spec.js"
+    "create-yss-spec": "bin/create-yss-spec.js"
   },
   "scripts": {
     "sync-template": "node scripts/sync-template.js",

package/src/cli.js

@@ -4,6 +4,7 @@ const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline/promises");
 const { spawnSync } = require("node:child_process");
+const { treeHash } = require("./template-hash");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_MANIFEST = JSON.parse(
@@ -489,35 +490,6 @@ function fileHash(filePath) {
   return sha256(fs.readFileSync(filePath));
 }
 
-function treeHash(rootPath) {
-  const digest = crypto.createHash("sha256");
-
-  function visit(currentPath, relativeDir = "") {
-    for (const entry of fs
-      .readdirSync(currentPath, { withFileTypes: true })
-      .sort((left, right) => left.name.localeCompare(right.name))) {
-      if (entry.name === ".DS_Store") {
-        continue;
-      }
-      const relativePath = relativeDir
-        ? `${relativeDir}/${entry.name}`
-        : entry.name;
-      const absolutePath = path.join(currentPath, entry.name);
-      if (entry.isDirectory()) {
-        digest.update(`dir:${relativePath}\0`);
-        visit(absolutePath, relativePath);
-      } else if (entry.isFile()) {
-        digest.update(`file:${relativePath}\0`);
-        digest.update(fs.readFileSync(absolutePath));
-        digest.update("\0");
-      }
-    }
-  }
-
-  visit(rootPath);
-  return digest.digest("hex");
-}
-
 function pathKind(absolutePath) {
   let stat;
   try {
@@ -1744,7 +1716,7 @@ function runSync(argv = []) {
 }
 
 function printHelp() {
-  console.log(`create-yss-spec 2.1.0
+  console.log(`create-yss-spec ${PACKAGE_MANIFEST.version}
 
 初始化：create-yss-spec --project-name <name> --business-domain <domain> --target-dir <dir>
 接管已有项目：create-yss-spec attach --target-dir <dir> --project-name <name> --business-domain <domain> --dry-run|--apply [--force]

package/src/template-hash.js

@@ -0,0 +1,44 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function compareNames(left, right) {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function treeHash(rootPath) {
+  const digest = crypto.createHash("sha256");
+
+  function visit(currentPath, relativeDir = "") {
+    for (const entry of fs
+      .readdirSync(currentPath, { withFileTypes: true })
+      .sort((left, right) => compareNames(left.name, right.name))) {
+      if (entry.name === ".DS_Store") {
+        continue;
+      }
+      const relativePath = relativeDir
+        ? `${relativeDir}/${entry.name}`
+        : entry.name;
+      const absolutePath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        digest.update(`dir:${relativePath}\0`);
+        visit(absolutePath, relativePath);
+      } else if (entry.isFile()) {
+        digest.update(`file:${relativePath}\0`);
+        digest.update(fs.readFileSync(absolutePath));
+        digest.update("\0");
+      }
+    }
+  }
+
+  visit(rootPath);
+  return digest.digest("hex");
+}
+
+module.exports = { treeHash };

package/template/.agents/skills/cross-repo-implementation-routing/SKILL.md

@@ -19,9 +19,10 @@ description: Use when a Harness change or vertical slice may require work across
 1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
-4. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
-5. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
-6. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
+4. 核对项目根路径：Harness 内项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。外部仓库记录各自的真实项目根。
+5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
+6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
+7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 
 ## Routing Matrix
 

package/template/.agents/skills/implementation-repo-onboarding/SKILL.md

@@ -20,8 +20,9 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
-5. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
-6. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+5. 判定实现位置：Harness 内只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。外部实现仓库记录真实项目根路径，不套用 Harness 占位路径。
+6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
 
 ## Baseline Checks
 
@@ -37,6 +38,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 - 不直接提交、推送、创建 MR / PR 或修改实现仓库。
 - 不把实现仓库源码复制进 Harness 仓库。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
+- 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
 - 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。
 
 ## Output

package/template/.agents/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -24,11 +24,14 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 ## 优先流程
 
 1. 确认项目名、基础包名、输出目录、数据库类型。
+   Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
 2. 运行 `scripts/generate_scaffold.py` 生成骨架。
 3. 检查生成的模块名、POM、配置文件、Smart Doc 配置和包路径。
-4. 使用 `./mvnw` 执行 `validate`、测试和打包验证。
+4. 由生命周期受控工作单元在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；生成器打印的下一步命令不构成验证证据。
 5. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
 
+受控验证命令由本 skill 的 `scripts/run_scaffold_verification.py` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、耗时、执行时间和 `scaffold-verification.json`；任何一条命令失败或未执行都必须阻断。
+
 ## 推荐命令
 
 ```bash
@@ -36,7 +39,13 @@ python3 scripts/generate_scaffold.py \
   --project-name my-service \
   --base-package com.yss.myservice \
   --output-dir /path/to/implementation-repo \
-  --database mysql
+  --database mysql \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --router-draft-ref <router-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json
 ```
 
 ## 生成结果应包含
@@ -47,20 +56,28 @@ python3 scripts/generate_scaffold.py \
 - `*-infrastructure`
 - `*-adapter`
 - `*-bootstrap`
-- 基础配置、模板代码、构建脚本
+- 基础配置、机械模板、构建脚本
 - `bootstrap/src/main/resources/smart-doc.json` 基础配置
 
 ## 使用约束
 
-- 先生成骨架，再做业务化定制，不要直接把脚手架当最终代码交付。
-- 默认不生成 `User CRUD` 示例；只有显式传入 `--with-example` 时才生成。
+- 先在生命周期批准的脚手架受控生成合同下生成骨架，再做业务化定制；不要直接把脚手架当最终代码交付。
+- 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若仓库已经存在相同工程，先核对覆盖范围。
 - 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行、OpenAPI 生成和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
+- 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper、Smart Doc 和机械模板，不是业务实现。
+- 脚手架合同必须携带 `contract_id`、`contract_version`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
+- 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation` 和固定三条验证命令，不接受仅凭任意字符串引用的放行。
+- 生成项目必须写入非业务元数据清单 `.yss/scaffold-generation.json`，回勾合同 ID、版本、批准引用、生成输入、受控模式和固定验证命令；清单缺失时不得交给后续 Router。
+- 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
+- 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板；非空目标目录使用 `--force` 默认禁止，除非覆盖范围、备份、回滚点和批准引用已经进入当前合同。
+- 脚手架完成后，所有后续生成的后端代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
 - `.mvn/settings.xml` 只能通过 `${env.MAVEN_REPO_USERNAME}` 和 `${env.MAVEN_REPO_PASSWORD}` 读取 Maven 仓库凭据；内部仓库构建前由 CI 或本地安全环境注入变量，禁止把 Maven 仓库用户名、明文密码或 Maven 加密密码写入 skill、模板或生成工程。
 - 涉及 API 契约时，先确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
 
@@ -80,6 +97,7 @@ python3 scripts/generate_scaffold.py \
 ## 按需读取
 
 - 主脚本：`scripts/generate_scaffold.py`
+- 受控验证器：`scripts/run_scaffold_verification.py`
 - 模板目录：`assets/templates/`
 - 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
 
@@ -87,4 +105,6 @@ python3 scripts/generate_scaffold.py \
 
 - 仅在实现仓库/输出目录、`scaffold_status=required` 和批准合同明确时运行。
 - 工程骨架属于 `controlled-generation`，必须记录生成器输入、预期文件和 `./mvnw ...` 编译/测试结果；不得将业务状态机、权限、事务或查询逻辑混入生成步骤。
+- 生成结果必须包含 `.yss/scaffold-generation.json`，并由验证器回勾该清单；清单与批准合同不一致时阻断。
+- `./mvnw validate`、`./mvnw test`、`./mvnw package` 必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、耗时、stdout/stderr 引用和执行时间；只列命令计划、生成器成功或打印输出均视为缺失证据并阻断。
 - 生成后按统一 `YSS Skill Execution Result` 返回 changed/evidence files、实际验证结果和新增影响，再由 Router 为业务工作单元重新路由。

package/template/.agents/skills/yss-ddd-scaffold-generator/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS DDD Scaffold"
   short_description: "生成多模块 YSS DDD 后端脚手架与工程骨架规范"
-  default_prompt: "Use $yss-ddd-scaffold-generator to create a standard YSS DDD backend scaffold with domain, application, infrastructure, adapter, and bootstrap modules."
+  default_prompt: "Use $yss-ddd-scaffold-generator only with a lifecycle-approved scaffold contract JSON to create a pure YSS DDD backend skeleton with domain, application, infrastructure, adapter, and bootstrap module boundaries; route all business code back through yss-router and the applicable YSS skills."

package/template/.agents/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -13,15 +13,24 @@ python3 .agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py \
   --project-name user-service \
   --base-package com.yss.user \
   --output-dir /path/to/implementation-repo \
-  --database mysql
+  --database mysql \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --router-draft-ref <router-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json
 ```
 
+上述合同参数必须替换为生命周期已批准且已持久化的当前脚手架合同；缺少时生成器会拒绝写入。
+
 ### 1.2 生成的项目结构
 
 ```
 output/user-service/
 ├── pom.xml
 ├── README.md
+├── .yss/scaffold-generation.json
 ├── user-service-domain/
 ├── user-service-application/
 ├── user-service-infrastructure/
@@ -39,7 +48,17 @@ cd output/user-service
 ./mvnw clean compile
 ```
 
-### 2.2 运行项目
+### 2.2 受控验证
+
+从生命周期工作目录执行固定验证器；它会在项目 evidence 目录实际运行三条 wrapper 命令并写入结果，不能用生成器打印的命令替代：
+
+```bash
+python3 .agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.py \
+  --project-root /path/to/implementation-repo/user-service \
+  --evidence-dir /path/to/implementation-repo/user-service/docs/evidence/scaffold
+```
+
+### 2.3 运行项目
 
 ```bash
 # 方式1: 使用 Maven 插件
@@ -50,45 +69,15 @@ cd output/user-service
 java -jar user-service-bootstrap/target/user-service-bootstrap-1.0.0-SNAPSHOT.jar
 ```
 
-### 2.3 访问应用
+### 2.4 验证基础工程
 
 ```bash
-# 健康检查
+# 纯脚手架不包含业务 Controller；这里只验证启动工程是否可访问
 curl http://localhost:8080/actuator/health
-
-# 查询用户列表
-curl -X POST http://localhost:8080/api/users/page \
-  -H "Content-Type: application/json" \
-  -d '{
-    "pageNum": 1,
-    "pageSize": 10
-  }'
-
-# 新增用户
-curl -X POST http://localhost:8080/api/users \
-  -H "Content-Type: application/json" \
-  -d '{
-    "username": "zhangsan",
-    "email": "zhangsan@example.com"
-  }'
-
-# 查询用户详情
-curl http://localhost:8080/api/users/1
-
-# 更新用户
-curl -X PUT http://localhost:8080/api/users \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": 1,
-    "username": "zhangsan",
-    "email": "zhangsan@yss.com",
-    "status": 1
-  }'
-
-# 删除用户
-curl -X DELETE http://localhost:8080/api/users/1
 ```
 
+业务 API、数据表和初始化数据不属于脚手架输出。完成 OpenAPI Freeze、Slice Implementation Contract 和生命周期批准后，按 `yss-router` 选择的 YSS skill 在对应垂直切片中实现并补充契约测试。
+
 ## 3. 添加新实体
 
 ### 3.1 创建 Domain 层对象